MAVLINKHUD

Board Configuration (hwdef)

Executive Summary

Unlike traditional ChibiOS applications that manually edit board.h and mcuconf.h, ArduPilot uses a Python-based generator: chibios_hwdef.py. This script reads a high-level description file (hwdef.dat) and auto-generates the low-level C headers required by ChibiOS.

This system allows ArduPilot to support hundreds of boards with a single codebase, simply by defining the pinout in a text file.

Theory & Concepts

1. The hwdef.dat Format

The hardware definition file maps STM32 pins to ArduPilot functions.

  • Format: PinName Function Label [Flags]
  • Example: PA9 USART1_TX TELEM1
    • Pin: PA9
    • Function: USART1_TX (The script looks up the Alternate Function index automatically).
    • Label: TELEM1 (Used in code as HAL_GPIO_PIN_TELEM1).

2. Auto-Generation Pipeline

  1. Input: libraries/AP_HAL_ChibiOS/hwdef/CubeOrange/hwdef.dat
  2. Processor: chibios_hwdef.py
  3. Outputs (in build directory):
    • board.h: ChibiOS pin mode definitions (PAL_MODE_ALTERNATE(7)).
    • mcuconf.h: Enables/Disables peripherals (#define STM32_SERIAL_USE_USART1 TRUE).
    • hwdef.h: ArduPilot-specific macros (HAL_SERIAL0_CONFIG).

Codebase Investigation

1. The Parser: chibios_hwdef.py

Located in libraries/AP_HAL_ChibiOS/hwdef/scripts/.

  • ChibiOSHWDef Class: Stores the pin map.
  • write_UART_config(): Iterates through SERIAL_ORDER and generates the HAL_SERIALx_CONFIG structs used by UARTDriver.cpp.
  • Automatic DMA: The script calculates DMA stream/channel assignments to minimize contention. If two enabled drivers use the same stream, it errors out or tries to find an alternative stream.

2. Driver Activation

If you define PA9 USART1_TX in hwdef.dat, the script automatically:

  1. Sets STM32_SERIAL_USE_USART1 to TRUE in mcuconf.h.
  2. Allocates RX/TX DMA streams.
  3. Generates the GPIO init code in board.h.

Source Code Reference

Practical Guide: Adding a Custom Board

To support a new flight controller:

  1. Copy an existing directory (e.g., MatekH743) to a new name.
  2. Edit hwdef.dat:
    • Update MCU, FLASH_SIZE_KB.
    • Map pins for UARTs, SPI, I2C.
    • Define SERIAL_ORDER (UART1, UART2, ...).
  3. Build: ./waf configure --board MyNewBoard
    • Tip: If the build fails with "DMA Contention", try swapping UARTs or disabling DMA on slow ports (NODMA).