119 lines
9.8 KiB
Markdown
119 lines
9.8 KiB
Markdown
# 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 点灯，并已接入 **BLE 协议栈**（自定义 GATT 透传服务 CLS + 独立 BLE 调度任务，见开发日志第 15 节）。目标硬件为 **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 # 入口：VTOR 重映射 → USART 初始化+banner → LED 初始化 → app_ble_init → 建队列/任务/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 UART 前端：CliTask 行接收/编辑/历史/Tab/Ctrl+Z，分行后交 cli_core 执行
|
||
│ ├── cli_core.c/.h # CLI 核心（命令表/handler/分词执行），输出经可切换 cli_out_fn（默认 UART DMA）；命令：help/version/sysinfo/log/led/bankinfo
|
||
│ ├── app_ota.c/.h # BLE OTA 接收器：4KB 扇区缓冲直写对侧 bank + CRC32 校验 + bootsetting 更新 + 复位切换
|
||
│ ├── app_version.h # 固件版本号 APP_FW_VERSION
|
||
│ ├── n32wb03x_it.c/.h # NMI / HardFault 异常处理 + USART1_IRQHandler（转发到 bsp_usart_rx_isr_handler）
|
||
│ ├── FreeRTOSConfig.h # heap 20KB，SVC/PendSV/SysTick 映射给 FreeRTOS port
|
||
│ └── ble/
|
||
│ ├── app_ble.c/.h # BLE 栈初始化/广播/连接事件 + BLE 调度任务 + notify 发送与下行回调 + app_ble_max_payload/is_connected
|
||
│ ├── app_ble_proto.c/.h # BLE 帧协议前端：字节流重组、CLI_REQ/CLI_RSP 传输、OTA 帧分发、pending 重试（BleTask 上下文）
|
||
│ ├── app_user_config.h # 广播名 CAIIC-MCM、连接参数、profile/日志开关（被 SDK rwip_config.h 包含）
|
||
│ └── app_profile/
|
||
│ ├── rwapp_config.h # CFG_APP_* → BLE_APP_* 映射
|
||
│ └── app_cls.c/.h # 自定义 128-bit UUID GATT 服务（写 + notify 两特征，基于 SDK rdtss profile 引擎）
|
||
├── MDK-ARM/
|
||
│ ├── embeddedSrc.uvprojx / .uvoptx # Keil µVision5 工程文件（含 DFU 组：..\..\Boot\src\boot_crc32.c）
|
||
│ ├── Objects/ # 编译产物（embeddedSrc.axf / .hex）
|
||
│ ├── bin/ # fromelf 生成的 embeddedSrc.bin
|
||
│ └── build.log
|
||
└── docs/开发日志.md
|
||
```
|
||
|
||
SDK 源码（固件库、CMSIS、FreeRTOS V9.0.0、BLE 协议栈/profile/ns_library、启动文件）通过相对路径 `..\..\nations-tec\N32WB03x_SDK_V2.0.0` 被 uvprojx 引用，**不复制进工程**。Bootloader 共享代码（`Boot/src/dfu_layout.h`、`boot_crc32.c`）经 `..\..\Boot\src` 引用。因此 `mcm-ddc-04` 目录不能脱离仓库根单独移动。
|
||
|
||
工程配置：器件 `N32WB031KEQ6-2`（512KB Flash），IROM 0x01008000 / 0x38000（APP1 区，前 32KB 留给 Bootloader），IRAM 0x20000000 / 0xC000，MicroLIB，全局宏 `N32WB03X, USE_STDPERIPH_DRIVER`；链接器 Misc 附加 BLE ROM 符号表 `symbol_g15.obj`。
|
||
|
||
## 构建与烧录
|
||
|
||
工具链：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=38000 RO-data=6856 RW-data=10600 ZI-data=31008`（RW+ZI≈40.6KB < 48KB，heap 仍为 20KB）。
|
||
|
||
烧录与运行：
|
||
|
||
1. Keil 打开 `MDK-ARM/embeddedSrc.uvprojx`，F7 编译
|
||
2. NS-LINK 接 SWD（PA4/PA5），F8 下载
|
||
3. 串口助手接 PB6(TX)/PB7(RX)，115200 8N1，复位后应看到启动 banner 与 `caiic->` CLI 提示符（输入 `help` 查看命令；LED 滚动日志默认关闭，用 `log on` 打开）
|
||
4. BLE：手机 nRF Connect 应能搜到并连接 `CAIIC-MCM`，可见自定义服务（写特征 + notify 特征）
|
||
|
||
注意：本工程当前尚未在真实硬件上实测（见开发日志第 8、9、10、15 节）。
|
||
|
||
## 硬件引脚约束（重要）
|
||
|
||
- **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 字 + BLE 任务 512 字，另加队列/TCB/空闲任务开销），使用 heap_4。
|
||
|
||
## BLE 架构约定（重要）
|
||
|
||
- **VTOR**：Cortex-M0 无 SCB->VTOR，向量重映射用 `PWR->VTOR_REG`（bit31=EN|[30:0]=基址）。APP 链接在 0x01008000，而 SDK `SystemInit()` 写成 0x81000000、`ns_ble_stack_init()` 内部清 0，因此 `main` 在任何中断使能前先设 `0x80000000|0x01008000`，`app_ble_init()` 之后再重设一次（见开发日志 15.3，含回退方案）。
|
||
- **BLE 调度任务**（`app/ble/app_ble.c`，栈 512 字，优先级 2）：循环 `rwip_schedule(); vTaskDelay(1ms);`。**ke_msg/ke_timer 只允许在该任务上下文运行**（SDK 约束），不要在其他任务或中断里直接调用。
|
||
- BLE 中断向量不在 `n32wb03x_it.c` 定义：启动文件中 BLE_*IRQHandler 为 weak，真正 handler 由 `symbol_g15.obj`（ROM）+ SDK RAM 重映射（0x200000e8/0x200009c0）提供。BLE_SW/FIFO IRQ 优先级 0，其 ISR 内禁止调用 FreeRTOS FromISR API。
|
||
- GATT 服务：自定义 CLS 服务（`app/ble/app_profile/app_cls.c`），复用 SDK rdtss profile 引擎；notify 发送为单包接口（忙返回 -1，上层重试）。**ns_sleep 低功耗不接**（与 FreeRTOS tick 冲突），NS_LOG/LPUART 不接。
|
||
|
||
## 代码风格
|
||
|
||
- 语言为 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`）已接入（开发日志第 15 节）；CLI-over-BLE 协议与 BLE OTA 为后续任务。
|