OpenThread stability issues with esp32c6/h2 and nrf52840

[ivmarkov]

EDIT: Items addressed or partially addressed by the updated ESP 802.15.4 driver explicitly marked as such.

This is an umbrella issue for tracking stability of openthread when operating with the esp-hal 802.15.4 radio. To be extended in future for NRF52.

The purpose of this issue is to:

• Describe all known problems
• Validate the fixes recently done in feat(api): add set_link_mode method for Thread link mode configuration #50
• Validate the fixes suggested downstream in rs-matter-embasy
• Possibly propose additional fixes
• Compare with the ESP-IDF openthread implementation (e.g. via this) which seems quite a bit more stable

======

Missing incoming UDP packets

The problem is that with MTD devices (we build openthread only with MTD mode for now), the radio will enter a sleep mode after transmission, rather than go into RX mode.
As a result, incoming packets might get missed.

• Proposed solution: enable rx_when_idle = true.
• Implemented by the updated 802.15.4 driver: Yes

UPDATE: Confirmed partially.

ESP-IDF actually, does the same, unconditionally.

UPDATE: Note that this is some sort of "logical" rx_on_when_idle = true operation!
The rx_on_when_idle = true is NEVER set into the PIB register of the radio.
It is just a software flag, which - when set to true - causes the software around the radio to "manually" switch it to RX mode - in the ISR handler itself. There is this NEXT_OPERATION(bool) macro, which is used only within the ISR and which - at the end of the ISR execution - causes the radio either to enter an RX receive mode, or not.

More findings:

• Implemented by the updated 802.15.4 driver: Yes - for timer0; timer1 not urgent as it is only necessary for tx/rx "at that time" operations

The ESP-IDF uses two timers - timer0 and timer1

• timer1 is used for "receive at" commands, so for now maybe less interesting
• timer0 however, is set to fire after ~ 200ms after a TX frame is sent and if it does fire, then this is treated as "TX ACK timeout event", i.e. we have not received the ACK for a TX event. Moreover, while waiting for the TX ack frame, the driver enters an "RX_ACK" state

Moreover, auto tx-ack (i.e. sending an ACK for a received RX frame) works only for frame version 1; for newer frames, the ESP-IDF radio driver "manually" sends an ACK frame:

// auto tx ack only works for the frame with version 0b00 and 0b01

Even for the "automatic" sending of an ACK frames, this is done explicitly by setting the radio driver in state ieee802154_set_state(IEEE802154_STATE_TX_ACK); - check if we are doing this.

Ditto for getting ACKs for sent TX frames, the radio driver explicitly sets the state to
ieee802154_set_state(IEEE802154_STATE_RX_ACK); - check if we are doing this. This is the moment when timer0 is set to 200ms.

Sub-proposal

• REJECTED - see above; all traces of this now removed from openthread

Only enable this AFTER the device had joined the Thread network. Justification here.

While I indeed do observe that the device cannot join the Thread network if rx_when_idle is - at that time - already set to true, I can't explain to myself yet how ESP-IDF does it, given that it unconditionally enables the flag already at the very beginning?

Moreover, just setting log-level to "Debug" in the light_thread rs-matter-embassy example makes the problem disappear (or become less of an issue) as it connects then after a few retries. But the question how ESP-IDF does it with always-enabled rx_when_idle remains. So indeed - maybe a deeper problem here, related to the ones below.

I suspect we have a deeper issue which is not diagnosed yet and which is exposed during device joining the Thread network with rx_when_idle = true?

UPDATE: See above - the ESP-IDF radio drive never sets rx_on_when_idle = true in the PIB register!!

openthread is configured with too few buffers ("NoBufs" error)

• Implemented by the updated 802.15.4 driver: Yes

This manifests itself with

INFO - [OpenThread] [N] 0MeshForwarder-: Dropping rx lowpan HC frame, error:NoBufs, len:52, src:2e9acaa65349e639, dst:0xffff, sec:no

Confirmed

The solution is to re-compile OpenThread C with this (which is already merged).

Perhaps, going with 128 is a bit too much though?
ESP-IDF uses 65 by default.

openthread cannot reassemble the 802.15.4 RX frames into an Ipv6 frame

• Implemented by the updated 802.15.4 driver: Yes

TBD: Put an openthread log entry of the error.

Confirmed

Also not observed with ESP-IDF.

The solution seems to be to:

• Enable rx_when_idle = true
• Increase the queue of the baremetal 802.15.4 driver from 10 to something larger (I use 50 ATM, but that might be too much). Since this is a conf parameter, no changes to esp-radio necessary

The esp-radio 802.15.4 driver seems to run in low-power mode?

• Implemented by the updated 802.15.4 driver: Yes (though only some bugfixes done in the driver); the default (in openthread) was 8dBm or less; ESP IDF was using 20dBm (max) by default)

Confirmed

What I'm observing is that ESP-IDF can connect from quite far, while esp-radio 802.15.4 seems to struggle with distance. I literally have to have the Matter controller at ~ 2-3m from the device, when using the baremetal driver.

In any case, it seems we are too simplistic in esp-radio as to how we set the power which is in dBm. We just set it in the register. ESP-IDF - in contrast - normalizes it to an "index" first.

Lot's of re-send retires observed at the Matter UDP packet level.

• Implemented by the updated 802.15.4 driver: No

The larger the packet, the more difficult to send:

WARN - 
<<SND Re-sending
      => UDP [fdac:bcdf:a3c9:1:cd4b:f2ff:8956:c860]:5540 [SID:72d9,CTR:58c96b1][I|A|R,EID:1,PROTO:1,OP:5,ACTR:82a3c88]
      IM::ReportData

Cause - unknown.

Some speculation:

• It could be that we do not support the Thread "security enh ack yet" - double check we are building OpenThread C with a version strictly smaller than OT_THREAD_VERSION_1_2
• Also what is this? Unsure.

The esp driver does not "give back" to openthread the TX ACK frame it got

• Implemented by the updated 802.15.4 driver: Yes

Basically here we should return to openthread the TX ACK frame. Might be the root cause for the re-send problem.

Need to figure out where exactly the received TX ACK frame is stored. Seems to be in the RX queue?! - https://github.com/esp-rs/esp-hal/blob/327071c262afaa0682ffd9ac55e0a747966e5214/esp-radio/src/ieee802154/raw.rs#L185

[MabezDev]

We based our ieee driver of the pre release code, IDF has since completely overhauled it. I wonder how good AI might be at porting that across 🤔 .

[ivmarkov]

We based our ieee driver of the pre release code, IDF has since completely overhauled it. I wonder how good AI might be at porting that across 🤔 .

We can try that... I would strongly suggest to use the most powerful model copilot can currently proxy - Opus 4.6.
Still, let me capture everything known so far, and potential solutions.

[bjoernQ]

From https://matrix.to/#/!LdaNPfUfvefOLewEIM:matrix.org/$kEnm2CijbyG-8sVpACv56WFq4uZHcXEAFr2GXaqI_E8?via=matrix.org&via=mozilla.org&via=tchncs.de

Documentation is the big problem here - and I personally don't have more information.

Given that, having the code manually translated to Rust (or automatically transpiled to Rust) is honestly probably an "esoteric" thing - and we could just use a the C driver (pre-compiled) ... haven't checked how feasible that is in reality ... as we do for WiFi and BT (while it's still good we can have a look into the C code here)

I guess this is something we could consider. If we don't really understand what the code is doing (and especially why) having the code available in Rust is not that useful - and in terms of keeping up with the changes in the C driver it makes things even worse

(This is also true for some other under-documented things but lets focus on the 802.15.4 driver here 😄 )

[ivmarkov]

From https://matrix.to/#/!LdaNPfUfvefOLewEIM:matrix.org/$kEnm2CijbyG-8sVpACv56WFq4uZHcXEAFr2GXaqI_E8?via=matrix.org&via=mozilla.org&via=tchncs.de

Documentation is the big problem here - and I personally don't have more information.
Given that, having the code manually translated to Rust (or automatically transpiled to Rust) is honestly probably an "esoteric" thing - and we could just use a the C driver (pre-compiled) ... haven't checked how feasible that is in reality ... as we do for WiFi and BT (while it's still good we can have a look into the C code here)

I guess this is something we could consider. If we don't really understand what the code is doing (and especially why) having the code available in Rust is not that useful - and in terms of keeping up with the changes in the C driver it makes things even worse

(This is also true for some other under-documented things but lets focus on the 802.15.4 driver here 😄 )

The external API necessary to support the C driver might be even smaller than I thought.
Originally in the Matrix chat I said "it seems to use two timers, the ieee802154 radio registers and then a way to register an ISR handler (with esp_intr_alloc)".

Turns out the two timers seem to be part of the ieee802154 peripheral itself.
So I wonder if there is more to it than just supporting esp_intr_alloc and esp_intr_free really.

[braska]

Hi — I ran into what I believe is this same family of issues, and I wanted to share some analysis I did in case any of it is useful.

My setup: I'm building a battery-powered Matter/Thread device on a Xiao ESP32-C6 — a simple toggle switch that reports state over Matter. During development I'm powering via USB (no SED configuration yet), so sleep behavior isn't a factor here. I deliberately chose the Rust/Embassy path over ESP-IDF — honestly, no practical reason, I just wanted to try the modern stack.

What I'm seeing:

• Can't commission the device at all. Sigma1/Sigma2/Sigma3 exchange is drowning in re-send retries
• Lots of SRP errors with code 28
• Serial console flooded with "queue is full" messages
• The same hardware commissions and runs fine with ESP-IDF

I have a strong feeling all of these symptoms share a common root cause — the 802.15.4 TX path is simply not getting frames out reliably enough for any higher-level protocol exchange to complete.

I found this issue which covers the re-send retry side of the problem. I'm not an embedded developer by background, but I wanted to contribute something, so I spent time digging through the actual source code of esp-rs/openthread, esp-radio, the ESP-IDF reference implementation, and the upstream OpenThread SubMac to try to understand what's going wrong.

I used Claude (Opus) to help with the investigation — I want to be upfront about that. I also tried hard to prevent it from hallucinating: every claim in the analysis below was checked against specific files and line numbers in the repos, and I validated the findings as best I could given my limited embedded/Rust knowledge. I'm sharing this in the hope that there's at least a grain of usefulness here, and I apologize in advance if I've gotten something wrong or if this is noise.

The full write-up is attached below.

---

Root-Cause Analysis: Matter UDP Re-send Retries in the esp-rs/openthread Rust Stack

Issue Reference: esp-rs/openthread#53

Date: March 2026

Scope: Source-code audit of the full TX/RX path from Matter application layer through OpenThread C core, the Rust platform port, and the ESP32 802.15.4 hardware driver.

---

1. Problem Statement

Devices running the esp-rs/openthread Rust stack exhibit excessive Matter-level UDP re-send retries. The pattern is:

WARN - <<SND Re-sending
    => UDP [fdac:bcdf:a3c9:1:cd4b:f2ff:8956:c860]:5540
    [SID:72d9,CTR:58c96b1][I|A|R,EID:1,PROTO:1,OP:5,ACTR:82a3c88]
    IM::ReportData

The larger the Matter payload (which means more 802.15.4 fragments), the worse the problem. The same hardware running the C-based ESP-IDF stack does not exhibit this behavior. The updated 802.15.4 hardware driver (PR #5006) did not resolve the issue.

---

2. Architecture Overview

The system has four layers involved in the TX path:

Matter application (Rust)
    ↓ UDP send
OpenThread C/C++ core (pre-compiled .a libraries from google/openthread)
    ↓ otPlatRadioTransmit() FFI callback
openthread Rust crate (openthread/src/ — platform.rs, lib.rs, esp.rs)
    ↓ Radio trait implementation, async embassy tasks
esp-radio 802.15.4 driver (esp-radio/src/ieee802154/ — raw.rs, mod.rs)
    ↓ hardware register commands
ESP32-C6/H2 IEEE 802.15.4 radio peripheral

Both ESP-IDF (C) and the Rust crate use the same OpenThread C++ core library. The difference is:

• Platform port: C callbacks in ESP-IDF vs. Rust FFI callbacks in the Rust crate
• 802.15.4 driver: C driver in ESP-IDF vs. Rust driver in esp-radio
• Execution model: FreeRTOS event loop in ESP-IDF vs. Embassy async tasks in Rust

OpenThread's SubMac layer (in src/core/mac/sub_mac.cpp) is where all retry decisions happen. It receives an error code from the platform and decides whether to do CSMA backoff retry, frame retransmission, or report failure upstream. The error code it receives, and the radio capabilities the platform advertises, completely determine the retry behavior.

---

3. Methodology

Every finding was verified against actual source code cloned on 2026-03-17:

• esp-rs/openthread at main — the Rust OpenThread crate
• esp-rs/esp-hal at main — contains the esp-radio 802.15.4 driver
• espressif/esp-idf at master — the reference C implementation
• openthread/openthread at main — the upstream OpenThread C++ core (web references)

All file paths and line numbers reference these specific versions.

---

4. Findings

4.1 CSMA_BACKOFF Capability Falsely Advertised — CRITICAL

What: The Rust port tells OpenThread that the hardware handles the full CSMA-CA (Carrier Sense Multiple Access with Collision Avoidance) algorithm. The hardware does not — it only performs a single CCA (Clear Channel Assessment) check.

Where in the Rust port (openthread/src/esp.rs:92-93):

const CAPS: Capabilities = Capabilities::ACK_TIMEOUT
    .union(Capabilities::CSMA_BACKOFF)  // ← claims hardware does CSMA-CA
    ;

Where in ESP-IDF (components/openthread/src/port/esp_openthread_radio.c:347-355):

otRadioCaps otPlatRadioGetCaps(otInstance *aInstance) {
    return (otRadioCaps)(OT_RADIO_CAPS_ENERGY_SCAN |
                        OT_RADIO_CAPS_RX_ON_WHEN_IDLE |
                        OT_RADIO_CAPS_TRANSMIT_SEC | OT_RADIO_CAPS_RECEIVE_TIMING |
                        OT_RADIO_CAPS_TRANSMIT_TIMING |
                        OT_RADIO_CAPS_ACK_TIMEOUT | OT_RADIO_CAPS_SLEEP_TO_TX);
    // NOTE: NO OT_RADIO_CAPS_CSMA_BACKOFF
}

How OpenThread uses this (openthread/src/core/mac/sub_mac.hpp:434-437):

bool RadioSupportsCsmaBackoff(void) const {
    return ((mRadioCaps & (OT_RADIO_CAPS_CSMA_BACKOFF | OT_RADIO_CAPS_TRANSMIT_RETRIES)) != 0);
}

When RadioSupportsCsmaBackoff() returns true, ShouldHandleCsmaBackOff() returns false, and SubMac's software CSMA-CA is entirely disabled. This has two devastating effects:

Effect A — No random backoff before transmit: StartCsmaBackoff() in sub_mac.cpp checks ShouldHandleCsmaBackOff(). When false, it jumps straight to BeginTransmit() with zero delay. On a Thread mesh with any traffic, this makes collisions significantly more likely.

Effect B — CSMA retries skipped on CCA failure: In HandleTransmitDone:

if (!ccaSuccess && ShouldHandleCsmaBackOff() && mCsmaBackoffs < aFrame.GetMaxCsmaBackoffs()) {
    mCsmaBackoffs++;
    StartCsmaBackoff();
    ExitNow();
}

Since ShouldHandleCsmaBackOff() is false, CCA failures skip the backoff retry loop entirely and go directly to the frame retransmission counter.

What the hardware actually does: The Rust driver (esp-radio/src/ieee802154/raw.rs:237-238) issues a single Command::CcaTxStart instruction. When the channel is busy, the hardware immediately reports CcaBusy or CcaFailed. There is no exponential backoff, no random delay, no multiple CCA attempts.

Quantified impact: IEEE 802.15.4 specifies macMaxCSMABackoffs (default 4, meaning up to 5 CCA attempts with exponential backoff) before each frame transmission. OpenThread configures macMaxFrameRetries to 15 for direct transmissions (OPENTHREAD_CONFIG_MAC_DEFAULT_MAX_FRAME_RETRIES_DIRECT). Normally: up to 5 CCA attempts × 15 frame retries = 75 total transmit opportunities. With the bug: 1 CCA attempt × 15 frame retries = 15 total opportunities, all without any backoff delay. This is a 5× reduction in resilience to channel contention.

Fix: Remove .union(Capabilities::CSMA_BACKOFF) from the capability declaration. One line change.

---

4.2 Receive Sensitivity Returns 0 Instead of -120 — HIGH

What: The otPlatRadioGetReceiveSensitivity callback returns 0 dBm instead of the correct -120 dBm for the ESP32 802.15.4 radio. This poisons all link quality calculations.

Where in the Rust port (openthread/src/lib.rs:1586-1593):

fn plat_radio_receive_sensititivy(&mut self) -> i8 {
    let sens = 0; // TODO
    sens
}

Where in ESP-IDF (components/openthread/src/port/esp_openthread_radio.c:40,449-451):

#define ESP_RECEIVE_SENSITIVITY -120
int8_t otPlatRadioGetReceiveSensitivity(otInstance *aInstance) {
    return ESP_RECEIVE_SENSITIVITY;
}

How OpenThread uses this: Link margin is computed as linkMargin = rssi - receiveSensitivity. For a typical frame received at RSSI = -60 dBm:

• Correct (ESP-IDF): linkMargin = -60 - (-120) = +60 dB → excellent link quality
• Buggy (Rust port): linkMargin = -60 - 0 = -60 dB → terrible / invalid link quality

OpenThread uses link margin for:

• Link quality classification (0-3 scale), which feeds into routing cost calculation
• Parent selection during MLE (Mesh Link Establishment) — a device with apparently terrible links to all neighbors may struggle to attach or may select a suboptimal parent
• The ComputeLinkMargin() function in mac.cpp feeds this to LinkQualityInfo, which routing depends on

Impact: Every link on the device appears to have the worst possible quality. The routing layer makes poor decisions, and the device may churn through parent selections. This indirectly increases retransmission pressure at the Matter level because the mesh routing is suboptimal.

Fix: Return -120 instead of 0. One line change.

---

4.3 TX Failure Reasons Collapsed to a Single Boolean — HIGH

What: The 802.15.4 hardware driver distinguishes many distinct TX failure modes (CCA busy, CCA failed, ACK timeout, ACK CRC error, coexistence break, security error), but all of them are reported to OpenThread as the same error code: OT_ERROR_CHANNEL_ACCESS_FAILURE.

The collapsing happens in three stages:

Stage 1 — ISR level (esp-radio/src/ieee802154/raw.rs): Every failure path calls the same super::tx_failed() function:

• ACK timeout via Timer0 overflow (line 741): super::tx_failed()
• ACK timeout via TxAbort/RxAckTimeout (line 771): super::tx_failed()
• ACK CRC/SFD/filter failures (line 764): super::tx_failed()
• CCA failed (line 787): super::tx_failed()
• CCA busy (line 792): super::tx_failed()
• Coexistence break (line 776): super::tx_failed()
• Security error (line 782): super::tx_failed()

Stage 2 — Signal level (esp-radio/src/ieee802154/mod.rs:420-424 → openthread/src/esp.rs:84-85):

fn tx_failed_callback() {
    TX_SIGNAL.signal(false); // All failures become `false`
}

The TX_SIGNAL is a Signal<CriticalSectionRawMutex, bool> — it can only carry true (success) or false (failure), with no room for error detail.

Stage 3 — Error mapping (openthread/src/lib.rs:1035-1041):

fn to_ot_err<E>(err: E) -> otError where E: RadioError {
    match err.kind() {
        RadioErrorKind::TxFailed => otError_OT_ERROR_CHANNEL_ACCESS_FAILURE,
        RadioErrorKind::TxAckFailed | RadioErrorKind::RxAckTimeout
        | RadioErrorKind::RxAckInvalid => otError_OT_ERROR_NO_ACK,
        _ => otError_OT_ERROR_ABORT,
    }
}

The mapping code was designed correctly — it has distinct paths for RxAckTimeout → OT_ERROR_NO_ACK. The RadioErrorKind enum (radio.rs:35-56) has all the right variants. But since Stage 2 collapses everything to false → RadioErrorKind::TxFailed, only the first branch ever fires.

How ESP-IDF distinguishes errors (components/openthread/src/port/esp_openthread_radio.c:196-204):

case ESP_IEEE802154_TX_ERR_CCA_BUSY:
case ESP_IEEE802154_TX_ERR_ABORT:
case ESP_IEEE802154_TX_ERR_COEXIST:
    err = OT_ERROR_CHANNEL_ACCESS_FAILURE;
    break;
case ESP_IEEE802154_TX_ERR_NO_ACK:
case ESP_IEEE802154_TX_ERR_INVALID_ACK:
    err = OT_ERROR_NO_ACK;
    break;

Why this matters: OpenThread's SubMac has different retry strategies for different error types:

• OT_ERROR_CHANNEL_ACCESS_FAILURE → CSMA backoff retry (but skipped due to Finding 4.1)
• OT_ERROR_NO_ACK → frame retransmission with optional exponential delay (OPENTHREAD_CONFIG_MAC_ADD_DELAY_ON_NO_ACK_ERROR_BEFORE_RETRY)

With all errors reported as CHANNEL_ACCESS_FAILURE, OpenThread never triggers its NO_ACK-specific retry logic. The ISR has access to the raw tx_abort_reason which distinguishes these cases — the information is available, just discarded.

Fix: Change TX_SIGNAL from Signal<bool> to a type that carries the error reason (e.g., Signal<Result<(), RadioErrorKind>>), and map the ISR abort reasons to the appropriate RadioErrorKind variants in each branch of isr_handle_tx_abort.

---

4.4 TX_SIGNAL Race Between Abort and New Transmission — HIGH

What: A race condition in the async TX flow can cause a new transmission to receive a stale success or failure signal from a previous transmission.

The race sequence:

The run_radio loop (openthread/src/lib.rs:832-841) uses embassy_futures::select::select to race the current TX operation against incoming commands:

let result = {
    let mut new_cmd = pin!(radio_cmd());
    let mut tx = pin!(radio.transmit(&psdu_buf[..psdu_len], cca, Some(&mut ack_psdu_buf)));
    embassy_futures::select::select(&mut new_cmd, &mut tx).await
};

When a new command wins the race (Either::First):

1. The code reports otPlatRadioTxDone(... OT_ERROR_ABORT) to OpenThread for TX 1 — correct.
2. The code sets cmd = new_cmd and continues to the next loop iteration.
3. If the new command is another TX, EspRadio::transmit() runs (esp.rs:116):
   • TX_SIGNAL.reset() — clears any stale signal
   • self.driver.transmit_raw() → calls ieee802154_transmit() → calls tx_init() → calls stop_current_operation_inner()
4. stop_current_operation_inner (raw.rs:287-306) sees the hardware is still in RxAck state (waiting for the ACK to TX 1) → calls stop_rx_ack().
5. stop_rx_ack() (raw.rs:350-370) checks if an AckRxDone event has occurred. If yes, it calls super::tx_done() → TX_SIGNAL.signal(true). If no, it calls super::tx_failed() → TX_SIGNAL.signal(false).
6. This signal fires after the TX_SIGNAL.reset() in step 3 but before the TX_SIGNAL.wait() for TX 2.
7. When TX 2 begins and reaches TX_SIGNAL.wait().await (esp.rs:128), it returns immediately with TX 1's stale result.

Consequences:

• Stale true (false success): TX 2 is reported as successful to OpenThread without ever completing over the air. The peer never received the frame. get_ack_frame() returns None (cleared in tx_init at raw.rs:188), so OpenThread gets success-with-no-ACK-data. The Matter layer eventually times out and retransmits.
• Stale false (false failure): TX 2 is immediately reported as failed before it even began transmitting. OpenThread retries unnecessarily, wasting airtime.

Why larger packets trigger this more: Large Matter messages fragment into many 802.15.4 frames. Between fragments, OpenThread processes tasklets and timers. More TX → tasklet → TX transitions = more opportunities for a new command to interrupt an in-flight TX.

Fix: Either: (a) drain/consume any pending signal inside stop_current_operation_inner before it calls tx_done/tx_failed, or (b) use a generation counter so that wait() can distinguish which TX the signal belongs to.

---

4.5 Source Address Match Table Completely Unimplemented — MEDIUM-HIGH

What: The OpenThread platform API includes 7 functions for managing the "source address match" table, which controls the Frame Pending bit in auto-generated ACK frames. None of these are implemented in the Rust port.

The missing APIs (declared in openthread-sys/src/include/riscv32imc-unknown-none-elf.rs:4877-4941):

• otPlatRadioEnableSrcMatch
• otPlatRadioAddSrcMatchShortEntry / otPlatRadioAddSrcMatchExtEntry
• otPlatRadioClearSrcMatchShortEntry / otPlatRadioClearSrcMatchExtEntry
• otPlatRadioClearSrcMatchShortEntries / otPlatRadioClearSrcMatchExtEntries

There are no implementations in platform.rs or anywhere else in the Rust crate. The pre-compiled OpenThread .a libraries must provide default (no-op) weak symbols, or linking would fail.

ESP-IDF implements all 7 (components/openthread/src/port/esp_openthread_radio.c:370-408):

void otPlatRadioEnableSrcMatch(otInstance *aInstance, bool aEnable) {
    esp_ieee802154_set_pending_mode(
        aEnable ? ESP_IEEE802154_AUTO_PENDING_ENHANCED : ESP_IEEE802154_AUTO_PENDING_DISABLE);
}
// ... plus 6 more entry management functions

Why this matters: The source address match table tells the 802.15.4 hardware which child devices have pending data. When a Sleepy End Device (SED) sends a Data Request, the hardware auto-ACK must set the Frame Pending bit if there's buffered data for that device. Without this table:

• The hardware's auto-pending mode is in its default state (likely disabled or always-on)
• SEDs either poll unnecessarily (wasting battery and airtime) or miss data meant for them
• Both scenarios generate extra traffic that increases collision probability

Since the Rust port builds as MTD (OT_MTD = "ON" in openthread-sys/gen/builder.rs:185), the device itself is an end device and wouldn't normally parent SEDs. But the missing implementation means the hardware pending mode is never configured at all, which may have side effects on the device's own Data Poll behavior as a child.

---

4.6 Missing otRadioFrame RxInfo Fields — MEDIUM-HIGH

What: The fill_frame() function that populates otRadioFrame for received frames omits several fields that ESP-IDF sets.

Rust port (openthread/src/lib.rs:754-785):

fn fill_frame(frame: &mut otRadioFrame, ...) {
    frame.mLength = psdu.len() as _;
    frame.mRadioType = 1;
    frame.mChannel = psdu_meta.channel;
    frame.mInfo.mRxInfo.mRssi = rssi;
    frame.mInfo.mRxInfo.mLqi = rssi_to_lqi(rssi);
    frame.mInfo.mRxInfo.mTimestamp = Instant::now().as_micros();
    // The following are NEVER set:
    // mAckedWithFramePending
    // mAckedWithSecEnhAck
    // mAckFrameCounter
    // mAckKeyId
}

ESP-IDF sets all of them (components/openthread/src/port/esp_openthread_radio.c:618-621,718-720):

radio_frame->mInfo.mRxInfo.mAckedWithFramePending = frame_info->pending;
// ...
s_receive_frame[...].mInfo.mRxInfo.mAckedWithSecEnhAck = s_with_security_enh_ack;
s_receive_frame[...].mInfo.mRxInfo.mAckFrameCounter = s_ack_frame_counter;
s_receive_frame[...].mInfo.mRxInfo.mAckKeyId = s_ack_key_id;

Impact: mAckedWithFramePending tells OpenThread whether the ACK sent in response to a received Data Request had the Frame Pending bit set. Without it, DataPollSender may generate unnecessary empty data frames. The security-related fields (mAckedWithSecEnhAck, mAckFrameCounter, mAckKeyId) are needed for Thread 1.2+ security, though the Rust port builds for Thread 1.1.

---

4.7 otPlatRadioGetRssi Returns Invalid (-128) — MEDIUM

Where (openthread/src/lib.rs:1578-1579):

fn plat_radio_get_rssi(&mut self) -> i8 {
    let rssi = -128; // TODO
    rssi
}

-128 is OT_RADIO_RSSI_INVALID in OpenThread. ESP-IDF calls esp_ieee802154_get_recent_rssi() to read the actual hardware RSSI register.

This function is used for energy detection and CCA energy-detect threshold comparison. While per-frame RSSI is correctly populated from received frames, the "current channel RSSI" always being invalid means energy scans (OT_RADIO_CAPS_ENERGY_SCAN is not advertised anyway) are non-functional and could affect CCA-ED mode decisions in some configurations.

---

4.8 RX_ON_WHEN_IDLE Capability Not Advertised — MEDIUM

Where (openthread/src/esp.rs:94):

// .union(Capabilities::RX_ON_WHEN_IDLE) TODO: Depends on coex being off in ESP-IDF

ESP-IDF advertises this cap (esp_openthread_radio.c:352): OT_RADIO_CAPS_RX_ON_WHEN_IDLE.

Without this capability, OpenThread's SubMac manages idle→receive transitions in software. This adds latency between TX completion and re-entering RX mode. During this gap, incoming frames (retransmitted fragments, ACKs from other nodes) can be missed, causing the peer to retransmit.

Fix: Uncomment the line. One-line change. The coexistence concern noted in the TODO is moot — the Rust driver currently doesn't support Wi-Fi/BLE coexistence anyway (ieee802154/mod.rs:13: "Coexistence with Wi-Fi or Bluetooth is currently not possible").

---

4.9 Enhanced ACK Generation Stubbed — MEDIUM

Where (esp-radio/src/ieee802154/raw.rs:619-623):

} else if should_send_enhanced_ack(frm) {
    // Enhanced ACK for frame version 0b10 - TODO: full enh-ack support
    state.state = Ieee802154State::TxEnhAck;
    *needs_next_op = false;
}

When should_send_enhanced_ack() returns true, the state machine enters TxEnhAck but no ACK frame is generated. The state eventually transitions out via next_operation_inner or stop_current_operation_inner. The sender never receives an ACK and must retransmit.

ESP-IDF implements a full esp_ieee802154_enh_ack_generator() callback with CSL IEs, Link Metrics probing IEs, and MAC security.

The Rust port builds for Thread 1.1 (OT_THREAD_VERSION = "1.1" in openthread-sys/gen/builder.rs:182), which should not normally require Enhanced ACKs. However, the MacCapabilities::all() setting at esp.rs:97 enables enhance_ack_tx in the hardware configuration, making this path reachable if a Thread 1.2+ peer sends frame version 0b10 frames.

---

4.10 Single RX Buffer vs. ESP-IDF's 20 — MEDIUM

Where (esp-radio/src/ieee802154/raw.rs:34):

static mut RX_BUFFER: [u8; FRAME_SIZE] = [0u8; FRAME_SIZE];

ESP-IDF uses CONFIG_IEEE802154_RX_BUFFER_SIZE (default 20) separate buffers with circular indexing.

The Rust driver mitigates this by copying RX_BUFFER into a VecDeque immediately in the ISR (receive_done() at raw.rs:372-384). However, tx_init() (line 195) calls set_next_rx_buffer() which points the hardware DMA back at the same RX_BUFFER for receiving the ACK. If a new data frame arrives while the hardware is DMA-writing the ACK into the buffer, partial corruption is possible. For fragmented Matter packets with many frames and ACKs in flight, this probability accumulates per-fragment.

---

4.11 rx_when_idle Deferred Application — MEDIUM

Where (openthread/src/lib.rs:1720-1729):

fn plat_radio_set_rx_on_when_idle(&mut self, on: bool) {
    let state = self.state();
    if state.ot.radio_conf.rx_when_idle != on {
        state.ot.pending_rx_when_idle = Some(on);
    }
}

The new value is only applied when a role change event (OT_CHANGED_THREAD_ROLE) fires (lib.rs:1501-1512). During the window between OpenThread requesting rx_when_idle=true and the role change firing, the radio may sleep after TX instead of switching to RX, missing incoming frames.

ESP-IDF applies it unconditionally and immediately at radio init time.

---

4.12 mRadioType = 1 Hardcoded Incorrectly — LOW-MEDIUM

Where (openthread/src/lib.rs:780):

frame.mRadioType = 1; // TODO: Figure out what is this

The correct value is 0 (kRadioTypeIeee802154). Value 1 corresponds to kRadioTypeTrel. In multi-radio builds this would cause link-type misidentification; in single-radio builds the field is likely ignored, but it is technically wrong.

---

4.13 Async TX Path Adds Non-Deterministic Latency — LOW-MEDIUM

The TX path goes through:

1. otPlatRadioTransmit (C → Rust FFI) at platform.rs:162-168
2. plat_radio_transmit() at lib.rs:1685-1703 → signals RadioCommand::Tx via Embassy Signal
3. Embassy executor polls run_radio task
4. radio_cmd().await resolves
5. radio.set_config() applies hardware configuration
6. radio.transmit() → transmit_raw() → hardware TX

Steps 2-5 add non-deterministic latency (microseconds to milliseconds depending on executor load). In ESP-IDF, otPlatRadioTransmit directly calls esp_ieee802154_transmit() synchronously.

For time-sensitive operations like responding to Data Polls or sending fragments within an expected timing window, this latency can cause peers to timeout and retransmit.

---

4.14 ensure_receive_enabled() Workaround Masks a Deeper Bug — LOW

Where (esp-radio/src/ieee802154/raw.rs:486-495):

// FIXME: we shouldn't need this - we need to re-align the original driver with our port
pub(crate) fn ensure_receive_enabled() {
    STATE.with(|state| {
        if state.state == Ieee802154State::Receive {
            set_cmd(Command::RxStart);
        }
    });
}

Called from Ieee802154::raw_received() at mod.rs:169, which means RxStart is re-issued on every RX poll even when already in receive state. The FIXME comment confirms this is a workaround for the radio unexpectedly dropping out of RX mode. Each time this happens, there's a window where incoming frames are lost. The root cause is undiagnosed.

---

4.15 MacCapabilities::all() Over-Advertises — LOW-MEDIUM

Where (openthread/src/esp.rs:97):

const MAC_CAPS: MacCapabilities = MacCapabilities::all();

This tells the MacRadio wrapper layer that the hardware handles all address filtering, ACK generation, and ACK reception. The MacRadio layer (radio.rs:549-592) conditionally enables software fallback filtering based on these caps — with all(), no software fallback exists. If the hardware's filtering has bugs or edge cases, no safety net catches the problem.

---

5. Cascade Failure Model

The most devastating aspect of these bugs is their interaction. For a large Matter message fragmented into N 802.15.4 frames, each fragment must survive the entire TX chain. The bugs compound multiplicatively:

1. Finding 4.2 (receive sensitivity = 0): OpenThread thinks all links are terrible. Link quality tracking is poisoned, potentially causing suboptimal parent selection and conservative routing behavior.

2. Finding 4.1 (CSMA_BACKOFF): Each frame gets a single CCA check instead of up to 5 with exponential backoff. Any channel activity (including the device's own reflected ACKs) causes immediate CCA failure with no retry.

3. Finding 4.3 (collapsed errors): CCA failure and ACK timeout are both reported as CHANNEL_ACCESS_FAILURE. SubMac's CHANNEL_ACCESS_FAILURE handling tries CSMA backoff retry — but that's disabled by Finding 4.1. So the error falls through to the frame retransmission counter, which burns through retries rapidly with no backoff delay between them.

4. Finding 4.4 (TX_SIGNAL race): Under heavy TX load (many fragments), the probability of a command interrupting an in-flight TX increases linearly with fragment count. Each race event either creates a false success (peer never got the frame → Matter timeout) or false failure (unnecessary retry → wasted airtime → increased collision probability).

The per-frame success probability under these combined bugs is significantly lower than normal. Since overall message success = (per-frame success)^N, the probability drops exponentially with fragment count. This precisely explains the observed symptom: "the larger the packet, the more difficult to send."

---

6. Recommended Fix Priority

Immediate — one-line changes, no architectural risk:

Finding	Fix	File:Line
4.1 CSMA_BACKOFF	Remove .union(Capabilities::CSMA_BACKOFF)	esp.rs:93
4.2 Receive sensitivity	Return -120i8 instead of 0	lib.rs:1587
4.8 RX_ON_WHEN_IDLE	Uncomment .union(Capabilities::RX_ON_WHEN_IDLE)	esp.rs:94
4.12 mRadioType	Change 1 to 0	lib.rs:780

Short-term — moderate effort, high payoff:

Finding	Fix	Complexity
4.3 Error differentiation	Change Signal<bool> to carry error kind; map ISR abort reasons to distinct RadioErrorKind variants	Moderate
4.6 Missing RxInfo fields	Populate mAckedWithFramePending and other fields from ACK frame data	Low
4.7 RSSI invalid	Read hardware RSSI register via esp_ieee802154_get_recent_rssi() equivalent	Low

Medium-term — deeper changes:

Finding	Fix	Complexity
4.4 TX_SIGNAL race	Add generation counter or drain stale signals in stop_current_operation_inner	Moderate
4.5 Source address match	Implement 7 platform API functions + configure hardware pending mode	Moderate
4.9 Enhanced ACK	Implement Enhanced ACK generation callback, or disable enhance_ack_tx config	High
4.10 Single RX buffer	Double-buffer or circular buffer for DMA	Moderate

---

7. Conclusion

The excessive Matter-level re-sends are not caused by a single bug but by a combination of at least 14 distinct issues in the Rust platform port and 802.15.4 driver. The three most impactful are the false CSMA_BACKOFF capability advertisement, the incorrect receive sensitivity value, and the error-collapsing TX signal design. Together with the TX_SIGNAL race condition, these create a system where every 802.15.4 frame has a significantly reduced probability of successful delivery compared to the reference ESP-IDF implementation.

Four of the highest-impact fixes are one-line changes. Applying just those four (CSMA_BACKOFF removal, receive sensitivity correction, RX_ON_WHEN_IDLE enablement, and mRadioType fix) should produce a measurable improvement in Matter reliability with negligible risk.

[ivmarkov]

Four of the highest-impact fixes are one-line changes. Applying just those four (CSMA_BACKOFF removal, receive sensitivity correction, RX_ON_WHEN_IDLE enablement, and mRadioType fix) should produce a measurable improvement in Matter reliability with negligible risk.

@braska We don't know until we actually DO apply these "one-line" changes. I've actually applied offline a week ago the CSMA_BACKOFF removal and the RX_ON_WHEN_IDLE restoration and I'm quite sure these do not improve the situation.

(Problem with AI is they are in the meantime very very useful, but they are also a bit too over-confident.)

Funnily enough:

• CSMA_BACKOFF was introduced by Claude Sonnet earlier
• Reporting RX_ON_WHEN_IDLE to OpenThread when OT is configured as a MTD (minimum thread device) has no effect I think.

Still, the other two one-liners might have a measurable impact. Also we need to try the other suggestions. Claude Opus should, that is. It is anyway in charge of the esp-hal 802.15.4 Radio driver in the meantime.

Also, and in any case - asking the AI to do a comparison between the ESP-IDF and our own impl for bug-hunting was a great idea - thanks! That's how BTW the new esp-hal 802.15.4 Radio driver was implemented.

[ivmarkov]

@braska I just implemented
"Immediate — one-line changes, no architectural risk" in #53 and there is NO measurable impact. So yes, the AI is over-confident in this case.

Will continue implementing other stuff.

NOTE: In any case, our OpenThread connectivity stability has definitely regressed terribly. I think it is either due to the upgrade to a more recent upstream OpenThread, or to the switch to Clang as the default compiler for the libs.