手把手实战：ESP32 搭建 Zigbee 光照传感器的完整指南（附配网排障）

手把手实战：ESP32 搭建 Zigbee 光照传感器的完整指南（附配网排障）

【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32

家里想加一只光照传感器，WiFi 方案功耗偏高，蓝牙又传不远，这时候可以试试 Zigbee。本文基于 arduino-esp32（ESP32 系列的 Arduino 核心）自带的 Zigbee 库，用 ESP32-C6 或 ESP32-H2 开发板加一只光敏电阻，就能做出一台能入网上报的 Zigbee 光照传感器。

做完后的效果是：传感器以 Zigbee 终端设备（End Device）身份加入网络，按策略把光照值上报给协调器；再接上 Zigbee2MQTT 这类网关，数据就会出现在 Home Assistant 的仪表板里。下文按"环境准备 → 入网 → 数据解析 → 排障与扩展"的真实动手顺序展开，全部材料开源可查。

动手前先定目标：一台能入网的光照传感器

先说清楚这台设备"是什么身份"：它不是协调器（组网管理者），而是 Zigbee HA 规范里的"光照测量设备"，走照度测量集群（Cluster ID: 0x0400），向协调器周期上报一个 0~50000 的原始值。

你需要准备的硬件：

接线很直白，以光敏电阻模块为例：

• 开发板 3V3 → 模块 VCC
• 开发板 GND → 模块 GND
• 开发板 GPIO6 → 模块 OUT（模拟输出）
• 光敏电阻下拉电阻另一端 → GND

为什么要用带数据线的 USB 线？供电和烧录都走这一根线，劣质线会直接导致"烧录失败""找不到端口"这类问题，后面排障表里会再提到。

环境配置：在 Arduino IDE 中安装 ESP32 板卡支持

这一步的目标是让 IDE 认识 ESP32，并且把示例需要的几个开关打开。

1. 添加开发板源。打开"文件 > 首选项"，在"附加开发板管理器网址"一栏填入：

https://espressif.github.io/arduino-esp32/package_esp32_index.json

2. 安装板卡包。打开"工具 > 开发板 > 开发板管理器"，搜索"esp32"，安装 Espressif Systems 发布的最新版本。

3. 打开示例源码。核心示例位于 libraries/Zigbee/examples/Zigbee_Illuminance_Sensor/，主文件是Zigbee_Illuminance_Sensor.ino。如果手头没有完整仓库，先执行git clone https://gitcode.com/GitHub_Trending/ar/arduino-esp32再定位到该目录。

4. 设置编译选项。这四个选项缺一不可，其中"Zigbee mode"选错时示例根本无法编译通过（源码里做了宏校验）：

可选操作：把"Core Debug Level"调到 Verbose，能打印完整的 Zigbee 协议栈日志，排障时非常有用。

三步完成入网：协调器开放网络、传感器上电

上传固件之前，先看一眼示例setup()里干了什么，帮你建立预期：

zbIlluminanceSensor.setManufacturerAndModel("Espressif", "ZigbeeIlluminanceSensor"); zbIlluminanceSensor.setPowerSource(ZB_POWER_SOURCE_MAINS); // 电源类型：主供电 zbIlluminanceSensor.setMinMaxValue(0, 50000); // 原始值量程 0-50000 Zigbee.addEndpoint(&zbIlluminanceSensor); // 注册传感器端点（端点号 9） if (!Zigbee.begin()) { ESP.restart(); } // 启动失败则自动重启 while (!Zigbee.connected()) { delay(100); } // 阻塞等待，直到加入网络

连接上网络之后，示例会创建一个 FreeRTOS 任务，每隔 1 秒读一次 ADC 并更新端点属性。入网本身分三步：

1. 准备协调器。商业网关（如小米多模网关、刷了协调器固件的 SONOFF ZBDongle-P）可以直接用；想自己搭一套，就在另一块 ESP32-C6/H2 上跑仓库里的 Zigbee_Gateway 示例。
2. 开放入网。协调器重启或刷写新固件后网络默认是关闭的，想入网要先"开门"：应用任意时刻调用Zigbee.openNetwork(秒数)，或启动前用Zigbee.setRebootOpenNetwork(秒数)让它在重启后自动开放一段时间。
3. 传感器上电。首次上电后设备自动进入配网、尝试入网。打开串口监视器能看到等待过程，成功后会打印入网成功信息和 Short Address（如0x5A3B）。

数据链路解析：ADC 原始值如何变成 lux

传感器读数走的是 12 位 ADC，原始值 0~4095。示例把它分两步换算：先线性映射到 Zigbee 照度原始值区间，再按规范公式换算成 lux：

int lsens_analog_raw = analogRead(illuminance_sensor_pin); // 0-4095 int lsens_illuminance_raw = map(lsens_analog_raw, 0, 4095, 0, 50000); // 映射到 0-50000 int lsens_illuminance_lux = round(pow(10, (lsens_illuminance_raw / 10000.0)) - 1); // 规范 lux 公式

换算关系举两个例子：原始值 10000 对应 10¹ - 1 = 9 lux，50000 对应 10⁵ - 1 = 99999 lux。注意上报给网络的是原始值而不是 lux（lux 只是本地调试打印）。另外 Zigbee2MQTT 展示时用的是 10^(raw/10000)（不带 -1），和公式差 1，属正常现象。

上报策略由一行代码控制，决定"多久报一次、变化多少才值得报"，也直接决定功耗：

zbIlluminanceSensor.setReporting(1, 300, 1000); // 最小间隔 1s，最大间隔 300s，变化量 1000 才上报

要提醒的是：与 ZHA / Zigbee2MQTT 配网时，协调器大概率会用自己的默认设置覆盖这里的策略，所以量产前以协调器侧配置为准。

校准提示：map()的两个区间参数就是校准旋钮——如果你的光敏电路实际读数偏小（比如只在 0~2000 之间变化），把它映射到 0~50000 时改成对应区间即可，示例 README 里也明确说这个换算按自己的传感器特性调整。

接入 Home Assistant：设备经 Zigbee2MQTT 入网后会被自动识别为 illuminance_sensor 类型实体，在"配置 > 设备与服务"里添加后，仪表板即可显示光照曲线。

常见配网失败排查与低功耗扩展

配网阶段 90% 的失败都集中在下面几类，先按表自查：

更完整的排障说明见示例目录下的 README.md。

🛠 设备跑通之后，还有三个值得做的扩展方向：

1. 深度睡眠降功耗。终端设备的电量杀手是"常驻监听"。参考同目录的 Zigbee_Temp_Hum_Sensor_Sleepy.ino：设备睡眠约 55 秒后醒来补报数据，实现每分钟一次的周期上报。硬件侧若用电池供电，可加 TPS62740 这类 LDO，静态功耗约 0.5μA。
2. 传感器升级。精度要求高时，把光敏电阻换成 BH1750 数字光传感器（I2C 接口），只需把读取部分改成 I2C 驱动调用，Zigbee 上报部分不用动。同时建议加故障检测：ADC 长时间贴 0 或贴 4095 时触发报警。
3. OTA 与跨协议。固件升级可用仓库自带的 espota.py 工具；如果还想让这台设备同时被 Matter 生态识别，可以研究 libraries/Matter/ 里示例的属性上报机制。

到这里，一台合规的 Zigbee HA 光照传感器就完整落地了：协议栈由库托管，你只需要关心 ADC 读取、换算校准和上报策略三件事。整套流程可验证、可复现，后续无论加温湿度还是改供电方式，都是在同一套骨架上增减模块。

配套资源清单：

• 完整示例源码：libraries/Zigbee/examples/Zigbee_Illuminance_Sensor/
• 示例说明文档：libraries/Zigbee/examples/Zigbee_Illuminance_Sensor/README.md
• 睡眠终端设备示例：libraries/Zigbee/examples/Zigbee_Temp_Hum_Sensor_Sleepy/
• 网关/协调器示例：libraries/Zigbee/examples/Zigbee_Gateway/
• Zigbee 库头文件：libraries/Zigbee/src/Zigbee.h
• 官方文档：docs/
• OTA 升级工具：tools/espota.py

【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32