200 lines
9.1 KiB
Markdown
200 lines
9.1 KiB
Markdown
# N32WB031 基础工程开发日志
|
||
|
||
日期：2025-06-09
|
||
工程：`H:\caiic_workspace\mothercup\embeddedSrc`
|
||
目标芯片：N32WB031（国民技术 BLE SoC，Cortex-M0，64MHz，Flash 256KB，RAM 48KB）
|
||
|
||
## 1. 任务目标
|
||
|
||
基于 N32WB03x SDK V2.0.0 新建裸工程，实现：
|
||
|
||
- UART 串口打印（printf 重定向）
|
||
- 集成 FreeRTOS，构建实时多任务架构
|
||
- GPIO 点灯（LED 周期翻转）
|
||
- 引脚分配不得与 SWD 调试管脚冲突
|
||
|
||
## 2. 参考资料
|
||
|
||
| 资料 | 路径 |
|
||
|---|---|
|
||
| SDK V2.0.0 | `nations-tec/N32WB03x_SDK_V2.0.0` |
|
||
| 器件包 | `nations-tec/N32WB03x_DFP.1.4.0.pack` |
|
||
| 用户手册 | `nations-tec/CN_UM_N32WB03X_Series_User_Manual_V1.5.pdf` |
|
||
| 硬件设计指南 | `nations-tec/CN_DG_N32WB03x_Series_Chips_Hardware_Design_Guide_V1.4.pdf` |
|
||
| STB 开发板资料 | `nations-tec/N32WB031_STB_V1.3` |
|
||
|
||
参考例程：
|
||
|
||
- 串口：`projects/n32wb03x_EVAL/peripheral/USART/Printf`
|
||
- 点灯：`projects/n32wb03x_EVAL/peripheral/GPIO/LedBlink`
|
||
- FreeRTOS：`projects/n32wb03x_EVAL/application/FreeRTOS/FreeRTOS_ThreadCreation`
|
||
|
||
## 3. 关键硬件结论
|
||
|
||
- **SWD 调试管脚：SWCLK=PA4，SWDIO=PA5**（复位后默认 AF0）——本工程所有 GPIO 分配均避开这两个脚
|
||
- STB 开发板板载 LED：LED1=PB0（跳线 J21）、LED2=PA6（跳线 J22），蓝色 LED，4.7K 限流
|
||
- 串口排针 J3 已引出 PB6/PB7
|
||
- 注意：PB8/PB9 默认接 32.768K 晶振；PB3 有下拉注意事项（手册 5.2.4）
|
||
|
||
## 4. 引脚分配表
|
||
|
||
| 功能 | 引脚 | 复用 | 说明 |
|
||
|---|---|---|---|
|
||
| USART1_TX | PB6 | AF4 | 115200 8N1 |
|
||
| USART1_RX | PB7 | AF4 | |
|
||
| LED1 | PB0 | GPIO 推挽输出 | 板载 D1 |
|
||
| LED2 | PA6 | GPIO 推挽输出 | 板载 D2 |
|
||
| SWDCLK | PA4 | AF0 | 调试占用，应用程序禁用 |
|
||
| SWDIO | PA5 | AF0 | 调试占用，应用程序禁用 |
|
||
|
||
## 5. 工程结构
|
||
|
||
```
|
||
embeddedSrc/
|
||
├── app/
|
||
│ ├── main.c # 入口：时钟更新 → USART 初始化+banner → LED 初始化 → 建队列/任务 → vTaskStartScheduler
|
||
│ ├── bsp_usart.c/.h # USART1 初始化 + fputc 重定向（'\n' 前自动补 '\r'）
|
||
│ ├── bsp_led.c/.h # LED1/LED2 初始化、on/off/toggle
|
||
│ ├── app_tasks.c/.h # 3 个 FreeRTOS 任务 + 日志队列
|
||
│ ├── n32wb03x_it.c/.h # NMI / HardFault 异常处理
|
||
│ └── FreeRTOSConfig.h # heap 8KB，SVC/PendSV/SysTick 映射给 FreeRTOS port
|
||
├── MDK-ARM/
|
||
│ ├── embeddedSrc.uvprojx
|
||
│ └── embeddedSrc.uvoptx
|
||
└── docs/
|
||
└── 开发日志.md（本文件）
|
||
```
|
||
|
||
SDK 源码（固件库、CMSIS、FreeRTOS V9.0.0、启动文件）以相对路径 `..\..\nations-tec\N32WB03x_SDK_V2.0.0` 引用，不复制到工程内。
|
||
|
||
工程配置：器件 N32WB031，IROM 0x01000000 / 0x40000，IRAM 0x20000000 / 0xC000，MicroLIB，宏定义 `N32WB03X, USE_STDPERIPH_DRIVER`。
|
||
|
||
## 6. 实时多任务架构
|
||
|
||
使用 FreeRTOS 原生 API（xTaskCreate / vTaskDelay / xQueue），不用 cmsis_os 封装。
|
||
|
||
| 任务 | 功能 | 周期/触发 | 栈（字） | 优先级 |
|
||
|---|---|---|---|---|
|
||
| LedTask | 翻转 LED1，向日志队列发送 LogMsg_t | 500ms | 128 | 2 |
|
||
| LedTask2 | 翻转 LED2，向日志队列发送 LogMsg_t | 1000ms | 128 | 2 |
|
||
| PrintTask | xQueueReceive 阻塞取消息并 printf | 队列驱动 | 256 | 3 |
|
||
|
||
生产者-消费者模型：LED 任务只负责投递消息，打印任务独占串口输出，避免多任务直接 printf 造成的输出交错。
|
||
|
||
调度相关：
|
||
|
||
- SysTick 由 FreeRTOS port 接管（FreeRTOSConfig.h 中 `xPortSysTickHandler → SysTick_Handler` 映射），main 中不再手动 `SysTick_Config`
|
||
- `configTOTAL_HEAP_SIZE = 8*1024`（48KB RAM 余量充足）
|
||
|
||
## 7. 编译验证
|
||
|
||
- 工具链：Keil µVision5（`D:\Keil_v5\UV4\UV4.exe`，ARMCC V5.06 update 6）
|
||
- 命令行：`UV4.exe -b embeddedSrc.uvprojx -j0 -o build.log`（工作目录 `embeddedSrc/MDK-ARM`）
|
||
- 结果：**0 Error(s), 0 Warning(s)**
|
||
- 体积：`Code=8248 RO-data=724 RW-data=100 ZI-data=10532`
|
||
- 产物：`Objects/embeddedSrc.axf`、`Objects/embeddedSrc.hex`、`bin/embeddedSrc.bin`
|
||
- 自查：全工程无 PA4/PA5 占用；SVC/PendSV/SysTick_Handler 无重复定义
|
||
|
||
## 8. 烧录与运行
|
||
|
||
1. Keil 打开 `embeddedSrc/MDK-ARM/embeddedSrc.uvprojx`，F7 编译
|
||
2. NS-LINK 接 SWD（PA4/PA5），F8 下载
|
||
3. 串口助手接 PB6(TX)/PB7(RX)，115200 8N1
|
||
4. 复位后预期输出：启动 banner + `LED1 toggled, count = N` / `LED2 toggled, count = N` 滚动日志
|
||
|
||
注意：未在真实硬件上运行验证。若 LED 不亮，检查 STB 板 J21/J22 跳线；若串口无输出，检查 J3 排针接线。
|
||
|
||
## 9. 后续计划
|
||
|
||
- 板卡实测验证 LED 与串口日志
|
||
- 按需接入 BLE 协议栈（SDK ble 例程为裸机 rwip_schedule 调度，与 FreeRTOS 架构需做整合设计）
|
||
|
||
---
|
||
|
||
日期：2026-09-01
|
||
|
||
## 10. UART DMA 发送 + 日志开关 + CLI 命令框架
|
||
|
||
### 10.1 DMA 可行性结论
|
||
|
||
N32WB031 具备 DMA 外设（5 通道），固件库支持 `USART_EnableDMA` 与通道重映射
|
||
（`DMA_RequestRemap`），USART1_TX 可映射到 DMA_CH1（参考官方例程
|
||
`projects/n32wb03x_EVAL/peripheral/USART/DMA_Interrupt`）。**硬件支持，已实现 DMA 发送。**
|
||
|
||
### 10.2 串口驱动扩展（bsp_usart）
|
||
|
||
- TX 双通道并存：`fputc` 轮询发送保留给调度器启动前的 banner 与 PrintTask；
|
||
新增 `bsp_usart_write_dma(buf, len)` 走 DMA_CH1（每次发送重新 `DMA_Init`，轮询
|
||
`DMA_FLAG_TC1` 完成标志 + 等 `USART_FLAG_TXC` 移位寄存器排空），供 CLI 输出使用。
|
||
- RX 新增 RXDNE 中断：`USART1_IRQHandler`（n32wb03x_it.c）→ `bsp_usart_rx_isr_handler()`，
|
||
字节经 `xQueueSendFromISR` 投递到 64 字节接收队列；应用侧用
|
||
`bsp_usart_read_byte(ch, timeout_ms)` 阻塞取字节。NVIC 优先级 = 3（最低，满足
|
||
`configMAX_SYSCALL_INTERRUPT_PRIORITY` 约束）。
|
||
- 新增 TX 互斥锁 `bsp_usart_tx_lock/unlock`：调度器未运行时为空操作；
|
||
PrintTask 的整条 printf 与 CLI 的整段应答各持锁一次，避免 log 开启后两类输出字节级交错。
|
||
|
||
### 10.3 主动打印开关
|
||
|
||
`app_tasks` 新增 `AppTasks_SetLogEnabled()/AppTasks_GetLogEnabled()`，**默认关闭**。
|
||
LED 任务照常翻转，仅在开关打开时才向日志队列投递消息。运行时通过 CLI
|
||
`log on|off` 切换，`log` 无参数查询当前状态。
|
||
|
||
### 10.4 CLI 框架（app_cli）
|
||
|
||
- 独立任务 `CliTask`（栈 256 字，优先级 3），独占完成：行接收 → 解析 → 执行 → 应答，
|
||
应答全部走 DMA TX（`cli_write`/`cli_printf`，需显式带 `\r\n`）。
|
||
- 命令表 `CliCmd_t s_cmds[]`（name/help/handler），新增命令只需在表中加一项。
|
||
- 行结束符兼容 **`\r\n`、`\n\r`、`\r`、`\n`** 四种：首个 `\r` 或 `\n` 触发分发，
|
||
紧跟的互补字符被吞掉一次。支持退格（0x08/0x7F）编辑，行缓冲 64 字节，超长响铃。
|
||
- 内置命令：`help`、`version`、`log [on|off]`、`led <1|2> <on|off|toggle>`。
|
||
- 提示符 `n32> `，空行仅重显提示符。
|
||
|
||
### 10.5 编译验证
|
||
|
||
- `UV4.exe -b embeddedSrc.uvprojx -j0 -o build.log`：**0 Error(s), 0 Warning(s)**
|
||
- 体积：`Code=14712 RO-data=944 RW-data=112 ZI-data=10696`（Flash/RAM 余量仍充足）
|
||
- 新增源文件：`app/app_cli.c/.h`；uvprojx 的 FWLB 组加入 `n32wb03x_dma.c`
|
||
- 烧录后预期：banner 之后出现 `CLI ready. Type 'help' for commands.` 与 `n32> ` 提示符；
|
||
默认无 LED 滚动日志，`log on` 后恢复。
|
||
- 注意：尚未上板实测，DMA 与中断路径需硬件验证。
|
||
|
||
---
|
||
|
||
日期：2026-09-01
|
||
|
||
## 11. 任务栈统一调整为 1024 字
|
||
|
||
- 上板实测 DMA/CLI/日志开关运行正常后，4 个任务栈统一调整为 1024 字（4KB/任务）：
|
||
`LED_TASK_STACK` / `PRINT_TASK_STACK`（app_tasks.c）、`CLI_TASK_STACK`（app_cli.c）。
|
||
- 4 任务共 16KB 栈，超出原 8KB heap，故 `configTOTAL_HEAP_SIZE` 由 8KB 调至 20KB
|
||
（含队列、TCB、空闲任务栈 128 字的开销）。
|
||
- 编译：0 Error / 0 Warning；体积 `Code=14712 RO-data=944 RW-data=112 ZI-data=22984`，
|
||
ZI 约占 48KB RAM 的 47%，余量充足。
|
||
|
||
---
|
||
|
||
日期：2026-09-01
|
||
|
||
## 12. CLI 增强：Ctrl+Z 关日志、Tab 补全、命令历史
|
||
|
||
均在 `app_cli.c` 的 CliTask 中实现：
|
||
|
||
- **Ctrl+Z（0x1A）**：立即 `AppTasks_SetLogEnabled(0)` 关闭主动打印，打印 `[log off]`
|
||
并重绘当前输入行。用于 log 滚动刷屏时快速停止。
|
||
- **Tab（0x09）自动补全**：仅补全行首命令名（已含空格则不动作）。唯一匹配则补全
|
||
并追加空格；多个匹配则先扩展公共前缀，无法扩展时列出候选并重绘输入行。
|
||
- **命令历史**：环形缓冲 8 条 × 64 字节（`s_history`），提交时去重（空行、与上一条
|
||
相同不入队）；上/下方向键（`ESC [ A` / `ESC [ B` 转义序列状态机解析）回翻历史，
|
||
越过最新一条回到空行。回翻采用"清行重绘"（`\r` + 提示符 + 空格擦除 + 重显）。
|
||
- `help` 输出末尾附按键说明。
|
||
- 编译：0 Error / 0 Warning；体积 `Code=15688 RO-data=944 RW-data=112 ZI-data=23496`。
|
||
|
||
---
|
||
|
||
日期：2026-09-01
|
||
|
||
## 13. CLI 提示符修改
|
||
|
||
- 命令行提示符由 `n32> ` 改为 `caiic->`（`app_cli.c` 中 `CLI_PROMPT` 宏）。
|
||
- 编译：0 Error / 0 Warning；体积 `Code=15692 RO-data=944 RW-data=112 ZI-data=23496`。
|