手把手实战ESP32 搭建 Zigbee 光照传感器的完整指南附配网排障【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32家里想加一只光照传感器WiFi 方案功耗偏高蓝牙又传不远这时候可以试试 Zigbee。本文基于 arduino-esp32ESP32 系列的 Arduino 核心自带的 Zigbee 库用 ESP32-C6 或 ESP32-H2 开发板加一只光敏电阻就能做出一台能入网上报的 Zigbee 光照传感器。做完后的效果是传感器以 Zigbee 终端设备End Device身份加入网络按策略把光照值上报给协调器再接上 Zigbee2MQTT 这类网关数据就会出现在 Home Assistant 的仪表板里。下文按环境准备 → 入网 → 数据解析 → 排障与扩展的真实动手顺序展开全部材料开源可查。动手前先定目标一台能入网的光照传感器先说清楚这台设备是什么身份它不是协调器组网管理者而是 Zigbee HA 规范里的光照测量设备走照度测量集群Cluster ID: 0x0400向协调器周期上报一个 0~50000 的原始值。你需要准备的硬件部件规格要求推荐型号主控支持 Zigbee 3.0ESP32-C6-DevKitM-1 / ESP32-H2-DevKitM-1光照传感器模拟输出型GL5528 光敏电阻 10KΩ 下拉电阻电源3.3V 稳定输出MicroUSB 5V开发阶段/ CR2032 电池部署阶段辅助工具-USB 数据线必须带数据线、杜邦线接线很直白以光敏电阻模块为例开发板 3V3 → 模块 VCC开发板 GND → 模块 GND开发板 GPIO6 → 模块 OUT模拟输出光敏电阻下拉电阻另一端 → GND为什么要用带数据线的 USB 线供电和烧录都走这一根线劣质线会直接导致烧录失败找不到端口这类问题后面排障表里会再提到。环境配置在 Arduino IDE 中安装 ESP32 板卡支持这一步的目标是让 IDE 认识 ESP32并且把示例需要的几个开关打开。1. 添加开发板源。打开文件 首选项在附加开发板管理器网址一栏填入https://espressif.github.io/arduino-esp32/package_esp32_index.json2. 安装板卡包。打开工具 开发板 开发板管理器搜索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选错时示例根本无法编译通过源码里做了宏校验菜单项应选值作用开发板ESP32C6 Dev Module / ESP32H2 Dev Module本示例仅支持 C6 与 H2Zigbee modeZigbee ED (end device)以终端设备角色入网Partition SchemeZigbee 4MB with spiffsZigbee 协议栈需要的分区布局USB CDC On BootEnabled让串口监视器可用方便观察配网过程可选操作把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 并更新端点属性。入网本身分三步准备协调器。商业网关如小米多模网关、刷了协调器固件的 SONOFF ZBDongle-P可以直接用想自己搭一套就在另一块 ESP32-C6/H2 上跑仓库里的 Zigbee_Gateway 示例。开放入网。协调器重启或刷写新固件后网络默认是关闭的想入网要先开门应用任意时刻调用Zigbee.openNetwork(秒数)或启动前用Zigbee.setRebootOpenNetwork(秒数)让它在重启后自动开放一段时间。传感器上电。首次上电后设备自动进入配网、尝试入网。打开串口监视器能看到等待过程成功后会打印入网成功信息和 Short Address如0x5A3B。数据链路解析ADC 原始值如何变成 lux传感器读数走的是 12 位 ADC原始值 0~4095。示例把它分两步换算先线性映射到 Zigbee 照度原始值区间再按规范公式换算成 luxint 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 lux50000 对应 10⁵ - 1 99999 lux。注意上报给网络的是原始值而不是 luxlux 只是本地调试打印。另外 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% 的失败都集中在下面几类先按表自查现象处理办法传感器一直连不上协调器在工具菜单把Erase All Flash Before Sketch Upload设为 Enabled 后重新烧录或长按 BOOT 键超过 3 秒触发工厂重置示例loop()里已内置该逻辑调用Zigbee.factoryReset()串口没有任何输出确认 USB CDC On Boot 已启用并换一根带数据线的 USB 线烧录失败降低串口连接速率再试找不到 COM 端口检查 USB 线是否带数据线、串口驱动是否装好更完整的排障说明见示例目录下的 README.md。 设备跑通之后还有三个值得做的扩展方向深度睡眠降功耗。终端设备的电量杀手是常驻监听。参考同目录的 Zigbee_Temp_Hum_Sensor_Sleepy.ino设备睡眠约 55 秒后醒来补报数据实现每分钟一次的周期上报。硬件侧若用电池供电可加 TPS62740 这类 LDO静态功耗约 0.5μA。传感器升级。精度要求高时把光敏电阻换成 BH1750 数字光传感器I2C 接口只需把读取部分改成 I2C 驱动调用Zigbee 上报部分不用动。同时建议加故障检测ADC 长时间贴 0 或贴 4095 时触发报警。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 手把手实战：ESP32 搭建 Zigbee 光照传感器的完整指南（附配网排障）
手把手实战ESP32 搭建 Zigbee 光照传感器的完整指南附配网排障【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32家里想加一只光照传感器WiFi 方案功耗偏高蓝牙又传不远这时候可以试试 Zigbee。本文基于 arduino-esp32ESP32 系列的 Arduino 核心自带的 Zigbee 库用 ESP32-C6 或 ESP32-H2 开发板加一只光敏电阻就能做出一台能入网上报的 Zigbee 光照传感器。做完后的效果是传感器以 Zigbee 终端设备End Device身份加入网络按策略把光照值上报给协调器再接上 Zigbee2MQTT 这类网关数据就会出现在 Home Assistant 的仪表板里。下文按环境准备 → 入网 → 数据解析 → 排障与扩展的真实动手顺序展开全部材料开源可查。动手前先定目标一台能入网的光照传感器先说清楚这台设备是什么身份它不是协调器组网管理者而是 Zigbee HA 规范里的光照测量设备走照度测量集群Cluster ID: 0x0400向协调器周期上报一个 0~50000 的原始值。你需要准备的硬件部件规格要求推荐型号主控支持 Zigbee 3.0ESP32-C6-DevKitM-1 / ESP32-H2-DevKitM-1光照传感器模拟输出型GL5528 光敏电阻 10KΩ 下拉电阻电源3.3V 稳定输出MicroUSB 5V开发阶段/ CR2032 电池部署阶段辅助工具-USB 数据线必须带数据线、杜邦线接线很直白以光敏电阻模块为例开发板 3V3 → 模块 VCC开发板 GND → 模块 GND开发板 GPIO6 → 模块 OUT模拟输出光敏电阻下拉电阻另一端 → GND为什么要用带数据线的 USB 线供电和烧录都走这一根线劣质线会直接导致烧录失败找不到端口这类问题后面排障表里会再提到。环境配置在 Arduino IDE 中安装 ESP32 板卡支持这一步的目标是让 IDE 认识 ESP32并且把示例需要的几个开关打开。1. 添加开发板源。打开文件 首选项在附加开发板管理器网址一栏填入https://espressif.github.io/arduino-esp32/package_esp32_index.json2. 安装板卡包。打开工具 开发板 开发板管理器搜索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选错时示例根本无法编译通过源码里做了宏校验菜单项应选值作用开发板ESP32C6 Dev Module / ESP32H2 Dev Module本示例仅支持 C6 与 H2Zigbee modeZigbee ED (end device)以终端设备角色入网Partition SchemeZigbee 4MB with spiffsZigbee 协议栈需要的分区布局USB CDC On BootEnabled让串口监视器可用方便观察配网过程可选操作把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 并更新端点属性。入网本身分三步准备协调器。商业网关如小米多模网关、刷了协调器固件的 SONOFF ZBDongle-P可以直接用想自己搭一套就在另一块 ESP32-C6/H2 上跑仓库里的 Zigbee_Gateway 示例。开放入网。协调器重启或刷写新固件后网络默认是关闭的想入网要先开门应用任意时刻调用Zigbee.openNetwork(秒数)或启动前用Zigbee.setRebootOpenNetwork(秒数)让它在重启后自动开放一段时间。传感器上电。首次上电后设备自动进入配网、尝试入网。打开串口监视器能看到等待过程成功后会打印入网成功信息和 Short Address如0x5A3B。数据链路解析ADC 原始值如何变成 lux传感器读数走的是 12 位 ADC原始值 0~4095。示例把它分两步换算先线性映射到 Zigbee 照度原始值区间再按规范公式换算成 luxint 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 lux50000 对应 10⁵ - 1 99999 lux。注意上报给网络的是原始值而不是 luxlux 只是本地调试打印。另外 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% 的失败都集中在下面几类先按表自查现象处理办法传感器一直连不上协调器在工具菜单把Erase All Flash Before Sketch Upload设为 Enabled 后重新烧录或长按 BOOT 键超过 3 秒触发工厂重置示例loop()里已内置该逻辑调用Zigbee.factoryReset()串口没有任何输出确认 USB CDC On Boot 已启用并换一根带数据线的 USB 线烧录失败降低串口连接速率再试找不到 COM 端口检查 USB 线是否带数据线、串口驱动是否装好更完整的排障说明见示例目录下的 README.md。 设备跑通之后还有三个值得做的扩展方向深度睡眠降功耗。终端设备的电量杀手是常驻监听。参考同目录的 Zigbee_Temp_Hum_Sensor_Sleepy.ino设备睡眠约 55 秒后醒来补报数据实现每分钟一次的周期上报。硬件侧若用电池供电可加 TPS62740 这类 LDO静态功耗约 0.5μA。传感器升级。精度要求高时把光敏电阻换成 BH1750 数字光传感器I2C 接口只需把读取部分改成 I2C 驱动调用Zigbee 上报部分不用动。同时建议加故障检测ADC 长时间贴 0 或贴 4095 时触发报警。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考