AI-on-the-edge-device 固件构建与烧录实战指南基于 PlatformIO 编译与部署 ESP32-CAM 抄表设备【免费下载链接】AI-on-the-edge-deviceEasy to use device for connecting old measuring units (water, power, gas, ...) to the digital world项目地址: https://gitcode.com/GitHub_Trending/ai/AI-on-the-edge-device本文是 AI-on-the-edge-device 开源项目的完整构建指南围绕仓库 code/README.md 的构建流程展开覆盖源码获取、子模块管理、终端与 VS Code 两种构建烧录路径、SD 卡准备以及参数文档维护约定。读完本文你将能独立把该仓库源码编译为可在 ESP32-CAM 上运行的固件完成烧录并接入自己的水表/电表/气表读数场景。准备阶段克隆仓库并初始化子模块克隆源码项目依赖若干 Git 子模块如 TFLite Micro 推理引擎、ESP32 摄像头驱动等因此不能只做浅克隆必须完整初始化子模块。在 Linux/macOS 终端执行git clone https://github.com/jomjol/AI-on-the-edge-device.git cd AI-on-the-edge-device git checkout main git submodule update --initWindows 用户建议在 Git Bash 或 VS Code 终端中执行相同命令。克隆完成后可以看到 code/components 目录下既有仓库内自研组件jomjol_*系列摄像头控制、图像处理、MQTT、InfluxDB、Webhook、日志等也有通过子模块引入的依赖组件esp-tflite-microTFLite Micro 运行时、esp32-camera摄像头驱动、esp-nn神经网络加速库、esp-protocols以及stb图像编解码库。子模块的版本锁定信息可以从 code/dependencies.lock 中确认例如当前锁定 ESP-IDF 为 5.3.1、espressif/esp-nn为 1.1.0构建目标芯片为esp32。更新子模块到指定版本当需要把某个子模块升级到新版本例如跟随esp-tflite-micro的最新构建时进入对应子模块目录切换版本后再重新初始化cd /components/submodule-name # 例如 tflite-micro-example git checkout VERSION # 例如最新 tflite-micro-example 构建的 HASH cd ../../ # 回到 code 目录层级 git submodule update --init需要注意切换版本前components目录中可能残留上一次 checkout 未删除的旧目录需要手动删除后再执行update --init否则可能混入过期文件导致编译异常。构建环境PlatformIO 与工程配置工具链要求项目使用 PlatformIO配合 ESP-IDF 框架进行构建需要先安装VS Code 及 PlatformIO IDE 插件见下文 VS Code 章节若仅用终端构建安装 PlatformIO Core 即可Linux 下常见缺失项是python3-venv表现为插件报错可执行sudo apt-get install python3-venv补装。platformio.ini 核心配置项目根配置文件 code/platformio.ini 中[platformio]段声明了源码目录src_dir main和默认环境default_envs esp32cam。主环境[env:esp32cam]的关键配置如下[env:esp32cam] extends common:esp32-idf board esp32cam framework espidf build_flags -D BOARD_ESP32CAM_AITHINKER -D ENABLE_MQTT -D MQTT_ENABLE_SSL -D MQTT_SUPPORTED_FEATURE_SKIP_CRT_CMN_NAME_CHECK -D ENABLE_INFLUXDB -D ENABLE_WEBHOOK -D ENABLE_SOFTAP board_build.partitions partitions.csv monitor_speed 115200平台与框架platform platformio/espressif32 6.11.0、framework espidf即基于 ESP-IDF 的 CMake 构建体系板级定义BOARD_ESP32CAM_AITHINKER会触发 code/include/defines.h 中 AiThinker ESP32-CAM 的引脚映射SD 卡 CLK/CMD/D0/D3、摄像头 XCLK/SIOD/SIOC 及数据总线、状态 LED IO33、闪光灯 IO4 等功能开关ENABLE_MQTT、ENABLE_INFLUXDB、ENABLE_WEBHOOK、ENABLE_SOFTAP分别控制对应模块是否参与编译MQTT 默认开启 SSLMQTT_ENABLE_SSL可按需注释分区表board_build.partitions partitions.csv对应 code/partitions.csv 中的双 OTA 分区布局ota_0/ota_1各 1900k外加nvs、otadata、phy_init这是固件支持网页 OTA 升级的前提串口监视波特率固定为 115200。此外code/sdkconfig.defaults 集中定义了 ESP-IDF 层的构建选项4MB Flash、自定义分区表、启用 PSRAMCONFIG_ESP32_SPIRAM_SUPPORTy、仅保留 OV2640/OV3660/OV5640 摄像头传感器支持、关闭断言以缩减固件体积等。注意该文件头部提示修改后需显式删除sdkconfig.esp32cam才能让改动生效。预置构建环境速查platformio.ini 还提供了多个面向不同场景的派生环境env通过extends组合出各种开发形态环境名用途esp32cam默认发布环境含完整功能开关esp32cam-dev全功能开发模式启用 clang-tidy 严格告警可开 DEBUG 选项esp32cam-debug叠加调试开关DEBUG_DETAIL_ON、DEBUG_ENABLE_SYSINFO、DEBUG_ENABLE_PERFMONesp32cam-power-management开启电源管理CONFIG_PM_ENABLE、Tickless Idleesp32cam-board-rev3适配 ESP32 芯片 Rev3 修订版esp32cam-cpu-freq-240将 CPU 频率从默认 160MHz 提到 240MHzesp32cam-dev-himem启用 8MB PSRAM 板子的 HiMem 扩展内存esp32cam-dev-task-analysis任务栈/堆跟踪分析TASK_ANALYSIS_ON、HEAP 追踪esp32cam-no-softap关闭 SoftAP 支持节省约 28KB Flash例如组合环境esp32cam-board-rev3-cpu-freq-240即为Rev3 芯片 240MHz 主频的完整开发配置。选择方法在构建命令中把--environment参数换成对应环境名。终端方式构建与烧录编译进入code目录后执行cd code platformio run --environment esp32cam编译产物输出到code/.pio/build/esp32cam/其中包含后续烧录所需的bootloader.bin、partitions.bin与firmware.bin。首次构建会拉取平台与依赖耗时较长属正常现象。上传烧录将 ESP32-CAM 通过 USB 转串口模块连接电脑后pio run --target upload --upload-port /dev/ttyUSB0也可以直接把串口设备写入platformio.ini之后省略端口参数[env:esp32cam] upload_port /dev/ttyUSB0串口日志监控pio device monitor -p /dev/ttyUSB0默认波特率 115200monitor_speed 115200。设备启动后会在日志中依次打印 SD 卡挂载、PSRAM 容量、堆内存、摄像头型号、WiFi 连接、固件/Web UI 版本号等自检信息。VS Code 图形化构建与烧录安装 VS Code 与 PlatformIO 插件下载安装 VS Code 后在扩展市场搜索并安装 PlatformIO IDE 插件。安装完成后请留意插件是否有报错必要时按提示手动补充 Python 库例如 Ubuntu 下的python3-venv。打开项目并构建先克隆并初始化子模块命令同前然后用 VS Code 打开工程的code目录cd AI-on-the-edge-device/code code .在 VS Code 底部菜单栏打开 PIO 终端PlatformIO 终端确认当前目录是code后执行platformio run --environment esp32cam也可以直接点击 PlatformIO 工具栏中的 Build 按钮走图形化流程构建产物位于code/.pio/build/esp32cam/。配置上传端口并烧录连接设备后执行pio device monitor从输出中确认设备对应的串口名称把该端口写入 code/platformio.iniupload_port 你的设备端口确认 SD 卡中已放入sd_card目录的内容见下一节并已在wlan.ini/ 配置中填写 WiFi 信息先擦除 Flashpio run --target erase再执行pio run --target upload此命令会把code/.pio/build/esp32cam/下的bootloader.bin、partitions.bin、firmware.bin一并写入设备最后pio device monitor观察 UART 日志确认启动状态。首次运行前的 SD 卡准备固件的配置、模型、网页 UI、日志与图片全部存放在 SD 卡上因此 SD 卡内容是否正确直接决定设备能否工作。SD 卡目录结构仓库根目录的 sd-card 文件夹列出了 SD 卡应包含的内容config/config.ini与 TFLite 模型、参考图、demo/演示图片集、html/网页 UI 模板、img_tmp/、firmware/OTA 升级文件目录、log/分类日志目录以及wlan.ini。注意 sd-card/Readme.md 中的明确警告不要直接把sd-card文件夹整体拷到 SD 卡上这样无法工作。仓库中的html目录只是模板真实html目录由构建流水线生成并打包到发布制品中应使用发布制品中的 SD 卡内容。修改 WiFi 与基本配置SD 卡根目录的 sd-card/wlan.ini 是最小必需配置文件至少填写ssid 你的WiFi名称 password 你的WiFi密码可选配置包括hostname默认watermeter、固定 IPip/gateway/netmask/dns、RSSIThreshold客户端主动漫游阈值默认 0 表示关闭以及 Web 界面/API 的明文用户名密码保护http_username/http_password文件内明确标注该方案未经安全审计明文传输风险自负。主参数文件 sd-card/config/config.ini 以 INI 分段组织[TakeImage]摄像头采集参数如CamQuality、CamAec、CamGainceiling、LEDIntensity、Demo等、[Alignment]参考图与搜索范围、[Digits]/[Analog]CNN 模型路径与 ROI 定义如main.dig1 294 126 30 54 false表示表名.数字位1 x y 宽 高、[PostProcessing]后处理规则、以及默认注释掉的[MQTT]、[InfluxDB]、[Webhook]、[GPIO]、[System]等数据上报与系统分段。代码层面配置路径在 code/include/defines.h 中定义为CONFIG_FILE /sdcard/config/config.iniWiFi 文件为WLAN_CONFIG_FILE /sdcard/wlan.ini。固件启动自检流程源码视角从 code/main/main.cpp 的app_main可以完整还原首次上电的自检顺序帮助定位为什么起不来挂载 SD 卡Init_NVS_SDCard()使用 SDMMC 外设挂载/sdcardFAT 文件系统失败会通过状态 LED 闪烁次数提示具体错误SD 未插入 / 文件系统不支持 / 其他错误创建必需目录/sdcard/firmware、/sdcard/img_tmp、/sdcard/demo、/sdcard/config/certs检查 PSRAMesp_psram_init()后校验容量PSRAM 必须 ≥ 4MB32Mbit且总堆内存需 ≥ 4MB否则无法继续——这是选择 ESP32-CAM 硬件时的硬性门槛初始化摄像头最多重试 3 次成功后打印传感器 PID/VER/MID 信息迁移旧配置migrateConfiguration()会把旧版本config.ini中的参数名自动重命名为新命名如[MakeImage]→[TakeImage]、Brightness→CamBrightness、Intervall→Interval等迁移前自动备份为config.bak同步时间NTP 时间服务设置 CPU 频率setCpuFrequency()若ENABLE_SOFTAP开启且没有 wlan.ini/config.ini则进入 SoftAP 配网模式SSIDAI-on-the-Edge见 code/include/defines.h连接 WiFi读取wlan.ini缺失、SSID/密码为空分别以不同 LED 错误码退出启动 Web 服务注册摄像头、文件、OTA、MQTT、GPIO 等 HTTP handler 后若系统状态无致命错误则启动识别主流程任务。每次编译时 code/main/gitversion.cmake 会通过git describe/git rev-parse把当前 tag、commit、分支、构建时间写入version.cpp并生成sd-card/html/version.txt设备启动时会把固件版本与 Web UI 版本做比对不一致会在日志中警告建议使用完整更新包重新安装。新增参数的文档维护约定仓库对参数变更有一条强制约定见 code/README.md 末尾新增或重命名任何参数时必须同步更新 param-docs/parameter-pages 下的对应文档详细要求参见 param-docs/README.md。从目录结构可以确认该约定已形成完整工作流每个参数一个 Markdown 文档按功能分段组织如TakeImage/CamAeLevel.md、CamQuality.md、CamZoom.md等 40 余个摄像头参数、PostProcessing/NUMBER.DecimalShift.md、NUMBER.ChangeRateThreshold.md等、MQTT/、InfluxDB/、InfluxDBv2/、Webhook/、AutoTimer/、System/、GPIO/、DataLogging/、Debug/、Digits/、Analog/、Alignment/文档模板位于 param-docs/templates/parameter.md批量生成脚本为 param-docs/generate-template-param-doc-pages.py工具链还包括 tools/parameter-tooltip-generator/generate-param-doc-tooltips.py 用于生成网页参数悬浮提示以及param-docs/expert-params.txt、param-docs/hidden-in-ui.txt等参数清单文件。这套约定保证了 Web 配置界面sd-card/html 下的edit_config_template.html、readconfigparam.js等与文档、固件解析逻辑三者的参数命名始终一致。常见问题与调试建议子模块拉取失败确认网络可访问子模块仓库重复执行git submodule update --init切换子模块版本前先手动清理components下的旧目录Python 环境报错Linux 下安装python3-venv后重启 VS Code / 终端设备反复重启或 SD 卡初始化失败检查 SD 卡是否为 FAT 格式、触点是否接触良好AiThinker 板卡 GPIO13 的内部上拉已由代码显式设置见 code/main/main.cpp劣质拷贝板可能仍需外部上拉PSRAM/内存不足导致启动中断固件强制要求 PSRAM ≥ 4MB、堆 ≥ 4MB购买时需确认 ESP32-CAM 板载 PSRAM 型号常见为 4MB PSRAM 的 AiThinker 版本固件与 Web UI 版本不一致优先使用包含sd-card/html完整内容的发布更新包重新安装避免混用不同版本的firmware.bin与网页资源需要更多诊断信息使用esp32cam-devesp32cam-debug组合环境或直接开esp32cam-debug的DEBUG_DETAIL_ON、DEBUG_ENABLE_SYSINFO、DEBUG_ENABLE_PERFMON重新编译串口日志会输出更细粒度的设备信息与执行详情。至此你已经掌握了从源码到可运行设备的全流程克隆与子模块管理、PlatformIO 环境理解、终端/VS Code 两种构建烧录方式、SD 卡内容准备与启动自检逻辑以及参数文档的同步维护规范。按本文步骤操作即可将 AI-on-the-edge-device 固件部署到自己的 ESP32-CAM 上开始把传统表计接入数字化世界。【免费下载链接】AI-on-the-edge-deviceEasy to use device for connecting old measuring units (water, power, gas, ...) to the digital world项目地址: https://gitcode.com/GitHub_Trending/ai/AI-on-the-edge-device创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考