# 安装与配网指南

本文说明如何在本机编译、烧录 ESP32-S3 固件，以及三种链路模式下的**首次配网**与**重新配网**。Android 协议细节见 [`Android端设备对接文档_v1.0.1.md`](Android端设备对接文档_v1.0.1.md)。

---

## 1. 环境准备

| 项 | 要求 |
|----|------|
| 芯片 | ESP32-S3 |
| ESP-IDF | **v5.5.x**（与团队 `.vscode/settings.json` 中 `idf.espIdfPathWin` 一致） |
| Flash | **16MB**（见 `partitions.csv`） |
| 系统 | Windows 10/11（下文以 PowerShell/CMD 为例） |

### 1.1 配置 ESP-IDF 环境

1. 安装 [ESP-IDF Windows 工具安装器](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32s3/get-started/windows-setup.html)，或确认本机已有 `esp\v5.5.x\esp-idf`。
2. 将用户环境变量 **`IDF_PATH`** 指向真实的 `esp-idf` 根目录（勿使用已删除的旧路径）。
3. 每次编译前激活环境（二选一）：
   - 开始菜单 → **「ESP-IDF 5.5 PowerShell」** / **CMD**
   - 项目目录执行：`call <IDF_PATH>\export.bat`（路径按本机修改）

若提示找不到 `idf.py`，参见 [`编译类型与UART模式配置指南.md`](编译类型与UART模式配置指南.md) §2.0。

### 1.2 克隆与进入工程

```bat
cd /d d:\myproject\esp32project\Android_control_driver
```

首次构建会由 `sdkconfig.defaults` 生成 `sdkconfig`；已存在 `sdkconfig` 时以本地保存的配置为准。

---

## 2. 选择链路模式（编译期三选一）

在 **`idf.py menuconfig`** → **`esp32s3_MYSDK`** → **链路模式** 中三选一。**同一时间仅一种模式编入固件**。

| 模式 | menuconfig | 与 Android 通信 | 仓库默认（`sdkconfig.defaults`） |
|------|------------|-----------------|----------------------------------|
| WiFi + MQTT | `APP_LINK_WIFI` | 路由器 + MQTT | 否 |
| BLE | `APP_LINK_BLE` | NimBLE GATT | 否 |
| **UART 串口** | `APP_LINK_UART` | UART1：GPIO17=TX、GPIO18=RX | **是** |

切换模式后建议：

```bat
idf.py fullclean
idf.py build
```

> **注意**：`APP_LINK_UART`（业务串口 GPIO17/18）与 **UART0 调试口**（GPIO43/44，下载/日志）不是同一路。调试口说明见 [`编译类型与UART模式配置指南.md`](编译类型与UART模式配置指南.md)。

---

## 3. 编译与开发烧录

### 3.1 编译

```bat
cd /d d:\myproject\esp32project\Android_control_driver
idf.py build
```

**Release 量产构建**（可选）：

```bat
idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.defaults.release" build
```

### 3.2 USB 串口烧录（开发推荐）

```bat
idf.py -p COM16 flash monitor
```

| 命令 | 说明 |
|------|------|
| `idf.py -p COM16 flash` | 烧录 bootloader + 分区表 + 应用 + **SPIFFS（配网页）** |
| `idf.py -p COM16 flash_app` | 仅烧应用（**不更新** `www` 配网页，改 HTML 后勿单独用这个） |
| `idf.py -p COM16 erase_flash` | 擦除整片（清空 NVS，会重新进配网） |

**进下载模式**：按住 **BOOT** → 按 **RESET** → 松开 **BOOT**；部分开发板可自动进入。

烧录失败时请检查：数据线、COM 口、驱动、是否被占用。

### 3.3 修改配网页后

配网 UI 来自 `www/`，经 CMake 打入 SPIFFS 分区 `storage`（`main/CMakeLists.txt` 中 `spiffs_create_partition_image`）。

修改 `www/index*.html` 后须 **完整 `idf.py build` + `flash`**（或至少包含 `storage.bin` 的烧录），仅 `flash_app` **不会**更新配网页。

---

## 4. 配网（SoftAP + 网页）

三种模式在缺少必填 NVS 时，都会开启 **SoftAP 热点**（SSID 默认 `esp32-apconfig`，可在 menuconfig **`ROBIOT WIFI SSID`** 修改）。

- 连接热点后，系统应 **自动弹出**「需登录网络 / 认证」页（Captive Portal）；固件对 `generate_204` 等检测 URL 返回 **302** 到配网页（**勿再返回 204**，否则 Android 认为已联网不弹窗）。
- 若未自动弹出：关移动数据，浏览器手动打开 **http://192.168.4.1**（设备 DNS 劫持任意域名到 `192.168.4.1`）。

### 4.1 各模式配网页与必填项

| 链路模式 | SPIFFS 页面 | 页面上需填写 | 写入 NVS |
|----------|-------------|--------------|----------|
| **WiFi** | `www/index.html` | WiFi 名称、WiFi 密码、设备 ID | `wifi_ssid`、`wifi_pass`、`device_id` |
| **BLE** | `www/index_ble.html` | 设备 ID、蓝牙广播名 | `device_id`、`ble_adv_name` |
| **UART** | `www/index_uart.html` | **仅设备 ID** | `device_id` |

**UART / BLE 模式说明**：

- 热点仅用于**写入 NVS**，不是让设备长期连路由器。
- **UART 模式**配网页**不出现** WiFi 名称/密码；正常运行时不启 BLE、不连 STA。
- 提交表单后设备约 1.5s 后自动重启。

### 4.2 何时自动进入配网

| 模式 | 条件 |
|------|------|
| WiFi | NVS 无 `wifi_ssid` |
| BLE | `device_id` 或 `ble_adv_name` 为空 |
| UART | `device_id` 为空 |

### 4.3 运行时再次进入配网（按键）

| 模式 | 操作 |
|------|------|
| **UART** | **GPIO4** 长按约 **2 秒** → 开热点，仅可改 **设备 ID** |
| **WiFi** | **GPIO0** 长按约 2 秒 → 可改 WiFi + 设备 ID；**GPIO4** → 仅设备 ID |
| **BLE** | **GPIO0** 或 **GPIO4** 长按约 2 秒 → 可改设备 ID / 蓝牙名（逻辑见 `wifidevnum_config.c`） |

UART 模式下进入配网时会暂停 UART1 业务通信，配网完成后重启恢复。

---

## 5. 量产烧录（无需本地编译）

产线或测试人员可直接使用仓库内已编译包，无需安装 ESP-IDF：

1. 打开 [`firmware/README.md`](../firmware/README.md)。
2. 下载 `firmware/release/factory/` 下全部 `.bin`。
3. 使用 **乐鑫 Flash Download Tools**，按 `flash_args.txt` 地址烧录（含 `storage.bin` 配网页）。

维护者更新发布包：

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

核对 `firmware/release/VERSION.txt` 后再提交 Git。

---

## 6. 烧录后自检

| 模式 | 建议检查 |
|------|----------|
| **UART** | 串口 115200/8/N/1；GPIO17→模块 RX、GPIO18→模块 TX；能收到心跳 JSON；`device_id` 与 App 一致 |
| **BLE** | 能扫描到 `ble_adv_name` + 后缀 `MP`；GATT 0xFFE1 可写 JSON |
| **WiFi** | 串口日志见 STA 获 IP；MQTT 订阅成功 |

协议与引脚详见 [`Android端设备对接文档_v1.0.1.md`](Android端设备对接文档_v1.0.1.md)。

---

## 7. 常见问题

| 现象 | 处理 |
|------|------|
| UART 模式热点里仍有 WiFi 输入框 | 固件未按 `APP_LINK_UART` 编译，或 SPIFFS 未更新 → `menuconfig` 选 UART 后 `fullclean` + `build` + `flash` |
| 改了 `www` 但网页不变 | 勿只用 `flash_app`；需完整烧录含 `storage` 的镜像 |
| 连热点不自动弹配网页 | 刷含 captive 302 修复的固件；关移动数据；仍不行则手动 **http://192.168.4.1** |
| `idf.py` 找不到 | 检查 `IDF_PATH` 与 `export.bat` |
| 切换链路模式后行为异常 | `idf.py fullclean` 后重新 `build` |

---

**文档版本**：1.1  
**最后更新**：2026年5月
