# PY32F040 OTA 开发框架

基于 PY32F040 的 OTA 双工程开发框架。**Bootloader 与 App 是两个独立的 Keil 工程**，
共用顶层 `Shared/`（OTA 契约）与 `Drivers/`（厂商 SDK）。

支持三种可配置 OTA 模式（`Shared/ota_config.h`）：

| 模式 | 说明 |
|------|------|
| 单备份 | BAK 下载 → 校验 → 拷贝覆盖主区，最省 Flash |
| 双备份 + RAM | A/B 交换，新固件崩溃可自动回滚 |
| 双备份 + 暂存区 | A/B 交换 + Flash scratch，升级最快、掉电恢复最稳 |

协议对接 jb_protocol（0x30/0x32/0x34），用户层在 `Protocol/jb_product.c` 对接。

详细设计见 [`Doc/OTA_AB_双备份升级设计.md`](Doc/OTA_AB_双备份升级设计.md)。

---

## 目录结构

```
PY32F040开发框架/
├── App/                 APP 工程（链接 0x08003000）
│   ├── Src/             main.c / application.c / system_py32f040.c
│   ├── Core/            ota_ab / iwdg / app_boot / jb_uart 等
│   ├── Protocol/        jb_protocol + jb_product（协议与用户层）
│   ├── Utils/
│   └── MDK-ARM/         project.uvprojx
├── Bootloader/          Bootloader 工程（链接 0x08000000）
│   ├── Src/             boot_main.c
│   ├── Code/            flash.h（实现见 Shared/flash.c）
│   └── MDK-ARM/         Bootloader.uvprojx
├── Drivers/             厂商 HAL/CMSIS（只读，勿改）
├── Shared/              OTA 契约【单一真源】
│   ├── ota_config.h     三模式配置入口
│   ├── flash.c          状态区读写
│   ├── crc32.c/h        固件 CRC32
│   ├── iwdg_config.h    看门狗超时参数
│   └── log.h
├── tools/               构建与打包脚本
├── Output/              构建产物（git 忽略）
└── Doc/                 设计文档
```

两工程通过 `..\..\Shared`、`..\..\Drivers` 引用共享层，**彼此零依赖**。

---

## 快速开始

### 环境要求

- Keil MDK（含 PY32F040 器件包）
- Python 3（用于 `tools/` 脚本，可选）

### 1) 一键构建

```bat
build.bat
```
或
```bat
python tools\build_all.py
```

产物输出到 `Output/`：

- `bootloader.hex|bin` — 0x08000000
- `app.hex|bin` — 0x08003000
- 末尾打印 `app.bin` 的 **fwCrc32**（0x30 请求需携带）

### 2) Keil 单独打开

| 工程 | 工程文件 |
|------|----------|
| Bootloader | `Bootloader/MDK-ARM/Bootloader.uvprojx` |
| App | `App/MDK-ARM/project.uvprojx` |

### 3) 修改 OTA 模式

只改 `Shared/ota_config.h` 中的 `OTA_BACKUP_MODE` / `OTA_SWAP_STRATEGY`，
然后重新构建两工程（无需手动同步两份代码）。

### 4) 打包发给用户

```bat
tools\pack_bootloader.bat   → Output\bootloader_package.zip
tools\pack_app.bat          → Output\app_package.zip
```

zip 内布局：`Bootloader|App/` + `Drivers/` + `Shared/` 平级。
对方解压后直接用 Keil 打开 `.uvprojx` 即可编译（已剔除 `.o/.d` 等中间产物）。

> 需解压整个 zip，保持相对目录结构，不要只拷贝子文件夹。

### 5) 出厂烧录

```bat
python tools\merge_hex.py   → Output\merged_single.hex
```

合并 Bootloader + App 为单一 hex。纯 OTA 远程升级只需 `app.bin`。

---

## 关键注意点

- **Shared/ 是唯一真源**：改 OTA 布局/状态机只改此处；`flash.h` 两工程各有一份（适配各自头文件路径）。
- **Drivers/ 只读**：厂商 SDK，两工程共用，勿修改。
- **链接地址**：由 Keil Target → ROM1（`OCR_RVCT4`）决定，须与 `Shared/ota_config.h` 的 `OTA_RUN_ADDR_BASE`（0x08003000）一致。
- **`.bat` 脚本保持纯 ASCII**：cmd 按 GBK 解析，含中文可能乱码。
- **IWDG**：Bootloader 跳转前启动看门狗；App 在 `app_boot.c` 中接管并喂狗，时钟配置不可关 LSI。

---

## 开发入口（常用文件）

| 目的 | 文件 |
|------|------|
| 改 OTA 模式/布局 | `Shared/ota_config.h` |
| OTA 下载逻辑 | `App/Core/ota_ab.c` |
| 协议 OTA 回调 | `App/Protocol/jb_product.c` |
| Bootloader 状态机 | `Bootloader/Src/boot_main.c` |
| App 启动流程 | `App/Core/app_boot.c` |
| 应用主循环 | `App/Src/application.c` |