# HCDF MID 405 充放电控制器固件

本仓库是基于 **STM32F405RG** 的四通道双向电源/电子负载控制固件。主程序运行在 **RT-Thread 5.2.2** 上，负责连接上位机、HMI、快充协议板和源载功率板，完成通道切换、源/载控制、继电器管理、状态采集、校准和固件升级。仓库同时包含独立 Bootloader，用于应用固件校验、更新和出厂固件恢复。

> 本项目直接控制电源与电子负载硬件。调试前应确认限压、限流、散热、急停和继电器默认状态；修改通道切换或输出控制逻辑后，先在断电或受限功率条件下验证。

## 系统概览

```mermaid
flowchart LR
    PC["上位机 / 测试系统"] -->|"UART1 · Modbus RTU"| CTRL["STM32F405 控制板"]
    HMI["HMI 屏幕"] <-->|"UART2"| CTRL
    CTRL <-->|"UART3 · 多路复用"| NORTH["4 路快充协议板"]
    CTRL <-->|"UART6 · 多路复用"| SOUTH["4 路源载功率板"]
    CTRL --> RELAY["继电器与通道选择"]
    CTRL --> FLASH["参数 / 日志 / 升级分区"]
    USB["USB CDC 调试终端"] <-->|"MSH / 日志"| CTRL
```

主程序把每个物理通道的控制状态集中保存在北向对象中，并从南向功率板刷新电压、电流、功率、故障和在线状态。上位机或 HMI 写入控制参数后，轮询线程将变化转换为协议板、功率板和继电器操作；采集结果再映射回 Modbus 寄存器和屏幕数据。

## 主要功能

- 四通道 Source/Sink 控制及通信通道复用。
- 电源侧快充协议设置，代码中包含 FCP、SCP、QC2.0/QC3.0、AFC、PD、UFCS 等协议编号；实际支持范围以 `docs/` 中的协议表和目标板固件为准。
- 电子负载恒压、恒流、恒功率、恒阻和开环模式，以及短路、OCP、动态测试控制。
- 上位机 Modbus RTU 服务，地址默认为 `0x01`，实现 `0x01/0x02/0x03/0x04/0x05/0x06/0x0F/0x10`，并提供 `0x20` 升级和 `0x21` 校准扩展功能。
- FAL 片内 Flash 管理、看门狗、硬件定时器、USB CDC 虚拟串口、FinSH/MSH 和 ULog。
- 带 CRC、包头校验、AES 解密、断电恢复和出厂分区回退的 Bootloader 升级流程。

## 目录结构

| 路径 | 说明 |
| --- | --- |
| `apps/chrg/` | RT-Thread 主固件、SCons 配置和 Keil 工程 |
| `apps/chrg/applications/bsp/` | GPIO、继电器、LED、串口封装、FAL、定时器、看门狗和 USB VCOM |
| `apps/chrg/applications/thread/` | 接收、轮询、Modbus 和 LCD 六个常驻业务线程 |
| `apps/chrg/applications/utils/` | Source/Sink 控制、功率板寄存器、协议编解码和通用工具 |
| `apps/chrg/board/` | 时钟、STM32 HAL、CubeMX 配置、驱动端口和链接脚本 |
| `apps/boot/` | 裸机 HAL Bootloader、YModem、固件校验/搬运和 Keil 工程 |
| `libs/` | CMSIS、STM32F4 HAL 和共享驱动 |
| `rt-thread/` | 随仓库维护的 RT-Thread 5.2.2 源码，不应随意做产品级改动 |
| `docs/` | 原理图、引脚表、通信协议、HMI 和调试资料 |
| `bin_pack/` | 升级包及 YModem 相关工具资料 |

## 通信接口与线程

主程序中的接口配置如下：

| 接口 | 波特率 | 作用 |
| --- | ---: | --- |
| UART1 | 115200, 8N1 | `thr.comm`：上位机 Modbus RTU 服务 |
| UART2 | 921600 | `thr.lcd`：HMI 收发；RT-Thread 初始控制台配置也指向 UART2 |
| UART3 | 230400 | `thr.nor`：快充协议板接收，`thr.rollnor` 负责轮询发送 |
| UART6 | 115200 | `thr.sou`：功率板接收，`thr.rollsou` 负责轮询和批量写寄存器 |
| USB CDC | USB FS | 环境初始化后将 RT-Thread 控制台切换到 `vcom` |

六个业务线程由 `chrg_thread.c` 统一创建。接收线程通过邮箱传递已解析消息，两个轮询线程通过事件触发，公共数据由互斥锁保护。修改线程优先级、栈大小或 IPC 类型时，应同时检查实时性和内存占用。

Bootloader 与主程序的串口用途不同：UART1 以 115200 接收升级数据，UART2 以 115200 输出启动和升级日志。

## Flash 布局与启动流程

STM32F405 片内 1 MiB Flash 使用三固件分区方案：

| 分区 | 地址范围 | 大小 | 用途 |
| --- | --- | ---: | --- |
| `boot` | `0x08000000` - `0x0800FFFF` | 64 KiB | Bootloader |
| `param` | `0x08010000` - `0x0801FFFF` | 64 KiB | 参数 |
| `log` | `0x08020000` - `0x0803FFFF` | 128 KiB | 日志预留区 |
| `app` | `0x08040000` - `0x0807FFFF` | 256 KiB | 当前运行固件 |
| `download` | `0x08080000` - `0x080BFFFF` | 256 KiB | 待更新固件 |
| `factory` | `0x080C0000` - `0x080FFFFF` | 256 KiB | 出厂恢复固件 |

上电后 Bootloader 等待主机约 5 秒，检查升级请求和各分区固件状态；无升级任务且 `app` 校验通过时，设置向量表并跳转到 `0x08040000`。升级过程依次完成包头检查、擦除、写入、CRC/完整性校验和状态落盘，异常时可尝试从 `download` 或 `factory` 恢复。分区地址在 `apps/boot/application/include/app_config.h`、`apps/chrg/board/ports/fal_cfg.h` 和主程序链接脚本中必须保持一致。

## 开发环境

推荐环境：

- Windows 10/11；
- Keil MDK 5 和对应 STM32F4 Device Pack；
- Python 3、SCons，以及 ARM Compiler 5 或 `arm-none-eabi-gcc`；
- RT-Thread Env（需要图形化配置时使用）。

仓库不附带编译器，`apps/chrg/rtconfig.py` 中的默认 GCC 路径为 `/usr/bin`。Windows 开发机通常需要通过 `RTT_CC` 和 `RTT_EXEC_PATH` 指定实际工具链位置。

## 编译主程序

### Keil MDK

直接打开 `apps/chrg/chrg.uvprojx`，选择 `chrg` Target 后 Build。也可从仓库根目录执行：

```powershell
& 'C:\Keil_v5\UV4\UV4.exe' -b '.\apps\chrg\chrg.uvprojx'
```

源文件或 Kconfig 发生变化后，可重新生成 Keil 工程：

```powershell
Set-Location .\apps\chrg
$env:RTT_CC = 'keil'
$env:RTT_EXEC_PATH = 'C:\Keil_v5'
scons --target=mdk5
```

### SCons

```powershell
Set-Location .\apps\chrg
$env:RTT_CC = 'gcc'
$env:RTT_EXEC_PATH = 'C:\ArmGNU\bin' # 修改为本机路径
scons -j4
```

成功后生成 `chrg.elf` 和 `rtthread.bin`。常用辅助命令：

```powershell
scons --menuconfig # 修改 RT-Thread 功能配置
scons -c            # 清理 SCons 输出
scons --target=mdk5 # 重新生成 Keil MDK5 工程
```

配置入口包括 `apps/chrg/.config`、`defconfig`、`rtconfig.h` 和 `Kconfig`。修改配置后应检查生成文件差异，避免 `.config`、`defconfig` 与 `rtconfig.h` 长期不一致。

## 编译 Bootloader

Bootloader 当前使用独立 Keil 工程：

```powershell
& 'C:\Keil_v5\UV4\UV4.exe' -b '.\apps\boot\boot.uvprojx'
```

确认链接地址为 `0x08000000`、空间不超过 64 KiB，并在烧写前核对主程序仍链接到 `0x08040000`。不要把 `Objects/`、`build/`、`.axf`、`.bin`、`.hex` 或 `.map` 文件提交到 Git。

## 下载、调试与验证

1. 首次装机先烧写 Bootloader，再写入与 `app` 分区匹配的主固件或升级包。
2. 连接 USB CDC 后打开串口终端，可通过 MSH 查看线程、设备和内存状态；主程序提示符为 `chrg `。
3. 分别验证四个通道的在线状态、通道切换、源/载输出、继电器动作和测量回读。
4. 使用上位机验证 Modbus 读写、非法地址/功能码响应以及多寄存器写入的生效时序。
5. 升级相关修改至少覆盖正常升级、CRC 错误、中途断电、无有效 App 和 Factory 恢复场景。

仓库没有产品级自动化测试或覆盖率门槛。每次修改至少应完成受影响 Target 的全量编译，并在 STM32F405 实机记录固件版本、板卡版本、串口日志和测试结果。`rt-thread/tools/testcases/` 仅用于 RT-Thread 构建工具，不代表业务固件测试。

## 配置与安全注意事项

- Bootloader 的分区、包头、CRC、加密参数必须与升级包工具保持一致；任意一侧单独修改都会导致升级失败。
- 当前 Bootloader 源码包含开发阶段的静态 AES 配置。量产前应替换为受控密钥方案，禁止在公开日志、README 或提交信息中泄露生产密钥。
- 改动 Modbus 寄存器映射时同步更新 `chrg_regs.h`、上位机、HMI 和 `docs/` 协议文件，并说明兼容策略。
- `docs/` 中可能同时存在多个版本的协议资料，调试前应核对日期、板卡版本和 Source/Sink 方向。
- 仓库根目录未提供明确的开源许可证；对外分发源码、固件或第三方组件前，请先确认项目授权和各依赖许可证。

## 参与开发

编码规范、测试要求以及提交/合并请求约定见 [AGENTS.md](AGENTS.md)。提交前请检查 `git status`，只包含本次修改所需的源码和文档；协议、链接脚本、Flash 分区及升级兼容性变化必须在评审说明中单独列出。