File format specification of configuration definition

this describes the possible elements of a configuration description in JSON format.

Table of Contents

File format specification of configuration definition	1

Kinds of Settings	2

general settings	3

peripheral settings	4

driver layer	5

signal names	6

Example	7

general settings	8

vendor_name	9

chip_name	10

project_type	11

file_comment	12

run_from	13

path_prefix	14

clock group	15

source	16

frequency	17

digital_output group	18

type	19

pad	20

invert	21

digital_input group	22

pad	23

analogue_input (ADC) group	24

analogue_output (DAC) group	25

Timer group	26

peripheral	27

mode	28

frequency	29

RTC group	30

UART group	31

pad_tx	32

pad_rx	33

pad_cts	34

pad_rts	35

bits_per_packet	36

parity	37

stop_bits	38

baud_rate	39

hardware_flow_control	40

receive_buffer_size	41

send_buffer_size	42

peripheral	43

IRQ	44

IRQ_priority	45

SPI group	46

pad_sck	47

pad_mosi	48

pad_miso	49

pad_ncs	50

role	51

communication_mode	52

frame_format	53

clock_polarity	54

clock_phase	55

SPI Mode	56

bit_order	57

baud_rate	58

The JSON format is defined here: https://www.json.org/json-en.html

All elements not listed as essential are optional. Being optional means that they can be missing and the configuration is still valid.

If elements that describe a peripheral are not present than that peripheral will not be used. No initialization code for that peripheral will be generated.

If elements that define general settings are missing then the default value for that setting is used. The section describing the element will also state the default value.

The essential elements are :

vendor_name

chip_name

Kinds of Settings

The settings defined in this file cover different areas.

general settings

peripheral settings

driver layer

signal names

general settings

general settings affect the whole project. These settings are general configurations and switches to enable additional features or to select modes for the project.

peripheral settings

peripheral settings are definitions of peripheral configuration. Examples are Pad names, enabled or disabled functionality and Speed settings.

driver layer

The peripherals can be used in different ways (polling, interrupt, DMA) and for different purposes (“send text”, “send binary packets”, “fixed length packet”, “variable length packet”) and implementing these functionality is device independent. This configuration file should therefore only give guidance to MBSP and select the API style the user want's to use.

signal names

The user shall not be bothered with the details of the used peripheral. The user should therefore not depend on peripheral names (“SPI0”, “UART3”, “GPIO PA9”, ..) but refer to these resources by names that make sense for the user. These names are defined in this file.

Example

{
"vendor_name": "Geehy",
"chip_name": "APM32F411VC",
"digital_output": {
"green_led": {
"type": "push pull",
"pad": "PA3"
}
}
"SPI": {
...
}
}

Keys like *digital_output* and *SPI* represent group names and are taken from a predefined set of group names understood by MBSP. Keys nested within them are arbitrary user-defined names for a instance in that group. In those instances the keys are from the defined set specific for that group.

general settings

these are settings on the top layer that effect the whole project.

vendor_name

Name of the company that sells the micro controller. As listed on https://chipselect.org

type: string

chip_name

Model number of the micro controller. As listed on https://chipselect.org

type: string

Model number is truncated so that it only contains relevant differences for code generation: flash and ram sizes are relevant, temperature range or package are not.

project_type

what type of project to generate.

type: string

default: “make”

Possible values are:

“hal only” : only creates the hardware driver files (in the hal/ folder) and hardware definitions (in the hal/hw/ folder)

“embeetle” : create an Embeetle IDE project

“make” : creates a makefile based “blinky” project.

file_comment

defines the comment at the top of each generated file.

type: string

default: “created”

Possible values are:

“created” : file comment list date and time of file creation as well as configuration file name.

“minimal” : short comment only stating the file name and that it was automatically created.

run_from

defines the location of the firmware code when run.

type: string

default: “flash”

Possible values are:

“flash” : firmware is located and run from the flash memory.

“ram” : firmware is located and run from the RAM.

“flash2ram” : firmware is located in flash, copied to RAM on boot and then executed from RAM.

path_prefix

if you use a “hal only” MBSP project located in a sub folder of your project then the name of the sub folder goes here.

type: string

default: “”

clock group

configuration of the used clocks.

"clock": {
"cpu": {
"source" : "hse",
"frequency" : "12 MHz",
}
}

source

defines the source of the clock signal. Supported clock sources are:

“hse” (High speed external)

…

type: enum

default: hse

frequency

defines the frequency that this clock has.

type: string (Hz, kHz, MHz)

default: “1 MHz”

digital_output group

This group contains all digital output signals.

Each signal is a sub group with the signal name as the group name.

"digital_output": {
"green_led": {
"type": "push pull"
"pad": "PA3"
}
}

type

defines what type of output mode should be used. Type can be:

push pull

open drain

type: enum

default: push pull

pad

defines the chip pad that the signal should be output on.

type: string

default: no default possible

invert

If this setting is set to “on” then turning this output “on” will generate a Low (Gnd) signal. Turning it “off” will generate a High (Vcc) level.

If this setting is set to “off” (=default) then turning this output “on” will generate a High (Vcc) signal. Turning it “off” will generate a Low (Gnd) level.

type: string

default: “off”

digital_input group

This group contains all digital input signals.

Each signal is a sub group with the signal name as the group name.

pad

defines the chip pad that the signal should be read from.

type: string

analogue_input (ADC) group

TBD

analogue_output (DAC) group

TBD

Timer group

This group contains all timer and counter peripherals.

"timer": {
"ms_tick": {
"peripheral" : "systick",
"mode" : "count overflows",
"frequency" : "1 kHz",
}
}

peripheral

defines which peripheral to use. peripherals can be:

systick (part of the ARM core)

timer1

timer2

…

type: String

default: systick

mode

defines the operation mode the timer/counte operates in. Possible modes are:

count overflows

type: enum

default: count overflows

frequency

The frequency defines the time between timer overflows. 1kHz means that the time between overflow events is 1/(1 kHz) = 1 ms.

type: string (Hz, kHz, MHz)

default: “1 kHz”

RTC group

TBD

UART group

This group defines all used Universal Asynchronous Receiver Transmitter (UART) interfaces.

Each UART is a sub group with the UART name as the group name.

"UART": {
"debug_uart": {
"pad_tx": "PA5",
"pad_rx": "PA6",
"pad_cts": "PA7",
"pad_rts": "PA15",
"bits_per_packet": "8",
"parity": "None",
"stop_bits": "1",
"baud_rate": "115200",
"hardware_flow_control": "no",
"receive_buffer_size": "100",
"send_buffer_size": "500",
"peripheral" : "UART0",
"IRQ" : "20",
"IRQ_priority" : "0",
}
}

pad_tx

The UART will send data on this pin. (Idle = High). Either this or the pad_rx must be given.

pad_rx

The UART will receive (read) signals on this pin. Either this or pad_rx must be given.

pad_cts

Clear to send signal for flow control. Will not be used if not defined.

pad_rts

Request to Send signal for flow control. Will not be used if not defined.

bits_per_packet

defines the number of data bits. Possible values are:

7

8

9

type: enum

default: 8

parity

defines the parity bit. Possible values are:

None : no parity bit used.

Odd : the parity bits value makes sure that the packet contains an odd number of bits with value “1”.

Even : the parity bits value makes sure that the packet contains an even number of bits with value “1”.

type: enum

default: None

stop_bits

defines the number of stop bits. Possible values are:

1

1,5

2

type: enum

default: 8

baud_rate

defines the number of bits send per second.

type: int

default: 115200

hardware_flow_control

defines if the Request to Send (RTS) and Clear to send (CTS) signals should be used for flow control. Possible values are:

off (RTS and CTS pins are not used.

RTS only

CTS only

on (RTS and CTS signals are used)

type: enum

default: off

receive_buffer_size

defines the number of bytes in the receive buffer of the driver.

type: int

default: 100

send_buffer_size

defines the number of bytes in the send buffer of the driver.

type: int

default: 500

peripheral

name of the UART peripheral to use.

type: String

IRQ

The interrupt number of the peripheral.

type: int

IRQ_priority

The interrupt priority of the interrupt.

type: int

SPI group

This group defines all used Serial Peripheral Interface (SPI) interfaces.

Each SPI interface is a sub group with the SPI name as the group name.

"SPI": {
"encoder_spi": {
"pad_sck": "PA5",
"pad_miso": "PA6",
"pad_mosi": "PA7",
"pad_ncs": "PA15",
"role": "master",
"communication_mode": "duplex",
"frame_format": "motorola",
"clock_polarity": "idle_low",
"clock_phase": "sample_on_leading_edge",
"bit_order": "msb_first",
"baud_rate": "10 MHz",
}
}

pad_sck

Serial Clock.

pad_mosi

“Master Out Slave In” data signal.

pad_miso

“Master In Slave Out” data signal.

pad_ncs

Chip Select signal (Low active).

role

Is either master(host) or slave(device).

type: enum

default: master

communication_mode

Describes the communication. Possible values are:

duplex : the traditional mode using MISO and MOSI to transmit and receive at the same time.

half-duplex : meaning the same wire between master and slave is used for both directions.

receive-only : send line is not used

send-only : receive Line is not used.

type: enum

default: duplex

frame_format

Describes the communication. Possible values are:

motorola : the “normal” SPI.

ti :

type: enum

default: motorola

clock_polarity

Also often called CPOL. Describes the communication. Possible values are:

idle_low

idle_high

type: enum

default: idle_low

clock_phase

Also often called CPHA. Describes the communication. Possible values are:

sample_on_leading_edge : samples the data on the edge from idle value to non-idle value.

sample_on_trailinging_edge : samples the data on the edge from non-idle value to idle value.

type: enum

default: sample_on_leading_edge

SPI Mode

Sometimes the documentation talks about a SPI Mode with the value of 0 to 3. This mode maps to the phase and polarity as described in the following table:

Mode	CPOL	CPHA	description
0	0	0	clock: idle_low, phase: sample_on_leading_edge
1	0	1	clock: idle_low, phase: sample_on_trailing_edge
2	1	0	clock: idle_high, phase: sample_on_leading_edge
3	1	1	clock: idle_high, phase: sample_on_trailing_edge

bit_order

Describes the communication. Possible values are:

msb_first : most significant bit first (bits on the line : 76543210 )

lsb_first : least significant bit first (bits on the line: 01234567 )

type: enum

default: msb_first

baud_rate

Is the number of bits per second exchanged on the data lines. Expressed as frequency of the clock line.

type: int (Hz)