Channel Change API

[dumpfheimer]

Hi!

I was having channel noise issues and looked into changing the channel of my network, which at the moment does not seem to be possible, so I spent some time gathering information and came up with this procedure:

How to change the channel (no UI yet)

1. Go to your Home Assistant Webpage, open javascript console (F12 in chrome) and copy+paste (replac 25 with the channel you desire):
   (await hassConnection).conn.sendMessage({"id": 99999, "type": "zha/channel_change", "channel": 25})
2. Stop Home Assistant / anything accessing the coordinator via serial
3. make a backup (check https://github.com/zigpy/zigpy-znp/blob/dev/TOOLS.md#network-backup )
4. edit that backup json and change the channel attribute to the new channel
5. restore the backup, start Home Assistant

After these steps my coordinator and all routers / powered devices where on the new channel (15->25)

Battery powered devices behaved differently. My Philips Hue remote noticed the channel change by itself. All my Xiaomi Aqara sensors (temp, window/door, motion) needed a single click on the reset button (no re-join, which would be a long click). Other devices like Tuya Remotes, and other motion sensors had to be re-joined.

All in all I still believe this API could be a valuable contribution, as I did not have to re-join my 80+ lights/switches/plugs.

I am hoping for comments/help on:

1. Overall value for zigpy project
2. The general setup / form. Does this fit the zigpy architecture? If not, what would you preferr?
3. A preferred way of failing this request (own exception, e.g. if the zigpy impl [znp,deconz...] does not yet support changing channels)
4. A way how to eliminate steps 2-4 (backup, edit, restore) to make the coordinator use the new channel immediately
5. UI Integration

Any other feedback and help is appretiated

Code:
Zigpy ZNP
https://github.com/dumpfheimer/zigpy-znp/tree/dumpfheimer/channel-change
Zigpy
https://github.com/dumpfheimer/zigpy/tree/dumpfheimer/channel-change
Home Assistant
https://github.com/dumpfheimer/core/tree/dumpfheimer/zha-channel-change

[puddly]

Good timing! zigpy-cli has had something similar for a while now for testing, relying on per-radio specialization where necessary (really only ZNP).

1. I think this is a super useful addition and I was hoping to start on this after energy scanning is done (Implement energy scanning during startup and on network formation #1183), for channel selection.
2. I think moving these commands onto ControllerApplication like async def change_channel(self, channel: int) -> None is a better approach than the current one (using ZDO commands) so what you have is fine. We can just do a default implementation in zigpy using ZDO commands, then allow the radio library to override the command if necessary (only ZNP). The only real consideration is whether or not we should poll for the channel change after the fact, which would require creating a separate "do the channel change" method in zigpy, and a public "do the channel change and wait for it to take effect" one for use externally.
3. Every common radio type supports this so I don't think it's a problem. XBee and ZiGate will be deprecated and EZSP, deCONZ, and ZNP all support this currently with zigpy-cli.
4. All coordinators that I've tested work with loopback ZDO requests or broadcasts. Something to consider is utilizing the network topology to send unicast requests to specific end devices and routers, but I don't know how well this will work.
5. That will be an interesting UI and something that should depend on an energy scan to allow for an informed decision, as often times a simple WiFi scan won't reveal non-WiFi sources of noise.

[MattWestb]

• 4 If i remember you can doing one broad cast with the new channel and all routers is putting in the table for its children but you is not knowing if its being cached ford of the children if they is not have pulling its parent. Uni cast is also working but little more tricky for using. Then you think all have getting the new key you is only sending one rolling network key command with the delay so the broadcast can spamming the network before they is jumping to the new channel.

By spec shall all this also working autonomous but i think its not implanted in most system but Open Thread is sing it and you can see the roll number and age of the network key in the data set.

All routers shall doing it OK but some sleepers getting problem (they shall searching for the pan and extended pan id if not finding its network) but Xiaomi is 110% not doing that.

[Hedda]

FYI, for reference, a couple of previous questions and discussions about Zigbee channel changing can be found in these other four requests:

• Is it (technically) possible to change ZigBee channel without having to re-pair every device? #908
• Possible to change Zigbee channel via API without un-pair and re-pair devices? #573
• Change Channel zigpy-znp#31
• Bellows Error changing Zigbee Channel bellows#191

1. I think this is a super useful addition and I was hoping to start on this after energy scanning is done

@puddly Was your idea also to have an easy UI in ZHA to allow users to change Zigbee channel later in an already formed Zigbee network?

That is, at least from an end-users point-of-view have a UI option to change the Zigbee channel without performing backup and restore?

4. A way how to eliminate steps 2-4 (backup, edit, restore) to make the coordinator use the new channel immediately

As mentioned in those other linked discussions/requests, some other Zigbee implementations allow changing the Zigbee channel on-the-fly.

I think allowing changing the Zigbee channel on an existing already formed Zigbee network via ZHA UI would be awesome, though such a feature would of course need to come with a disclaimer/warning about the fact that not only will some devices probably need to be manually power-cycled if they do not reconnect automatically after a while but also provide information up front that there is a potential risk that some devices might not reconnect at all and if so those devices will have to be manually re-paired/re-joined.

@pipiche38 You mentioned that a feature for this has been implemented in your ZigbeeforDomoticz plugin and at least works well with devices that are fully Zigbee 3.0 compliant:

#908 (comment)

On the ZigbeeforDomoticz plugin we are doing it (with the zigpy layer and in native zigate as well). If your end device is ZB3.0 compliant, you will change the channel, notified all listening devices and they will shift to the new channel, and then the ZB3.0 ZED will send a device annoucement and will takle the new channel

[dumpfheimer]

Hi!

Thanks for getting back to me so quickly and in detail!

This is all over the place now, sorry:

I will take a look at the ZDO commands to implement a base command in zigpy and, if I have some time left, I will take a look at HA frontend development, too.

Tbh, if you already have channel changes on your radar, you might be quicker just copying whatever seems worth copying - please just let me know if you would prefer that.

Regarding # 4: All ~80 routers in my network perfectly switched channel with the "broadcast" 0xFFFB address. It would be awesome, if end devices could be switched over too. Maybe we can split up the request into 2 different functions.

1. The notifying of channel change to network members. This function could have parameters to let the application (HA, etc) move single devices before actually changing the channel. And
2. The actual channel change of the coordinator
   something like this:

    async def notify_change_channel(self, channel: int, destination=0xFFFD):
        await self._znp.request(
            c.ZDO.MgmtNWKUpdateReq.Req(
                Dst=0xFFFD,
                ....
            )
        )

    async def perform_coordinator_change_channel(self, channel: int):
       coordinator.please_switch_channel(channel)

Then, a channel change could look somewhat like this:

1. Get all the end devices. Call notify_change_channel(X, destination=0xABCD) for every end device while making the user press a button to wake the device and make sure the request was received.
2. Send a broadcast to all router devices notify_change_channel(X)
3. Perform the channel change perform_coordinator_change_channel(X)

I was shortly thinking about sending the request to the routers one by one, but I think the broadcast is the better approach.
If the application would iterate over the routers and trigger a channel change one by one the network would degrade over time. I would suspect that in larger networks the last devices might not even be reachable anymore because so many routers are missing. The only way around that would be a more complex way of sending the requests to the devices furthest away first, making sure no route is lost in the process. But tbh the broadcast worked fine for me (but all my routers are powered on all the time).

[MattWestb]

Some interesting reading then rolling the network key in 3.4: an1233-zigbee-security.pdf.

Its looks unnicast is not recommended if you not dont have special requirements and doing broadcast and waiting before roiling the network key is the normal way to doing it.

[dumpfheimer]

Is now implemented. Thanks, puddly!