AGENTS.md

项目概述

本仓库是基于国民技术（Nations）N32WB031 BLE SoC 的嵌入式固件工程集合。N32WB031 是一颗 Cortex-M0 内核的低功耗蓝牙芯片（64MHz HSI，Flash 256KB，RAM 48KB）。

当前唯一的活跃工程是 mcm-ddc-04/：一个基于 N32WB03x SDK V2.0.0 从零搭建的裸工程，演示 UART 串口打印（printf 重定向 + DMA 发送 + RX 中断）、CLI 命令框架、FreeRTOS 多任务、GPIO 点灯。目标硬件为 N32WB031_STB_V1.3 开发板（NS-LINK 调试器，SWD 下载）。

仓库顶层目录：

mcm-ddc-04/ — 主工程（应用代码、MDK 工程文件、开发日志）
nations-tec/ — 厂商资源：SDK V2.0.0、DFP 器件包、STB 开发板资料（原理图/BOM/PCB）、官方 PDF 文档。这些内容为只读参考资料，不要修改。
app/、Boot/、docs/ — 顶层空目录，为后续规划预留的占位（当前无内容）

关键参考路径（相对仓库根）：

SDK：nations-tec/N32WB03x_SDK_V2.0.0（固件库 firmware/、中间件 middlewares/Nationstech/ble_library 与 middlewares/Third_Party/FreeRTOS、官方例程 projects/n32wb03x_EVAL/、DFU 工具 utilities/dfu）
官方例程：USART printf projects/n32wb03x_EVAL/peripheral/USART/Printf、点灯 peripheral/GPIO/LedBlink、FreeRTOS application/FreeRTOS/FreeRTOS_ThreadCreation
开发日志与详细设计决策：mcm-ddc-04/docs/开发日志.md

工程结构（mcm-ddc-04）

mcm-ddc-04/
├── app/
│   ├── main.c            # 入口：SystemCoreClockUpdate → USART 初始化+banner → LED 初始化 → 建队列/任务/CLI → vTaskStartScheduler
│   ├── bsp_usart.c/.h    # USART1 初始化（PB6/PB7，115200 8N1）+ fputc 重定向（'\n' 前自动补 '\r'）+ DMA TX（CH1，轮询完成）+ RXDNE 中断字节队列 + TX 互斥锁
│   ├── bsp_led.c/.h      # LED1(PB0)/LED2(PA6) 初始化、on/off/toggle
│   ├── app_tasks.c/.h    # 3 个 FreeRTOS 任务 + 日志队列（生产者-消费者模型）+ 主动打印开关（默认关）
│   ├── app_cli.c/.h      # CLI 独立任务：行接收/解析/执行/应答（应答走 DMA TX），命令表驱动
│   ├── n32wb03x_it.c/.h  # NMI / HardFault 异常处理 + USART1_IRQHandler（转发到 bsp_usart_rx_isr_handler）
│   └── FreeRTOSConfig.h  # heap 20KB，SVC/PendSV/SysTick 映射给 FreeRTOS port
├── MDK-ARM/
│   ├── embeddedSrc.uvprojx / .uvoptx   # Keil µVision5 工程文件
│   ├── Objects/  # 编译产物（embeddedSrc.axf / .hex）
│   ├── bin/      # fromelf 生成的 embeddedSrc.bin
│   └── build.log
└── docs/开发日志.md

SDK 源码（固件库、CMSIS、FreeRTOS V9.0.0、启动文件）通过相对路径 ..\..\nations-tec\N32WB03x_SDK_V2.0.0 被 uvprojx 引用，不复制进工程。因此 mcm-ddc-04 目录不能脱离仓库根单独移动。

工程配置：器件 N32WB031，IROM 0x01000000 / 0x40000，IRAM 0x20000000 / 0xC000，MicroLIB，全局宏 N32WB03X, USE_STDPERIPH_DRIVER。

构建与烧录

工具链：Keil µVision5（ARMCC V5.06 update 6），安装于 D:\Keil_v5。

命令行构建（工作目录必须为 mcm-ddc-04/MDK-ARM）：

"D:\Keil_v5\UV4\UV4.exe" -b embeddedSrc.uvprojx -j0 -o build.log

构建成功后自动执行 fromelf --bin --output=.\bin\embeddedSrc.bin .\Objects\embeddedSrc.axf。当前基线结果：0 Error(s), 0 Warning(s)，体积 Code=15692 RO-data=944 RW-data=112 ZI-data=23496。

烧录与运行：

Keil 打开 MDK-ARM/embeddedSrc.uvprojx，F7 编译
NS-LINK 接 SWD（PA4/PA5），F8 下载
串口助手接 PB6(TX)/PB7(RX)，115200 8N1，复位后应看到启动 banner 与 caiic-> CLI 提示符（输入 help 查看命令；LED 滚动日志默认关闭，用 log on 打开）

注意：本工程当前尚未在真实硬件上实测（见开发日志第 8、9、10 节）。

硬件引脚约束（重要）

SWD 调试管脚 SWCLK=PA4 / SWDIO=PA5：应用程序绝对禁止占用，否则下载/调试失效。
板载 LED：LED1=PB0（跳线 J21）、LED2=PA6（跳线 J22），蓝色，4.7K 限流。
USART1：TX=PB6 / RX=PB7，复用 AF4，经排针 J3 引出。
PB8/PB9 默认接 32.768K 晶振；PB3 有下拉注意事项（用户手册 5.2.4）。

实时架构约定

使用 FreeRTOS V9.0.0 原生 API（xTaskCreate / vTaskDelay / xQueue），不使用 cmsis_os 封装。
任务模型：LedTask（LED1，500ms）、LedTask2（LED2，1000ms）为生产者，只向日志队列投递 LogMsg_t；PrintTask（优先级 3，栈 1024 字）消费队列并 printf。主动日志打印由 AppTasks_SetLogEnabled() 控制，默认关闭（CLI 命令 log on|off 切换）。新增需要打印的任务时沿用此生产者-消费者模式，不要在中断或多个任务里直接 printf。
CLI 任务（优先级 3，栈 1024 字，见 app_cli.c）：从 USART1 RXDNE 中断的字节队列取输入，行结束符 \r\n / \n\r / \r / \n 均识别；解析-执行-应答一体化，应答走 bsp_usart_write_dma（DMA_CH1）。新命令在 s_cmds[] 命令表中注册。支持 Tab 命令补全、上下方向键历史回翻（8 条环形缓冲）、Ctrl+Z 关闭主动打印。
串口输出并发：PrintTask 的整条 printf 与 CLI 的整段应答分别持有 bsp_usart_tx_lock() 互斥锁，避免字节级交错；调度器启动前该锁为空操作。
SysTick 由 FreeRTOS port 接管（FreeRTOSConfig.h 中 xPortSysTickHandler → SysTick_Handler 映射）：main 中不要手动 SysTick_Config，n32wb03x_it.c 中不要重复定义 SVC/PendSV/SysTick_Handler。
USART1_IRQn 中断优先级为 3（最低），因 ISR 内调用 FreeRTOS FromISR API，必须 ≥ configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY（=3）。
configTOTAL_HEAP_SIZE = 20*1024（4 个任务栈各 1024 字 = 16KB，另加队列/TCB/空闲任务开销），使用 heap_4。

代码风格

语言为 C（ARMCC，C 库 MicroLIB），文件头与函数头使用 Doxygen 风格注释（@file / @brief），注释用英文。
命名：BSP 层函数 bsp_<module>_<action>；应用层聚合函数 AppTasks_* / AppCli_*；引脚/时钟等硬件参数集中在头文件顶部宏定义。
使用 SDK 标准外设库 API（如 RCC_EnableAPB2PeriphClk、GPIO_InitPeripheral、USART_Init），不要直接操作寄存器。
新增 GPIO 前必须核对开发日志第 4 节引脚分配表，避开 PA4/PA5。

测试策略

无自动化测试框架；验证方式为：

Keil 命令行构建必须保持 0 Error / 0 Warning；
烧录后通过串口输出与 LED 行为人工确认。

其他注意事项

nations-tec/ 下的 SDK、器件包与 PDF 为第三方只读资料，改动应只发生在 mcm-ddc-04/（或新增工程目录）内。
BLE 协议栈（middlewares/Nationstech/ble_library）尚未接入；官方 BLE 例程基于裸机 rwip_schedule 调度，与 FreeRTOS 整合需要专门设计（见开发日志第 9 节）。

7.0 KiB Raw Blame History Unescape Escape