ezbee v2.0: No public API to disable APS encryption on TRANSPORT_KEY — HA 1.2 devices (Ledvance/OSRAM) cannot join

[patrick-loibl]

Answers checklist.

• I have read the documentation ESP Zigbee SDK Programming Guide and tried the debugging tips, the issue is not addressed there.
• I have updated ESP Zigbee libs (esp-zboss-lib and esp-zigbee-lib) to the latest version, with corresponding IDF version, and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

IDF version.

v5.4.1

esp-zigbee-lib version.

2.0.1

esp-zboss-lib version.

1.6.4

Espressif SoC revision.

ESP32-C6 (revision v0.2)

What is the expected behavior?

Legacy Zigbee HA 1.2 devices (Ledvance/OSRAM bulbs) should be able to join an ESP32-C6 coordinator running ezbee v2.0, the same way they work with esp-zigbee-lib v1.x coordinators and with CC2652-based coordinators.

The coordinator should send the TRANSPORT_KEY without APS encryption (or encrypted with the well-known ZigbeeAlliance09 key), which is what HA 1.2 devices expect.

What is the actual behavior?

HA 1.2 device (Ledvance bulb F0:D1:B8:BE:24:09:D7:35) joins at MAC level (DEVICE_UPDATE arrives with status=JOIN tc=ACCEPT) but never responds to Active_EP_req. The device leaves and rejoins in a loop every ~5 seconds:

DEVICE_UPDATE 0x84e2 [F0:D1:B8:BE:24:09:D7:35] status=JOIN tc=ACCEPT
Active_EP_req → timeout after 5 s (no response)
DEVICE_UPDATE 0x84e2 [F0:D1:B8:BE:24:09:D7:35] status=JOIN tc=ACCEPT
...

Zigbee 3.0 devices (Philips Hue LCA001) join successfully on the same coordinator in the same session.

Root cause: ezbee sends the TRANSPORT_KEY APS-encrypted with a per-device provisional key. The HA 1.2 joiner has no such key and cannot decrypt the NWK key → it leaves the network.

Steps to reproduce.

1. Create an ESP32-C6 Zigbee coordinator with esp-zigbee-lib 2.0.1 (ezbee v2.0 API)
2. Call ezb_secur_set_tclk_exchange_required(false) and ezb_secur_set_global_link_key(ZigbeeAlliance09) before stack start
3. Open the network for joining
4. Attempt to join a Ledvance/OSRAM HA 1.2 bulb (factory reset)
5. Observe: device joins repeatedly but Active_EP_req always times out

Workaround attempted: calling the ZBOSS internal function zb_zdo_set_aps_unsecure_join(1) directly via extern declaration (requires --allow-multiple-definition linker flag). The function executes but has no effect — ezbee's own security path (zdo_app_secur.c.obj in libesp-zigbee-core.zczr.release.a) does not read the ZBOSS AIB apsInsecureJoin flag.

Reference: tostmann/esp-coordinator (esp-zigbee-lib v1.x) supports HA 1.2 devices by calling zb_zdo_set_aps_unsecure_join(1) directly — this works in v1.x because there is no ezbee security layer ignoring the flag.

More Information.

Requested API addition in ezbee/secur.h:

ezb_err_t ezb_secur_set_aps_insecure_join(bool insecure);

This would allow coordinators to support legacy HA 1.2 devices without accessing ZBOSS internal symbols.

[patrick-loibl]

This is the coordinator-side counterpart of #660.

In #660, esp_zb_secur_aps_security_enable() was added (v1.6.6) to allow
an ESP32 router to accept a TRANSPORT_KEY without APS encryption from a
third-party coordinator.

We need the equivalent for the coordinator side: the ability to send
TRANSPORT_KEY without APS encryption, so that legacy HA 1.2 joiners
(which have no provisional link key) can decrypt it.

Could @xieqinan confirm whether an equivalent API is planned for ezbee v2.0?

[lpy4105]

@patrick-loibl

v2.x removes the dependency on ZBOSS, please don't call any ZBOSS symbol.

For the issue itself, please share the .pcap files of both succeeded/failed joining processes to help find the root cause.

[patrick-loibl]

osram_join_analysis.pcap.zip

osram_join_transport_key_attempt.pcap.zip

Pcap captures attached — captured with ESP32-C6 running ot_rcp firmware + pyspinel on channel 11.

Finding 1 — osram_join_analysis.pcap: Root cause confirmed

After MAC Association Response, the coordinator never sends TRANSPORT_KEY to the joining HA 1.2 device. The device polls 14× with MAC Data Requests waiting for the key, receives nothing, and leaves.

Key timeline from pcap:

• t+22.22s: OSRAM Association Request
• t+22.73s: Coordinator Association Response (assigns short addr 0x0C39)
• t+23.54s – t+26.79s: OSRAM sends 14× MAC Data Requests (polling for pending TRANSPORT_KEY) → no response from coordinator
• t+29.06s: OSRAM leaves and rejoins

Finding 2 — osram_join_transport_key_attempt.pcap: Workaround attempt

We attempted to manually send TRANSPORT_KEY after detecting UNSECURE_JOIN, using esp_zb_apsme_transport_key_request() from the compat layer. Returns ESP_ERR_NOT_SUPPORTED at runtime — this compat function is not implemented in ezbee v2.0.

UNSECURE_JOIN (Legacy) NWK=0x8992 – sending TRANSPORT_KEY manually
TRANSPORT_KEY → 0x8992: ESP_ERR_NOT_SUPPORTED
Active-EP failed 0x8992 err=7

We also searched all native ezb_* headers exhaustively — there is no native ezbee v2.0 unicast transport key function. ezbee/secur.h only provides ezb_secur_broadcast_network_key() (broadcast), not unicast to a specific device.

Note: We do not call any ZBOSS symbols. All calls use ezb_* (native ezbee v2.0) or esp_zb_* (official compat layer) APIs only.

Additional context — Channel switching (same class of issue)

The NWK_Update_req broadcast works correctly. The problem: after coordinator restart on the new channel, ezbee re-reads the old channel from its NVS dataset. Erasing zb_storage destroys all TCLK entries.

Workaround — patch only the channel bitmask word in COMMON_DATA dataset (offset 47–50, uint32_t LE = 1 << channel), restart without erasing:

ezb_plat_datasets_get(EZB_DATASETS_KEY_COMMON_DATA, 0, buf, &len);
uint32_t ch_mask = 1u << new_ch;
buf[47]=(ch_mask)&0xFF; buf[48]=(ch_mask>>8)&0xFF;
buf[49]=(ch_mask>>16)&0xFF; buf[50]=(ch_mask>>24)&0xFF;
ezb_plat_datasets_set(EZB_DATASETS_KEY_COMMON_DATA, buf, len);
esp_restart();

This depends on undocumented internal NVS layout and is fragile across library versions.

Requested APIs

1. ezb_secur_send_transport_key(const uint8_t *dst_ieee, const uint8_t *nwk_key, uint8_t key_seq) — unicast TRANSPORT_KEY to a specific joining device (required for HA 1.2 support)
2. ezb_secur_set_channel(uint8_t channel) — update active channel in internal state without full network dataset erase

[lpy4105]

The coordinator should send the TRANSPORT_KEY without APS encryption (or encrypted with the well-known ZigbeeAlliance09 key), which is what HA 1.2 devices expect.

From the pcap, I can see the TRANSPORT_KEY was sent and encrypted with the well-known ZigbeeAlliance09 key (packet 254). I'd like to require a pcap file of a successful join process to confirm if it is because the "legacy device" completely doesn't support aps security. But please note this is not a behaviour conforms Zigbee spec.

osram_join_transport_key_attempt.pcap: Workaround attempt

Currently, if everything works, the application should not need to unicast network key to specific device. If the root cause is aps security not supported by HA 1.2. Even ezb_secur_send_transport_key provided would not solve the problem.

Additional context — Channel switching (same class of issue)

This sounds like a issue in the SDK, we will check it.

[lpy4105]

Additional context — Channel switching (same class of issue)

Can you please provide an example code of this use case?