基础任务一:开发环境搭建、LED 控制与串口输出
工程:basic_task_01
平台:NUCLEO-H533RE / Zephyr RTOS
1. 任务目标与实际完成范围
基础任务一要求搭建 ST 开发板开发环境,实现声音、灯光基本控制,并输出串口信息。
本项目没有购买蜂鸣器,当前硬件不支持声音输出。因此,本任务实际范围确定为开发环境搭建、LED 控制、按键交互及串口日志,声音控制不纳入本次实现和验收。
项目本次实现
| 开发环境 | 使用 Zephyr 工程、设备树 overlay、CMake 和 Kconfig 组织应用,通过 west / pyOCD 构建及下载 |
| 灯光控制 | 支持关闭、常亮及 1/5/50 Hz 闪烁;按键操作使用闪烁和关闭模式 |
| 按键交互 | 短按切换频率,长按切换开关,包含消抖及长按单次触发 |
| 串口输出 | USART2 输出启动、按键操作及错误日志,921600、8N1、无流控 |
| 声音控制 | 未购买蜂鸣器,当前硬件不支持;没有分配 GPIO 或实现驱动 |
2. 硬件资源与接线
2.1 硬件组成
本任务使用开发板自带的 LD2 LED、B1 用户按键及 ST-LINK 虚拟串口,无需外接 LED、按键或串口转换器。电脑通过开发板 ST-LINK USB 接口完成供电、下载、调试及日志接收。
资源信号/管脚板上连接或入口软件对应关系
| LD2 绿色 LED | PA5,高电平点亮 | 板载;等效 D13 / CN5-6 | led0 → gpio_dt_spec → LED 服务 |
| B1 用户按键 | PC13,沿用板级有效电平定义 | 板载;等效 CN7-23 | sw0 → gpio_pin_get_dt() → 按键事件 |
| USART2 TX | PA2 | 板载 ST-LINK VCP 通路 | usart2 → UART 日志后端 → PC 接收 |
| USART2 RX | PA3 | 板载 ST-LINK VCP 通路 | 保留控制台接收资源;本任务未实现串口命令解析 |
| SWD | PA13 / PA14 | 板载 ST-LINK | 固件下载与调试 |
| 电源及地 | USB 供电、板载地 | ST-LINK USB 入口 | 无需额外外设电源 |
管脚映射依据仓库 docs/01_hardware.md 及当前 overlay。CN 编号表示开发板连接器针号,PA5 等表示 MCU 端口,两者不能混用。本任务使用板上现成电路,无需在上述等效排针处重复接线。
2.2 原理图与连接示意
原理图资料入口:
以上为仓库已记录的资料链接,使用时需核对实物板版本。下图为本任务的功能连接示意,不表示器件级电路和电阻参数。

2.3 实物图
图 1-1:开发板整体与 USB 连接
图 1-2:LED 运行与串口输出
3. 开发环境与工程组织
工程采用 Zephyr RTOS,目标板标识为 nucleo_h533re/stm32h533xx。编译使用 Zephyr SDK,下载调试使用板载 ST-LINK 与 pyOCD,串口终端连接 ST-LINK 对应的虚拟串口。端口号以电脑实际枚举结果为准。
文件职责
| src/main.c | 启动服务,将按键事件转换为 LED 命令 |
| src/led_service.c | LED GPIO 初始化、目标状态管理和闪烁线程 |
| src/button_service.c | 按键扫描、消抖、长短按判定及事件回调 |
| include/led_service.h | LED 启动、常亮、关闭和频率控制接口 |
| include/button_service.h | 按键事件类型和服务启动接口 |
| boards/nucleo_h533re.overlay | 配置 USART2 波特率、启用用户按键 |
| prj.conf | GPIO、串口、延迟日志和系统 tick 配置 |
| CMakeLists.txt | 注册源文件及头文件目录 |
4. 实现思路
4.1 将操作策略与硬件执行分开
应用层只决定“下一步显示什么状态”,按键服务只上报事件,LED 服务负责 GPIO 输出。两个工作线程采用静态栈,由 main() 显式启动,不使用自动启动线程宏。
执行单元优先级/栈工作内容
| 按键线程 | 8 / 1536 字节 | 每 5 ms 读取一次,按下与释放消抖 10 ms,长按阈值 1500 ms |
| LED 线程 | 10 / 1024 字节 | 独占运行期 LED GPIO 写入,执行目标模式 |
| 日志处理线程 | 由 Zephyr 配置 | 延迟格式化和 UART 输出,日志栈配置为 1536 字节 |
Zephyr 抢占线程优先级数值越小,优先级越高。按键回调在按键线程中执行,仅提交 LED 命令和日志,不执行长时间等待。
4.2 LED 控制与及时响应
LED 服务通过互斥锁保护目标模式与频率,通过信号量唤醒执行线程。新命令可以打断原闪烁等待,连续提交时以最新目标为准。接口返回成功表示请求被接受,GPIO 动作由工作线程异步完成。
闪烁采用约 50% 占空比:半周期为 500000 / hz 微秒。
频率完整周期亮/灭半周期
| 1 Hz | 1000 ms | 500 ms |
| 5 Hz | 200 ms | 100 ms |
| 50 Hz | 20 ms | 10 ms |
系统 tick 配置为 1000 Hz。上述为设计值,线程调度和 GPIO 执行会产生误差,实际频率仍需仪器测量。
4.3 按键策略
上电默认 1 Hz 闪烁。
LED 开启时短按:1 → 5 → 50 → 1 Hz,释放后触发。
长按达到 1500 ms:关闭或重新开启 LED;重新开启恢复关闭前频率。
持续按住只触发一次长按,释放后不追加短按。
LED 关闭时短按:恢复 1 Hz。
5. 工作流程图

6. 关键代码
以下片段摘自当前工程,部分仅保留核心语句,完整错误处理见对应源文件。
6.1 通过设备树绑定硬件
来源:src/led_service.c、src/button_service.c。
static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios); static const struct gpio_dt_spec button = GPIO_DT_SPEC_GET(DT_ALIAS(sw0), gpios);
代码通过板级别名取得管脚和有效电平,不在应用层重复写入 PA5、PC13。gpio_pin_get_dt() 返回逻辑有效电平,按键判断应使用其逻辑值。
6.2 短按选择下一档
来源:src/main.c 的 on_button_event()。
size_t next = led_disabled ? 0 : (rate_index + 1) % ARRAY_SIZE(blink_rates);
ret = led_set_blink_hz(blink_rates[next]);
if (ret == 0) {
rate_index = next;
led_disabled = false;
LOG_INF("Short press: LED %u Hz", blink_rates[next]);
}只有命令被服务接受后才更新应用状态,避免提交失败后软件状态与目标状态不一致。
6.3 可被命令打断的闪烁等待
来源:src/led_service.c 的 led_worker()。
k_timeout_t wait = mode == LED_BLINK ? K_USEC(500000U / hz) : K_FOREVER;
if (k_sem_take(&led_wakeup, wait) == 0) {
break;
}
lit = !lit;等待超时后翻转 LED;收到通知则退出当前模式执行循环,重新读取目标。常亮和关闭模式使用无限等待,减少无意义轮询。
6.4 长按只触发一次
来源:src/button_service.c 的 button_worker()。
if (stable && candidate && !long_sent && now - pressed_since >= LONG_PRESS_MS) {
long_sent = true;
event_callback(BUTTON_LONG_PRESS);
}long_sent 阻止按住期间重复上报。稳定释放时也检查该标志,防止一次长按随后又被认作短按。释放边界按候选释放电平的起始时刻计算,排除释放消抖时间对长短按分类的影响。
6.5 串口与日志配置
来源:boards/nucleo_h533re.overlay、prj.conf。
&usart2 {
current-speed = <921600>;
status = "okay";
};CONFIG_LOG=y CONFIG_LOG_MODE_DEFERRED=y CONFIG_LOG_BACKEND_UART=y CONFIG_LOG_BUFFER_SIZE=2048 CONFIG_PRINTK=n CONFIG_BOOT_BANNER=n CONFIG_SYS_CLOCK_TICKS_PER_SEC=1000
应用统一使用 LOG_INF/LOG_ERR。延迟日志将格式化及发送移交日志线程;不在每次 LED 翻转时输出日志,以减少对闪烁时序的影响。
7. Debug 问题与处理
7.1 pyOCD 不识别目标芯片:已有环境修复记录
仓库 docs/02_build_flash.md 记录过 Target type stm32h533retx not recognized。原因是使用的 pyOCD 环境缺少 STM32H533 CMSIS 目标支持包。
处理方法是在与 IDE 使用相同的 Python / pyOCD 环境安装对应支持包,并用 pyocd list --targets 检查 stm32h533retx。已有记录显示安装 Keil.STM32H5xx_DFP 2.3.1 后目标可被列出;该记录没有执行烧录,因此只能证明目标支持包问题已解决。
7.2 切换构建配置后的缓存冲突
已有任务说明指出,切换构建配置后可能提示需要 pristine。处理方式是对指定构建目录执行 west build -p always,重新配置并构建。本项为已有排查方法,当前没有任务一的独立报错截图和修复后构建日志。
7.3 按键重复触发与临界时长:代码中的处理措施
当前代码使用候选状态、稳定状态及 10 ms 消抖区分机械抖动;用 long_sent 防止长按重复和释放后追加短按;以释放候选状态起始时间计算按住时长,避免把释放消抖时间计入长按阈值。
上述措施已在源码中实现,但现有资料不足以复原每项措施之前的现场故障,故不将其表述为已完成的实测修复。验收时应重复测试 1500 ms 附近的释放行为。
7.4 GPIO 访问异常:代码中的保护措施
按键读取失败时取消当前手势,恢复后重新消抖,避免错误样本延续旧手势。LED 写入失败时记录错误并等待新命令,避免高频重试和日志刷屏。启动接口检查设备就绪及重复启动;非法频率返回 -EINVAL,未启动控制返回 -EACCES。
8. 构建、运行与效果验证
8.1 复现步骤
以下命令在仓库根目录、已经激活 Zephyr 工具环境的终端执行,沿用任务一已有说明中的构建目录:
west build -p always -b nucleo_h533re/stm32h533xx -d basic_task_01/build/nucleo_h533re/stm32h533xx basic_task_01 -- "-DDTC_OVERLAY_FILE=boards/nucleo_h533re.overlay" west flash -d basic_task_01/build/nucleo_h533re/stm32h533xx
连接串口终端,选择 ST-LINK 虚拟串口,设置 921600、8N1、无流控。复位后观察默认闪烁和启动日志,再进行短按、长按验证。若 Windows 构建出现长路径错误,可参考任务二的短构建目录方案另行配置,不能将任务二的修复结果当作任务一验证结果。
8.2 当前实现效果与预期日志
当前源码已形成“按键输入 → 事件判定 → LED 命令 → GPIO 输出 → 日志反馈”的完整软件链路。按代码预期,上电为 1 Hz,短按循环三档,长按关闭或恢复原频率。led_on() 提供常亮 API,但当前按键策略没有常亮入口。
以下是源码消息内容组成的预期示例,省略 Zephyr 日志时间戳和模块前缀,不是本次采集的实机日志:
Basic task 01 starting; UART 921600 8N1 Ready: LED 1 Hz; short press cycles rate; hold 1500 ms to toggle LED Short press: LED 5 Hz Short press: LED 50 Hz Long press: LED off Long press: LED on, 50 Hz
8.3 验收记录与待补材料
验证内容判据当前证据/待补内容
| 构建、链接及下载 | 生成目标固件并成功写入 | 待补任务一独立构建及下载记录;本次文档编写未执行构建或烧录 |
| 串口输出 | 参数正确、启动和操作日志可读 | 源码及配置已核对;待补实机截图 |
| 三档闪烁 | 1/5/50 Hz,约 50% 占空比 | 已核对半周期计算;待补仪器实测值 |
| 短按切档 | 三档循环,关闭时短按恢复 1 Hz | 已核对代码;待补连续操作记录 |
| 长按开关 | 每次仅触发一次,恢复原档,释放不追加短按 | 已核对代码;待补临界时长及按住上电测试 |
| 错误处理 | 无效参数、重复启动及 GPIO 错误可诊断 | 已核对保护分支;待补实际测试记录 |
| 声音输出 | 本次不适用 | 用户确认没有购买蜂鸣器,硬件不支持 |
本任务的软件实现已覆盖当前硬件可支持的灯光、按键及日志功能。实物照片、实际频率、构建资源占用和实机操作结果补齐后,可形成完整验收记录。
<iframe src="//player.bilibili.com/player.html?isOutside=true&aid=117626957207473&bvid=BV1T8sN6sE5E&cid=43662839269&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"></iframe>


我要赚赏金
