# esp32c3

**Repository Path**: imzack/esp32c3

## Basic Information

- **Project Name**: esp32c3
- **Description**: 使用 esp32c3 super mini 做一些 iot 设备
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-15
- **Last Updated**: 2026-01-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32‑C3 SuperMini BLE 控制 + Wi‑Fi 配网 + OTA 平台（端到端示例）

本仓库是一个从固件到 App 再到 OTA 平台的端到端示例：手机通过 BLE 连接 ESP32‑C3 SuperMini，控制 PWM（风扇）与环境光，并可通过 BLE 下发 Wi‑Fi 配网，最后由本地 OTA 平台托管固件并让设备走 HTTP OTA 升级。

## 包含内容

- 设备端（Arduino / ESP32‑C3）：`bleborder/`
  - BLE GATT（加密 + Bonding）
  - PWM（GPIO2）控制 + 状态回读 + 定时/计划任务
  - 环境光（WS2812）控制 + 状态回读
  - Wi‑Fi 扫描/配网（由 App 通过 BLE 下发 SSID/密码，设备自行连接路由器）
  - OTA：设备连上 Wi‑Fi 后，从 OTA 平台下载 `.bin` 并升级
- iOS Apps（SwiftUI + CoreBluetooth）：`iosapp/`
  - `iosapp/esp32c3pwm/`：较小的 PWM 控制示例
  - `iosapp/pwmfan/`：完整 App（含 Wi‑Fi 配置、OTA 升级、Widget）
- Android App（Compose）：`Androidapp/`
- OTA 平台（前后端）：`ota-platform/`
  - `ota-platform/backend/`：Express + Prisma(SQLite)，固件上传/稳定版/设备列表/OTA 历史
  - `ota-platform/frontend/`：Vite + React（中文 UI），管理与看板
- 协议/原型文档：`docs/`
  - `docs/esp32c3_pwm_ble_function_spec.md`：PWM v2 协议与验收（仅 PWM 主线，Wi‑Fi/OTA 以代码为准）

## 功能概览

- PWM（GPIO2）
  - 频率：`1 kHz` ~ `100 kHz`
  - 占空比：`1%` ~ `99%`
  - 实时更新 + 状态回读（Read + Notify）
- BLE 安全
  - Just Works + Bonding
  - 受保护特征要求链路加密（首次操作会弹系统配对）
- Wi‑Fi（设备端 STA）
  - BLE 下发 SSID/密码
  - 扫描附近热点并返回列表（SSID/RSSI/加密方式）
  - 连接状态/错误/IP 回读
- OTA（设备端 HTTP OTA）
  - OTA 平台托管固件并提供检查更新 API
  - 设备端校验 SHA256，成功后重启到新固件
- iOS Widget（`pwmfan`）
  - 主 App 写入 App Group 数据，Widget 展示设备状态

## 目录结构

- `bleborder/`：ESP32‑C3 Arduino 固件（BLE + PWM + Ambient + Wi‑Fi + OTA）
  - `bleborder/bleborder.ino`：入口
  - `bleborder/partitions.csv`：自定义 OTA 分区（双 OTA 分区）
- `iosapp/esp32c3pwm/`：iOS（PWM 示例）
- `iosapp/pwmfan/`：iOS（完整 App + Widget）
- `Androidapp/`：Android（Compose）
- `ota-platform/`：OTA 平台（backend + frontend）
- `docs/`：协议与 UI 原型

## BLE UUID（同一 Service 下的多能力特征）

- Service：`629873FE-0BBD-44E5-BD97-CCD5FD6C0DA1`
- PWM
  - Control（Write）：`2B9E14B6-ACB8-4D43-8480-245F239FA81C`
  - Status（Read + Notify）：`BEE65CC4-5387-4D76-AF01-1521FE909794`
- Ambient
  - Control（Write）：`A7B3DAD0-6D3C-4D1B-9C43-8E6B7B6E2F59`
  - Status（Read + Notify）：`7E25BA23-62C5-4D99-9F2A-25E8E7BA7AE1`
- Wi‑Fi（协议版本 1，见 `iosapp/pwmfan/pwmfan/WiFiProtocol.swift`）
  - Scan Control（Write）：`C1A7E3B9-4F2D-4A1E-9B8C-7D6E5F4A3B2C`
  - Scan Results（Notify）：`D2B8F4CA-5E3F-4B2F-AC9D-8E7F6A5B4C3D`
  - Config（Write）：`E3C9A5DB-6F4A-4C3E-BD8F-9A8B7C6D5E4F`
  - Status（Read + Notify）：`F4DAB6EC-7A5B-4D4F-CE9A-AB9C8D7E6F5A`
- OTA（协议版本 1，见 `iosapp/pwmfan/pwmfan/OTAProtocol.swift`）
  - Control（Write）：`B1C2D3E4-1234-5678-9ABC-DEF012345678`
  - Status（Notify）：`C2D3E4F5-2345-6789-ABCD-EF0123456789`

## 固件：编译与烧录（Arduino IDE 2.x）

1. 打开 `bleborder/bleborder.ino`
2. 安装 ESP32 Arduino Core（建议 3.x）
3. `Tools > Board` 选择你的 ESP32‑C3（例如 `ESP32C3 Dev Module`）
4. 关键配置：
   - Flash Size：匹配你的板子（`bleborder/partitions.csv` 适配 4MB）
   - Partition Scheme：选择 `Custom`，并确保 `bleborder/partitions.csv` 被作为自定义分区表使用
5. 选择端口，点击 Upload

清除绑定/设置：
- 长按 `GPIO9` 约 5 秒：清除 bonding + NVS，并重启
- 或串口命令：输入 `clear`

导出 `.bin`（用于 OTA 平台）：
- Arduino IDE 2.x：`Sketch > Export Compiled Binary`
- 一般使用导出的 `bleborder.ino.bin` 作为 OTA 升级包

## iOS：运行与功能入口

### `esp32c3pwm`（PWM 示例）

1. 打开 `iosapp/esp32c3pwm/esp32c3pwm.xcodeproj`
2. 真机运行（模拟器无法使用蓝牙）
3. 首次控制会弹系统配对弹窗，确认后即可访问受保护特征

### `pwmfan`（完整 App + Wi‑Fi + OTA + Widget）

1. 打开 `iosapp/pwmfan/pwmfan.xcodeproj`
2. 真机运行（需要蓝牙权限）
3. `设置` 页面：
   - `Wi‑Fi 设置`：扫描热点并下发 SSID/密码（设备连接 Wi‑Fi 后会显示 IP）
   - `OTA 升级`：检查更新/开始升级（设备需已连接 Wi‑Fi 且可访问 OTA 平台）

Widget：
- 需要配置 App Groups（主 App 与 Widget 使用同一个 Group ID）
- 参考：`iosapp/WIDGET_SETUP_GUIDE.md`

## Android：运行

1. 用 Android Studio 打开 `Androidapp/`
2. 运行到手机（Android 12+ 需要“附近设备/蓝牙权限”）
3. 首次可能触发系统配对弹窗，完成后 App 自动刷新状态

## OTA 平台：启动（本地）

### 后端（Express + Prisma）

```bash
cd ota-platform/backend
npm install
npm run db:generate
npm run dev
```

- 默认监听 `http://localhost:3000`
- SQLite 数据库：`ota-platform/backend/data/ota.db`（已忽略，不会被提交）
- 固件上传目录：`ota-platform/backend/uploads/`（只保留 `.gitkeep`，上传文件默认忽略）

### 前端（Vite + React）

```bash
cd ota-platform/frontend
npm install
npm run dev
```

- 默认监听 `http://localhost:5173`
- 已配置反向代理：`/api` → `http://localhost:3000`

## OTA 联调流程（建议）

1. 固件侧设置 OTA 服务地址
   - 修改 `bleborder/BleBorderConfig.h` 中的 `kOtaServerHost`/`kOtaServerPort`（必须是设备所在局域网可访问的地址）
2. 启动 OTA 平台（backend + frontend）
3. Arduino 导出 `bleborder.ino.bin`，在 OTA 平台“固件管理”上传并设置为“稳定版”
4. iOS `pwmfan`：
   - 先 `Wi‑Fi 设置` 让设备连上路由器
   - 再到 `OTA 升级` 检查并开始升级

注意：
- OTA 依赖 OTA 分区（`bleborder/partitions.csv` 已提供双 OTA 分区）；首次串口刷机时分区表必须已生效，后续 OTA 只更新应用 bin

## 常见问题

- 串口端口不存在/占用：确认数据线与端口名是否变化；关闭串口监视器后重试；必要时按住 BOOT 再上传
- iOS 安装失败提示 `Info.plist` 缺少 `CFBundleIdentifier`：确认 target 使用的 `Info.plist` 内包含 `CFBundleIdentifier=$(PRODUCT_BUNDLE_IDENTIFIER)`
- Wi‑Fi/OTA 一直失败：检查设备是否已连上 Wi‑Fi、`kOtaServerHost` 是否可从设备访问、OTA 平台端口是否开放