Fall back to the default TX power when a restored backup's TX power is rejected

[zigpy-review-bot]

Fixes the network restore failure reported in home-assistant/core#176927.

Problem

Migrating a network from a Home Assistant Connect ZBT-2 to an old EM357-based adapter fails while restoring the backup: formNetwork returns EmberStatus.PHY_INVALID_POWER and write_network_info raises FormationFailure, leaving the config flow stuck on "Restoring network settings to new adapter".

Since #690, write_network_info forms the network with the TX power stored in the backup instead of the previously hard-coded 8 dBm. That value comes from whatever radio created the backup: the ZBT-2 firmware recommends 10 dBm for EU/CEPT countries, so a backup taken from it contains tx_power: 10. The EM35x tops out at 8 dBm and appears to reject anything higher outright, where newer radios clamp it.

Fix

• write_network_info retries formNetwork once with DEFAULT_TX_POWER (8 dBm, the value every restore used before Backup/restore routing table and allow specifying TX power during formation #690) when the radio rejects the backup's TX power. zigpy re-applies the configured or recommended TX power on startup anyway (whenever a TX power or country is configured; ZHA passes Home Assistant's country along), so the value used during formation only needs to be one the radio accepts.
• EZSP.formNetwork raises a new InvalidTxPower exception for this status. It subclasses FormationFailure, so existing handlers are unaffected.
• EmberStatus.PHY_INVALID_POWER is now mapped to sl_Status.TRANSMIT_INVALID_POWER (like PHY_INVALID_CHANNEL → TRANSMIT_INVALID_CHANNEL right next to it), which also gets rid of the Unknown status <EmberStatus.PHY_INVALID_POWER: 139> warning from the issue.

Testing

Unit tests only, I don't have an EM35x adapter to try this on. The backup from the issue isn't attached, so the 10 dBm value is inferred from the ZBT-2 firmware's country table rather than read from it.

@javicalle, if you still have that setup around, could you check whether the migration to the Bitron stick goes through with this branch? A debug log of the restore would confirm the TX power that ends up in the backup.

cc @TheJulianJES

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.58%. Comparing base (15ccb49) to head (417c461).

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #755      +/-   ##
==========================================
+ Coverage   99.55%   99.58%   +0.02%     
==========================================
  Files          64       64              
  Lines        4284     4294      +10     
==========================================
+ Hits         4265     4276      +11     
+ Misses         19       18       -1     

☔ 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.

[javicalle]

Ok there's a first try to test the new code.
IS NOT the real one, just make a backup and try to restore the backup from the same device (BV 2010/10 ZHA dongle).

The attached log is from the restore process:

home-assistant_zha_2026-09-20T11-53-37.201Z.log

The whole process went well. I did a lot of testing with the current version at the time, and I think that this test also produced an error.

When I have a little more time, I'll perform a full test of migrating from the "Home Assistant Connect ZBT-2" to the BV 2010/10 ZHA dongle.

[javicalle]

I have checked the full migration process succesfully with the new code.

Previous to the test I have migrated from my current zigbee dongle (BV 2010/10) to the 'Home Assistant Connect ZBT-2'. Once migrated I have restarted my HA instance.

After the restart, I have enbled the ZHA debug logs and I migrated from the 'Home Assistant Connect ZBT-2' to my BV 2010/10 dongle.

This time, the migration process finish succesfully and my zigbee network is available.

This is the migration debug file:
home-assistant_zha_2026-09-20T19-03-59.629Z.log

Let me know if you need me to do any other kind of tests.

[puddly]

If it works then this looks good to me!

[javicalle]

And as a note for my future self, I was able to test against the branch following the instructions in this post:

• https://github.com/zigpy/bellows#testing-new-releases

configuring against the branch:

pypi:
  - >-
    git+https://github.com/zigpy/bellows@zigpy-bot/restore-invalid-tx-power-fallback
apk: []