Here is the complete, high-quality English translation of your technical article. The tone is kept highly professional, precise, and scannable, matching the style of advanced embedded systems and drone development documentation.

Integrating KiCad and hwdef: A Practical Development Flow for Linking PCB Design Data and ArduPilot’s hwdef.dat

In the previous article, we explained the practical calculations involved in impedance design. In this article (FC40), we will focus on the integration between KiCad and hwdef.dat.

As the final installment of the PCB Design series, we will discuss how to bridge the PCB design knowledge covered so far (FC21 to FC39) with the ArduPilot board definitions using hwdef.dat introduced in FC5, framing it as a practical, real-world development workflow.

The Issue of Disconnect Between PCB Design and Firmware Definitions

In custom Flight Controller (FC) development, hardware design (schematic captured and PCB laid out in KiCad) and firmware configuration (pin definitions in hwdef.dat) are carried out using separate tools and entirely different file formats.

A typical problem caused by this disconnect is inconsistency: changes made in the PCB design are not reflected in hwdef.dat, or vice versa. For example, if a PCB designer changes the Chip Select (CS) pin of an SPI bus from PC2 to PC3 but forgets to manually update this change in hwdef.dat, the firmware will run assuming the old pinout. As a result, the IMU will fail to be recognized.

This article explains a practical workflow to minimize this disconnect and streamline—or even semi-automate—the conversion process from PCB design data to hwdef.dat.

Mapping Between KiCad Netlists and hwdef.dat

Let's clarify how KiCad's schematic/PCB design data maps directly to the syntax inside hwdef.dat.

Pin Names vs. Net Names

The net name (e.g., SPI1_SCK) connected to an MCU pin (e.g., PA5) in the KiCad schematic corresponds directly to a pin definition line in hwdef.dat:

PA5 SPI1_SCK SPI1

This line essentially describes the exact same information found on the KiCad schematic—"Pin PA5 has the net name SPI1_SCK and functions as SPI1"—just written in a different format.

Device Connections

Consider the SPI device definition for an IMU (as explained in FC6):

SPIDEV icm42688 SPI1 DEVID1 ICM42688_CS CS SPEED_4MHZ MODE3

The corresponding information in the KiCad schematic represents the actual connectivity: which GPIO pin the ICM-42688-P's CS pin connects to, and which physical SPI peripheral instance the SPI bus belongs to.

By understanding this mapping, we can devise an approach to semi-automate the conversion from PCB design to hwdef.dat.

Extracting Netlists from KiCad

KiCad allows you to export netlists from design data in various formats, which can serve as an excellent starting point for generating hwdef.dat.

• Standard Netlist Export: The netlist export feature in KiCad (Tools > Generate Netlist) typically outputs in SPICE or KiCad-native formats. Because these formats are not easily human-readable, additional processing is required to convert them directly into hwdef.dat.
• BOM (Bill of Materials) Integration: By combining netlist data with a BOM export, you can extract the reference designators (e.g., U1, U2) of specific ICs along with their connected pin data in a structured format like CSV.
• Conversion via Custom Scripts: This approach utilizes KiCad’s Python API (the pcbnew module) to generate hwdef.dat-formatted text directly from the PCB design files. While full automation can be complex, automating just the pin definition segment (MCU GPIO assignments) drastically reduces manual human error.

Below is a conceptual example of a simple Python script for this purpose:

Python

import pcbnew

board = pcbnew.LoadBoard("my_fc.kicad_pcb")
for footprint in board.GetFootprints():
if "STM32H743" in footprint.GetReference():
for pad in footprint.Pads():
net_name = pad.GetNetname()
pin_name = pad.GetPadName()
print(f"{pin_name} {net_name}")

A semi-automated workflow—where the output of such a script is manually cleaned up and formatted into hwdef.dat syntax—is widely adopted as a highly realistic and reliable development process.

Design Change Management: Syncing PCB Modifications with hwdef.dat

Here are practical management strategies to ensure that PCB design changes made during development are reliably propagated to hwdef.dat.

• Centralized Change Tracking: Manage both the KiCad project and hwdef.dat within the same Git repository. Ensure that PCB design updates and corresponding hwdef.dat modifications are logged within the same commit or linked pull requests. This guarantees full traceability.
• Pinout Tables as Intermediate Documentation: A highly practical approach is maintaining an intermediate document—such as a spreadsheet or a Markdown table—that documents the pinouts extracted manually or via scripts from the KiCad schematic. This document serves as the "single source of truth" shared between hardware and firmware engineers. Whenever a change occurs, this document is updated first before modifying the respective files.
• Integration into the Review Process: Add a specific checklist item to the design review process (explained in FC30): "Have all PCB changes been correctly reflected in hwdef.dat?" Pay extra attention to changes that directly impact critical functionality, such as CS pins, interrupt pins, and SPI/I2C bus assignments.

Verifying hwdef.dat via SITL Integration

Let's look at practical methods for leveraging SITL (covered in FC20) to validate changes made to hwdef.dat.

• Build Verification: Once hwdef.dat is updated following a PCB modification, the first step is to check if it compiles successfully in the SITL environment (or during an actual target board build). While basic, this step is vital. Pin collisions (e.g., mistakenly assigning multiple functions to the same pin) are usually caught as compilation errors.
• Logical Connectivity Validation: ArduPilot features mechanisms to parse the hwdef.dat syntax and verify whether defined peripherals (IMUs, barometers, GNSS, etc.) are recognized properly. By pairing this with SITL configurations that simulate these devices, you can validate the logical correctness of hwdef.dat to a high degree without physical hardware.
• Division of Labor with Physical Testing: SITL validation proves whether the hwdef.dat description is grammatically and logically sound. However, electrical validation (Signal Integrity (SI) perspectives, such as the impedance and noise impacts discussed throughout this series)—like whether the IMU can actually communicate over that SPI configuration—ultimately requires physical hardware testing. The "limitations of SITL" discussed in FC20 apply here as well.

Documentation Architecture for Custom FC Development

To maintain reliability in custom FC development projects, a structured documentation ecosystem should be maintained:

Document TypeRole in the EcosystemSchematics (KiCad Schematic)The primary source of truth defining electrical connections.PCB Design Data (KiCad PCB)The secondary source containing physical layouts, routing, stackups, and component placement (FC21–FC39).Pinout Table (Intermediate Doc)Functions as the bridge between the schematic and hwdef.dat.hwdef.dat (Firmware Config)The final configuration file enabling ArduPilot to recognize the hardware (FC5).Datasheets & App Notes CollectionA reference library organizing datasheets for selected components (STM32H7, ICM-42688-P, DC-DC converters, etc.) and application notes that justify design decisions.Design Review ChecklistsA structured framework outlining verification points for each design phase (FC27, FC30).

Establishing a pipeline where these documents are updated in lockstep forms the foundation of highly reliable custom FC development.

Example Team Development Workflow

Here is how a practical workflow looks during multi-engineer custom FC development:

1. Hardware Engineering Phase: The hardware engineer handles circuit and PCB design in KiCad (applying knowledge from FC21 to FC39) and updates the centralized pinout table upon design freeze.
2. Firmware Engineering Phase: The firmware engineer uses the pinout table to draft or update hwdef.dat and validates it via an SITL build check.
3. Integration Testing Phase: Once the prototype PCB arrives, the firmware is flashed onto the target board (following the bootloader workflow detailed in FC5) to verify that all sensors and communication interfaces function correctly.
4. Feedback Loop on Failure: If an issue arises during hardware testing (e.g., the IMU is not detected), the team isolates whether it stems from a hwdef.dat typo or a physical PCB flaw. The cause is pinpointed by cross-referencing the pinout table, reviewing the schematics, and probing continuity with a multimeter. Corrective measures are then applied either to the PCB layout (for the next prototype revision) or to hwdef.dat (if software-side mitigation is possible).

Practical Troubleshooting: Common Inconsistency Patterns

Below are typical patterns where mismatches between PCB designs and hwdef.dat frequently occur:

• Pin Label Mismatch: The most elementary error. This happens when a developer confuses the physical package pin numbers from the MCU datasheet with the logical GPIO names (e.g., misidentifying a pin number as PA5).
• SPI Mode Mismatches: This issue is easily overlooked during the layout phase. If the MODE parameter (SPI clock polarity and phase settings) is incorrectly specified in the hwdef.dat SPIDEV line, communication will fail entirely despite the physical traces being perfectly routed. This parameter must always be double-checked against the sensor's datasheet.
• Missing Pull-Up/Pull-Down Configurations: A frequent issue with I2C buses. If physical pull-up resistors are omitted from the PCB layout, it can sometimes be partially salvaged by enabling the MCU’s internal pull-ups via software (PULLUP flag in hwdef.dat). However, fundamentally, this should be caught and resolved during the PCB design phase.
• Clock Settings vs. Peripheral Speed Mismatches: This relates closely to the MCU clock design covered in FC3 and FC4. You must verify that the SPI speed specified in hwdef.dat (e.g., SPEED_4MHZ) does not exceed the sensor’s maximum rated speed, and that it remains reasonable considering trace lengths and transmission line effects (FC25, FC38).

Conclusion

PCB design in KiCad and ArduPilot’s hwdef.dat are fundamentally two sides of the same coin—they express identical hardware connection data in different formats. Establishing a strict synchronization process using an intermediate pinout table is vital for both development efficiency and system reliability. By combining semi-automation via KiCad’s Python API, centralized change tracking via Git, and early validation through SITL (FC20), you can minimize the risks of hardware-firmware misalignment.

This concludes our PCB Design series (FC31 to FC40). Across five sub-series—Fundamentals, Sensors, Navigation, Hardware Design, and PCB Design—we have systematically mapped out the entire landscape of custom flight controller development: from control theory and sensor circuitry to power/ground styling, high-speed signal PCB routing, and final firmware integration.