Galeros OpenIris ESP32 固件开发实战

Galeros OpenIris ESP32 固件开发实战：从零构建智能配网与实时日志系统

本文详细介绍了基于 ESP32 的 OpenIris 摄像头固件二次开发项目，着重讲解网页配网系统和实时 Web 日志监控的实现方案。

零、开发环境搭建（VSCode + PlatformIO）

本节详细介绍如何在 VSCode 中配置 PlatformIO 开发环境，并完成固件编译与烧录。

0.1 安装 Visual Studio Code

  1. 访问 VS Code 官网 下载并安装 VS Code
  2. 启动 VS Code，点击左侧扩展图标（或按 Ctrl+Shift+X）

VS Code 扩展图标位置

图 0-1：VS Code 左侧扩展图标位置

0.2 安装 PlatformIO 插件

  1. 在扩展搜索框中输入 PlatformIO
  2. 找到 PlatformIO IDE 插件，点击安装

PlatformIO 插件搜索

图 0-2：搜索并安装 PlatformIO 插件

  1. 安装完成后，点击 Reload Now 重启 VS Code

PlatformIO 安装完成

图 0-3：PlatformIO 安装完成，点击 Reload Now

0.3 打开项目并编译

  1. 打开 VS Code，点击 File → Open Folder
  2. 选择项目根目录 Openiris_esp32_aithinker

打开项目文件夹

图 0-4：打开项目文件夹

  1. 等待 PlatformIO 自动下载依赖（首次可能需要 1-3 分钟）

依赖下载中

图 0-5：PlatformIO 正在下载依赖

  1. 依赖下载完成后，在底部找到 PlatformIO 图标，点击展开菜单

PlatformIO 菜单

图 0-6：点击底部 PlatformIO 菜单

  1. 点击 Build（或按 Ctrl+Alt+B）开始编译

点击 Build 编译

图 0-7：点击 Build 开始编译

  1. 编译成功后会看到类似输出：
1
2
3
4
5
6
7
Advanced Memory usage is available via "Build"
================================================
INFO: Successfully burned binary to flash
Environment         Status    Duration
-------------------- --------- --------
esp32AIThinker      SUCCESS   00:01:32
================================================

编译成功

图 0-8：编译成功输出

0.4 烧录固件到开发板

  1. 用 USB 线连接 ESP32 开发板到电脑
  2. 在 PlatformIO 菜单中点击 Upload（或按 Ctrl+Alt+U）

点击 Upload 烧录

图 0-9：点击 Upload 烧录固件

  1. 烧录过程中开发板上的指示灯会闪烁

  2. 烧录成功后设备会自动重启

烧录成功

图 0-10：烧录成功提示

一、项目背景与目标

在 ESP32 开发中，WiFi 配置一直是开发者头痛的问题。传统方式需要：

  1. 硬编码 WiFi 凭证 → 每次换环境要重新烧录
  2. 串口终端手动输入 → 依赖电脑工具
  3. BLE 配网 → 需要额外 App

Galeros OpenIris 正是为解决这些痛点而生的二次开发固件。项目目标非常明确：

让 ESP32 设备开箱即用，通过浏览器即可完成 WiFi 配置，并实时监控设备运行日志。

二、核心功能架构

2.1 智能网页配网系统

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
┌─────────────────────────────────────────────────────────┐
│                    首次上电流程                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   设备上电 ──→ 检查 NVS 中是否有保存的 WiFi             │
│                    │                                     │
│         ┌─────────┴─────────┐                           │
│         ▼                   ▼                           │
│    已保存 WiFi           无保存 WiFi                    │
│         │                   │                           │
│         ▼                   ▼                           │
│    尝试连接 ──→ 失败 ──→ 开启 AP 热点                   │
│                    │                                   │
│                    ▼                                   │
│            SSID: Galeros_ESP32                         │
│            密码: Galeros_ESP32                         │
│                    │                                   │
│                    ▼                                   │
│         浏览器自动弹出配网页面                          │
│         (Captive Portal)                               │
│                    │                                   │
│                    ▼                                   │
│         用户输入 WiFi 信息并提交                        │
│                    │                                   │
│                    ▼                                   │
│           保存到 NVS 分区，重启设备                     │
│                                                         │
└─────────────────────────────────────────────────────────┘

首次配网界面

图 2-1：首次配网时连接 AP 热点后浏览器自动弹出的配网页面

配网成功后，设备会重启并连接 WiFi。此后可通过以下地址访问配置管理页面：

配置网络界面

图 2-2：STA 模式下访问 http://设备IP:8080 看到的配置管理页面，可查看当前连接的 WiFi 并重新配置

关键实现代码 (main.cpp)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// AP 模式配置
void etvr_eye_tracker_web_init() {
  // 先尝试连接已保存的 WiFi
  wifiHandler.begin();
  
  if (WiFi.isConnected()) {
    // 已连接，启动正常服务
    startNormalServices();
  } else {
    // 未连接，进入 AP 模式
    WiFi.mode(WIFI_AP);
    WiFi.softAP(AP_SSID, AP_PASSWORD);
    WiFi.softAPConfig(apIP, apIP, IPAddress(255, 255, 255, 0));
    dnsServer.start(DNS_PORT, "*", apIP);
    
    // 启动配网页面
    setupConfigServer(true);
  }
}

2.2 实时 Web 日志监控

项目实现了双通道日志系统：

通道 端口 功能
配置管理页面 8080 WiFi 配置修改
Web 日志监控 1234 实时日志查看 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
┌────────────────────────────────────────────────────────┐
│                  Web 日志系统架构                      │
├────────────────────────────────────────────────────────┤
│                                                        │
│  ┌──────────────┐    ┌──────────────┐                 │
│  │  ESP_LOG     │    │ Serial.printf│                 │
│  │  (vprintf)   │    │              │                 │
│  └──────┬───────┘    └──────┬───────┘                 │
│         │                   │                           │
│         ▼                   ▼                         │
│  ┌──────────────────────────────────┐                 │
│  │       日志缓冲队列               │                 │
│  │   (早期日志缓存 20 条)           │                 │
│  └────────────────┬────────────────┘                 │
│                   │                                    │
│                   ▼                                    │
│  ┌──────────────────────────────────┐                 │
│  │    AsyncEventSource (SSE)        │                 │
│  └────────────────┬────────────────┘                 │
│                   │                                    │
│                   ▼                                    │
│  ┌──────────────────────────────────┐                 │
│  │      浏览器 WebSocket            │                 │
│  └──────────────────────────────────┘                 │
│                                                        │
└────────────────────────────────────────────────────────┘

日志发送核心函数 (main.cpp)：

1
2
3
4
5
6
7
8
9
10
11
12
13
extern "C" void SendLogToWeb(const char *initialCustomLog) {
  if (initialCustomLog != nullptr && strlen(initialCustomLog) > 0) {
    if (events != nullptr) {
      // 使用 Server-Sent Events 推送日志
      events->send(initialCustomLog, nullptr, millis());
    }
  }
}

// 在流媒体服务器中的使用
String logMsg = "大小: " + String(_jpg_buf_len / 1024) + "KB, " +
                "时间: " + String(latency) + "ms";
SendLogToWeb(logMsg.c_str());

三、技术实现详解

3.1 配网页面实现

使用 AsyncWebServer 构建轻量级 Web 服务器：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// AP 模式配网页面
configServer->on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
  request->send(200, "text/html", ap_config_html);
});

// 保存 WiFi 配置
configServer->on("/save", HTTP_POST, [](AsyncWebServerRequest *request) {
  String ssid = request->getParam("ssid", true)->value();
  String pass = request->getParam("password", true)->value();
  
  // 保存到 NVS 分区
  deviceConfig.setWifiConfig("main", ssid.c_str(), pass.c_str(), 0, 52,
                             false, true);
  
  request->send(200, "text/plain", "配置已保存！设备即将重启...");
  delay(2500);
  ESP.restart();
});

3.2 Captive Portal 自动弹出

1
2
3
4
5
6
7
8
9
10
11
12
13
class CaptiveRequestHandler : public AsyncWebHandler {
public:
  void handleRequest(AsyncWebServerRequest *request) {
    // 重定向到配网页面
    request->redirect("http://" + apIP.toString());
  }
};

// AP 模式下启用
if (isAP) {
  configServer->addHandler(new CaptiveRequestHandler())
      .setFilter(ON_AP_FILTER);
}

3.3 日志回调系统（存在 bug）

1
2
3
4
5
6
7
8
9
10
11
12
13
// 自定义 ESP_LOG 输出函数
int custom_log_vprintf(const char *format, va_list args) {
  char buffer[512];
  int len = vsnprintf(buffer, sizeof(buffer), format, args);
  
  if (len > 0 && logSystemReady && globalLogCallback) {
    globalLogCallback(String(buffer));
  }
  return len;
}

// 启用日志重定向
esp_log_set_vprintf(custom_log_vprintf);

⚠️ 注意：日志回调功能目前存在 bug，建议使用 SendLogToWeb() 函数发送自定义日志。

四、使用教程

4.1 首次配网步骤

步骤 操作
1 设备上电，若无保存 WiFi 会自动开启热点
2 手机/电脑连接 Galeros_ESP32（密码相同）
3 浏览器自动弹出配网页面，或访问 192.168.4.1
4 输入家用 WiFi 名称和密码
5 点击「保存并重启」
6 设备自动重启并连接 WiFi

4.2 访问服务

1
2
3
4
5
6
7
8
┌────────────────────────┬──────────────────────────────┐
│ 功能                   │ 访问地址                     │
├────────────────────────┼──────────────────────────────┤
│ Web 日志监控           │ http://设备IP:1234           │
│ 配置管理页面           │ http://设备IP:8080           │
│ 视频流地址             │ http://设备IP:81/stream      │
│ mDNS 访问              │ http://Galeros-ESP32.local   │
└────────────────────────┴──────────────────────────────┘

Web 日志监控界面

图 4-1：访问 http://设备IP:1234 看到的实时 Web 日志监控页面，可实时查看设备运行日志

五、项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Galeros-ESP/
├── src/
│   ├── main.cpp              # 主程序入口
│   └── html_content.h        # HTML 页面内容
├── lib/src/
│   ├── openiris.hpp          # 主头文件
│   ├── data/                 # 数据层
│   │   ├── CommandManager/   # 命令管理
│   │   ├── StateManager/    # 状态管理
│   │   └── config/          # 配置管理
│   ├── io/                   # 外设层
│   │   ├── Serial/          # 串口管理
│   │   ├── LEDManager/      # LED 控制
│   │   └── camera/          # 摄像头
│   └── network/             # 网络层
│       ├── wifihandler/     # WiFi 处理
│       ├── api/             # Web API
│       ├── stream/          # 视频流
│       └── mDNS/            # mDNS 服务
├── ini/                      # 配置文件
│   ├── boards.ini
│   ├── pinouts.ini
│   └── user_config.ini
└── platformio.ini            # PlatformIO 配置

六、用户可配置参数

在 main.cpp 顶部可修改以下参数：

1
2
3
4
5
6
7
8
9
10
11
// WiFi 配置
const char *AP_SSID = "Galeros_ESP32";     // AP 热点名称
const char *AP_PASSWORD = "Galeros_ESP32"; // AP 热点密码

// 端口配置
const uint16_t CONFIG_PORT = 8080;  // 配置页面端口
const uint16_t LOG_PORT = 1234;     // 日志页面端口

// 功能开关
const bool enableCallbackLog = true;   // 启用日志回调
const bool enableDetailedLog = true;  // 启用详细日志

七、待实现功能

  • 修复日志回调系统 bug
  • 添加日志级别颜色区分（DEBUG / INFO / ERROR）
  • 支持网页端扫描附近 WiFi 列表
  • OTA 更新时暂停日志推送
  • 添加暗黑模式支持
  • 优化内存占用

八、总结

Galeros OpenIris 项目为 ESP32 开发者提供了一个开箱即用的配网解决方案：

✅ 优点

  • 无需硬编码 WiFi，浏览器一键配网
  • 独立的 Web 日志服务器，调试更方便
  • 配置保存在 NVS，重启后依然有效
  • 美化后的配网和管理界面

⚠️ 需要注意

  • 日志回调功能存在 bug，推荐使用 SendLogToWeb() 发送自定义日志
  • 首次使用必须通过 AP 配网方式配置 WiFi

项目地址：https://github.com/mayan613/Openiris_esp32_aithinker

欢迎 Star 和 Issue！

项目教程
#开源项目 #教程
Galeros OpenIris ESP32 固件开发实战
https://www.galeros.xyz/2026/05/01/Galeros-OpenIris-ESP32-固件开发实战/
作者
Galeros Studio 彩咖工作室
发布于
2026年5月1日
许可协议