peripheral-driver

Peripheral Driver Development (Adaptation Based on Open-Source Libraries)

Applicable Scenarios

• Need to develop BSP drivers for external devices (AT24C02, MPU6050, SSD1306, etc.).
• Want to find mature open-source driver libraries and adapt them to the project's BSP architecture.
• Already have open-source driver code and need to rename, organize, and inject HAL handles to comply with project specifications.
• The device is relatively simple, does not need an open-source library, and needs generated BSP skeleton files to get started quickly.

Required Inputs

• Target device name (e.g., AT24C02、MPU6050）。
• Communication bus type (I2C / SPI / UART / 1-Wire / GPIO).
• HAL handle name (e.g., hi2c1、hspi2), usually from CubeMX-generated code.
• Optional: device I2C address, path to the downloaded open-source driver directory.

Automatic Detection

• Script --scan mode automatically analyzes C/H files in the input directory, identifying function signatures, HAL call patterns, naming styles, and include dependencies.
• --list-devices mode lists devices and recommended libraries already recorded in device-adaptation.md .
• If the target device is recorded in device-adaptation.md , directly provide the recommended library and adaptation key points.

Execution Steps

1. Confirm the target device and bus type. If the device is recorded in references/device-adaptation.md , directly refer to the recommended library and adaptation key points.
2. Read references/search-and-evaluate.md, and search GitHub/Gitee for candidate open-source driver libraries according to the search strategy.
3. Score the candidate libraries according to the evaluation checklist and select the most suitable library. If there is no suitable library, skip to step 6.
4. Download the selected open-source library code to a local temporary directory.
5. Run --scan to analyze the open-source code and view the adaptation suggestion report:

   python3 scripts/bsp_adapter.py --scan ./downloaded_driver/
   

6. Perform adaptation (choose one of two):
   • Has an open-source library: Run --adapt to adapt the code to the BSP specification:

     python3 scripts/bsp_adapter.py \
       --adapt ./downloaded_driver/ \
       --device <device_name> --handle <hal_handle> \
       --output ./Hardware/bsp_<device>/
     

   • No suitable library: Run --scaffold to generate BSP skeleton files:

     python3 scripts/bsp_adapter.py \
       --scaffold --device <device_name> --bus <bus_type> \
       --handle <hal_handle> --addr <i2c_addr> \
       --output ./Hardware/bsp_<device>/
     

7. Integrate the generated BSP files into the USER CODE area of main.c , referring to the integration guide output by the script.
8. Compile and verify, then hand over to build-* skill。

Driver architecture design and implementation best practices reference stm32-hal-development/references/peripheral-driver-guide.md。

Failure Triage

• When no usable open-source driver library can be found, use --scaffold to generate a skeleton and prompt the user to refer to the datasheet for manual implementation.
• When the open-source library uses bare register operations or non-STM32 platform APIs, return project-config-error, and recommend manually adapting the communication layer.
• When the open-source library's license is GPL or there is no license, remind the user of license risks and recommend finding an alternative library or implementing it themselves.
• When compilation fails after adaptation, hand over to the build-* skill to handle build errors.

Platform Notes

• The built-in script uses the Python standard library (os、re、pathlib、argparse), with no additional dependencies.
• The generated C code follows the STM32 HAL BSP specification and is compatible with GCC, IAR, and Keil toolchains.
• Path format follows platform-compatibility.md。

Output Conventions

• --scan Output adaptation recommendation report: detected functions, HAL calls, naming style, adaptation difficulty assessment.
• --adapt Output the adapted BSP files and main.c integration guide.
• --scaffold Output skeleton files that conform to the BSP template specification.
• --list-devices Output the recommended libraries and adaptation difficulty for the recorded devices.
• For detailed usage of all modes, see references/usage.md。

Handoff relationships

• Upstream:stm32-hal-development(provides methodology and BSP templates).
• Downstream:build-cmake、build-iar、build-keil(compile verification).