基于 Arduino_Core_STM32 的 Nucleo L476RG 板载 Blink 点亮实战

基于 Arduino_Core_STM32 的 Nucleo L476RG 板载 Blink 点亮实战

本指南以 STM32duino 官方文档 Blink-example.md 为核心，完整讲解如何在一台 Nucleo L476RG 开发板上，使用 Arduino IDE 2 运行并烧录 Arduino 内置的 Blink 示例：从环境准备、板卡选择、编译上传，到现象验证与故障排查，一条龙跑通「STM32 核心 + ST-Link 烧录 + 板载 LED 闪烁」的完整闭环。读完本文，你将掌握 STM32 核心（Arduino_Core_STM32）在 Arduino IDE 2 下的标准上手流程，并理解 LED_BUILTIN 是如何由板卡 variant 文件自动映射到真实 GPIO 引脚的。

Blink 示例是什么

Blink 是 Arduino 世界最经典的入门示例，不需要任何额外库即可运行。其核心逻辑非常简单：在 setup() 中把板载 LED 引脚配置为输出，在 loop() 中让 LED 以 1 秒周期交替点亮、熄灭：

// Arduino 内置示例 01.Basics > Blink
void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH);   // 点亮 LED
  delay(1000);                       // 等待 1 秒
  digitalWrite(LED_BUILTIN, LOW);    // 熄灭 LED
  delay(1000);                       // 等待 1 秒
}

代码中使用的是 LED_BUILTIN 宏，而不是某个写死的 GPIO 编号。这正是 Arduino 生态的「板卡抽象」设计：不同板卡的 LED 引脚由各自的 variant（板卡变体定义）文件决定，用户编写跨板可移植的通用代码。

在 Arduino_Core_STM32 中，这个抽象由两层完成：

1. LED_BUILTIN 在板卡 variant 头文件中定义。以 Nucleo L476RG 为例，variant_NUCLEO_L476RG.hT_L476R(C-E-G)T_L486RGT/variant_NUCLEO_L476RG.h#L127-L131) 中写着：

// On-board LED pin number
#ifndef LED_BUILTIN
  #define LED_BUILTIN             PA5
#endif
#define LED_GREEN               LED_BUILTIN

即 Nucleo L476RG 的板载用户 LED（绿色）被定义在 PA5 引脚上，同时它也被别名命名为 LED_GREEN。

2. 核心层通过 digitalPinToPinName()、pinMode()、digitalWrite() 等 API 把 Arduino 数字引脚号转换为真实的 GPIO 端口与引脚并操作底层寄存器。相关实现可查看 cores/arduino/pins_arduino.h 与 cores/arduino/wiring_digital.c。

如果某个板卡的 variant 没有定义 LED（例如许多通用核心板），LED_BUILTIN 会被回退为 PNUM_NOT_DEFINED（见 variant_generic.hT_L476R(C-E-G)T_L486RGT/variant_generic.h#L122-L123)），此时使用 LED_BUILTIN 的示例将无法点亮任何 LED，这也正是选择正确板卡型号的意义所在。

前提条件（Prerequisites）

动手之前，请确认满足以下条件：

• 一块 Nucleo L476RG 开发板（ST 官方评估板，板载 ST-LINK 调试器与一颗用户 LED）；
• 安装了 STM32 核心（Arduino_Core_STM32） 的 Arduino IDE 2；
• 一根 USB 数据线，连接到开发板的 ST-LINK USB 接口（Nucleo-64 板上的 USB 口通常标记为与 ST-LINK 对应，注意不要误插到仅供电的副 USB 口）。

[!WARNING] 自核心版本 2.8.0 起，本核心仅支持 Arduino IDE 2。如需使用 Legacy IDE（1.8.X），请参考 Getting Started_V1。

如果 STM32 核心尚未安装，请先按 Getting Started 的步骤完成安装，核心步骤如下：

1. 打开 Arduino IDE 2，进入 File > Preferences，在 "Additional Boards Managers URLs" 中填入 STM32 官方 Board Manager 索引地址（由 BoardManagerFiles 提供）；
2. 打开 Tools > Board > Boards Manager，筛选 "Contributed" 类型，找到 STM32 MCU based boards 并点击 Install；
3. 安装完成后，在 Tools > Board 菜单中即可看到 STM32 boards 系列选项（Nucleo-64 / Nucleo-144 / Discovery 等）。

选择板卡型号

第一步：连接开发板

用 USB 数据线将 Nucleo L476RG 的 ST-LINK USB 接口连接到电脑。Windows 下会安装对应驱动并枚举出一个调试口与一个虚拟串口；Linux 下通常表现为 /dev/ttyACM0 之类的设备节点。

第二步：配置 Board、Board part number 与 Port

在 Arduino IDE 2 中依次完成三处关键选择：

1. Tools > Board，选择 STM32 boards，然后选择 Nucleo-64；
2. Tools > Board part number，选择 Nucleo L476RG；
3. Tools > Port，选择由开发板提供的端口（即 ST-LINK 枚举出的端口）。

截图与更详细的界面说明可参见 Getting Started 的 Configuring IDE 小节。

这里特别强调 Board part number 的重要性：它决定了核心为该板卡加载哪一份 variant 与编译配置。在 boards.txt 中，NUCLEO_L476RG 条目被映射为：

Nucleo_64.menu.pnum.NUCLEO_L476RG=Nucleo L476RG
Nucleo_64.menu.pnum.NUCLEO_L476RG.build.mcu=cortex-m4
Nucleo_64.menu.pnum.NUCLEO_L476RG.build.fpu=-mfpu=fpv4-sp-d16
Nucleo_64.menu.pnum.NUCLEO_L476RG.build.float-abi=-mfloat-abi=hard
Nucleo_64.menu.pnum.NUCLEO_L476RG.build.series=STM32L4xx
Nucleo_64.menu.pnum.NUCLEO_L476RG.build.product_line=STM32L476xx
Nucleo_64.menu.pnum.NUCLEO_L476RG.build.variant=STM32L4xx/L475R(C-E-G)T_L476R(C-E-G)T_L486RGT

可以看到，Nucleo L476RG 使用 Cortex-M4 核心、单精度 FPU 硬浮点，编译目标系列为 STM32L4xx，variant 指向 STM32L4xx/L475R(C-E-G)T_L476R(C-E-G)T_L486RGT 目录。而正是这个 variant 目录下的 variant_NUCLEO_L476RG.hT_L476R(C-E-G)T_L486RGT/variant_NUCLEO_L476RG.h) 定义了 LED_BUILTIN = PA5、USER_BTN = PC13、串口实例等板卡专属信息。选错型号（例如选成没有 LED 定义的通用核心板）就可能出现「烧录成功但 LED 不亮」的现象。

打开示例并上传

打开内置 Blink 示例

Arduino 内置的 Blink 示例位于：

File > Examples > 01.Basics > Blink

它是 IDE 自带的内置示例，无需任何第三方库。需要说明的是，STM32duino 社区还提供了更丰富的 STM32 专用示例库 STM32duino Examples（按板卡、通信、外设与基准测试分组），安装方式与示例清单见 Examples，但本文使用的 Blink 不需要安装它。

编译与上传

1. 点击 Verify（勾号图标）编译 sketch，确认代码与板卡配置无误；
2. 点击 Upload（右箭头图标）将固件烧录到开发板。

如果点击 Upload 后仍报错或无法下载，可进一步在 Tools > Upload Method 中切换烧录方式，常见方式详见 Upload methods。

上传方法背后的机制（源码视角）

Nucleo-64 板卡集成了 ST-LINK，其默认上传路径在 platform.txt 中定义：

• Mass Storage（拖放式烧录）：ST 官方板（Nucleo / Discovery / Eval）的 ST-LINK 会虚拟出一个 U 盘，把编译生成的二进制文件（如 build/<sketch>.bin）拖进该虚拟磁盘即可完成编程，烧录后二进制文件会从虚拟磁盘消失，见 Upload methods 的 Mass Storage 小节；
• STM32CubeProgrammer（SWD/Serial/DFU/J-Link）：通过 tools.stm32CubeProg.upload.pattern（见 platform.txt）调用 stm32CubeProg.sh 脚本，依据 {upload.protocol} 选择 swd、jlink、serial 或 dfu 接口，并把固件写入 {upload.address}（默认 0x8000000，见 platform.txt）。

在 platform.txt 中可见：

tools.stm32CubeProg.upload.pattern="{busybox}" sh "{path}/{cmd}" -i {upload.protocol} -b "{build.path}/{build.project_name}.bin" -o {build.flash_offset} {upload.options}

{upload.options} 用于传递额外参数，例如 SWD 烧录后的复位选项 -rst、串口烧录时的 {serial.port.file} -s 等。使用这些方式前需要单独安装 STM32CubeProgrammer 并确保其可执行文件位于 PATH 中。

预期结果（Expected result）

上传成功后，Nucleo L476RG 板载的用户 LED 会每秒闪烁一次（亮 1 秒、灭 1 秒）。因为 sketch 使用了 LED_BUILTIN，LED 引脚由板卡 variant 自动选定，也就是前面提到的 PA5。

从核心源码看，这一现象背后的执行链路是：

• cores/arduino/main.cpp 中，Arduino 运行时先调用一次 setup()，随后无限循环调用 loop()；
• pinMode(LED_BUILTIN, OUTPUT) 通过 digitalPinToPinName() 把 PA5 解析为真实引脚后配置为推挽输出；
• digitalWrite() 与 delay(1000) 交替驱动引脚电平，配合 1 秒延时形成周期闪烁。

故障排查（Troubleshooting）

按以下清单逐项检查，绝大多数问题都能定位：

• 上传失败：核对是否选对了 Board（Nucleo-64）、Board part number（Nucleo L476RG）与 Port；确认 USB 数据线不是「仅充电线」；必要时切换 Upload methods 中其他烧录方式。
• 找不到端口（Port 列表为空）：重新拔插开发板；确认 USB 线确实连接在 ST-LINK 接口上（而不是其他仅供电口）；Windows 下可检查设备管理器中 ST-LINK 的驱动是否正常。
• 上传成功但 LED 不亮：按一下开发板的 Reset 复位按键重新运行程序；再次确认 Tools > Board part number 选中的是 Nucleo L476RG —— 如果误选了无 LED 定义的型号，LED_BUILTIN 将无法正确映射到 PA5，Blink 自然不亮。

此外，若烧录涉及 SWD（ST-Link）、Serial 或 DFU 等 STM32CubeProgrammer 路径，请先确认该工具已安装且路径被正确配置（Linux 下还需要注意 Arduino IDE 启动环境是否继承了 PATH，详见 Upload methods 的 STM32CubeProgrammer 小节）。

下一步可以做什么

点亮板载 LED 只是 STM32duino 之旅的起点。跑通本文流程后，你可以：

• 前往 Examples 安装 STM32duino Examples 库，体验 STM32 专属的通信、外设与基准测试示例；
• 阅读 Getting Started 完整掌握 STM32 核心的安装与 IDE 配置；
• 参考 Upload methods 了解 SWD、Serial、DFU、J-Link、HID Bootloader、Maple DFU 等全谱系烧录方案，适配更多不带 ST-LINK 的通用核心板；
• 如果想为其他 STM32 板卡复用这段经验，只需在 Arduino IDE 中更换 Board part number，核心会自动加载对应的 variant 定义，LED_BUILTIN 的映射逻辑完全一致。