Fix spurious "Unknown status" warning from XNCP replies on Simplicity SDK firmware

[zigpy-review-bot]

The problem

On firmware built against Simplicity SDK, every startup and every periodic network backup logs a WARNING that reads like a real failure but is a normal, expected condition:

DEBUG [bellows.ezsp] Sending XNCP frame: XncpCommand(command_id=<XncpCommandId.GET_MFG_TOKEN_OVERRIDE_REQ: 2>, status=<EmberStatus.SUCCESS: 0>, payload=GetMfgTokenOverrideReq(token=<EzspMfgTokenId.MFG_CUSTOM_EUI_64: 12>))
DEBUG [bellows.ezsp] Received XNCP frame: XncpCommand(command_id=<XncpCommandId.GET_MFG_TOKEN_OVERRIDE_RSP: 32770>, status=<EmberStatus.undefined_0x2d: 45>, payload=GetMfgTokenOverrideRsp(value=b''))
WARNING [bellows.types.named] Unknown status <EmberStatus.undefined_0x2d: 45>, converting to generic <sl_Status.FAIL: 1>

Seen on a Home Assistant Connect ZBT-2 running 9.1.1.0 build 0 (20260805160939) — a builder artifact from Simplicity SDK 2026.6.1, not a released image.

Worth being explicit that no shipped firmware hits this yet: silabs-firmware-builder's latest release (v2026.02.23) predates its Simplicity SDK migration, so released images still take the Gecko SDK path and decode fine. This is a fix ahead of the planned Simplicity SDK beta rather than a response to breakage in the field.

Root cause

An XNCP frame is a uint16 command ID, then one status byte, then the payload. The firmware types that byte as the SDK's native status type, so its meaning depends on which SDK the image was built against (xncp_types.h):

build	status type	OK	bad argument	not found
Gecko SDK 4.x	EmberStatus	0x00	0x02	0x03
Simplicity SDK	sl_status_t, truncated to one byte	0x00	0x21	0x2D

The split is on #ifdef STACK_TYPES_HEADER, so it tracks the SDK family rather than any particular release. bellows decodes that byte as an EmberStatus unconditionally and then runs it through sl_Status.from_ember_status(). On Simplicity SDK firmware this goes wrong two ways:

• 0x2D (SL_STATUS_NOT_FOUND) is not a valid EmberStatus, so it becomes undefined_0x2d and trips the "Unknown status" warning.
• 0x21 (SL_STATUS_INVALID_PARAMETER) is worse, because it is a valid EmberStatus — it silently mis-decodes as the unrelated EmberStatus.SERIAL_INVALID_PORT, with no warning at all.

The path that hits this on every startup is load_network_info() → can_burn_userdata_custom_eui64() → get_mfg_token(MFG_CUSTOM_EUI_64). The firmware only overrides MFG_STRING and MFG_BOARD_NAME, so NOT_FOUND for any other token is the correct, expected reply, and get_mfg_token() already handles it by falling back to the raw token value. Only the log line is wrong.

The fix

Give the XNCP status byte its own XncpStatus enum instead of borrowing EmberStatus, and compare against it directly rather than routing it through sl_Status.from_ember_status() — that helper translates EZSP command statuses, and its warning is a genuinely useful signal that this was drowning out.

The values the two encodings actually use don't collide, so both fit in one enum. But bellows only ever needs OK vs. not-OK here, and 0x00 is success under either interpretation, so nothing depends on that staying true if firmware adds status values later.

No behaviour change beyond the log line

I checked this exhaustively rather than by inspection. For all 256 possible status byte values, the old and new success tests agree on whether to raise InvalidCommandError:

for b in range(256):
    old = sl_Status.from_ember_status(EmberStatus(b)) != sl_Status.OK
    new = XncpStatus(b) != XncpStatus.OK
    assert old == new          # holds for every byte

That follows from the only SL_STATUS_MAP entries producing sl_Status.OK being EmberStatus.SUCCESS and EzspStatus.SUCCESS, both 0x00. Request frames also serialize to the same bytes as before, since XncpStatus.OK and EmberStatus.SUCCESS are both 0x00 in one byte.

Why not just extend SL_STATUS_MAP

Adding 0x2D there would silence the warning, but unlike #742/#743 — where NETWORK_BUSY really is an EmberStatus that was mapped to the wrong sl_Status — this byte isn't an EmberStatus value at all, so there's nothing correct to map it to. It would also leave the 0x21 → SERIAL_INVALID_PORT mis-decode in place.

Tests

Added a regression test covering both encodings of "this token has no override", asserting that the call succeeds and logs no warning. It fails on dev for the 0x2D case and passes for both with this change. Full suite: 443 passed.

[zigpy-review-bot]

One adjacent thing I noticed while tracing this. It's a firmware-side observation, not something to fix here, but flagging it in case it's useful upstream.

The XNCP status slot is a single byte (uint8_t rsp_status in xncp_core.c, written to replyPayload[2]), but on Simplicity SDK builds xncp_status_t is typedef'd to sl_status_t. So the firmware implicitly truncates a 32-bit status to 8 bits on every reply.

That's harmless today, because only three values are ever returned and all of them survive truncation (SL_STATUS_OK 0x0000, SL_STATUS_INVALID_PARAMETER 0x0021, SL_STATUS_NOT_FOUND 0x002D). It stops being harmless as soon as a handler returns anything >= 0x100, and the SL_STATUS_ZIGBEE_* range at 0x0Cxx collides directly with bytes that are already meaningful:

sl_status_t	truncated	collides with
SL_STATUS_ZIGBEE_DELIVERY_FAILED	0x0C02 → 0x02	EMBER_BAD_ARGUMENT (the byte Gecko SDK builds use)
SL_STATUS_ZIGBEE_MAX_MESSAGE_LIMIT_REACHED	0x0C03 → 0x03	EMBER_NOT_FOUND
SL_STATUS_ZIGBEE_APS_MESSAGE_CANCELED	0x0C21 → 0x21	SL_STATUS_INVALID_PARAMETER

The bounded part: no error value in sl_Status truncates to 0x00, so a truncated failure can never be read as success. It degrades to a different error, not to no error.

Nothing to do in bellows either way — it has to tolerate already-shipped firmware, and the XncpStatus in this PR treats every non-zero byte as an opaque failure, so a truncated value still fails cleanly.

Separately, a documentation nit in the same header, since it caused a real mistake: the #ifdef STACK_TYPES_HEADER branch is labelled // Simplicity SDK (2025.x), but the commit that introduced it (df44c39, "Simplicity SDK 2026.6.0") pinned simplicity_sdk:2026.6.0, and every manifest still pins 2026.6.x today. The branch isn't version-scoped either — it keys off STACK_TYPES_HEADER, so it covers Simplicity SDK generally. I took that label at face value and had to correct "2025.x" out of this PR's description and commit message after the fact, so it seems worth fixing before it misleads someone else.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.55%. Comparing base (818f191) to head (f774ddf).

Additional details and impacted files

@@           Coverage Diff           @@
##              dev     #744   +/-   ##
=======================================
  Coverage   99.55%   99.55%           
=======================================
  Files          64       64           
  Lines        4263     4269    +6     
=======================================
+ Hits         4244     4250    +6     
  Misses         19       19           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[TheJulianJES]

@zigpy-review-bot Review.

[zigpy-review-bot]

Reviewed at f774ddf. The change is correct and the description's reasoning holds up — I re-derived the load-bearing claims rather than taking them on trust. No blockers; two optional notes below.

This PR is authored by the bot, so this is a comment-only review: the bot does not approve its own PRs, even when the verdict is "looks good".

Verified (6 checks)

• The SDK split is real and the value table is right. In silabs-firmware-builder, src/zigbee_ncp/extension/xncp_extension/inc/xncp_types.h gates on #ifdef STACK_TYPES_HEADER: xncp_status_t is EmberStatus with EMBER_SUCCESS/EMBER_BAD_ARGUMENT/EMBER_NOT_FOUND on the Gecko branch, sl_status_t with SL_STATUS_OK/SL_STATUS_INVALID_PARAMETER/SL_STATUS_NOT_FOUND on the Simplicity branch. Those three macros are the only values any handler ever assigns to *ctx->status (xncp_core.c, xncp_common_commands.c, xncp_zbt2_commands.c), so {0x00, 0x02, 0x03} / {0x00, 0x21, 0x2D} really is exhaustive for current firmware, and XncpStatus covers all five.
• The 256-value equivalence holds. Ran the description's loop against this branch: sl_Status.from_ember_status(EmberStatus(b)) != sl_Status.OK and XncpStatus(b) != XncpStatus.OK agree for every b in range(256) — zero mismatches. InvalidCommandError is raised on exactly the same inputs as before.
• Request frames are byte-identical. XncpStatus.OK.serialize() and EmberStatus.SUCCESS.serialize() are both b"\x00"; XncpCommand.from_payload(GetSupportedFeaturesReq()).serialize() is b"\x00\x00\x00" on both dev and this branch.
• Unknown bytes stay quiet. XncpStatus is a t.enum8, so zigpy's _EnumMixin._missing_ synthesises undefined_0x.. members without logging: XncpStatus.deserialize(b"\x99\xAA") gives (<XncpStatus.undefined_0x99: 153>, b"\xaa"), which compares unequal to OK. An unrecognised status still fails cleanly, and silently.
• The two mis-decodes described are the ones that actually happen. On dev: EmberStatus(0x2D) is undefined_0x2d → sl_Status.FAIL plus the warning, and EmberStatus(0x21) is SERIAL_INVALID_PORT → sl_Status.INVALID_PARAMETER, with no warning at all.
• The regression test bites. Reverting bellows/ to 818f191 while keeping the new test: the \x2D parametrisation fails on the leaked Unknown status <EmberStatus.undefined_0x2d: 45> warning, the \x03 one passes. Full suite on the branch: 443 passed. A GPT-5.6 Sol second opinion over the same diff came back with no findings.

Optional — the scope is complete, and it's worth saying why. The outer customFrame status at bellows/ezsp/__init__.py:758 still goes through sl_Status.from_ember_status(), and customFrame is declared with "status": t.EmberStatus in bellows/ezsp/v4/commands.py:320 and inherited unchanged by every later version — so on paper that's the same SDK-dependent decode one layer up. It's inert: xncp_incoming_custom_frame_handler() ends with an unconditional return XNCP_STATUS_OK; (xncp_core.c:66) on both SDK branches, so that byte is always zero. Nothing to change here — noting it so the next person doesn't have to re-derive why only the inner status needed fixing.

Optional — nothing pins the request wire format. Every customFrame call assertion in tests/test_xncp.py builds its expected bytes with XncpCommand.from_payload(...).serialize(), i.e. the code under test on both sides of the ==, so a future change to XncpStatus.OK's value would sail through green. One literal-bytes assertion — XncpCommand.from_payload(GetSupportedFeaturesReq()).serialize() == b"\x00\x00\x00" — would turn the description's "request frames serialize to the same bytes as before" argument into something CI actually enforces.

[TheJulianJES]

This looks fine to me. @puddly Any objections?

[puddly]

LGTM!