ESP32 Arduino 打造低功耗 Zigbee 光照传感器完整指南烧录、入网到 Home Assistant 接入与避坑【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32一块 ESP32-C6 或 ESP32-H2 开发板、Arduino 框架、一只光敏电阻就能做出一个可以直接接入 Home Assistant 的 Arduino Zigbee 光照传感器。本文按真实操作顺序走完烧录、配网、代码原理和 lux 换算最后给你一份省电与避坑清单。先说成果做完你手里有什么一个符合 Zigbee HAZigbee Home Automation紫蜂家庭自动化设备规范的照度测量终端设备上电即自动寻找网络、加入后按策略上报光照数据串口能看到每一秒的原始 ADC 值和换算后的 lux 值方便你校准想更省电官方配套的睡眠版示例Zigbee_Temp_Hum_Sensor_Sleepy.ino演示了采集→上报→深睡循环深睡期间整机电流是微安级一节纽扣电池能撑很久接入 Home Assistant 后仪表板里直接出现光照实体不用再写任何对接代码。下面这张官方外设接线示意图可以先混个脸熟左边的板子、右边的传感器模块中间就是几根杜邦线的事。本例硬件很简单光敏电阻 一个 10kΩ 下拉电阻组成分压电路接到 GPIO6示例中illuminance_sensor_pin 6开发板引脚接到3V3光敏电阻上端VCCGPIO6光敏电阻与下拉电阻中间点OUTGND10kΩ 下拉电阻另一端完整可编译代码在 Zigbee_Illuminance_Sensor.ino支持的目标只有 ESP32-C6 和 ESP32-H2其他芯片跑不了这个例子。 动手前硬件与工具清单选什么规格红线备选方案主控板ESP32-C6-DevKit 或 ESP32-H2-DevKit内置 Zigbee 射频任何带 C6/H2 的第三方开发板变体定义在 variants/ 下光照传感器模拟电压输出即可光敏电阻最便宜高精度需求换 I2C 数字光照芯片如 BH1750 一类读取代码要改成 I2C下拉电阻10kΩ与光敏电阻阻值匹配分压中点根据光敏电阻阻值等比调整电源开发期 USB 5V 直插部署期 CR2032 或电池 低压差稳压供电不稳时先换根带数据线的 USB 线再排查工具USB 数据线务必带数据线充电线烧不进固件杜邦线若干协调器负责建网的主机商业网关或自刷一块 C6/H2没有网关就用另一块 C6/H2 烧网关示例见 Zigbee_Gateway让设备上线装库、设参数、烧录、入网Arduino IDE 里怎么开 Zigbee 终端设备模式先装 ESP32 板级支持文件 偏好设置里添加板级管理器网址再到工具 开发板 开发板管理器搜 esp32 安装步骤详见仓库文档 docs/en/installing.rst。安装成功后开发板管理器里就能搜到并安装 ESP32 核心打开文件 偏好设置对应的管理器界面确认版本后回到本项目工具菜单下做四个必改设置开发板ESP32C6 Dev Module 或 ESP32H2 Dev ModuleZigbee modeZigbee ED (end device)——终端设备模式传感器只做从不建网选错了示例里的#error会直接阻止编译Partition SchemeZigbee 4MB with spiffs——Zigbee 协议栈要独立分区默认分区表装不下USB CDC On BootEnabled——开了才有串口否则你只能盲烧。烧录、开放入网、看串口编译上传波特率 115200 打开串口监视器看到Zigbee started successfully!就开始打点等待入网。协调器一侧开放入网协调器重启后默认网络是关闭的在协调器固件里调用Zigbee.openNetwork(时间秒数)或Zigbee.setRebootOpenNetwork(时间秒数)放在它自己的Zigbee.begin()之前来开门。传感器侧上电后自动搜索并加入串口停止打点即成功之后每秒刷一行 raw / lux 数值说明采集任务已在跑。看懂关键几行代码为什么这么写初始化先登记我是谁再 begin()#define ZIGBEE_ILLUMINANCE_SENSOR_ENDPOINT 9 uint8_t illuminance_sensor_pin 6; // 传感器接 GPIO6 ZigbeeIlluminanceSensor zbIlluminanceSensor ZigbeeIlluminanceSensor(9); zbIlluminanceSensor.setManufacturerAndModel(Espressif, ZigbeeIlluminanceSensor); zbIlluminanceSensor.setPowerSource(ZB_POWER_SOURCE_MAINS); // 告诉网络我是市电供电 zbIlluminanceSensor.setMinMaxValue(0, 50000); // 量程 0-50000即 0-100000 lux Zigbee.addEndpoint(zbIlluminanceSensor); // 端点注册完才能 Zigbee.begin()端点Endpoint设备里暴露给网络的一个接口必须先addEndpoint再begin()顺序反了网络里看不到这个传感器。setPowerSource看着可选其实影响网关怎么对待你——电池设备会收到不同的电源属性查询。光照值为什么是 10 的幂int raw_adc analogRead(illuminance_sensor_pin); // 12 位 ADC0-4095 int raw map(raw_adc, 0, 4095, 0, 50000); // 线性映射到 Zigbee 量程 int lux round(pow(10, raw / 10000.0) - 1); // lux 10^(raw/10000) - 1 zbIlluminanceSensor.setIlluminance(raw); // 上报的是 raw不是 luxZigbee 规范对光照用了对数刻度raw 0 对应 0 lux50000 对应 100000 lux中间按 10 的幂分布——因为人眼对环境光本身就是对数敏感线性刻度在暗处浪费大量量程。注意最后一行端点里存的是 raw 值换算成 lux 只是给你看和校准用的。另外示例里先用analogSetAttenuation(ADC_11db)把 ADC 量程放宽到约 3.3V分压电路才不用吃紧。上报策略delta 比定时更省电// min1s、max0关闭纯周期上报、delta1000 // 含义光照 raw 值变化超过 1000 才上报且最快每秒一次 zbIlluminanceSensor.setReporting(1, 0, 1000);setReporting必须在Zigbee.begin()之后调用。delta 驱动的变化才报意味着白天光照平稳时几乎不发包——这是终端设备省电的主要来源之一。示例里 BOOT 键短按还会触发一次report()强制上报调试时很好用。数据去哪了照度集群与 Home Assistant 接入上报走的是 ZCLZigbee Cluster LibraryZigbee 的应用层协议包中的照度测量集群Cluster ID 0x0400网关/协调器看到的就是这个集群的标准属性。换算关系记住正反两条lux 10^(raw/10000) - 1反算raw 10000 × log10(lux 1)。小细节示例注释提到 Zigbee2MQTT 用的是不带-1的版本高亮处两者几乎无差暗处差不到 1 lux不用纠结。接入路径协调器 → Zigbee2MQTT 插件/集成 → Home Assistant。设备入网后 HA 一般会自动生成illuminance_sensor实体仪表板里就能看到实时 lux。有个预期管理示例注释里写了和 HA 或 Zigbee2MQTT 配网时对方的默认报告配置大概率会覆盖你setReporting设的参数想改到网关侧去改。API 细节都收敛在 libraries/Zigbee/src/Zigbee.h 里想加属性、加回调翻它就行。 省电与避坑清单要深睡就抄睡眠版Zigbee_Temp_Hum_Sensor_Sleepy.ino 的套路是测量→report()→等网络确认带 3 次重试→esp_deep_sleep_start()约一分钟一轮照度传感器可以把上报间隔拉长到几分钟。配网失败三板斧① 确认协调器确实openNetwork了且还在有效窗口内② 换带数据线的 USB 线、降低串口速度③ 终端设备侧清旧网络——工具 Erase All Flash Before Sketch Upload设为 Enabled或长按 BOOT 键 3 秒示例 loop 里已实现触发Zigbee.factoryReset()。ADC 死值检测raw 长期贴 0 或 4095多半是传感器断路/短路或衰减挡位不对示例用ADC_11db对应到约 3.3V加个连续 N 次相同值的判断即可报警。校准别偷懒map()的四个参数就是你的校准旋钮拿已知光照度的环境打两个点改参数比改公式安全。商业部署需要过 Zigbee 联盟 3.0 设备认证注意各地信道与发射功率法规中国大陆常用信道 11-26。更多排错COM 口不识别、烧录失败等直接翻示例目录下的 README.md。 三个可以立刻上手的扩展温湿度复合传感器把睡眠版示例的ZigbeeTempSensor端点加进来同一块板两个端点同时上报照度 温湿度一次搞定。OTA 固件升级仓库里有现成的 Zigbee_OTA_Client 示例配合 tools/espota.py 工具链批量部署后不用逐块拔线刷固件。太阳能 深睡节点深睡循环已经是微安级加块小太阳能板和大容量电池就是不需要换电池的楼道/阳台光照节点电源属性记得改成ZB_POWER_SOURCE_BATTERY。想继续深挖协议细节docs/ 里有完整的 Zigbee 文档章节示例目录 libraries/Zigbee/examples/ 下还有 30 多个设备类型可以直接抄骨架。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ESP32 + Arduino 打造低功耗 Zigbee 光照传感器：完整指南（烧录、入网到 Home Assistant 接入与避坑）
ESP32 Arduino 打造低功耗 Zigbee 光照传感器完整指南烧录、入网到 Home Assistant 接入与避坑【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32一块 ESP32-C6 或 ESP32-H2 开发板、Arduino 框架、一只光敏电阻就能做出一个可以直接接入 Home Assistant 的 Arduino Zigbee 光照传感器。本文按真实操作顺序走完烧录、配网、代码原理和 lux 换算最后给你一份省电与避坑清单。先说成果做完你手里有什么一个符合 Zigbee HAZigbee Home Automation紫蜂家庭自动化设备规范的照度测量终端设备上电即自动寻找网络、加入后按策略上报光照数据串口能看到每一秒的原始 ADC 值和换算后的 lux 值方便你校准想更省电官方配套的睡眠版示例Zigbee_Temp_Hum_Sensor_Sleepy.ino演示了采集→上报→深睡循环深睡期间整机电流是微安级一节纽扣电池能撑很久接入 Home Assistant 后仪表板里直接出现光照实体不用再写任何对接代码。下面这张官方外设接线示意图可以先混个脸熟左边的板子、右边的传感器模块中间就是几根杜邦线的事。本例硬件很简单光敏电阻 一个 10kΩ 下拉电阻组成分压电路接到 GPIO6示例中illuminance_sensor_pin 6开发板引脚接到3V3光敏电阻上端VCCGPIO6光敏电阻与下拉电阻中间点OUTGND10kΩ 下拉电阻另一端完整可编译代码在 Zigbee_Illuminance_Sensor.ino支持的目标只有 ESP32-C6 和 ESP32-H2其他芯片跑不了这个例子。 动手前硬件与工具清单选什么规格红线备选方案主控板ESP32-C6-DevKit 或 ESP32-H2-DevKit内置 Zigbee 射频任何带 C6/H2 的第三方开发板变体定义在 variants/ 下光照传感器模拟电压输出即可光敏电阻最便宜高精度需求换 I2C 数字光照芯片如 BH1750 一类读取代码要改成 I2C下拉电阻10kΩ与光敏电阻阻值匹配分压中点根据光敏电阻阻值等比调整电源开发期 USB 5V 直插部署期 CR2032 或电池 低压差稳压供电不稳时先换根带数据线的 USB 线再排查工具USB 数据线务必带数据线充电线烧不进固件杜邦线若干协调器负责建网的主机商业网关或自刷一块 C6/H2没有网关就用另一块 C6/H2 烧网关示例见 Zigbee_Gateway让设备上线装库、设参数、烧录、入网Arduino IDE 里怎么开 Zigbee 终端设备模式先装 ESP32 板级支持文件 偏好设置里添加板级管理器网址再到工具 开发板 开发板管理器搜 esp32 安装步骤详见仓库文档 docs/en/installing.rst。安装成功后开发板管理器里就能搜到并安装 ESP32 核心打开文件 偏好设置对应的管理器界面确认版本后回到本项目工具菜单下做四个必改设置开发板ESP32C6 Dev Module 或 ESP32H2 Dev ModuleZigbee modeZigbee ED (end device)——终端设备模式传感器只做从不建网选错了示例里的#error会直接阻止编译Partition SchemeZigbee 4MB with spiffs——Zigbee 协议栈要独立分区默认分区表装不下USB CDC On BootEnabled——开了才有串口否则你只能盲烧。烧录、开放入网、看串口编译上传波特率 115200 打开串口监视器看到Zigbee started successfully!就开始打点等待入网。协调器一侧开放入网协调器重启后默认网络是关闭的在协调器固件里调用Zigbee.openNetwork(时间秒数)或Zigbee.setRebootOpenNetwork(时间秒数)放在它自己的Zigbee.begin()之前来开门。传感器侧上电后自动搜索并加入串口停止打点即成功之后每秒刷一行 raw / lux 数值说明采集任务已在跑。看懂关键几行代码为什么这么写初始化先登记我是谁再 begin()#define ZIGBEE_ILLUMINANCE_SENSOR_ENDPOINT 9 uint8_t illuminance_sensor_pin 6; // 传感器接 GPIO6 ZigbeeIlluminanceSensor zbIlluminanceSensor ZigbeeIlluminanceSensor(9); zbIlluminanceSensor.setManufacturerAndModel(Espressif, ZigbeeIlluminanceSensor); zbIlluminanceSensor.setPowerSource(ZB_POWER_SOURCE_MAINS); // 告诉网络我是市电供电 zbIlluminanceSensor.setMinMaxValue(0, 50000); // 量程 0-50000即 0-100000 lux Zigbee.addEndpoint(zbIlluminanceSensor); // 端点注册完才能 Zigbee.begin()端点Endpoint设备里暴露给网络的一个接口必须先addEndpoint再begin()顺序反了网络里看不到这个传感器。setPowerSource看着可选其实影响网关怎么对待你——电池设备会收到不同的电源属性查询。光照值为什么是 10 的幂int raw_adc analogRead(illuminance_sensor_pin); // 12 位 ADC0-4095 int raw map(raw_adc, 0, 4095, 0, 50000); // 线性映射到 Zigbee 量程 int lux round(pow(10, raw / 10000.0) - 1); // lux 10^(raw/10000) - 1 zbIlluminanceSensor.setIlluminance(raw); // 上报的是 raw不是 luxZigbee 规范对光照用了对数刻度raw 0 对应 0 lux50000 对应 100000 lux中间按 10 的幂分布——因为人眼对环境光本身就是对数敏感线性刻度在暗处浪费大量量程。注意最后一行端点里存的是 raw 值换算成 lux 只是给你看和校准用的。另外示例里先用analogSetAttenuation(ADC_11db)把 ADC 量程放宽到约 3.3V分压电路才不用吃紧。上报策略delta 比定时更省电// min1s、max0关闭纯周期上报、delta1000 // 含义光照 raw 值变化超过 1000 才上报且最快每秒一次 zbIlluminanceSensor.setReporting(1, 0, 1000);setReporting必须在Zigbee.begin()之后调用。delta 驱动的变化才报意味着白天光照平稳时几乎不发包——这是终端设备省电的主要来源之一。示例里 BOOT 键短按还会触发一次report()强制上报调试时很好用。数据去哪了照度集群与 Home Assistant 接入上报走的是 ZCLZigbee Cluster LibraryZigbee 的应用层协议包中的照度测量集群Cluster ID 0x0400网关/协调器看到的就是这个集群的标准属性。换算关系记住正反两条lux 10^(raw/10000) - 1反算raw 10000 × log10(lux 1)。小细节示例注释提到 Zigbee2MQTT 用的是不带-1的版本高亮处两者几乎无差暗处差不到 1 lux不用纠结。接入路径协调器 → Zigbee2MQTT 插件/集成 → Home Assistant。设备入网后 HA 一般会自动生成illuminance_sensor实体仪表板里就能看到实时 lux。有个预期管理示例注释里写了和 HA 或 Zigbee2MQTT 配网时对方的默认报告配置大概率会覆盖你setReporting设的参数想改到网关侧去改。API 细节都收敛在 libraries/Zigbee/src/Zigbee.h 里想加属性、加回调翻它就行。 省电与避坑清单要深睡就抄睡眠版Zigbee_Temp_Hum_Sensor_Sleepy.ino 的套路是测量→report()→等网络确认带 3 次重试→esp_deep_sleep_start()约一分钟一轮照度传感器可以把上报间隔拉长到几分钟。配网失败三板斧① 确认协调器确实openNetwork了且还在有效窗口内② 换带数据线的 USB 线、降低串口速度③ 终端设备侧清旧网络——工具 Erase All Flash Before Sketch Upload设为 Enabled或长按 BOOT 键 3 秒示例 loop 里已实现触发Zigbee.factoryReset()。ADC 死值检测raw 长期贴 0 或 4095多半是传感器断路/短路或衰减挡位不对示例用ADC_11db对应到约 3.3V加个连续 N 次相同值的判断即可报警。校准别偷懒map()的四个参数就是你的校准旋钮拿已知光照度的环境打两个点改参数比改公式安全。商业部署需要过 Zigbee 联盟 3.0 设备认证注意各地信道与发射功率法规中国大陆常用信道 11-26。更多排错COM 口不识别、烧录失败等直接翻示例目录下的 README.md。 三个可以立刻上手的扩展温湿度复合传感器把睡眠版示例的ZigbeeTempSensor端点加进来同一块板两个端点同时上报照度 温湿度一次搞定。OTA 固件升级仓库里有现成的 Zigbee_OTA_Client 示例配合 tools/espota.py 工具链批量部署后不用逐块拔线刷固件。太阳能 深睡节点深睡循环已经是微安级加块小太阳能板和大容量电池就是不需要换电池的楼道/阳台光照节点电源属性记得改成ZB_POWER_SOURCE_BATTERY。想继续深挖协议细节docs/ 里有完整的 Zigbee 文档章节示例目录 libraries/Zigbee/examples/ 下还有 30 多个设备类型可以直接抄骨架。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
