peripheral-driver

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

外设驱动开发（基于开源库适配）

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

适用场景

Applicable Scenarios

需要为外部设备（AT24C02、MPU6050、SSD1306 等）开发 BSP 驱动。
想找到成熟的开源驱动库并适配到项目的 BSP 架构中。
已有开源驱动代码，需要重命名、整理、注入 HAL handle 以符合项目规范。
设备较简单，不需要开源库，需要生成 BSP 骨架文件快速起步。

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.
Have existing open-source driver code that needs renaming, organizing, and HAL handle injection to comply with project specifications.
The device is relatively simple, no open-source library is needed, and BSP skeleton files need to be generated to get started quickly.

必要输入

Required Inputs

目标设备名称（如
```
AT24C02
```
、
```
MPU6050
```
）。
通信总线类型（I2C / SPI / UART / 1-Wire / GPIO）。
HAL handle 名称（如
```
hi2c1
```
、
```
hspi2
```
），通常来自 CubeMX 生成的代码。
可选：设备 I2C 地址、已下载的开源驱动目录路径。

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

自动探测

Automatic Detection

脚本
```
--scan
```
模式自动分析输入目录中的 C/H 文件，识别函数签名、HAL 调用模式、命名风格和 include 依赖。
```
--list-devices
```
模式列出
```
device-adaptation.md
```
中已记录的设备和推荐库。
如果目标设备在
```
device-adaptation.md
```
中有记录，直接提供推荐库和适配要点。

The script's
```
--scan
```
mode automatically analyzes C/H files in the input directory to identify function signatures, HAL call patterns, naming conventions, and include dependencies.
The
```
--list-devices
```
mode lists the devices recorded in
```
device-adaptation.md
```
and recommended libraries.
If the target device is recorded in
```
device-adaptation.md
```
, directly provide the recommended library and adaptation key points.

执行步骤

Execution Steps

确认目标设备和总线类型。如果设备在 references/device-adaptation.md 中有记录，直接参考推荐库和适配要点。
阅读 references/search-and-evaluate.md，按搜索策略在 GitHub/Gitee 上寻找候选开源驱动库。
按评估清单对候选库打分，选择最合适的库。如果没有合适的库，跳到步骤 6。
下载选定的开源库代码到本地临时目录。

运行

--scan

分析开源代码，查看适配建议报告：

bash

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

执行适配（二选一）：

有开源库：运行

--adapt

将代码适配到 BSP 规范：

bash

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

无合适库：运行

--scaffold

生成 BSP 骨架文件：

bash

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

将生成的 BSP 文件集成到
```
main.c
```
的 USER CODE 区域，参考脚本输出的集成指南。
编译验证，交给
```
build-*
```
skill。

驱动架构设计和实现最佳实践参考 stm32-hal-development/references/peripheral-driver-guide.md。

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.
Read references/search-and-evaluate.md, and search for candidate open-source driver libraries on GitHub/Gitee according to the search strategy.
Score the candidate libraries according to the evaluation checklist and select the most suitable one. If no suitable library is found, skip to step 6.
Download the selected open-source library code to a local temporary directory.
Run
```
--scan
```
to analyze the open-source code and view the adaptation suggestion report:
bash
```
python3 scripts/bsp_adapter.py --scan ./downloaded_driver/
```

Perform adaptation (choose one of the two):

With open-source library: Run

--adapt

to adapt the code to BSP specifications:

bash

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:

bash

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

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

For best practices in driver architecture design and implementation, refer to stm32-hal-development/references/peripheral-driver-guide.md.

失败分流

Failure Diversion

当搜索不到任何可用的开源驱动库时，使用
```
--scaffold
```
生成骨架并提示用户参考规格书手动实现。
当开源库使用裸寄存器操作或非 STM32 平台 API 时，返回
```
project-config-error
```
，建议手动适配通信层。
当开源库许可证为 GPL 或无许可证时，提醒用户许可证风险，建议寻找替代库或自行实现。
当适配后编译失败时，交给
```
build-*
```
skill 处理构建错误。

When no available open-source driver libraries can be found, use
```
--scaffold
```
to generate a skeleton and prompt the user to manually implement it by referring to the specification sheet.
When the open-source library uses bare register operations or non-STM32 platform APIs, return
```
project-config-error
```
and suggest manually adapting the communication layer.
When the open-source library has a GPL license or no license, remind the user of license risks and suggest finding an alternative library or implementing it independently.
When compilation fails after adaptation, hand it over to the
```
build-*
```
skill to handle build errors.

平台说明

Platform Description

自带脚本使用 Python 标准库（
```
os
```
、
```
re
```
、
```
pathlib
```
、
```
argparse
```
），无额外依赖。
生成的 C 代码遵循 STM32 HAL BSP 规范，兼容 GCC、IAR、Keil 工具链。
路径格式遵循 platform-compatibility.md。

The built-in script uses Python standard libraries (
```
os
```
,
```
re
```
,
```
pathlib
```
,
```
argparse
```
) with no additional dependencies.
The generated C code complies with STM32 HAL BSP specifications and is compatible with GCC, IAR, and Keil toolchains.
Path formats follow platform-compatibility.md.

输出约定

Output Conventions

```
--scan
```
输出适配建议报告：检测到的函数、HAL 调用、命名风格、适配难度评估。
```
--adapt
```
输出适配后的 BSP 文件和
```
main.c
```
集成指南。
```
--scaffold
```
输出符合 BSP 模板规范的骨架文件。
```
--list-devices
```
输出已记录设备的推荐库和适配难度。
所有模式的详细用法见 references/usage.md。

```
--scan
```
outputs an adaptation suggestion report: detected functions, HAL calls, naming conventions, and adaptation difficulty assessment.
```
--adapt
```
outputs the adapted BSP files and
```
main.c
```
integration guide.
```
--scaffold
```
outputs skeleton files that comply with BSP template specifications.
```
--list-devices
```
outputs the recommended libraries and adaptation difficulty for recorded devices.
Detailed usage of all modes can be found in references/usage.md.

交接关系

Handover Relationships

上游：
```
stm32-hal-development
```
（提供方法论和 BSP 模板）。
下游：
```
build-cmake
```
、
```
build-iar
```
、
```
build-keil
```
（编译验证）。

Upstream:
```
stm32-hal-development
```
(provides methodology and BSP templates).
Downstream:
```
build-cmake
```
,
```
build-iar
```
,
```
build-keil
```
(compilation and verification).