# 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 8KB，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`）：

```bash
"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=14712 RO-data=944 RW-data=112 ZI-data=10696`。

烧录与运行：

1. Keil 打开 `MDK-ARM/embeddedSrc.uvprojx`，F7 编译
2. NS-LINK 接 SWD（PA4/PA5），F8 下载
3. 串口助手接 PB6(TX)/PB7(RX)，115200 8N1，复位后应看到启动 banner 与 `n32> ` 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，栈 256 字）消费队列并 printf。**主动日志打印由 `AppTasks_SetLogEnabled()` 控制，默认关闭**（CLI 命令 `log on|off` 切换）。新增需要打印的任务时沿用此生产者-消费者模式，不要在中断或多个任务里直接 `printf`。
- CLI 任务（优先级 3，栈 256 字，见 `app_cli.c`）：从 USART1 RXDNE 中断的字节队列取输入，行结束符 `\r\n` / `\n\r` / `\r` / `\n` 均识别；解析-执行-应答一体化，应答走 `bsp_usart_write_dma`（DMA_CH1）。新命令在 `s_cmds[]` 命令表中注册。
- 串口输出并发：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 = 8*1024`，使用 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。

## 测试策略

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

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

## 其他注意事项

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