企业官网建设流程全解析

如何用 ESP32 Arduino 在 10 分钟跑通 Zigbee 光照传感器：从零组网到 Home Assistant 可视化

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

用 arduino-esp32 项目自带的 Zigbee 库，在 ESP32-C6/H2 上 10 分钟就能搭出一台符合 ZCL 规范的光照传感器：1 个光敏电阻、1 段示例代码，入网后以微安级待机电流上报 0–100000 lux 量程的 lux 值，可直接被 Zigbee2MQTT 和 Home Assistant 识别。

硬件与固件配置一次备齐

IDE 四项关键参数：开发板选ESP32C6 Dev Module（或 H2），Zigbee mode选Zigbee ED (end device)——示例源码第 30–32 行有编译期检查，选错模式直接编译报错；Partition Scheme选Zigbee 4MB with spiffs（Zigbee 栈需要独立分区）；USB CDC On Boot选Enabled（启用串口看日志）。

接线就是一个电阻分压，共 4 根线：

[ESP32-C6 DevKit] [光敏电阻分压] 3V3 ──────────────────► 光敏电阻上端 GPIO6 (ADC) ◄────────── 中间节点（接 10KΩ 电阻） GND ◄───────────────── 10KΩ 电阻下端

提示：示例默认把传感器接在 GPIO6（见illuminance_sensor_pin变量），BOOT 键默认兼做长按 3 秒工厂重置。接线位置不同就改这两个变量即可。

最小可运行路径：4 段关键代码

示例源码在libraries/Zigbee/examples/Zigbee_Illuminance_Sensor/Zigbee_Illuminance_Sensor.ino，整份不到 150 行，下面只拆 4 段。

设备身份注册（第 79–92 行），决定网关侧如何显示和管理这台设备：

zbIlluminanceSensor.setManufacturerAndModel("Espressif", "ZigbeeIlluminanceSensor"); zbIlluminanceSensor.setPowerSource(ZB_POWER_SOURCE_MAINS); // 电池供电改 ZB_POWER_SOURCE_BATTERY zbIlluminanceSensor.setMinMaxValue(0, 50000); // 对应 0–100000 lux Zigbee.addEndpoint(&zbIlluminanceSensor);

启动协议栈并阻塞等待入网（第 94–108 行）：Zigbee.begin()失败即重启，之后死等到拿到网络地址才往下走——这就是入网成功的判定点：

if (!Zigbee.begin()) { Serial.println("Zigbee failed to start!"); ESP.restart(); } while (!Zigbee.connected()) { delay(100); }

采集与单位换算（第 46–61 行）：12 位 ADC 原始值线性映射到 Zigbee 照度原始值，再按 ZCL 公式还原 lux：

int lsens_analog_raw = analogRead(illuminance_sensor_pin); int lsens_illuminance_raw = map(lsens_analog_raw, 0, 4095, 0, 50000); int lsens_illuminance_lux = round(pow(10, (lsens_illuminance_raw / 10000.0)) - 1); zbIlluminanceSensor.setIlluminance(lsens_illuminance_raw); // 上报用原始值

上报策略（第 119 行）：setReporting(最小间隔, 最大间隔, 变化量)三个参数控制多久发一次、变化多少才发，必须在Zigbee.begin()之后调用：

zbIlluminanceSensor.setReporting(1, 0, 1000); // 原始值每变化 1000 上报，最快 1 秒 1 次

校准建议：map()的 4 个参数就是线性校准系数，用已知 lux 值打两三个点改参数即可；analogSetAttenuation(ADC_11db)（第 72 行）让 ADC 覆盖到约 3.3V 满量程，别漏配。

入网成功标志与 30 秒排查

协调器侧先跑libraries/Zigbee/examples/Zigbee_Gateway/Zigbee_Gateway.ino（编译时选Zigbee ZCZR (coordinator/router)模式），它在第 88 行开放网络 180 秒：

Zigbee.setRebootOpenNetwork(180);

协调器串口打印Formed network successfully即建网完成。此时给传感器上电，成功入网的标志是串口出现类似日志：

Zigbee started successfully! Connecting to network Joined network successfully (Extended PAN ID: ff:ff:..., PAN ID: 0xA1B2, Channel:15, Short Address: 0x5A3B) [Illuminance Sensor] raw analog value: 2048 [Illuminance Sensor] lux value: 9 lux

拿到 Short Address、lux 行开始滚动，数据链路就通了；协调器侧同时会打印New device commissioned or rejoined (short: 0x5A3B)，双向确认。

最常见故障：60 秒仍停在Connecting to network。八成是协调器网络已关闭，或传感器还留着上次组网配置——烧录时把Erase All Flash Before Sketch Upload设为Enabled，或在程序里加一行Zigbee.factoryReset();清掉旧网络信息再试。

功耗、生态接入与合规各做一步

• 上报间隔再降一档：setReporting(1, 300, 1000)把最大间隔放到 300 秒，光照缓变场景几乎不影响观感，空闲期只剩网络维持流量；要再低就参考libraries/Zigbee/examples/Zigbee_Temp_Hum_Sensor_Sleepy/Zigbee_Temp_Hum_Sensor_Sleepy.ino的深睡唤醒写法。
• 接入主流平台：Zigbee2MQTT 会自动识别为illuminance_sensor实体。注意示例第 56 行注释——Z2M 用的公式是10^(raw/10000)（不带-1），与 ZCL 规范公式差 1 lux，介意绝对精度就按平台习惯换算。
• 合规提醒：商用产品需通过 Zigbee 3.0 联盟认证；信道与发射功率遵守当地无线电法规，国内 2.4G 可用信道 11–26。

下一步 3 件事：

1. 把光敏电阻换成 BH1750（I2C 数字光强计），去掉map()校准环节，读数直接就是 lux；
2. 用libraries/Zigbee/examples/下的Zigbee_Temperature_Sensor、Zigbee_On_Off_Light各搭一台，组成"测光 + 控灯"的最小闭环；
3. 给传感器固件接 OTA，参考同目录Zigbee_OTA_Client示例。

配套资源（均在项目内）：

• 完整示例与说明：libraries/Zigbee/examples/Zigbee_Illuminance_Sensor/
• 协调器/网关示例：libraries/Zigbee/examples/Zigbee_Gateway/
• 核心库源码：libraries/Zigbee/
• API 文档：docs/en/zigbee/
• 源码获取：git clone https://gitcode.com/GitHub_Trending/ar/arduino-esp32，芯片规格查 ESP32-C6 / ESP32-H2 官方数据手册

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