YAML Conventions and Syntax
This section covers the additional conventions BMGR defines on top of standard YAML: fill-in markers, enumeration syntax, the ${BOARD_PATH} variable, and anchor/merge syntax. All three board-level YAML files follow these conventions.
The [IO] Marker
When a field comment includes [IO], the field corresponds to a real hardware pin and must be filled in according to the actual schematic; do not copy example values or template defaults (typically -1).
- name: i2c_main
type: i2c
config:
sda_io_num: 10 # [IO]
scl_io_num: 11 # [IO]
The [TO_BE_CONFIRMED] Marker
When a field comment includes [TO_BE_CONFIRMED], the current value is a placeholder or generic default; each such field must be confirmed and replaced with the actual value when adapting for a specific board. Common examples include screen resolution, timing parameters, voltage levels, and I2C addresses—fields that require consulting the component datasheet.
Enumeration Values
Enumeration fields in YAML use the exact enumeration name from the ESP-IDF driver or related component header files; do not use custom strings or numeric substitutes. For example, the GPIO direction field should be GPIO_MODE_OUTPUT, not 1 or "output"; the MIPI DPI clock source should be MIPI_DSI_DPI_CLK_SRC_DEFAULT, not a numeric value or abbreviation. The generator outputs the string as-is into C source code; a misspelled enumeration name will be caught at compile time.
The ${BOARD_PATH} Variable
${BOARD_PATH} in board YAML refers to the root directory of the current board definition (the directory containing board_devices.yaml). When referencing local components under the board directory, use this variable instead of hardcoding a relative path. gen_bmgr_codes/idf_component.yml is generated by BMGR and expands relative paths relative to that directory, which is error-prone. ${BOARD_PATH} is substituted uniformly by BMGR during generation, giving it stable semantics when written in board YAML:
dependencies:
my_company/my_driver:
version: "*"
override_path: ${BOARD_PATH}/packages/my_driver
Note
Only the ${BOARD_PATH} form is recognized. Variants such as {{BOARD_PATH}} or $BOARD_PATH are not substituted.
YAML Anchors and Merge (Standard YAML)
BMGR does not restrict YAML parsing behavior, so standard syntax such as & anchors, * aliases, and <<: merge keys can be used directly; they are commonly used to eliminate duplicate configuration for peripherals of the same type:
peripherals:
- name: spi_lcd
type: spi
version: "1.0.0"
role: master
config: &spi_master_default
mosi_io_num: 11 # [IO]
miso_io_num: -1 # Not needed for write-only devices
sclk_io_num: 12 # [IO]
max_transfer_sz: 32768
- name: spi_touch
type: spi
version: "1.0.0"
role: master
config:
<<: *spi_master_default
mosi_io_num: 35 # [IO]
sclk_io_num: 36 # [IO]
Semantic Peripheral Bindings
Device entries reference peripherals by semantic role. Use the role-specific *_name field that matches the device parser, instead of relying on the peripheral name prefix or list order:
devices:
- name: display_lcd
type: display_lcd
sub_type: spi
peripherals:
- spi_name: spi_lcd
The supported selector is determined by the device type and sub-type. Examples include pa_name and reset_name for codec GPIOs, i2c_name for I2C control buses, spi_name for SPI buses, dsi_name and ldo_name for DSI displays, and gpio_name for GPIO control lines. Each peripheral entry must contain at most one role-specific selector.
Legacy string references and mappings that contain only name remain accepted for compatibility. BMGR infers the role from the device context and emits a warning. An unknown selector, a duplicate role, a reference that combines name with *_name, or a referenced peripheral with the wrong type is rejected during parsing.