NUCLEO-H503RB（stm32h503-st-nucleo）BSP 的 Arduino 生态兼容与引脚排布指南-平芜编程栈

操作系统
嵌入式
物联网
嵌入式OS
RTOS

【免费下载链接】rt-thread

RT-Thread is an open source IoT Real-Time Operating System (RTOS). https://rt-thread.github.io/rt-thread/

项目地址：https://gitcode.com/gh_mirrors/rt/rt-thread

本文围绕 RT-Thread 仓库中bsp/stm32/stm32h503-st-nucleo开发板的 RTduino（RT-Thread Arduino 生态兼容层）适配展开，系统讲解如何在 NUCLEO-H503RB 上开启 Arduino 兼容模式、D0~D15 与 A0~A5 的完整引脚映射关系，以及这些映射在pins_arduino.c/pins_arduino.h源码中的具体实现与底层设备接管逻辑。读完本文，你将能够像写 Arduino 程序一样操作这块 STM32H503 开发板，并直接复用 Arduino 社区的海量传感器、显示与通信库。

1 RTduino：RT-Thread 的 Arduino 生态兼容层

stm32h503-st-nucleoBSP 已完整适配 RTduino 软件包。RTduino 是运行在 RT-Thread 之上的一层 Arduino 兼容封装：它把 RT-Thread 的pin（GPIO）、serial（UART）、adc、pwm、i2c等设备框架接口映射为 Arduino 风格的pinMode()、digitalWrite()、digitalRead()、analogRead()、analogWrite()、Serial2、Wire等 API，同时提供setup()/loop()应用入口，让熟悉 Arduino 的开发者可以零成本迁移到 RT-Thread 平台，并复用 Arduino 社区丰富的第三方库，显著增强 RT-Thread 生态。

这一层的入口代码位于 BSP 的applications/arduino_main.cpp（源码入口），其默认实现即为标准 Arduino 骨架：

#include <Arduino.h> void setup(void) { /* put your setup code here, to run once: */ Serial2.begin(); } void loop(void) { /* put your main code here, to run repeatedly: */ Serial2.println("Hello Arduino!"); delay(800); }

即系统启动后通过Serial2（对应下文引脚表中的 D0/D1）持续输出 "Hello Arduino!"，每 800ms 一次——编译烧录后即可在串口终端直接观察到效果。

1.1 如何开启针对本 BSP 的 Arduino 生态兼容层

开启方式有两种，任选其一：

Env 工具：在 BSP 目录下执行menuconfig；
RT-Thread Studio IDE：在项目资源管理器中双击RT-Thread Settings。

随后按如下路径勾选：

Hardware Drivers Config ---> Onboard Peripheral Drivers ---> [*] Compatible with Arduino Ecosystem (RTduino)

勾选该选项后，BSP 的 board/Kconfig 会自动连锁使能一组配套外设，开发者无需手动逐个配置：

自动使能项	说明
`PKG_USING_RTDUINO`	拉取并编译 RTduino 软件包
`BSP_USING_STLINK_TO_USART`、`BSP_USING_UART1`	板载 ST-LINK 虚拟串口链路与 Arduino Serial2 使用的 uart1
`BSP_USING_GPIO`	数字引脚（pin 设备）
`BSP_USING_ADC`/`BSP_USING_ADC1`	模拟输入 A0~A5 对应的 adc1
`BSP_USING_PWM`/`BSP_USING_PWM1/2/3`及其 CH 通道	D5、D6、D9、D10、D11 对应的 PWM 输出
`RT_USING_I2C`、`BSP_USING_SOFT_I2C`/`SOFT_I2C1`	软件 I2C 总线 swi2c1（Wire 库依赖）
`RTDUINO_USING_WIRE`、`RTDUINO_USING_SERVO`（imply）	Arduino Wire（I2C）与 Servo 功能组件

从构建脚本 applications/arduino_pinout/SConscript 可以看到，引脚映射文件仅在PKG_USING_RTDUINO使能时参与编译；而 applications/SConscript 则进一步通过RTDUINO_NO_SETUP_LOOP开关控制是否编译arduino_main.cpp，即是否启用setup()/loop()入口。

2 Arduino 引脚排布总览

NUCLEO-H503RB 通过板载 Zio/Arduino UNO V3 兼容连接器引出 16 个数字引脚（D0~D15）与 6 个模拟引脚（A0~A5），完整映射定义位于 pins_arduino.c 与 pins_arduino.h。以下表格逐项列出对应关系（GET_PIN(X, y)为 RT-Thread 的引脚编号宏，表示 GPIOX 的第 y 脚）：

Arduino引脚编号	STM32引脚编号	5V容忍	备注
0 (D0)	GET_PIN(B, 15)	是	Serial2-RX，默认被 RT-Thread 的 UART 设备框架 uart1 接管
1 (D1)	GET_PIN(B, 14)	是	Serial2-TX，默认被 RT-Thread 的 UART 设备框架 uart1 接管
2 (D2)	GET_PIN(A, 10)	是
3 (D3)	GET_PIN(B, 3)	是
4 (D4)	GET_PIN(B, 5)	是
5 (D5)	GET_PIN(B, 4)	是	PWM1-CH2，默认被 RT-Thread 的 PWM 设备框架 pwm1 接管
6 (D6)	GET_PIN(B, 10)	是	PWM2-CH3，默认被 RT-Thread 的 PWM 设备框架 pwm2 接管
7 (D7)	GET_PIN(A, 8)	是
8 (D8)	GET_PIN(C, 7)	是
9 (D9)	GET_PIN(C, 6)	是	PWM3-CH1，默认被 RT-Thread 的 PWM 设备框架 pwm3 接管
10 (D10)	GET_PIN(C, 9)	是	PWM3-CH4，默认被 RT-Thread 的 PWM 设备框架 pwm3 接管
11 (D11)	GET_PIN(A, 7)	是	PWM3-CH2，默认被 RT-Thread 的 PWM 设备框架 pwm3 接管
12 (D12)	GET_PIN(A, 6)	是
13 (D13)	GET_PIN(A, 5)	是	板载用户 LED
14 (D14)	GET_PIN(B, 7)	是	I2C1-SDA，默认被 RT-Thread 的 I2C 设备框架 swi2c1 接管
15 (D15)	GET_PIN(B, 6)	是	I2C1-SCL，默认被 RT-Thread 的 I2C 设备框架 swi2c1 接管
16 (A0)	GET_PIN(A, 0)	是	ADC1-CH0，默认被 RT-Thread 的 ADC 设备框架 adc1 接管
17 (A1)	GET_PIN(A, 1)	是	ADC1-CH1，默认被 RT-Thread 的 ADC 设备框架 adc1 接管
18 (A2)	GET_PIN(A, 2)	是	ADC1-CH14，默认被 RT-Thread 的 ADC 设备框架 adc1 接管
19 (A3)	GET_PIN(B, 0)	是	ADC1-CH9，默认被 RT-Thread 的 ADC 设备框架 adc1 接管
20 (A4)	GET_PIN(C, 1)	是	ADC1-CH11，默认被 RT-Thread 的 ADC 设备框架 adc1 接管
21 (A5)	GET_PIN(C, 0)	是	ADC1-CH10，默认被 RT-Thread 的 ADC 设备框架 adc1 接管

注意：
数字引脚与模拟引脚的 Arduino 编号是连续的：D0~D15 依次为 0~15，A0~A5 依次为 16~21，任何情况下都不应打乱该顺序，否则会导致 RTduino 引脚映射错位（详见下文的源码约束）。
所有引出引脚均为 5V 容忍：可直接与 5V 逻辑的 Arduino 模块互连，但板载电平仍为 3.3V，供电与逻辑参考电平请以 3.3V 为准。

3 源码级解读：引脚映射表与设备接管

3.1 引脚编号宏与设备名（pins_arduino.h）

pins_arduino.h 定义了 RTduino 与用户代码共享的关键宏：

#define D0 (0) /* ... D1~D15 依序递增 ... */ #define A0 (16) /* ... A1~A5 依序递增 ... */ #define RTDUINO_PIN_MAX_LIMIT A5 /* pin number max limit check */ #define F_CPU 250000000L /* CPU:250MHz */ #define LED_BUILTIN D13 /* Default Built-in LED */ /* swi2c1 : PB.7-SDA PB.6-SCL */ #define RTDUINO_DEFAULT_IIC_BUS_NAME "swi2c1" /* Serial2(uart1) : PB.14-TX PB.15-RX */ #define RTDUINO_SERIAL2_DEVICE_NAME "uart1"

各宏含义：

D0~D15、A0~A5：Arduino 引脚别名，必须按序定义且不可更改。RTDUINO_PIN_MAX_LIMIT作为引脚合法性检查上限（值为A5，即 21），RTduino 内部会用它与引脚编号做边界校验；
F_CPU：声明 CPU 主频为 250MHz（与 NUCLEO-H503RB 的 STM32H503RB 最高主频一致，详见 README_zh.md），供依赖延时计算（如delayMicroseconds）的 Arduino 库使用；
LED_BUILTIN：指定板载用户 LED 对应 D13（GPIO A5），Arduino 的LED_BUILTIN惯用法由此生效；
RTDUINO_DEFAULT_IIC_BUS_NAME：Wire（I2C）默认总线名。注意本 BSP 使用的是软件 I2C 总线swi2c1（引脚 PB7-SDA / PB6-SCL），而非硬件 I2C；
RTDUINO_SERIAL2_DEVICE_NAME：ArduinoSerial2对象对应的 RT-Thread 串口设备名uart1（PB14-TX / PB15-RX）。

3.2 pin_map_table：引脚映射的核心数据结构（pins_arduino.c）

pins_arduino.c 中的pin_map_table[]是 RTduino 解析引脚功能的唯一事实来源，其条目格式为：

{ Arduino Pin, RT-Thread Pin [, Device Name, Channel] }

其中[]表示可选字段。源码注释明确给出了两条约束：

数字引脚（Digital）严禁携带设备名与通道号——它们只走 GPIO（pin）设备；
模拟/复用引脚（Analog）必须携带设备名与通道号（ADC、PWM 或 DAC），用于把引脚绑定到对应设备实例。

完整映射表如下（与上文引脚总览一一对应）：

const pin_map_t pin_map_table[] = { { D0, GET_PIN(B, 15), "uart1" }, /* Serial-RX */ { D1, GET_PIN(B, 14), "uart1" }, /* Serial-TX */ { D2, GET_PIN(A, 10) }, { D3, GET_PIN(B, 3) }, { D4, GET_PIN(B, 5) }, { D5, GET_PIN(B, 4), "pwm1", 2 }, /* PWM */ { D6, GET_PIN(B, 10), "pwm2", 3 }, /* PWM */ { D7, GET_PIN(A, 8) }, { D8, GET_PIN(C, 7) }, { D9, GET_PIN(C, 6), "pwm3", 1 }, /* PWM */ { D10, GET_PIN(C, 9), "pwm3", 4 }, /* PWM */ { D11, GET_PIN(A, 7), "pwm3", 2 }, /* PWM */ { D12, GET_PIN(A, 6) }, { D13, GET_PIN(A, 5) }, { D14, GET_PIN(B, 7), "swi2c1" }, /* I2C-SDA (Wire) */ { D15, GET_PIN(B, 6), "swi2c1" }, /* I2C-SCL (Wire) */ { A0, GET_PIN(A, 0), "adc1", 0 }, /* ADC */ { A1, GET_PIN(A, 1), "adc1", 1 }, /* ADC */ { A2, GET_PIN(A, 2), "adc1", 14 }, /* ADC */ { A3, GET_PIN(B, 0), "adc1", 9 }, /* ADC */ { A4, GET_PIN(C, 1), "adc1", 11 }, /* ADC */ { A5, GET_PIN(C, 0), "adc1", 10 }, /* ADC */ };

几点值得注意的底层细节：

UART：D0/D1 被绑定到uart1，与 board/Kconfig 中BSP_USING_STLINK_TO_USART+BSP_USING_UART1的自动使能配合，实现即插即用的串口调试与通信。
PWM：D5/D6/D9/D10/D11 分别路由到pwm1-CH2、pwm2-CH3、pwm3-CH1、pwm3-CH4、pwm3-CH2。调用 Arduino 的analogWrite()时，RTduino 会依据该表把占空比写入对应 PWM 设备通道。
I2C（Wire）：D14/D15 绑定到软件 I2C 总线swi2c1，其 SCL/SDA 默认引脚号（22/23）由 board/Kconfig 中的RT_SOFT_I2C1_SCL_PIN_DEFAULT/RT_SOFT_I2C1_SDA_PIN_DEFAULT提供，可在 menuconfig 中调整。
ADC：A0~A5 的 ADC 通道号与 STM32 外设的通道编号并不连续（0、1、14、9、11、10），这是由 STM32H503 的 ADC1 通道复用关系决定的，映射时必须严格照表填写，不能按顺序想当然地递增。

4 使用建议与注意事项

结合上文源码与 BSP 配置，实际使用时请留意以下几点：

引脚编号顺序不可改变：pins_arduino.h中 D/A 别名与pins_arduino.c中pin_map_table[]的条目顺序必须严格对应且连续，否则 RTduino 无法正确解析引脚功能；
被设备框架接管的引脚不能当普通 GPIO 用：如 D0/D1（uart1）、D5/D6/D9/D10/D11（PWM）、D14/D15（swi2c1）、A0~A5（adc1）。若用户代码在setup()中将这些引脚重新pinMode()为普通输出，会与底层设备驱动产生冲突，通常应先通过 RT-Thread 设备接口（rt_device_find等）或关闭相应外设配置后再使用；
板载 LED 与 D13 共用：LED_BUILTIN即 D13（PA5），对 D13 执行digitalWrite(LED_BUILTIN, HIGH/LOW)可直接点亮/熄灭板载用户 LED；
Wire 走软件 I2C：RTDUINO_DEFAULT_IIC_BUS_NAME为swi2c1，速率与稳定性受软件时序影响，对时序敏感的外设建议优先使用硬件 I2C 外设或调整软 I2C 引脚配置；
首次编译前更新软件包：如 BSP README_zh.md 所述，使用前需在 ENV 中执行pkgs --update拉取 HAL 库、CMSIS 库及 RTduino 软件包，否则编译无法通过；
引脚表为只读事实来源：如需增删或改接引脚，应同步修改pin_map_table[]与pins_arduino.h中的别名宏、RTDUINO_PIN_MAX_LIMIT，并保持两文件一致，改动后重新执行scons构建。

5 小结

本文完整梳理了 NUCLEO-H503RB（stm32h503-st-nucleo）BSP 的 RTduino Arduino 生态兼容能力：通过 board/Kconfig 一键开启兼容层，即可获得 D0~D15、A0~A5 共 22 个标准 Arduino 引脚，其中 UART（uart1）、PWM（pwm1/2/3）、软件 I2C（swi2c1）、ADC（adc1）均已被底层设备框架自动接管，映射实现在 pins_arduino.c 与 pins_arduino.h 中。在此基础上，开发者可以像使用 Arduino UNO 一样编写setup()/loop()程序并复用 Arduino 社区库，快速构建基于 RT-Thread 的 IoT 原型与产品。