Merge branch 'feature/android_initial_version' into 'master'

交接文档/Android_control_driver.md

+# Android_control_driver 项目交接文档
+# 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 清单逐项确认后签字。**