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]

Was this page helpful?