基于ESP32超低成本全屋温湿度监控可视化软硬件全套开发记录

作者：金金金

项目状态：迭代更新中、稳定7×24小时运行

最后更新：2026年07月

项目定位：完全自研、无第三方云依赖、低成本、可复刻、可拓展的全屋多房间温湿度远程监控解决方案

代码下载[：]

ESP-home_副本.zip

一、项目背景与需求初衷

1.1 实际使用痛点

我最近需要对多层自建住宅，包含地下室、多层卧室、书房、阁楼等多个独立空间，不同楼层、房间的温湿度环境进行检测。目的是为了适配相应的加除湿机和空调通风，但个房间朝向和墙体薄厚差异极大，直接影响温湿度，对人员体表舒适度影响很大。

我想要先监控并且可视化各房间的温湿度情况和各时间段变化趋势，后期匹配自动化指令实现温湿度精准控制，配合自己网关联动多品牌智能家居系统（小米、美的、格力等），打通数据渠道，做到自我控制家庭智能电气。

在完成这一目标前我先做出一小步，先能够使用分布式部署温湿度传感器将房屋各项数据获取分析，然后再开发联动功能。

• 地下室长期密闭潮湿，回南天极易墙面结露、滋生霉菌，无法精准判断除湿机启停时机；
• 中层卧室夏季空调温控模糊，夜间常出现过冷/过热问题，无法依据全天温度曲线优化空调设置；
• 顶层阁楼隔热差，夏季极端高温，需要监测全天温度峰值、低谷时段，科学规划通风、降温方案；
• 全屋无统一数据汇总渠道，各房间环境数据孤立，无法横向对比、无法追溯历史趋势。

为了解决全屋环境可视化、数据可留存、趋势可分析的核心需求，我调研了市面主流民用、工业级温湿度监测方案，但均无法满足个性化、私有化、低成本的使用需求。

1.2 市面成品方案全面测评与短板分析

市面上在售的温湿度监测设备，普遍存在数据不自主、联网受限、无法导出、拓展性差、溢价严重等问题，详细对比如下：

1.3 自我开发核心目标

基于现有方案的短板，我确立了这套自研系统的核心设计原则，也是区别于商用成品的核心优势：

• 数据私有化：不依赖任何第三方云平台，所有数据本地服务器存储，100%自主可控；
• 全量数据留存：永久存储历史温湿度数据，支持任意时间段回溯、复盘；
• 多房间可视化对比：曲线直观展示不同楼层、房间的环境差异与变化趋势；
• 离线容错机制：断网自动缓存数据，联网自动批量补报，零数据丢失；
• 低成本可批量部署：单设备硬件成本极低，多房间全覆盖无压力；
• 可无限拓展迭代：开源架构，支持后续新增报警、低功耗、智能家居联动等功能。

综上，市面上无适配方案，因此我开发这套基于ESP32-C3+SHT40的私有化多房间温湿度监控系统。

二、全套硬件方案选型（原理+对比+取舍逻辑）

硬件选型核心思路：家用场景够用、精度拉满、功耗可控、成本最低、稳定性优先，经过多轮横向对比，最终敲定主控+传感器组合。

2.1 主控芯片选型对比与最终方案

主流物联网WiFi主控横向测评，结合本项目联网、采集、缓存、低功耗、调试便捷性需求筛选：

最终选用 ESP32-C3 SuperMini 作为全屋所有监测节点主控，兼顾性能、功耗、成本、调试便捷性，4MB Flash可完美支撑自定义分区表、LittleFS离线缓存、后续OTA升级需求。

2.2 温湿度传感器选型对比

温湿度传感器决定整套系统的数据精度，家用监测优先选择高精度、低漂移、稳定性强、接线简单的型号，杜绝廉价传感器数据失真、波动大的问题：

SHT40 为瑞士Sensirion第四代温湿度传感芯片，具备超低功耗、低温漂、抗干扰能力强的特点，是民用自研监测项目的顶配传感器，完全满足全屋高精度环境监测需求。

2.3 全套物料清单（可直接复刻采购）

整套设备无小众配件，全部通用耗材，全网可购，批量部署成本极低：

单节点硬件总成本：约¥15，9房间全屋部署仅需百元级别，性价比碾压所有商用成品设备。

三、硬件接线与焊接实操教程（零基础可复刻）

3.1 ESP32-C3 SuperMini引脚说明

该开发板体积小巧（21×18mm），类似一元硬币，集成USB-C调试口，无需转接即可烧录程序、查看日志。不同批次板子引脚丝印基本一致，实操前务必核对板载丝印，避免接线错误。

引脚功能简图：

3.2 标准接线方案（固定引脚，固件适配）

本项目固件已固定I2C引脚，无需代码修改，直接按以下对应关系接线即可，零适配成本：

接线逻辑示意图：

3.3 焊接与实操注意事项（避坑重点）

SHT40 原生为1.5×1.5mm超小DFN封装，无法直接手工焊接杜邦线，因此必须使用带转接板的成品模块，大幅降低制作难度。

若自行焊接裸片，实操流程如下：

1. 在转接板焊盘涂抹微量低温焊膏；
2. 热风枪调至300℃恒温，均匀加热焊接，避免高温烫坏芯片；
3. 焊接完成后焊接2.54mm排针，方便杜邦线插接；
4. 万用表通断检测VDD与GND，杜绝短路烧板。

致命避坑提醒：SHT40 最大耐压3.6V，严禁接入5V电压，直接烧毁传感器！全程使用ESP32-C3 3.3V引脚供电。

3.4 实物图片

—— 整套硬件完整接线实物图

—— SHT40转接板焊接过程特写

四、全套开发环境搭建（零基础复刻教程）

本项目采用 VSCode + PlatformIO跨平台开发环境，适配Windows/Mac/Linux，无需复杂配置，一键编译烧录，全程可视化操作。

4.1 开发工具安装流程

1. 下载安装 VS Code 最新稳定版；
2. 插件市场搜索安装 PlatformIO IDE 插件；

3. 重启VS Code，底部出现PlatformIO状态栏即安装成功。

4.2 完整项目目录结构

4.3 platformio.ini 核心配置（已优化无报错）

该配置完美适配ESP32-C3，修复串口无输出、Json弃用警告、分区失效等所有问题：

关键宏说明：ARDUINO_USB_CDC_ON_BOOT=1 强制开启USB虚拟串口，解决ESP32-C3上电无日志、串口打印失效问题。

4.4 自定义分区表配置

ESP32-C3默认分区无文件系统，无法支持离线缓存，自定义 partitions.csv 适配项目需求：

分区优势：双OTA分区支持后续远程升级，1.47MB LittleFS分区，可存储数万条离线缓存数据。

4.5 后端运行环境搭建

后端基于Node.js开发，零配置、轻量化、无需数据库服务，一键启动：

仅依赖两个核心包，部署简单、占用资源极低，普通电脑、低配服务器均可7×24小时稳定运行。

五、固件核心逻辑深度解析

整套固件为全节点独立架构，无网关、无子机区分，所有房间设备运行同一份代码，大幅降低部署、维护、迭代成本。

5.1 设备核心工作流程

每30秒定时执行一次完整任务：

1. 校验NTP标准时间戳有效性
2. 读取SHT40高精度温湿度数据
3. WiFi在线：直接HTTP上报后端
4. WiFi离线/上报失败：数据存入LittleFS离线缓存
5. 网络恢复：自动批量补发所有缓存数据，自动去重

5.2 关键踩坑修复：NTP标准时间戳机制

早期版本最大BUG：使用设备开机毫秒 millis() 作为时间戳，设备重启后时间归零，导致历史数据时间错乱、图表漂移、数据完全失效。

最终最优解决方案：仅NTP同步成功后才采集上报，无标准时间则跳过采集，杜绝无效、错误数据入库。设备同步NTP后，依靠芯片RTC时钟维持时间精准度，断网也能保证时间戳绝对准确。

5.3 智能WiFi重连策略

为兼顾稳定性与省电，设计分级重连机制：

• 正常联网：断线3次后进入2分钟静默重连，避免频繁重连占用资源；
• 未同步NTP：取消静默限制，持续重试联网校时，优先保证时间精准；
• 定时巡检WiFi状态，自动重连、自动恢复上报，无人值守运行。

5.4 LittleFS离线缓存机制

自定义轻量化缓存结构体，极致节省存储空间：

struct LogEntry {
uint32_t ts; // 标准Unix时间戳
int16_t temp; // 温度放大100倍整型存储
uint16_t hum; // 湿度放大100倍整型存储
};

采用滚动分文件存储机制，单文件存储500条数据，自动轮转、自动清理、断点续传，断网数月数据也不会丢失，联网后自动批量补报。

5.5 ESP-NOW架构舍弃原因（实战踩坑总结）

初期计划采用「网关+子机」ESP-NOW组网架构，但实测发现ESP32-C3（RISC-V架构）存在硬件兼容BUG：WiFi联网状态下，ESP-NOW接收回调失效，仅可发送无法接收，多轮调试、换库、改参数均无法修复。

最终优化架构：所有设备直连WiFi、独立上报，架构更简单、稳定性更强、无组网延迟、无单点故障，更适合家用长期稳定运行。

六、后端服务架构与数据库设计

6.1 后端技术栈

• 运行环境：Node.js（轻量化、跨平台、部署简单）
• 数据库：SQLite3（单文件零配置、无需独立服务、迁移便捷）
• Web服务：Express.js（轻量高效HTTP服务）
• 可视化图表：ECharts5.x（前端CDN加载，无需本地部署）

6.2 核心数据库表结构

三张核心数据表，分工清晰、冗余极低、支持百万级数据存储：

6.3 服务启动与外网部署

本地启动命令：

cd ESP32sever
node server.js

本地后台访问地址：http://本地IP:3009/admin

外网反向代理Nginx配置（域名访问）：

server {
listen 80;
server_name 自定义域名;

location / {
    proxy_pass http://127.0.0.1:3009;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
location /static {
    proxy_pass http://127.0.0.1:3009;
    expires 30d;
}

}

七、Web后台功能全解析（核心可视化能力）

自研暗色主题管理后台，功能全覆盖，兼顾颜值与实用性，支持设备管理、数据可视化、日志排查、趋势分析。

7.1 数据仪表盘（总览面板）

核心统计卡片：已绑定设备数、在线设备数、历史数据总量、待绑定设备数；实时展示各房间最新温湿度数据、系统运行时长，全屋环境状态一目了然。

—— 后台仪表盘首页截图

7.2 多房间数据对比（核心功能）

支持自定义时间区间（48小时/7天/30天），勾选多房间同时对比，温度、湿度双曲线可视化展示，鼠标悬浮精准查看时间点数值，可直观分析不同楼层、房间的环境差异、昼夜变化趋势、极端温湿度时段。

—— 多房间数据对比曲线截图

7.3 上报日志管理

全量记录设备上报行为，支持按设备、时间、上报结果筛选，精准定位断网、上报失败、数据异常等问题，设备运行状态全程可追溯。

—— 系统上报日志页面截图

7.4 设备绑定与管理

自动识别新设备上线，支持一键绑定房间、修改归属、解绑重置，预设全屋楼层房间模板，批量部署无需手动配置，新手也能快速上手。

—— 设备管理页面截图

八、设备部署与长期运维方案

8.1 部署规范

• 安装位置：房间居中、避开阳光直射、空调出风口、墙面角落，保证数据采集精准；
• 供电方式：5V/1A常规手机充电头，设备工作电流约80mA，超低功耗；
• 网络要求：连接2.4G WiFi（ESP32-C3不支持5G频段），优选1/6/11信道，稳定性最佳；
• 防护方案：热缩管绝缘包裹/3D打印透气外壳，防尘防潮，适配长期室内运行。

8.2 稳定性与数据安全

• 设备无硬件看门狗，经过7×24小时长期压力测试，无死机、无重启、无数据异常；
• 所有数据本地SQLite单文件存储，迁移、备份、复刻极其简单；
• 完全私有化部署，无第三方数据上传，隐私与数据安全100%可控。

九、串口日志全场景解读（调试排错手册）

固件输出全流程日志，覆盖上电、联网、校时、采集、上报、缓存、补报全场景，新手也能快速定位问题。

9.1 正常启动上线日志

=== 设备启动 ===
设备ID: dev-XXXXXXX
MAC: XXXXXXXX
WiFi连接成功
WiFi OK 本地内网IP
NTP..... OK 2026-07-21 18:00:00
注册 HTTP 200 resp={"code":0,"msg":"已注册"}
SHT40 OK t=26.80 h=55.30
采集 ts=1784640098 t=26.80 h=55.30
上报成功 resp={"code":0,"msg":"ok"}

—— 设备日志截图，查看串口日志需要执行命令，如图。

9.2 断网缓存+联网补报日志

WiFi连接断开
WiFi失败
SHT40 OK t=26.83 h=55.28
采集 ts=1784640128 t=26.83 h=55.28
WiFi离线 缓存
缓存#0[1] ts=1784640128 t=26.8 h=55.3

WiFi恢复连接
NTP..... OK 2026-07-21 18:05:00
WiFi已恢复
补报 #0 17条
补报 #0 批次(17条)
补报 #0 完成

—— 离线缓存+批量补报日志截图

9.3 上报失败重试机制日志

网络波动、服务器临时离线时，设备自动重试上报，失败则存入缓存，保障零数据丢失。

十、程序烧录

10.1 项目编译

pio run -e gateway

首次编译自动下载工具链与依赖库，等待数分钟即可完成。

或通过插件执行upload和build进行烧录和编译

十一、基于1Panel+Docker的后端部署教程（Node.js 容器化部署）

本项目后端采用1Panel运维面板 + Docker容器化部署，全程可视化操作、无需复杂服务器命令，支持开机自启、容器自愈、版本便捷更新，兼顾稳定性与易维护性，适合长期7×24小时运行。以下为从零到上线的完整部署步骤，全程预留截图点位，可直接穿插实操截图。

11.1 前期部署准备

部署前需提前完成两项基础环境配置，保障后续部署无报错：

• 服务器已安装最新版 1Panel运维面板，且面板后台可正常登录；
• 1Panel应用商店已安装并启动 Docker 服务，Docker状态正常、无启动异常；
• 服务器防火墙/安全组放行端口：3009端口（后端服务端口）、80/443端口（域名访问）。

11.2 上传后端项目源码至服务器

通过1Panel文件管理功能，上传并整理后端项目文件：

1. 登录1Panel后台，点击左侧【文件】，进入服务器自定义部署目录（可新建 /esp-monitor 专属项目文件夹）；
2. 将本地完整后端文件夹 ESP32sever 上传至该目录，确保文件夹内包含 server.js、package.json、static 静态资源目录；
3. 核对文件完整性，避免上传过程中文件缺失、损坏。

11.3 1Panel新版创建Node.js运行环境（新版面板专属）

1Panel新版已取消应用商店一键安装Node.js容器的方式，统一采用**【运行环境】模块手动创建Node.js环境**，适配性更强、配置更灵活，专属项目运行环境隔离更干净，具体操作步骤如下：

1. 登录1Panel新版后台，左侧菜单栏点击【网站】-【运行环境】，进入环境创建页面；
2. 点击右上角【创建环境】，在环境列表中选择 Node.js 运行环境；
3. 选择稳定版镜像（推荐16.x/18.x LTS版本，兼容性最佳，适配本项目Express+SQLite运行），点击下一步；
4. 配置新版运行环境核心参数：
   - 环境名称：自定义 esp-temperature-env（专属本项目，方便区分）
   - 项目挂载目录：服务器 /esp-monitor/ESP32sever 挂载至容器工作目录 /app
   - 端口映射：新增端口映射，主机端口 3009 绑定 容器端口 3009
   - 开机自启：默认开启，保障服务器重启后环境与服务自动恢复
   - 容器自愈：开启异常自动重启功能
5. 确认所有参数无误后，点击【提交创建】，系统自动拉取Node.js镜像、初始化专属运行环境，等待环境部署完成且状态显示运行中。

11.4 端口放行与访问测试

部署完成后，记得服务器放行端口并测试服务可用性：

11.7 域名反向代理配置（外网访问可选）

若需通过域名外网访问，借助1Panel自带Nginx服务配置反向代理：

1. 1Panel【网站】-【创建网站】，填写已备案域名，选择运行环境；
2. 保存配置，重启Nginx，即可通过域名无障碍访问后台。

11.8 后续运维与更新说明

• 项目更新：直接替换服务器 ESP32sever 内源码，重启容器即可生效，无需重新部署环境；
• 日志查看：1Panel容器详情页可实时查看运行日志，快速排查上报、连接异常问题；
• 数据备份：直接复制项目目录内SQLite数据库文件，即可完成全量数据备份，迁移便捷；
• 异常恢复：容器自愈功能自动重启崩溃服务，无人值守长期稳定运行。