基于 ESP32 的物联网智能家居环境检测节点是一个能同时覆盖嵌入式采集、物联网通信、后端接口和前端展示的完整练习项目。它一端用 ESP32 读取温湿度、光照等环境参数通过 MQTT 协议上报到消息服务器另一端用 Python 订阅数据、落库并开放 REST API最上层用 Vue 把数据渲染成看板和列表。整条链路跑通后你不仅理解 MQTT 为什么适合海量物联网设备还能把 Arduino、FastAPI、Vue 三个技术栈串成一个系统。这篇文章从环境准备、固件编写、后端编写、前端展示到联调排错按步骤完成一个可运行的环境检测节点适合正在做课程设计、毕业设计或想从点灯进阶到完整物联网项目的开发者。1. 先拆解环境检测节点的数据链路再决定技术选型1.1 一个环境检测节点要完成的四件事很多人第一次做物联网项目会急着把传感器接上、把代码烧进去结果卡在“数据能从设备出来但存不下来、看不了”。原因是只盯着硬件没有把整条数据链路想清楚。一个环境检测节点至少要完成四件事采集数据温湿度、光照、空气质量等传感器读数。传输数据把采集到的数据从设备发到服务器。存储数据把历史数据保存下来方便回看和做趋势分析。展示数据通过网页或 App 把当前值、历史曲线、异常告警呈现给用户。如果只做前两步那就只是一个“能看到串口日志的传感器实验”。只有把四件事全部串起来才算是一个可用的物联网系统。本文采用的最小组合是“ESP32 MQTT Python Vue”其中 ESP32 负责采集与发送MQTT 负责传输Python 负责订阅与存储Vue 负责展示。1.2 为什么选择 ESP32 而不是传统单片机或树莓派ESP32 是乐鑫推出的一款低功耗微控制器内置 Wi-Fi 和蓝牙价格便宜开发资料多。相比传统 STM32 需要外接 ESP8266 模块才有网络能力ESP32 一块板子就能完成“传感器采集 网络传输”两件事。方案网络能力开发难度功耗适合场景传统 STM32需要外接模块较高较低工业控制、需要严苛时序的场景ESP32自带 Wi-Fi / 蓝牙较低较低智能家居节点、课堂实验、原型验证树莓派自带网口 / Wi-Fi低较高需要跑模型、本地图像识别、复杂业务逻辑对于智能家居环境检测这类轻量数据采集任务ESP32 的 ADC、I2C、UART 外设足够使用2.4GHz Wi-Fi 也能覆盖家庭局域网通信需求。Arduino 框架的生态更让初学者能快速上手不需要深入研究寄存器操作。1.3 数据链路MQTT 为什么是核心枢纽整体数据流可以这样理解ESP32 传感器采集 - MQTT 发布topic: home/node1/environment - MQTT Broker消息中转 - Python 后端订阅 - SQLite 落库 - REST API - Vue 前端轮询展示为什么不直接用 HTTP 从 ESP32 请求后端接口HTTP 是请求-响应模型设备需要不断主动上报服务端无法第一时间感知设备掉线而且重复建立连接的开销比 MQTT 长连接高。MQTT 基于发布/订阅模型Broker 承担消息中转设备只需要维护一条长连接消息就能被所有订阅方收到。对智能家居这种“节点多、单条消息小、实时性要求中等”的场景MQTT 是更贴近生产的选择。1.4 硬件与软件准备清单建议准备一份硬件清单避免调试到一半发现缺少上拉电阻类别名称说明硬件ESP32 DevKitC 开发板常见型号即可注意 Micro USB 数据线要支持数据传输硬件DHT22 温湿度传感器精度高于 DHT11适合演示环境检测硬件BH1750 光照传感器I2C 接口读取环境光强单位 lux硬件面包板 杜邦线用于快速接线不需要焊接软件Arduino IDE建议使用 2.x 版本用于编写和烧录 ESP32 程序软件MosquittoMQTT Broker安装在开发电脑或局域网服务器软件Python 3.9运行后端服务软件Node.js 18运行 Vue 前端工程如果暂时没有 DHT22也可以用 DHT11但代码里的数据类型和精度会略有差异。传感器准备不齐时可以先用串口模拟数据把后端和前端跑通再接真实硬件这是一种很实用的分阶段调试方式。2. 搭建 ESP32 开发环境先把 WiFi 连接跑通2.1 在 Arduino IDE 中添加 ESP32 开发板支持打开 Arduino IDE 后需要先让 IDE 认识 ESP32。进入“文件 - 首选项”在“附加开发板管理器网址”中填入乐鑫官方提供的 ESP32 开发板管理 JSON 地址。然后在“工具 - 开发板 - 开发板管理器”中搜索 ESP32安装名为esp32 by Espressif Systems的开发板支持包。安装过程需要从网络下载较多文件耗时取决于网络情况。如果下载很慢可以重试或通过离线安装包方式安装但要注意从可供信任的渠道获取并校验压缩包内容。安装完成后在“工具 - 开发板”中应该能看到ESP32 Dev Module选项。这里有一个和“ESP32 SPIFFS 插件”相关的误区。SPIFFS 是 ESP32 的文件系统通常用于保存网页、JSON 配置等静态资源本教程用不到。如果看到相关插件安装教程不要混淆把它当成后续配网或升级功能的扩展项即可。2.2 安装传感器和 MQTT 依赖库在“工具 - 管理库”中搜索并安装以下库库名用途PubSubClient by Nick OLearyMQTT 客户端负责连接 Broker、发布消息DHT sensor library by Adafruit读取 DHT11 / DHT22 温湿度数据Adafruit Unified SensorDHT 库的依赖统一传感器数据格式BH1750 by Christopher Laws读取 BH1750 光照传感器安装完库之后建议重启 Arduino IDE避免库索引没有刷新导致编译报错。2.3 最小程序连接 WiFi 并打印 IP先不要急着接传感器第一步是把 ESP32 连上家里的 Wi-Fi。这样能确认开发环境、串口驱动、板子型号都没问题。#include WiFi.h const char* WIFI_SSID your_wifi; const char* WIFI_PASSWORD your_password; void setup() { Serial.begin(115200); WiFi.mode(WIFI_STA); WiFi.begin(WIFI_SSID, WIFI_PASSWORD); Serial.print(Connecting WiFi); while (WiFi.status() ! WL_CONNECTED) { delay(500); Serial.print(.); } Serial.println(); Serial.print(WiFi connected, IP: ); Serial.println(WiFi.localIP()); } void loop() { delay(1000); }烧录后打开串口监视器波特率选择115200。如果看到WiFi connected, IP: 192.168.x.x说明板子已经成功上网。需要注意ESP32 只支持 2.4GHz 频段的 Wi-Fi。如果家里路由器开启了 5GHz 和 2.4GHz 双频合一设备可能扫描不到或连接不稳定建议暂时给物联网设备单独开一个 2.4GHz 的 SSID。2.4 这一步最常见的两个问题第一个问题是串口监视器没有输出。原因通常是 Micro USB 数据线只能充电不能传数据或者没有安装 CP2102/CH340 串口驱动。换一根数据线或者查看设备管理器里是否有对应 COM 口能快速定位。第二个问题是 Wi-Fi 一直打印点号但连不上。优先检查 SSID 和密码是否写错再检查路由器是否设置了设备白名单、AP 隔离等安全策略。如果仍连不上可以用手机开 2.4GHz 热点验证板子本身是否正常。3. ESP32 采集程序温湿度、光照读取和 MQTT 发布3.1 传感器接线本节以 DHT22 温湿度传感器和 BH1750 光照传感器为例。BH1750 模块一般有 4 个引脚VCC、GND、SDA、SCL部分模块还引出 ADDR 地址引脚悬空时默认 I2C 地址为0x23。传感器传感器引脚接 ESP32 引脚说明DHT22VCC3.3V供电正极DHT22GNDGND供电负极DHT22DATAGPIO4数据引脚代码里通过DHTPIN配置BH1750VCC3.3V供电正极BH1750GNDGND供电负极BH1750SDAGPIO21I2C 数据线BH1750SCLGPIO22I2C 时钟线如果使用的是 DHT22 裸传感器而不是模块DATA 与 VCC 之间需要接一个 4.7k 上拉电阻否则数据可能间歇性读取失败。大多数淘宝成品模块已经内置上拉电阻可以直接接线。3.2 采集与发布程序的工作流程程序整体流程是固定的初始化串口方便输出日志。初始化 I2C 总线让 BH1750 能通信。初始化 DHT 传感器。连接 Wi-Fi。设置 MQTT 服务器地址并连接 Broker。在循环中读取传感器数据拼装成 JSON通过 MQTT 发布。这样设计的目的是把“硬件初始化”和“网络连接”分开。如果 DHT 引脚接错串口日志能尽早暴露问题而不需要等 Wi-Fi 和 MQTT 全部跑通之后才发现传感器根本没工作。3.3 核心代码下面是一个可直接烧录的示例程序。编译前把 Wi-Fi 地址和 MQTT Broker 地址替换成自己的环境。#include WiFi.h #include PubSubClient.h #include DHT.h #include BH1750.h #include Wire.h #define DHTPIN 4 #define DHTTYPE DHT22 const char* WIFI_SSID your_wifi; const char* WIFI_PASSWORD your_password; const char* MQTT_HOST 192.168.1.100; const int MQTT_PORT 1883; const char* MQTT_TOPIC home/node1/environment; const char* DEVICE_ID node1; DHT dht(DHTPIN, DHTTYPE); BH1750 lightMeter; WiFiClient espClient; PubSubClient mqttClient(espClient); void setupWifi() { WiFi.mode(WIFI_STA); WiFi.begin(WIFI_SSID, WIFI_PASSWORD); Serial.print(Connecting WiFi); while (WiFi.status() ! WL_CONNECTED) { delay(500); Serial.print(.); } Serial.println(); Serial.print(WiFi connected, IP: ); Serial.println(WiFi.localIP()); } void reconnectMqtt() { while (!mqttClient.connected()) { Serial.print(Attempting MQTT connection...); if (mqttClient.connect(DEVICE_ID)) { Serial.println(connected); } else { Serial.print(failed, rc); Serial.print(mqttClient.state()); Serial.println( retry in 5s); delay(5000); } } } void publishEnvironment() { float humidity dht.readHumidity(); float temperature dht.readTemperature(); float lux lightMeter.readLightLevel(); if (isnan(humidity) || isnan(temperature)) { Serial.println(DHT read failed); return; } if (isnan(lux)) { lux 0; } String payload {; payload \deviceId\:\ String(DEVICE_ID) \,; payload \temperature\: String(temperature, 1) ,; payload \humidity\: String(humidity, 1) ,; payload \lux\: String(lux, 1); payload }; mqttClient.publish(MQTT_TOPIC, payload.c_str(), true); Serial.print(Published: ); Serial.println(payload); } void setup() { Serial.begin(115200); Wire.begin(21, 22); dht.begin(); if (!lightMeter.begin()) { Serial.println(BH1750 not found, check wiring); } setupWifi(); mqttClient.setServer(MQTT_HOST, MQTT_PORT); } void loop() { if (!mqttClient.connected()) { reconnectMqtt(); } mqttClient.loop(); publishEnvironment(); delay(5000); }这段代码有五个关键点实际项目里经常踩坑。第一Wire.begin(21, 22)中传入的 21 和 22 必须和接线一致。不同 ESP32 开发板的默认 I2C 引脚不一定相同显式指定能避免“明明库是好的但数据一直为零”的问题。第二mqttClient.connect(DEVICE_ID)中的 DEVICE_ID 是 MQTT 客户标识同一 Broker 下不能有重复否则后连接的设备会把前面的连接踢掉。多节点时应改成 node1、node2 这样的唯一值。第三mqttClient.publish(MQTT_TOPIC, payload.c_str(), true)的第三个参数是 retained也就是遗嘱消息。设置为 true 后Broker 会保留最近一条消息新订阅者一上线就能立即拿到当前环境状态而不是必须等下一次发布。这对环境监测页面非常有用。第四delay(5000)让设备每 5 秒发布一次。DHT22 两次采样间隔不能低于 2 秒所以 5 秒是合理值。如果改成 500 毫秒会频繁触发传感器读取失败。第五reconnectMqtt()中做的是阻塞式重连。演示场景可以接受但生产环境需要增加最大重试次数、Wi-Fi 状态检查、看门狗等处理防止设备长时间卡在重连循环里。3.4 MQTT 主题和 JSON 数据格式设计MQTT 主题用于区分不同设备、不同数据类型。推荐格式为home/{deviceId}/environment例如home/node1/environment home/kitchen/environment这样后端在订阅时可以使用通配符home//environment一次订阅所有节点的环境数据也能用home/node1/#订阅某个节点的所有数据。Payload 使用 JSON 格式{ deviceId: node1, temperature: 26.3, humidity: 58.2, lux: 320.0 }字段命名建议统一风格。如果 ESP32 端使用 camelCase后端解析时也使用 camelCase不要一边写deviceId一边写device_id否则在联调阶段会浪费大量时间。3.5 串口日志验证烧录成功后打开串口监视器正常情况下会看到类似下面的日志Connecting WiFi......... WiFi connected, IP: 192.168.1.50 Attempting MQTT connection...connected Published: {deviceId:node1,temperature:26.3,humidity:58.2,lux:320.0}如果看到Attempting MQTT connection...failed, rc-4说明 MQTT Broker 地址填错了、端口不对或者 Broker 没有启动。如果看到DHT read failed说明 DHT 接线或传感器类型有问题。4. 搭建 MQTT Broker让数据先“有地方去”4.1 Broker 在链路中的位置MQTT Broker 是消息中转站。ESP32 发布消息到 BrokerPython 后端从 Broker 订阅消息。设备之间不直接通信这样带来三个好处设备不需要知道后端在哪、后端离线时消息可以暂存、多个订阅者可以同时消费同一份数据。本教程使用 Mosquitto它是开源 MQTT Broker 中最常见的一种。开发环境只需要单机模式不需要集群。4.2 安装和启动 MosquittoUbuntu / Debian 系统执行sudo apt update sudo apt install -y mosquitto mosquitto-clients systemctl status mosquittomacOS 使用 Homebrewbrew install mosquitto brew services start mosquittoWindows 可以到官方下载安装包安装后以服务方式运行。安装完成后mosquitto_sub和mosquitto_pub这两个命令行工具会一并可用它们在后端开发阶段非常有用。4.3 修改监听地址和匿名访问默认配置下Mosquitto 只监听本机回环地址127.0.0.1。如果 ESP32 和 Broker 在同一台电脑上跑那没问题。如果 Broker 跑在开发机上ESP32 通过局域网连接就需要修改监听地址。找到 Mosquitto 配置文件/etc/mosquitto/mosquitto.conf加入listener 1883 0.0.0.0 allow_anonymous true然后重启 Mosquittosudo systemctl restart mosquitto注意allow_anonymous true只适合本机学习和受信任的局域网环境。生产环境必须关闭匿名访问开启用户名密码认证和 TLS 加密否则局域网内的其他设备可以随意订阅和发送消息。4.4 用命令行工具验证消息通道先开一个