~~ODT~~

====== File format specification of configuration definition ======

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

{{odt>toc:leader_sign=.;indents=0,0.5,1;}}

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 =====

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

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.


===== All the Settings =====
  * [[adc_group            | analogue_input (ADC) group]]
  * [[dac_group            | analogue_output (DAC) group]]
  * [[clock_group          | clock group]]
  * [[digital_output_group | digital_output group]]
  * [[digital_input_group  | digital_input group]]
  * [[general_settings     | general settings]]
  * [[I2C_group            | Inter-Integrated Circuit (I2C) group]]
  * [[QSPI_group           | QSPI group]]
  * [[rtc_group            | Real Time Clock group]]
  * [[SPI_group            | SPI group]]
  * [[timer_group          | Timer group]]
  * [[UART_group           | UART group]]
  * [[watchdog_group       | watchdog group]]