# Android_control_driver 项目交接文档

> 本文档为 **Android_control_driver**（固件项目名 `ESPRCCar`）项目的完整交接说明，覆盖项目概述、Git 仓库、目录结构、构建、烧录、OTA、配网、协议、设备扩展、维护流程与全部细节，请接手人员通读后即可独立开展后续开发与维护工作。

---

## 1. 项目基本信息

| 项 | 内容 |
|----|------|
| 项目名称（仓库名） | **Android_control_driver** |
| 固件工程名称（CMake project） | **ESPRCCar** |
| 当前固件版本 | **1.0.2**（来源于 `CONFIG_MY_APP_VERSION`，见 `sdkconfig.defaults` / `main/Kconfig.projbuild`） |
| 主控芯片 | **ESP32-S3**（16MB Flash） |
| 开发框架 | **ESP-IDF v5.5.1** |
| 主要语言 | C |
| 主要组件 | FreeRTOS、NimBLE、cJSON、SPIFFS、MQTT、HTTP Server、DNS Server |
| 当前默认链路模式 | **UART**（`CONFIG_APP_LINK_UART=y`） |
| 当前默认分支 | `feature/android_initial_version`（已推送到远端） |
| 主分支 | `master` |
| 仓库语言 | 中文 |

---

## 2. Git 仓库信息

### 2.1 远端地址

| 协议 | 地址 |
|------|------|
| HTTP（fetch / push） | **http://git.yd-ss.com/leimingyu/Android_control_driver.git** |

```
origin  http://git.yd-ss.com/leimingyu/Android_control_driver.git (fetch)
origin  http://git.yd-ss.com/leimingyu/Android_control_driver.git (push)
```

> 接手人员需联系管理员开通该 Git 仓库（GitLab/Gitea）账号并加入对应权限组，获取 push 权限。

### 2.2 分支结构

| 分支 | 说明 | 是否在远端 |
|------|------|------------|
| `master` | 主干（稳定发布） | 是（`origin/master`，且为远端默认分支 HEAD） |
| `feature/android_initial_version` | Android 对接初版开发分支（**当前工作分支**） | 是 |

### 2.3 提交历史（截至交接日 2026-07-30）

```
f51b8cf  2026-07-30  release                                       (95744)
76e8da9  2026-07-08  bug修改完，串口通信                              (95744)
5eb7707  2026-06-06  第二次提交修改bug，第一版问题还在                  (95744)
8f3a151  2026-05-28  Initial commit                                (95744)
```

提交人统一为 `95744 <1712248550@qq.com>`。

### 2.4 克隆命令

```bat
git clone http://git.yd-ss.com/leimingyu/Android_control_driver.git
cd Android_control_driver
git checkout feature/android_initial_version
```

克隆完成后 **不要**直接编译，需先按 §5 完成 ESP-IDF 环境准备，再执行 `idf.py reconfigure`。

---

## 3. 项目用途与核心特性

本项目是基于 **ESP32-S3** 的设备控制固件，**编译期三选一**链路模式（未选中的链路代码不会编入固件），同一份代码可分别烧出 WiFi / BLE / UART 三个版本：

| 模式 | menuconfig 选项 | 配网页 | 通信方式 | OTA 方式 |
|------|-----------------|--------|----------|----------|
| **WiFi + MQTT** | `APP_LINK_WIFI` | `index.html`（WiFi SSID/密码 + 设备 ID） | STA + MQTT JSON | HTTPS |
| **BLE** | `APP_LINK_BLE` | `index_ble.html`（设备 ID + 蓝牙广播名） | NimBLE GATT JSON | 0xFFE2 二进制流 |
| **UART** | `APP_LINK_UART` | `index_uart.html`（**仅设备 ID**） | UART1（GPIO17 TX / GPIO18 RX）JSON + `\n` | 与 BLE 相同协议 |

设备控制指令统一由 `remote_control` 模块处理（位于 `main/protocol/remote_control.c`），与链路解耦。

### 3.1 关键特性

- **三链路编译期可选**：互斥 `choice`，未选中的源码不编入固件，减小体积。
- **FreeRTOS 任务统一管理**：任务表集中在 `main/core/task_manager.c`，业务模块通过 `app_task_start(APP_TASK_xxx, ...)` 启动，避免散落 `xTaskCreate`。
- **设备策略可扩展**：内核分层（core / drivers / protocol / link / app），新车型只需新增 `device_xxxx.c` 并注册。
- **Debug / Release 双构建**：Release 模式 UART0 完全静默，仅通过业务通道（BLE 0xFFE3 / UART1 JSON）上报 W/E。
- **量产发布包内置于仓库**：`firmware/release/` 含 OTA / factory 全套 bin，产线/Android 端无需克隆仓库本地编译。
- **BLE GATT OTA**：手机端可分包推送固件到 0xFFE2，设备写入 OTA 分区后自动重启切换。

---

## 4. 目录结构总览

```
Android_control_driver/
├── main/                          ← 固件源码
│   ├── main.c                     ← 入口，仅调用 app_run()
│   ├── ota.c / ota.h              ← OTA 入口（兼容老接口）
│   ├── ota_binary_stream.c/.h     ← BLE/UART 二进制流 OTA
│   ├── ota_manager.c/.h           ← OTA 总管理
│   ├── CMakeLists.txt
│   ├── Kconfig.projbuild          ← 项目 menuconfig 配置项
│   ├── idf_component.yml
│   ├── app/
│   │   ├── app_run.c/.h           ← 应用主流程 app_run()
│   │   ├── example_uart_comm_usage.c    ← UART0 通信示例
│   │   └── example_uart_link_usage.c    ← UART1 链路示例
│   ├── core/
│   │   ├── build_config.h         ← 编译期宏集中
│   │   ├── system_init.c/.h       ← NVS/SPIFFS/事件循环 初始化
│   │   └── task_manager.c/.h      ← FreeRTOS 任务统一表
│   ├── device/
│   │   ├── device_model.c/.h      ← 设备型号选择
│   │   └── device_nvs.h            ← 设备配置 NVS 键
│   ├── drivers/
│   │   ├── driver_manager/        ← 统一驱动初始化
│   │   ├── gpiotrol/               ← PWM/RC 车控制底座
│   │   │   ├── rc_pwm_control.c/.h ← 6 路 50Hz PWM + AUX 角色 + PID
│   │   │   ├── device_drive.h      ← 设备策略接口 (stop/control/shot)
│   │   │   ├── betteryread.c/.h    ← 电池电压读取
│   │   │   └── devices/
│   │   │       ├── 1101/           ← 1101 车型实现
│   │   │       └── 1102/           ← 1102 车型实现（含刹车 device_1102_brake）
│   │   └── uart_comm/              ← UART0 普通通信（Release 模式可选）
│   ├── link_common/
│   │   ├── link_dma_ble.c/.h       ← BLE DMA 收发底层
│   │   └── link_dma_uart.c/.h     ← UART DMA 收发底层
│   ├── link_ble/
│   │   └── link_ble.c/.h          ← NimBLE GATT 服务（仅 APP_LINK_BLE 编译）
│   ├── link_uart/
│   │   └── link_uart.c/.h          ← UART1 链路（仅 APP_LINK_UART 编译）
│   ├── link_wifi/
│   │   └── mqttconf_commun.c/.h   ← MQTT 连接/心跳/消息（仅 APP_LINK_WIFI 编译）
│   ├── protocol/                   ← 跨链路共用协议层
│   │   ├── remote_control.c/.h    ← 设备控制 JSON 解析与执行
│   │   ├── heart_payload.c/.h     ← 心跳负载构造
│   │   ├── ota_frame_protocol.c/.h ← OTA 数据帧协议
│   │   ├── ota_offer_protocol.c/.h ← OTA 询问/结果 JSON
│   │   └── ota_uart_tune.c/.h     ← UART OTA 调优参数
│   └── provision/
│       └── wifidevnum_config.c/.h ← SoftAP + HTTP + DNS 劫持配网门户
├── www/                            ← 配网页静态资源（SPIFFS 镜像来源）
│   ├── index.html                 ← WiFi 模式
│   ├── index_ble.html             ← BLE 模式
│   └── index_uart.html             ← UART 模式
├── docs/                           ← 项目文档（见 §10）
├── firmware/                       ← Git 发布固件包
│   ├── README.md
│   └── release/
│       ├── VERSION.txt             ← 版本信息
│       ├── manifest.json           ← 全量发布清单
│       ├── ota_manifest.json       ← Android OTA 机器可读 JSON
│       ├── Android端设备对接文档_v1.0.1.md
│       ├── Android端设备对接文档_v1.0.2.md
│       ├── ota/
│       │   └── ESPRCCar.bin        ← BLE/UART OTA 镜像（≤6MiB）
│       └── factory/                ← 量产烧录用
│           ├── ESPRCCar.bin
│           ├── bootloader.bin
│           ├── partition-table.bin
│           ├── ota_data_initial.bin
│           ├── storage.bin
│           └── flash_args.txt
├── scripts/
│   ├── copy_firmware_release.bat   ← Windows 发布复制脚本
│   └── copy_firmware_doc.ps1       ← PowerShell 文档复制脚本
├── build/                          ← 本地构建输出（不入 Git）
├── managed_components/             ← 组件依赖（idf.py 自动拉取，不入 Git）
├── 交接文档/                        ← 本交接文档目录
├── CMakeLists.txt                  ← 工程根 CMake（project(ESPRCCar)）
├── partitions.csv                  ← 分区表（双 OTA + SPIFFS）
├── sdkconfig.defaults              ← 默认配置（含链路模式、UART 引脚等）
├── sdkconfig.defaults.ble          ← BLE 模式覆盖
├── sdkconfig.defaults.release      ← Release 覆盖
├── sdkconfig                       ← menuconfig 生成（不入 Git）
├── dependencies.lock               ← 组件锁（不入 Git）
├── README.md                       ← 项目主 README
├── .clangd / .cursor / .vscode / .devcontainer  ← IDE 配置
└── .gitignore
```

### 4.1 关键源文件说明

| 文件 | 作用 |
|------|------|
| `main/main.c` | `app_main()` 入口，仅一行 `app_run()` |
| `main/app/app_run.c` | 应用主流程：系统初始化 → 驱动初始化 → 链路启动 → OTA 状态机 |
| `main/core/system_init.c` | NVS、SPIFFS、事件循环初始化 |
| `main/core/task_manager.c` | FreeRTOS 任务表集中管理（DNS、按键、心跳、MQTT、OTA、UART 等） |
| `main/protocol/remote_control.c` | 设备控制 JSON 协议统一解析与执行 |
| `main/drivers/gpiotrol/rc_pwm_control.c` | 6 路 50Hz PWM + AUX 角色选择 + PID 接口 + 策略分发 |
| `main/drivers/gpiotrol/device_drive.h` | 设备策略接口（`stop/control/shot`） |
| `main/provision/wifidevnum_config.c` | SoftAP 配网门户（含 DNS 劫持） |
| `main/link_ble/link_ble.c` | NimBLE GATT 服务（0xFFE1~0xFFE4） |
| `main/link_uart/link_uart.c` | UART1 链路实现 |
| `main/link_wifi/mqttconf_commun.c` | MQTT 连接、心跳、消息处理 |
| `main/ota_manager.c` | OTA 总入口（BLE / UART / HTTPS 共用） |

---

## 5. 开发环境搭建

### 5.1 必备工具

| 工具 | 版本/说明 |
|------|----------|
| ESP-IDF | **v5.5.1**（已验证版本） |
| Python | 3.8+（ESP-IDF 自带） |
| CMake | ≥3.16（ESP-IDF 自带） |
| Ninja | ESP-IDF 自带 |
| 编译器 | xtensa-esp32s3-elf（ESP-IDF 自带） |
| 操作系统 | Windows 10/11（开发机）；Linux/macOS 亦可 |
| IDE | VS Code / Cursor（推荐，已含 `.vscode` 配置） |
| Git | 任意现代版本 |

### 5.2 Windows 环境安装步骤

1. 安装 ESP-IDF v5.5.1 至 `C:\Users\<用户名>\esp\v5.5.1\esp-idf`（推荐路径，README 中默认使用）。
2. 运行 ESP-IDF 安装器，勾选 Python、CMake、Ninja、Git、xtensa 工具链。
3. 克隆本仓库（见 §2.4）。
4. 打开 **"ESP-IDF PowerShell"** 或 **"ESP-IDF CMD"**，或手动：
   ```bat
   cd /d C:\Users\17122\esp\v5.5.1\esp-idf
   call export.bat
   cd /d d:\myproject\esp32project\Android_control_driver
   ```
5. 首次编译前：
   ```bat
   idf.py reconfigure
   idf.py build
   ```

### 5.3 USB 驱动

ESP32-S3 开发板常见 USB 转串口芯片为 CH340/CP2102，安装对应驱动后出现 `COMx` 端口。本项目 README 默认示例使用 `COM16`，请按实际改动。

---

## 6. 构建与配置

### 6.1 链路模式切换（重要）

链路模式由 `sdkconfig.defaults` 中的 `CONFIG_APP_LINK_*` 决定，**当前默认为 UART**：

```
# CONFIG_APP_LINK_WIFI is not set
# CONFIG_APP_LINK_BLE is not set
CONFIG_APP_LINK_UART=y
```

切换方式：

1. **menuconfig 切换**（推荐手动调试）：
   ```bat
   idf.py menuconfig
   # → esp32s3_MYSDK → 链路模式（编译期三选一）
   ```
   切换后必须 `idf.py fullclean` 再 `build`，否则条件编译残留会导致行为异常。

2. **配置覆盖文件**（CI/CD 推荐）：使用 `sdkconfig.defaults.release` 等覆盖文件：
   ```bat
   idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.defaults.release" build
   ```

### 6.2 Debug / Release 构建

通过 `menuconfig` → `esp32s3_MYSDK` → **编译优化级别** 选择：

| 构建类型 | 优化级别 | 日志输出 | 适用场景 |
|----------|----------|----------|----------|
| **Debug** | -Og | 完整 ESP_LOG 输出到 UART0 | 开发调试 |
| **Release** | -Os | UART0 **完全静默**；W/E 经 BLE 0xFFE3 / UART1 JSON 上报 | 量产发布 |

Release 模式下 `sdkconfig.defaults.release` 关键项：
```
CONFIG_ROBO_APP_FW_RELEASE=y
CONFIG_ESP_CONSOLE_NONE=y
```

> **注意**：从 Debug 首次切换到 Release，若 `sdkconfig` 中日志级别仍为 INFO，请删除 `sdkconfig` 文件后重新 `menuconfig`，让 `select` 生效。

### 6.3 常用编译命令

```bat
:: 默认 Debug 构建（UART 链路）
idf.py build

:: Release 构建（CI/CD 推荐）
idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.defaults.release" build

:: 全清后重新编译（切换链路或构建类型后必须）
idf.py fullclean
idf.py build

:: 仅查看当前配置
idf.py menuconfig
```

### 6.4 关键 menuconfig 配置项（`main/Kconfig.projbuild`）

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `APP_LINK_MODE` | `APP_LINK_UART` | 链路模式三选一 |
| `MY_APP_VERSION` | `1.0.1`（sdkconfig.defaults 中改为 1.0.2） | 固件版本号 |
| `APP_DEBUG_UART_NUM` | `0` | 调试串口外设编号 |
| `APP_UART_LINK_BAUDRATE` | `115200` | UART 链路波特率（9600/115200/230400/460800/921600） |
| `APP_UART_LINK_TX_GPIO` | `17` | UART1 TX |
| `APP_UART_LINK_RX_GPIO` | `18` | UART1 RX |
| `APP_OTA_UART_MAX_CHUNK` | `1024` | UART OTA 单帧最大载荷（240~1024） |
| `APP_BLE_OTA` | `y`（依赖 BLE） | 启用 BLE GATT OTA |
| `APP_BLE_TX_POWER` | `-24 dBm` | BLE 发射功率（贴机推荐最低） |
| `APP_PWM_IO15_ROLE` | `ESC` | GPIO15 PWM 角色（舵机/电调） |
| `APP_PWM_IO16_ROLE` | `SERVO` | GPIO16 PWM 角色 |
| `ROBO_APP_FW_BUILD` | `Debug` | Debug/Release 选择 |
| `ROBIOT_WIFI_SSID` | `esp32-apconfig` | 配网热点名 |
| `ROBOIOT_MQTT_URL` | `0.0.0.0` | MQTT 服务器地址（需改实际地址） |

### 6.5 分区表（`partitions.csv`）

| 分区 | 类型 | 子类型 | 偏移 | 大小 |
|------|------|--------|------|------|
| nvs | data | nvs | 自动 | 0x6000 |
| otadata | data | ota | 自动 | 0x2000 |
| phy_init | data | phy | 自动 | 0x1000 |
| ota_0 | app | ota_0 | 自动 | 0x600000（6MiB） |
| ota_1 | app | ota_1 | 自动 | 0x600000（6MiB） |
| storage | data | spiffs | 自动 | 0x50000 |

Flash 总大小：**16MB**（`CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y`）。

### 6.6 烧录地址（factory 全量烧录）

| 文件 | 偏移 |
|------|------|
| `bootloader.bin` | `0x0` |
| `partition-table.bin` | `0x8000` |
| `ota_data_initial.bin` | `0xf000` |
| `ESPRCCar.bin` | `0x20000` |
| `storage.bin` | `0xc20000` |

Flash 参数：`dio` / `80m` / `16MB`。

---

## 7. 烧录方式

### 7.1 进入下载模式

- 按住 **BOOT** 键 → 按 **RESET** 键 → 松开 **BOOT** 键
- 或 ESP32-S3 某些开发板支持自动进下载模式

### 7.2 方式一：idf.py（开发阶段推荐）

```bat
:: 烧录应用 + 分区表 + bootloader
idf.py -p COM16 flash

:: 只烧应用（保留原分区表）
idf.py -p COM16 flash_app

:: 烧录并打开串口监控
idf.py -p COM16 flash_monitor

:: 仅监控
idf.py -p COM16 monitor
```

### 7.3 方式二：esptool.py（生产/离线）

```bat
:: 整片烧录
esptool.py --chip esp32s3 --port COM16 write_flash 0x0 build/ESPRCCar.bin

:: 按分区烧录
esptool.py --chip esp32s3 --port COM16 write_flash ^
    0x0    build/bootloader/bootloader.bin ^
    0x8000 build/partition_table/partition-table.bin ^
    0x20000 build/ESPRCCar.bin
```

### 7.4 方式三：乐鑫 Flash Download Tools（GUI，量产推荐）

加载 `firmware/release/factory/` 下各 `.bin`，地址见 `flash_args.txt`：
- `bootloader.bin` → `0x0`
- `partition-table.bin` → `0x8000`
- `ota_data_initial.bin` → `0xf000`
- `ESPRCCar.bin` → `0x20000`
- `storage.bin` → `0xc20000`

### 7.5 方式四：JTAG（调试）

- 使用 ESP-Prog 或 ESP32-S3 内置 USB JTAG
- `idf.py gdb` / `idf.py openocd`

---

## 8. OTA 升级

### 8.1 OTA 方式总览

| 方式 | 通道 | 文件 | 说明 |
|------|------|------|------|
| **BLE OTA** | 0xFFE2 | `firmware/release/ota/ESPRCCar.bin` | 手机 App 分包推送，写入 OTA 分区后重启 |
| **UART OTA** | UART1 | `firmware/release/ota/ESPRCCar.bin` | 与 BLE 协议相同，串口传输 |
| WiFi HTTPS | HTTPS | 服务器 URL | `APP_LINK_WIFI` 模式可用 |

### 8.2 BLE / UART OTA 流程（手机/主机端）

1. 连接设备 → 使能 0xFFE4 Notify（进度/状态）
2. 发送 `0x01` + 4 字节固件长度（小端）→ 开始
3. 循环发送 `0x02` + 数据包（每包 ≤511 字节，UART 模式默认 ≤1024）→ 数据
4. 发送 `0x03` → 结束，设备校验后自动重启切换 OTA 分区

> 详细协议见 `docs/Android端设备对接文档_v1.0.1.md` §3.4～§3.4.11（含 MTU、ATT 错误、排错）及 §5.7（Android 测试步骤）；UART 见 §7；WiFi/MQTT 见 §8。

### 8.3 OTA 注意事项

- OTA 文件必须是**应用镜像**（`.bin`），不是合并后的整片 flash 镜像。
- 文件大小必须 ≤ 分区表中的 OTA 分区大小（当前 6MiB）。
- BLE OTA 开关由 `APP_BLE_OTA` 控制（默认启用，仅 BLE 模式可见）。
- UART OTA 单帧最大载荷 `APP_OTA_UART_MAX_CHUNK` 默认 1024，须与 Android 发送缓冲一致。
- 双 OTA 分区自动切换，首次启动会写入 `ota_data_initial.bin` 决定从 ota_0 启动。

### 8.4 OTA 状态查询

通过 0xFFE4（BLE）或对应 UART JSON 字段：
- `message_type=1002`：OTA 询问/结果 JSON
- 心跳中可能携带 OTA 进度信息

---

## 9. 配网流程

### 9.1 三种模式配网页

| 模式 | 热点页 | 必填字段 |
|------|--------|----------|
| WiFi | `www/index.html` | WiFi SSID/密码 + 设备 ID |
| BLE | `www/index_ble.html` | 设备 ID + 蓝牙广播名 |
| UART | `www/index_uart.html` | **仅设备 ID** |

### 9.2 配网步骤（用户侧）

1. 设备进入配网模式（首次上电自动进入，或长按重置键）：
   - UART 模式：长按 **GPIO4** 约 2 秒可重新配网。
2. 手机连接热点 `esp32-apconfig`（默认名，可改 `ROBIOT_WIFI_SSID`）。
3. 浏览器打开 **http://192.168.4.1**（部分手机会自动弹出）。
4. 按模式填入字段 → 提交 → 设备保存到 NVS → 重启进入正常工作模式。

### 9.3 配网底层（开发侧）

- 实现：`main/provision/wifidevnum_config.c`
- 技术：SoftAP + HTTP Server + DNS 劫持（强制 `192.168.4.1` 跳转）
- 存储：NVS（键见 `main/device/device_nvs.h`）
- 静态资源：从 `storage` SPIFFS 分区读取（`www/` 镜像来源）

### 9.4 NVS 关键键

| 键（DEVICE_CFG_KEY_*） | 内容 |
|------------------------|------|
| `device_id` | 设备 ID |
| `wifi_ssid` / `wifi_password` | WiFi 凭据（仅 WiFi 模式） |
| `ble_adv_name` | BLE 广播名（仅 BLE 模式） |

---

## 10. 协议说明

### 10.1 设备控制 JSON（remote_control）

跨链路共用，BLE 走 0xFFE1，UART 走 UART1 JSON，WiFi 走 MQTT topic。

核心字段（详见 `docs/Android端设备对接文档_v1.0.1.md`）：
- `type`：指令类型（control / stop / shot 等）
- `device`：设备型号（1101 / 1102）
- 通道值：油门、转向、AUX 等

### 10.2 BLE GATT 服务（NimBLE）

| 通道 | 用途 |
|------|------|
| **0xFFE1** | UTF-8 JSON 控制通道（与 MQTT 共用 `remote_control`） |
| **0xFFE2** | OTA 固件二进制流（opcode：0x01 开始 / 0x02 数据 / 0x03 结束），受 `APP_BLE_OTA` 控制 |
| **0xFFE3** | 心跳（`message_type=1`，约 3s）+ 告警/错误（`4`/`5`，出现时即时 Notify） |
| **0xFFE4** | OTA 状态 JSON（Read + Notify，每包应答进度） |

详见 `docs/Android端设备对接文档_v1.0.1.md` §3.2 ~ §3.6。

### 10.3 UART 协议

- 物理层：UART1，GPIO17 TX / GPIO18 RX，默认 115200 8N1
- 链路层：JSON + `\n` 分隔
- OTA：与 BLE 共用 `ota_binary_stream` 协议（opcode 一致）

### 10.4 MQTT 协议（WiFi 模式）

- 服务器地址：`ROBOIOT_MQTT_URL`（默认 `0.0.0.0`，**部署前必须改**）
- 心跳：定期 JSON 上报
- 控制：订阅下行 topic，JSON 走 `remote_control`

---

## 11. 设备扩展指南（新增车型）

### 11.1 引脚约定（50Hz PWM）

| 通道 | GPIO | 默认角色 |
|------|------|----------|
| 驱动芯片1 A/B | IO10、IO21 | 主驱动 |
| 驱动芯片2 A/B | IO11、IO12 | 副驱动 |
| AUX1 | IO15 | 电调 ESC（`APP_PWM_IO15_ESC`，初始化 1500us） |
| AUX2 | IO16 | 舵机（`APP_PWM_IO16_SERVO`，初始化 90° / 1500us） |

> 1102 车型转向固定使用 IO16，必须设为 SERVO。

### 11.2 新增设备步骤

1. 新建 `main/drivers/gpiotrol/devices/<型号>/device_<型号>.c/.h`，实现 `device_<型号>_get_ops()`（接口见 `device_drive.h`：`stop/control/shot`）。
2. 在 `main/drivers/gpiotrol/rc_pwm_control.c` 的型号选择逻辑里增加映射。
3. 在 `main/CMakeLists.txt` 加入对应源码文件。
4. 在 `main/device/device_model.c` 中增加型号枚举（如需）。
5. 保持 `remote_control` 协议层不变，避免影响 App / BLE / WiFi 上层。

### 11.3 现有设备

| 型号 | 文件 | 说明 |
|------|------|------|
| 1101 | `devices/1101/device_1101.c` | 基础车型 |
| 1102 | `devices/1102/device_1102.c` + `device_1102_brake.c` | 含独立刹车逻辑 |

---

## 12. 文档索引（`docs/`）

| 文档 | 内容 |
|------|------|
| `安装与配网指南.md` | **安装必读**：环境、编译烧录、三种模式配网页与按键配网、量产包 |
| `Android端设备对接文档_v1.0.1.md` | **Android 必读**（固件 1.0.1）：WiFi/MQTT §8、BLE §2~§6、UART §7 |
| `Android端设备对接文档_v1.0.2.md` | Android 对接 v1.0.2（与当前固件版本对应） |
| `Android端蓝牙对接文档.md` | 旧名索引，已弃用，请改用 v1.0.1+ |
| `编译类型与UART模式配置指南.md` | Debug/Release 构建、UART0 调试口复用、日志配置 |
| `firmware/README.md` | Git 发布固件包说明（OTA / factory 烧录） |

---

## 13. 发布流程（维护者）

### 13.1 发版前 checklist

- [ ] 改 `main/Kconfig.projbuild` 与 `sdkconfig.defaults` 中 `CONFIG_MY_APP_VERSION` 至新版本号
- [ ] 选定链路模式（默认 UART，按需切换）
- [ ] 选定构建类型（Debug / Release）
- [ ] `idf.py fullclean && idf.py build`
- [ ] 烧录到测试机验证功能（控制 / 配网 / OTA / 心跳）
- [ ] 更新 `docs/Android端设备对接文档_v<x.x.x>.md`（如协议有变）
- [ ] 更新 `README.md` 与本交接文档（如有结构变化）

### 13.2 更新发布包

```bat
idf.py build
scripts\copy_firmware_release.bat
```

脚本会刷新：
- `firmware/release/VERSION.txt`（人类可读：版本、时间、SHA256、大小）
- `firmware/release/ota_manifest.json`（Android OTA 机器可读）
- `firmware/release/manifest.json`（全量发布清单）
- `firmware/release/factory/*.bin`（量产烧录用）
- `firmware/release/ota/ESPRCCar.bin`（OTA 镜像）
- 同步 `docs/Android端设备对接文档_v<x.x.x>.md` 到 `firmware/release/`

> **脚本不会执行任何 git 命令**，Git 提交由维护者手动操作。

### 13.3 Git 提交规范

当前仓库提交信息较简洁（如 `release`、`bug修改完，串口通信`），建议后续采用约定式提交：

```
<type>(<scope>): <subject>

<body>
```

- type：`feat` / `fix` / `docs` / `refactor` / `chore` / `release`
- scope：`ble` / `uart` / `wifi` / `ota` / `driver` / `protocol` / `provision` 等
- 例：`feat(ble): 增加 0xFFE3 错误码 6 上报`、`fix(uart): 修复 OTA 分包丢包重试`

### 13.4 旧版本管理

按用户偏好：**新版本占据官方目录，旧版本重命名加版本号归档**（如 `Android端设备对接文档_v1.0.1.md` 与 `v1.0.2.md` 并存）。

---

## 14. 常见问题与排错

### 14.1 编译类

| 现象 | 原因 / 解决 |
|------|-------------|
| 切换链路模式后行为异常 | 必须 `idf.py fullclean` 再 `build`，条件编译残留导致 |
| 首次切 Release 日志级别没变 | 删除 `sdkconfig` 后重新 `menuconfig`，让 `select` 生效 |
| `managed_components` 缺失 | 首次 `idf.py reconfigure` 会自动拉取，需联网 |
| 找不到 `app_run.h` | 检查 `main/CMakeLists.txt` 是否包含新增源文件目录 |

### 14.2 烧录类

| 现象 | 原因 / 解决 |
|------|-------------|
| 串口连接失败 | 检查数据线（是否数据线而非充电线）、端口号、BOOT/RESET 进入下载模式 |
| 烧录后无日志 | Release 模式 UART0 静默，属正常；切回 Debug 或看 BLE 0xFFE3 / UART1 |
| `esptool` 报 `Failed to connect` | 按住 BOOT → 按 RESET → 松开 BOOT，再重试 |

### 14.3 运行类

| 现象 | 原因 / 解决 |
|------|-------------|
| 配网页打不开 | 检查是否连上 `esp32-apconfig` 热点；浏览器输 `http://192.168.4.1` |
| UART 通信乱码 | 波特率不匹配（默认 115200）；检查 `APP_UART_LINK_BAUDRATE` 与 Android 端一致 |
| BLE 连接后无心跳 | 检查 0xFFE3 Notify 是否使能；BLE 发射功率 `APP_BLE_TX_POWER` 是否过低 |
| OTA 卡在 0% | 0xFFE2 未收到 0x01 开始帧；或固件大小超 6MiB；或文件不是应用镜像 |
| 设备不识别车型 | `device_model` 未匹配；新增车型需在 `rc_pwm_control.c` 注册 |

### 14.4 日志类（Release 静默策略）

按用户偏好：**Release 版本仅保留 error 和 warning 日志**，通过业务通道（BLE 0xFFE3 / UART1 JSON）上报，UART0 完全静默。如需调试：

1. 临时切回 Debug 构建：`menuconfig` → `esp32s3_MYSDK` → 编译优化级别 → Debug
2. 或在 Release 下手动启用 UART0 通信模式（见 `docs/编译类型与UART模式配置指南.md`）

---

## 15. 依赖与外部组件

### 15.1 managed_components（idf.py 自动拉取）

| 组件 | 用途 |
|------|------|
| `espressif__cJSON` | JSON 解析与生成（设备控制协议、OTA 状态、心跳） |

其他 ESP-IDF 内置组件：`freertos`、`nvs_flash`、`spiffs`、`esp_wifi`、`esp_event`、`esp_http_server`、`mqtt`、`bt`（NimBLE）、`driver`、`esp_timer`、`esp_app_desc` 等。

### 15.2 锁文件

- `dependencies.lock`：组件版本锁（**不入 Git**，本地生成）
- `managed_components/`：组件源码（**不入 Git**，自动拉取）

---

## 16. IDE 与开发体验

### 16.1 VS Code / Cursor

仓库已含 `.vscode/`、`.cursor/`、`.clangd` 配置：
- clangd 索引：使用 `compile_commands.json`（`idf.py build` 后生成于 `build/`）
- 任务集成：可使用 IDE 内置 ESP-IDF 插件

### 16.2 Dev Container（可选）

`.devcontainer/` 提供基于 Docker 的 ESP-IDF 编译环境，**非必须**，本地安装 ESP-IDF 即可。

### 16.3 代码风格

- 缩进：4 空格
- 命名：snake_case（C 函数/变量）；宏 UPPER_CASE
- 模块前缀：`app_`、`link_`、`device_`、`rc_`、`ota_` 等
- 日志：使用 `ESP_LOGI/W/E`，模块 tag 集中定义

---

## 17. 任务管理（FreeRTOS）

### 17.1 任务表（`main/core/task_manager.c`）

业务模块**禁止直接 `xTaskCreate`**，统一通过：

```c
app_task_start(APP_TASK_xxx, task_entry, arg, &handle);
```

### 17.2 已纳管任务

- DNS（配网门户劫持）
- 按键监控（GPIO4 长按重置）
- BLE 心跳
- MQTT 心跳 / MQTT 初始化 / MQTT 异常监控
- OTA 信息延迟上报
- UART 通信示例
- NimBLE Host（通过 `app_task_start_nimble_host()`）

### 17.3 任务参数

任务名、栈大小、优先级、核心绑定（ESP32-S3 双核）均集中在任务表中维护，修改时只改一处。

---

## 18. 安全与发布注意事项

1. **MQTT 服务器地址**：`ROBOIOT_MQTT_URL` 默认 `0.0.0.0`，发布前**必须改**为生产服务器。
2. **WiFi 配网热点**：默认 `esp32-apconfig`，建议发布时改独特名避免冲突。
3. **Git 提交**：`build/`、`managed_components/`、`sdkconfig`、`dependencies.lock` 不入 Git（已在 `.gitignore`）；`firmware/release/` 入 Git。
4. **密钥/证书**：如有 MQTT TLS 证书或私有密钥，**不要**提交到仓库，使用 menuconfig 内嵌或 NVS 烧录。
5. **OTA 镜像校验**：发布前核对 `firmware/release/VERSION.txt` 中的 SHA256 与 `ota_manifest.json` 一致。
6. **Release 静默**：量产固件 UART0 无日志输出属正常，调试需切 Debug。

---

## 19. 交接清单

接手人员请逐项确认：

### 19.1 代码与仓库
- [ ] 已克隆仓库 `http://git.yd-ss.com/leimingyu/Android_control_driver.git`
- [ ] 已切换到 `feature/android_initial_version` 分支
- [ ] 已开通 push 权限
- [ ] 已阅读 `README.md`、本交接文档、`docs/安装与配网指南.md`
- [ ] 已阅读 `docs/Android端设备对接文档_v1.0.1.md` 与 `v1.0.2.md`

### 19.2 环境
- [ ] ESP-IDF v5.5.1 已安装
- [ ] `idf.py --version` 可正常输出版本
- [ ] USB 驱动已安装，开发板识别为 COMx
- [ ] 首次 `idf.py build` 成功

### 19.3 烧录与运行
- [ ] Debug 版本烧录成功并看到 UART0 日志
- [ ] Release 版本烧录成功（UART0 静默）
- [ ] 三种链路模式各烧录验证一次（WiFi / BLE / UART）
- [ ] 配网流程跑通（手机连热点 → 浏览器配置 → 设备重启）

### 19.4 功能验证
- [ ] 设备控制（stop / control / shot）正常
- [ ] 心跳上报正常（BLE 0xFFE3 / UART JSON / MQTT）
- [ ] OTA 升级跑通一次（BLE 或 UART）
- [ ] 1101 / 1102 两车型控制正常

### 19.5 发布流程
- [ ] 理解 `scripts/copy_firmware_release.bat` 作用
- [ ] 理解 `firmware/release/` 目录结构
- [ ] 知道如何改版本号（`CONFIG_MY_APP_VERSION`）
- [ ] 知道如何切换 Debug / Release
- [ ] 知道如何新增车型（§11）

### 19.6 资产清单

| 资产 | 位置 | 状态 |
|------|------|------|
| 源代码 | Git 仓库 `main/` 等 | 已提交 |
| 发布固件 | `firmware/release/` | 已提交，当前 v1.0.2 |
| Android 对接文档 | `docs/` + `firmware/release/` | v1.0.1 / v1.0.2 |
| 安装与配网指南 | `docs/安装与配网指南.md` | 已提交 |
| 本交接文档 | `交接文档/Android_control_driver.md` | 本次新增 |
| 测试设备 | ESP32-S3 开发板 + 1101/1102 车型 | 实物交接 |

---

## 20. 联系人

| 角色 | 名字 | 联系方式 | 说明 |
|------|------|----------|------|
| 原开发者 / 交接方 | 95744 | 1712248550@qq.com（Git 提交邮箱） | 项目原作者，所有提交均出自此账号 |
| Git 仓库管理员 | — | 联系 `git.yd-ss.com` 平台管理员 | 账号开通、权限分配 |
| Android 对接方 | — | 见 Android 端项目组 | 协议联调 |

> 接手后请将本节"原开发者"保留为咨询对象，并补充接手人员信息。

---

## 21. 后续建议（非强制）

1. **提交规范**：采用约定式提交（feat / fix / docs / release），便于追溯。
2. **CI/CD**：可接入 GitLab CI，使用 `sdkconfig.defaults.release` 自动构建 Release 包。
3. **单元测试**：当前无单元测试，建议对 `protocol/remote_control.c`、`ota_frame_protocol.c` 增加主机侧测试。
4. **静态分析**：可启用 `clang-tidy` / `cppcheck`，仓库已含 `.clangd`。
5. **MQTT TLS**：生产环境建议启用 TLS 并使用证书而非明文。
6. **版本号自动化**：`CONFIG_MY_APP_VERSION` 与 `firmware/release/VERSION.txt` 当前手动维护，可脚本化联动 git tag。
7. **多设备抽象**：若后续车型增多，可考虑将 `devices/` 改为组件化（每个车型一个独立 idf_component）。

---

## 22. 变更记录

| 日期 | 版本 | 变更说明 | 作者 |
|------|------|----------|------|
| 2026-05-28 | 1.0.0 | Initial commit | 95744 |
| 2026-06-06 | 1.0.1 | 第二次提交修改bug | 95744 |
| 2026-07-08 | 1.0.1 | bug修改完，串口通信 | 95744 |
| 2026-07-30 | 1.0.2 | release（当前版本） | 95744 |
| 2026-07-30 | — | 新增本交接文档 | — |

---

## 附录 A：常用命令速查

```bat
:: ===== 环境 =====
cd /d C:\Users\17122\esp\v5.5.1\esp-idf
call export.bat
cd /d d:\myproject\esp32project\Android_control_driver

:: ===== 配置 =====
idf.py menuconfig
idf.py reconfigure

:: ===== 编译 =====
idf.py build
idf.py fullclean
idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.defaults.release" build

:: ===== 烧录 =====
idf.py -p COM16 flash
idf.py -p COM16 flash_app
idf.py -p COM16 flash_monitor
idf.py -p COM16 monitor

:: ===== esptool 离线烧录 =====
esptool.py --chip esp32s3 --port COM16 write_flash 0x0 build/ESPRCCar.bin

:: ===== 发布包 =====
scripts\copy_firmware_release.bat

:: ===== Git =====
git clone http://git.yd-ss.com/leimingyu/Android_control_driver.git
git checkout feature/android_initial_version
git pull
git status
git log --oneline -10
```

## 附录 B：关键文件路径速查

| 用途 | 路径 |
|------|------|
| 入口 | `main/main.c` → `main/app/app_run.c` |
| 链路选择 | `sdkconfig.defaults`（`CONFIG_APP_LINK_*`） |
| menuconfig 项 | `main/Kconfig.projbuild` |
| 分区表 | `partitions.csv` |
| 设备策略接口 | `main/drivers/gpiotrol/device_drive.h` |
| PWM 底座 | `main/drivers/gpiotrol/rc_pwm_control.c` |
| 协议解析 | `main/protocol/remote_control.c` |
| 任务表 | `main/core/task_manager.c` |
| 配网门户 | `main/provision/wifidevnum_config.c` |
| BLE 服务 | `main/link_ble/link_ble.c` |
| UART 链路 | `main/link_uart/link_uart.c` |
| MQTT | `main/link_wifi/mqttconf_commun.c` |
| OTA 总入口 | `main/ota_manager.c` |
| OTA 二进制流 | `main/ota_binary_stream.c` |
| 发布固件 | `firmware/release/` |
| 配网页 | `www/index*.html` |

## 附录 C：Git 仓库元数据

```
仓库地址:    http://git.yd-ss.com/leimingyu/Android_control_driver.git
默认分支:    master
工作分支:    feature/android_initial_version
首次提交:    2026-05-28 (8f3a151)
最新提交:    2026-07-30 (f51b8cf) - release
提交者:      95744 <1712248550@qq.com>
当前固件版本: 1.0.2
芯片:        ESP32-S3 (16MB Flash)
框架:        ESP-IDF v5.5.1
```

---

**交接完成，请接手人员按 §19 清单逐项确认后签字。**
