Arduino ESP32 Zigbee 多设备验证测试指南ZigbeeCore 与 26 种端点类的端到端测试架构解析【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32导读本文以 Arduino ESP32 官方仓库arduino-esp32中的 Zigbee 验证测试套件 为蓝本完整剖析这套基于ESP32-C6 / ESP32-H2 双设备multi-DUT的 Zigbee 库验证方案。它覆盖ZigbeeCore栈配置、26 种 Zigbee 端点类注册、设备端深层 API 测试getter 往返、回调、上报、组网/入网以及协调器Coordinator→ 终端设备End device的真实 ZCL 无线互联互通interop。读完本文你将掌握这套测试的架构、全部测试用例、串口驱动协议与 FQBN 配置要求并能对照源码理解Zigbee.begin()幂等性、IAS Zone 入网机制等关键实现细节。测试目标与总体架构Zigbee 验证测试的核心目标是在真实 802.15.4 无线链路上对 arduino-esp32 的 Zigbee 库进行栈级、端点级、协议级三层验证。与单板测试不同它使用两块开发板构成一个最小 Zigbee 网络从而在无外部 Hub 的情况下完成真实无线数据收发测试。┌──────────────────────────────┐ 802.15.4 ┌───────────────────────┐ │ Coordinator (device0) │◄─────── wireless ────────►│ End device (device1) │ │ • All 26 endpoint types │ │ • Light temp sensor │ │ • Deep API switch interop │ epSwitch ──on/off──► │ • Remote light control│ └──────────────┬───────────────┘ └──────────┬────────────┘ │ serial │ serial ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ pytest (test_zigbee.py) │ └─────────────────────────────────────────────────────────────────────────────────┘架构图引自 tests/validation/zigbee/README.md分工如下Coordinatordevice0运行 coordinator/coordinator.ino注册全部 26 种 Zigbee 端点类型执行ZigbeeCore与深度端点 API 测试并作为协调器组建网络End devicedevice1运行 end_device/end_device.ino注册ZigbeeLight与ZigbeeTempSensor两个端点加入协调器网络接受协调器开关的远程控制pytest 驱动test_zigbee.py 通过串口分别与两块板卡通信按状态机依次推进测试阶段。端点注册与前begin()配置集中在 coordinator/zigbee_endpoint_matrix.h深度端点测试则位于 coordinator/zigbee_endpoint_deep_tests.h。硬件、运行环境与构建要求该测试对硬件和构建配置有明确且严格的要求见 README 的 Requirements 章节 与 ci.yml项目要求说明硬件两块ESP32-C6 或 ESP32-H2开发板必须支持 802.15.4 射频Zigbee 协议的物理层承载仿真支持Wokwi / QEMU不支持802.15.4 射频无法被仿真模拟CI Runnertwo_duts双 DUT被测设备专用运行器SoC 配置CONFIG_ZB_ENABLEDy、CONFIG_SOC_IEEE802154_SUPPORTEDy启用 Zigbee 协议栈并确认 SoC 支持 IEEE 802.15.4Coordinator FQBNPartitionSchemezigbee_zczr,ZigbeeModezczr协调器使用 ZCZRZigbee Coordinator Zigbee Router分区与模式End device FQBNPartitionSchemezigbee,ZigbeeModeed终端设备使用 edend device模式上述 FQBN 后缀在 ci.yml 中以fqbn_append字段形式配置平台项wokwi: false、qemu: false进一步确认了必须使用真实硬件。值得一提的是固件代码对编译环境的健壮性两份.ino均以#if CONFIG_ZB_ENABLED包裹主体逻辑当CONFIG_ZB_ENABLED未使能时会编译一个仅输出test_zigbee_not_supportedTEST_IGNORE_MESSAGE(Zigbee not enabled in sdkconfig)的降级版本保证在非 Zigbee 目标上编译不失败、测试被标记为忽略而非误报。Coordinator 端测试用例协调器固件 coordinator.ino 在setup()中通过 Unity 框架顺序执行以下测试测试函数覆盖内容test_coordinator_configZigbeeCore在begin()之前的 setters/getters扫描时长、调试模式、绑定、射频/主机配置test_coordinator_register_all_endpoints注册全部 26 种端点类型并完成begin()前的簇cluster配置test_coordinator_begin调用begin()并验证重复begin()返回falsetest_coordinator_stop_startstop()/start()的暂停与恢复test_coordinator_rolegetRole()返回协调器角色test_coordinator_form_networkopenNetwork()组建网络connected()确认打印NETWORK_READYtest_coordinator_endpoint_deep_tests14 组深度测试灯、插座、风扇、窗帘、IAS Zone、温湿度、环境传感器、模拟/二进制/多态 I/O、电气测量Unity 测试结束后loop()会在 pytest 发送RUN_INTEROP命令后执行协调器→终端设备的开关/灯互联互通测试。begin() 前的 ZigbeeCore 配置细节从 coordinator.ino 的test_coordinator_config可以看到协调器使用的关键配置 API 及断言值Zigbee.setScanDuration(2); TEST_ASSERT_EQUAL(2, Zigbee.getScanDuration()); Zigbee.setRxOnWhenIdle(true); TEST_ASSERT_TRUE(Zigbee.getRxOnWhenIdle()); Zigbee.setDebugMode(true); TEST_ASSERT_TRUE(Zigbee.getDebugMode()); Zigbee.allowMultiEndpointBinding(true); TEST_ASSERT_TRUE(Zigbee.allowMultiEndpointBinding()); Zigbee.setTimeout(ZB_TIMEOUT_MS); // 30000 ms Zigbee.setPrimaryChannelMask(ESP_ZB_TRANSCEIVER_ALL_CHANNELS_MASK); esp_zb_radio_config_t radio Zigbee.getRadioConfig(); TEST_ASSERT_EQUAL(ZB_RADIO_MODE_NATIVE, radio.radio_mode); esp_zb_host_config_t host Zigbee.getHostConfig(); TEST_ASSERT_EQUAL(ZB_HOST_CONNECTION_MODE_NONE, host.host_connection_mode);这些断言从侧面印证了库的默认/配置行为射频模式为ZB_RADIO_MODE_NATIVE原生模式区别于 RCP 主机模式、主机连接模式为ZB_HOST_CONNECTION_MODE_NONE。对应 API 声明可在 ZigbeeCore.h 中查证begin、started、connected、getRole、addEndpoint等。26 种端点注册矩阵zigbee_endpoint_matrix.h 定义了 26 个端点宏ZB_EP_LIGHT1到ZB_EP_RANGE_EXT26并逐一实例化对应端点类。完整清单如下端点宏类典型用途ZB_EP_LIGHTZigbeeLight开关灯ZB_EP_DIMMABLEZigbeeDimmableLight可调光灯ZB_EP_COLOR_DIMZigbeeColorDimmableLight彩色可调光灯ZB_EP_SWITCHZigbeeSwitch开关用于 interop 遥控ZB_EP_COLOR_DIMMER_SWZigbeeColorDimmerSwitch彩色调光开关ZB_EP_OUTLETZigbeePowerOutlet智能插座ZB_EP_FANZigbeeFanControl风扇控制ZB_EP_THERMOSTATZigbeeThermostat恒温器ZB_EP_COVERINGZigbeeWindowCovering窗帘/百叶ZB_EP_ANALOGZigbeeAnalog模拟量输入/输出ZB_EP_BINARYZigbeeBinary二进制输入/输出ZB_EP_MULTISTATEZigbeeMultistate多态输入/输出ZB_EP_TEMPZigbeeTempSensor温湿度传感器ZB_EP_PRESSUREZigbeePressureSensor气压传感器ZB_EP_FLOWZigbeeFlowSensor流量传感器ZB_EP_ILLUMINANCEZigbeeIlluminanceSensor光照度传感器ZB_EP_OCCUPANCYZigbeeOccupancySensor人体占用传感器ZB_EP_CO2ZigbeeCarbonDioxideSensorCO₂ 传感器ZB_EP_PM25ZigbeePM25SensorPM2.5 传感器ZB_EP_WINDZigbeeWindSpeedSensor风速传感器ZB_EP_CONTACTZigbeeContactSwitch门磁/接触开关ZB_EP_VIBRATIONZigbeeVibrationSensor振动传感器ZB_EP_DOOR_HANDLEZigbeeDoorWindowHandle门窗把手ZB_EP_ELECTRICALZigbeeElectricalMeasurement电气量测量ZB_EP_GATEWAYZigbeeGateway网关ZB_EP_RANGE_EXTZigbeeRangeExtender范围扩展器这些类均可通过Zigbee.h统一引入——Zigbee.h 集中 include 了ep/目录下全部端点头文件与上述矩阵一一对应。register_all_zigbee_endpoints()对每个端点调用setManufacturerAndModel(Espressif, ZBValXXX)后再调用Zigbee.addEndpoint(ep)任何一个端点注册失败都会使函数返回false并触发断言。注册前的簇配置是测试重点几个有代表性的配置片段// 彩色灯声明支持的调色能力 epColorDim.setLightColorCapabilities(ZIGBEE_COLOR_CAPABILITY_HUE_SATURATION | ZIGBEE_COLOR_CAPABILITY_X_Y | ZIGBEE_COLOR_CAPABILITY_COLOR_TEMP); // 温湿度复合传感器温度量程 容差 湿度子传感器 epTemp.setMinMaxValue(-40.0f, 85.0f); epTemp.setTolerance(0.5f); epTemp.addHumiditySensor(0.0f, 100.0f, 0.5f, 45.0f); // 模拟量 I/O输入输出通道、量程与分辨率 epAnalog.addAnalogInput(); epAnalog.addAnalogOutput(); epAnalog.setAnalogInputMinMax(0.0f, 100.0f); epAnalog.setAnalogOutputResolution(0.1f); // 电气测量DC 电压/电流通道、量程与乘除系数 epElectrical.addDCMeasurement(ZIGBEE_DC_MEASUREMENT_TYPE_VOLTAGE); epElectrical.addDCMeasurement(ZIGBEE_DC_MEASUREMENT_TYPE_CURRENT); epElectrical.setDCMultiplierDivisor(ZIGBEE_DC_MEASUREMENT_TYPE_VOLTAGE, 1, 10);begin() 幂等性与栈生命周期coordinator.ino 验证了 Zigbee 栈生命周期的关键语义TEST_ASSERT_TRUE(Zigbee.begin(ZIGBEE_COORDINATOR, true)); // 首次 begin 成功 // 等待 started() 变为 true30 秒超时 TEST_ASSERT_FALSE_MESSAGE(Zigbee.begin(ZIGBEE_COORDINATOR, true), duplicate begin() must return false); // 重复 begin 必须失败 TEST_ASSERT_TRUE_MESSAGE(Zigbee.started(), stack must keep running after rejected begin());这印证了 README 中的说明Zigbee.begin()每次启动只调用一次第二次调用返回false且不会破坏已启动的协议栈。stop()/start()则对应started()标志的清除与恢复test_coordinator_stop_start中start()后等待最多 5 秒恢复。End device 端测试用例终端设备固件 end_device.ino 在setup()中先阻塞等待串口START命令然后执行 Unity 测试测试函数覆盖内容test_end_device_configZigbeeCore在begin()之前的 setters/getters扫描时长 3、setDebugMode(false)、allowMultiEndpointBinding(false)等test_end_device_add_endpointsZigbeeLight与ZigbeeTempSensor的注册及前配置test_end_device_beginbegin()验证重复begin()返回falsetest_end_device_stop_startstop()/start()生命周期test_end_device_rolegetRole()返回 end device 角色test_end_device_join_network加入协调器网络connected()确认打印JOINEDtest_end_device_temp_sensor入网后执行setReporting、setTemperature、reportTemperaturetest_end_device_zcl_interop协调器开关通过绑定控制本机灯RUN_INTEROP触发test_end_device_light本地灯回调、开关、restoreLight终端设备的端点注册end_device.ino展示了典型应用写法zbLight.setManufacturerAndModel(Espressif, ZBValidationED); zbLight.onLightChange(onRemoteLightChange); TEST_ASSERT_TRUE(Zigbee.addEndpoint(zbLight)); zbTemp.setMinMaxValue(-10.0f, 50.0f); zbTemp.setTolerance(0.5f); zbTemp.setManufacturerAndModel(Espressif, ZBValEDTemp); TEST_ASSERT_TRUE(Zigbee.addEndpoint(zbTemp));入网后的温度传感器上报路径end_device.ino验证了配置上报 → 更新数值 → 主动上报的完整链路TEST_ASSERT_TRUE(zbTemp.setReporting(1, 300, 0.5f)); // 最小间隔 1s、最大间隔 300s、变化阈值 0.5 TEST_ASSERT_TRUE(zbTemp.setTemperature(22.5f)); TEST_ASSERT_TRUE(zbTemp.reportTemperature());深度端点 API 测试14 组协调器组网成功、connected()为真之后test_coordinator_endpoint_deep_tests调用 zigbee_endpoint_deep_tests.h 中的run_all_zigbee_endpoint_deep_tests()执行 14 组测试其设计深度对标 Matter phase-0 冒烟测试——在无 Hub 的真实设备上验证回调、getter 往返、上报与多值路径测试组关键验证点test_light_onoff_roundtripsetLight(false/true)与getLightState()往返test_light_callback_and_restoreonLightChange回调触发与状态一致性、restoreLighttest_dimmable_levels调光等级0/128/255往返、onLightChange(state, level)回调、setLightLevel、setLightStatetest_color_light_rgb_and_levelRGBsetLightColor(10,20,30)与getLightColor、色温、亮度、onLightChangeRgb回调、颜色能力位test_power_outletsetState/getPowerOutletState/restoreState、onPowerOutletChange回调test_fan_mode_sequencesetFanModeSequence(FAN_MODE_SEQUENCE_LOW_MED_HIGH_AUTO)与getFanMode()默认FAN_MODE_OFFtest_window_coveringBLIND_LIFT_AND_TILT类型、升降/倾斜限位、0/50/100% 升降与 25/75% 倾斜test_ias_zone_devicesIAS Zone 入网前拒绝写入、入网恢复restoreIASZoneEnroll、入网后完整 setreporttest_temp_humidity_sensor温度/湿度上报配置、数值设置、reportTemperature/reportHumidity/reporttest_environmental_sensors压力、流量、照度、CO₂、PM2.5、风速、占用的上报配置与数值往返test_analog_io模拟输入/输出往返、浮点精度断言TEST_ASSERT_FLOAT_WITHIN(0.01f,...)、onAnalogOutputChange回调test_binary_io二进制输入/输出往返、上报、onBinaryOutputChange回调test_multistate_io多态输入/输出往返、状态名长度校验、上报、onMultistateOutputChange回调test_electrical_measurementDC 电压/电流测量、上报配置setDCReporting与reportDCIAS Zone 入网机制的源码级验证IAS Zone入侵报警系统区域设备接触开关、振动传感器、门窗把手有一个重要行为未入网enrolled时禁止写入和上报。深度测试通过生产环境的重启恢复路径来模拟入网zigbee_endpoint_deep_tests.h// 未入网set 必须失败 TEST_ASSERT_FALSE_MESSAGE(epContact.enrolled(), contact should start un-enrolled); TEST_ASSERT_FALSE_MESSAGE(epContact.setClosed(), setClosed must fail when not enrolled); // 通过底层 esp_zb_zcl_set_attribute_val 注入伪造的 CIE 地址与 ZoneID fake_ias_zone_enroll_attrs(ZB_EP_CONTACT); TEST_ASSERT_TRUE_MESSAGE(epContact.restoreIASZoneEnroll(), restoreIASZoneEnroll failed); TEST_ASSERT_TRUE_MESSAGE(epContact.enrolled(), contact should be enrolled after restore); // 入网后完整的 set report 路径 TEST_ASSERT_TRUE(epContact.setClosed()); TEST_ASSERT_TRUE(epContact.setOpen());这里通过esp_zb_lock_acquire(portMAX_DELAY)加锁后直接调用 ESP-IDF 层esp_zb_zcl_set_attribute_val设置ESP_ZB_ZCL_ATTR_IAS_ZONE_IAS_CIE_ADDRESS_ID与ESP_ZB_ZCL_ATTR_IAS_ZONE_ZONEID_ID再调用restoreIASZoneEnroll()走设备重启恢复的同一代码路径验证了生产场景下重启后恢复入网状态的正确性。接触开关、振动、门窗把手三种 IAS 设备均被完整覆盖。串口协议与 pytest 驱动流程由于协调器与终端设备烧录节奏不同pytest 在协调器完成测试套件后再驱动终端设备测试通过一套明确定义的串口标记协议同步双方README 的 Serial Protocol 章节协调器打印[COORDINATOR] Ready运行 Unity 测试依次打印[COORDINATOR] NETWORK_READY→API_TESTS_DONE→INTEROP_READY→DONE终端设备打印[ENDDEVICE] Readypytest 向终端设备发送START终端设备运行 Unity 测试、加入网络打印[ENDDEVICE] JOINEDpytest 向两台设备发送RUN_INTEROP协调器打印[COORDINATOR] INTEROP_ARMED开关驱动终端设备灯光 → 终端设备打印[ENDDEVICE] REMOTE_LIGHT_ON/REMOTE_LIGHT_OFF→ 两台设备均打印SWITCH_INTEROP_DONE终端设备完成剩余 Unity 测试打印[ENDDEVICE] DONE。对应的 pytest 实现位于 test_zigbee.py其中使用dut[0]/dut[1]获取两台设备句柄用expect_exact按超时窗口逐阶段等待标记例如等待协调器就绪超时 120 秒、等待NETWORK_READY超时 180 秒、等待深度测试完成超时 300 秒并用write(START\n)、write(RUN_INTEROP\n)发送命令。各阶段超时设置如下阶段等待标记超时协调器就绪[COORDINATOR] Ready120 s组网 深度测试NETWORK_READY/API_TESTS_DONE180 s / 300 s互操作就绪与完成INTEROP_READY/DONE60 s / 30 s终端设备就绪[ENDDEVICE] Ready180 s入网[ENDDEVICE] JOINED60 s无线遥控REMOTE_LIGHT_ON/REMOTE_LIGHT_OFF各 90 s双方收尾两个SWITCH_INTEROP_DONE/[ENDDEVICE] DONE30~120 sZCL 互联互通interop的状态机协调器的 interop 逻辑由ZbInteropState枚举状态机驱动coordinator.ino 与 loop() 实现ZB_INTEROP_WAIT_BIND收到RUN_INTEROP后进入等待epSwitch.bound()绑定建立于终端设备入网时的自动绑定。若 60 秒内未绑定成功打印SWITCH_INTEROP_FAILED并结束ZB_INTEROP_LIGHT_ON调用epSwitch.lightOn()保持 2 秒后epSwitch.lightOff()ZB_INTEROP_LIGHT_OFF保持 1 秒后打印SWITCH_INTEROP_DONE。终端设备侧通过onRemoteLightChange回调end_device.ino分别打印REMOTE_LIGHT_ON/REMOTE_LIGHT_OFF并在test_end_device_zcl_interop中以 60 秒窗口断言两个标记都出现过从而证明真实 ZCL on/off 命令经由 802.15.4 无线链路成功到达终端设备。测试边界与设计取舍README 的 Notes 章节明确了该套件的覆盖范围与有意为之的边界理解这些对正确使用测试结果至关重要begin()单次语义每次启动只调用一次第二次调用返回false已在两端固件中断言验证。深度来源不同与 Matter 验证不同Zigbee 无法在单台 DUT 上中途注销/重启网络——本套件的深度来自 getter 往返、回调、上报、begin()前簇配置以及第二块板卡上的真实 ZCL 无线交互。注册但无本地 setter 的端点恒温器、网关、范围扩展器在协调器上注册但 Arduino API 中没有简单的本地属性 setter其控制路径通过注册与 ZCL 示例覆盖。未覆盖路径终端设备→协调器的开关控制未覆盖需要 bind/discover API协调器→终端设备 interop 利用入网时自动绑定。未覆盖的 APIscanNetworks、factoryReset、RCP 主机模式未在此套件中覆盖可在 libraries/Zigbee/examples 下的库示例如Zigbee_Scan_Networks、Zigbee_Gateway中找到对应用法。结语这套 Zigbee 多设备验证测试是 arduino-esp32 测试体系中覆盖度极高的端到端方案它用两块 ESP32-C6/H2 开发板搭建了真实的 Zigbee 网络通过 Unity设备端与 pytest主机端两级框架把栈配置、26 种端点注册、深度 API 行为与跨设备 ZCL 互通全部纳入自动化回归。无论是想理解 Zigbee 库 API 的正确用法还是希望复用这套双 DUT 测试模式来验证自己的 Zigbee 固件tests/validation/zigbee 目录下的固件源码、端点矩阵、深度测试与 pytest 驱动都是可直接研读与运行的完整参考实现。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考