GitHub开源实战：真机跑过才收录的ESP32项目清单

awesome-esp32 是一份人工精选的 ESP32 项目列表。仓库自己的介绍只有一句话：值得去构建、去抄，或者只是看着它跑起来的 ESP32 项目。在 GitHub 上，这份清单的地址是：

https://github.com/s0lness/awesome-esp32

它不是普通的链接堆砌。门槛写进了 CONTRIBUTING.md，分类原则很清楚，仓库里还藏着一份从实战项目里蒸馏出来的开发实践文档。

1. 三道门槛，star 数不作数

大多数 awesome list 的收录标准是看着不错。这份清单不是。三条全要，缺一不可：

1. 公开源码，且能构建。视频展示不算数，代码不在仓库里就不收。
2. 真机运行证据。照片、视频，或者任何人都能打开的在线 demo。3D 渲染、PCB 预览、模拟器截图统统不算——只存在于图片里的东西，等于没跑过。
3. 别人能复现。README 里写清了用什么板子、怎么烧录。

还有一条：新分类至少要有两个项目才能建。一个项目的分类什么都不说明。

收录标准：https://github.com/s0lness/awesome-esp32/blob/main/CONTRIBUTING.md

2. 清单里有什么

结构很干净。顶层只有两个分区：

• Applications：人们真的在 ESP32 上跑起来的东西
• Tools, utilities & libraries：你用来造这些东西的工具

应用侧按用途分类，不按硬件分类。芯片、屏幕、是否电池供电，用行尾标签表达，比如 e-ink、s3-amoled、p4、c3、headless、battery、ecosystem。

用途走分类，硬件走标签。这样不会出现「电子墨水」这种只有一块屏、什么用途都往里塞的分类。

挑几个值得点进去看的。

通信与组网

Meshtastic 是离网、加密的 LoRa 网状网消息系统。清单里称它为 ESP32 无线电项目的参照系。一个固件铺到 12 种架构，板卡矩阵的分层构建本身就值得读源码。

https://github.com/meshtastic/firmware

Waycast 跑在 ESP32-P4 触屏仪表盘上，做车对车 LoRa 网状网：临时路况、车队位置、离线地图，不依赖蜂窝网络。

https://github.com/alviso/waycast

音频

squeezelite-esp32 把一块裸 ESP32 当成多房间音频播放器，AirPlay、Spotify、蓝牙端点合一。实践文档里不少实时音频的坑都来自它，比如 DMA buffer 大小，以及 FLAC 直连流在 ESP32 上会卡——这是 TCP/IP 吞吐瓶颈，调任务优先级解决不了。

https://github.com/sle118/squeezelite-esp32

esp32_basic_synth 是一颗芯片加一个 DAC 的复音 MIDI 合成器。能在 MCU 上跑起来，靠的是预算而不是祈祷：编译期定死复音数，一个 buffer 大小当延迟旋钮，音频循环独占一个核。

https://github.com/marcel-licence/esp32_basic_synth

工具型应用

ESP-KVM 用 ESP32-P4 加 TC358743 HDMI 桥做 IP-KVM：把目标机屏幕抓到浏览器里，同时伪装成 USB 键鼠，没装系统也能进 BIOS。大约 50 美元级硬件，干的是 300 美元级设备的事。

https://github.com/espkvm/espkvm

Midbar 是硬件密码保险箱，密钥由开机主密码派生，部分版本配合 RFID 卡。

https://github.com/Northstrix/Midbar

好玩但硬核

esp32-gameos 是掌机游戏 OS：启动器加六款全程序化生成的游戏，60fps，无引擎、无资源文件，画面都是代码算出来的。

https://github.com/MikeWilson/esp32-gameos

esp32-fluidbox 让设备外壳里住着一个 3D 粒子流体：大约 900 个粒子跟着加速度计晃，像屏幕后面真的有液体。

https://github.com/V4C38/esp32-fluidbox

pixelcat 是电子宠物猫，会学你的作息，对触摸和声音有反应，而且永远不会不可恢复地死掉——这句话背后是一整套崩溃记录与恢复机制。

https://github.com/toddsherman/pixelcat

居家与生态

Tasmota、WLED 这些万人固件也在列。它们十年生产环境攒下来的经验，正是后面那份实践文档的主要素材。

工具侧也不含糊：ESP-IDF、esp-hal（bare-metal Rust）、MicroPython、ESPHome 四大框架都在；ESP Web Tools 可以在浏览器里用 WebSerial 烧录，不必先装工具链；仿真有 Wokwi（浏览器里仿真 ESP32）和乐鑫官方的 QEMU 分支（CI 和调试用）。

3. 实践指南

清单里藏着两个 guides。对写固件的人来说，esp32-practices.md 可能是全仓库最有价值的文件。

它把清单里各项目的工程经验，蒸馏成一份板级无关的实践清单。每一条都标注了出处——是谁踩过这个坑、在哪学到的。

https://github.com/s0lness/awesome-esp32/blob/main/guides/esp32-practices.md

随便摘几条，都是可以直接抄进自己项目的。

内存

ESPHome 把 setup() 之后的任何堆分配视为可靠性 bug，现场崩溃就是这么来的，连 std::string 返回值都弃用。

PSRAM 比看起来慢得多：经典 ESP32 上比 DRAM 大约慢 15 倍，八线 S3 上慢 2～4 倍，而且经典 ESP32 上不支持 DMA。DMA buffer、ISR 触及的代码、热像素路径必须留在内部 RAM；大而冷的状态（世界缓冲、历史记录，甚至任务栈）放 PSRAM。

还有一个数字值得记住：ESP32 在最大空闲 DRAM 块低于大约 10KB 时会崩溃。WLED 的 p_malloc 降级阶梯（先 PSRAM 再 DRAM），就是为这个准备的。

任务、时序、看门狗

ESP32 上 yield() 永远不会运行 IDLE 任务，所以它不喂任务看门狗。忙循环里必须 delay(1)。看门狗 panic 只是晚期症状，之前先出现的往往是任务内存泄漏和定时器静默停止。

不要直接比较 millis()：49.7 天回绕会让比较反向。Meshtastic 专门有一个 CI job 拒绝裸比较。

WLED 的 bootloop 阶梯也很值得抄：RTC 内存里数崩溃次数，间隔超过 2 分钟则清零；然后逐级升级——恢复配置备份 → 重置配置 → 回滚 OTA 分区 → 把文件系统 dump 到串口。

OTA

分区策略常见两种：经典双 app 加回滚（ESPHome、xiaozhi），或者 Tasmota 的 safeboot（一个大 app 槽加一个小工厂恢复镜像）。

有个细节很容易踩：esp_ota_mark_app_valid_cancel_rollback() 作用于启动分区。

过大的镜像会烧录成功，然后 bootloader 静默启动另一个槽里的旧镜像——你在调试上周的固件。这是 pocket-pet 的教训。启动日志里搜 Loaded app from partition 那一行。

连接性

重连要阶梯，不要死循环。TRMNL 把重试间隔做成一级对象：API 15/30/60 秒，WiFi 60/180/300 秒。Tasmota 每 44 分钟重扫一次，只漫游到信号好 10dB 以上的 AP，这个迟滞是用来防止网状网抖动的。

把 BSSID 和 channel 跟凭据一起缓存，连接时跳过扫描——这是实际世界里最大的启动提速点。

MQTT 用 LWT 加保留的 online/offline 当集群心跳。

文档里还有选型建议（什么时候上 IDF，什么时候 Arduino + PlatformIO，什么时候用 ESPHome）、板卡矩阵的分层构建（Meshtastic 的 12 架构、xiaozhi 的 70+ 板卡虚基类）、实时音频（有界队列、代次计数器杀掉过期音频帧）。每一节都能对照源码看为什么。

4. 小结

对写 ESP32 的人来说，awesome-esp32 的价值很高。

• 真机跑过、可构建、可复现。
• 它把踩坑经验系统化了。
• 它把值得做和用了 ESP32 区分开了。

你最近有接触 ESP32 项目吗？欢迎在 云栈社区 聊聊你的实战经验或疑惑。