ZHA Firmware Update Guide

When I get some time I should grab the updated params and update the docs too, but yeah that’s what’s listed on the integration page :slight_smile:

Hello @justinlindh,

Thanks for this write-up. It inspired me to look into what firmware I had on my switches. Turns out, my 7 switches are running 2.11.

As a result, I followed your instructions step-by-step. Unfortunately, I ran into some hiccups. First, for months now I have had the OTA update line in the YAML set to true. However, in that time I never received and OTA update. Naturally, I tried your method of pushing them locally (download file, restarting HA, etc.). After some time, the updates were never pushed. Then I tried @chack 's solution which did initiate the update as I saw the visual prompts. Despite the warnings in the logs about the args, the updates appear to have completed.

However, I am still seeing a 2.11 firmware version even after restarting and shutting HA down completely. Would you have any idea as to what I am overlooking here? It is likely something so simply.

Thanks in advance.

[Update 9.4.23]
After some time, the updates began pushing automatically - albeit at the same time. I believe this flooded my zigbee network which resulted in numerous failures. I kept trying to cluster command approach one at a time, and eventually this method did work.

Apologies, but I just haven’t run into that specific issue yet, so I’m not entirely sure. Generally, that’s where I’d start enabling debug logging.

Reading your update, though, sounds like you were eventually able to get it working. Awesome! I hadn’t considered too many simultaneous updates to be something that could be a problem, but I’ve only updated 2 switches at a time so far. Good to know, though, since future firmware pushes might repro that same issue for me and others!

Thank you for the guide, however I would prefer to just have the update done automatically. Is there any reason 2.15 is still in beta if it is being installed in production devices?

Following up on the dev tool update code, the following is the way to format the cluster command for updating without getting the error about args being deprecated.

PLEASE NOTE - this will only work for the VZM31-SN and the file version lines up with 2.15 (only expect the last 2 characters to change for other versions), the VZM35-SN fan switch as an example uses a different image_type field. I also haven’t tested if this lets you check for a specific upgrade that may let you pick a higher version but not the newest (older versions weren’t supported by zigpy last I checked, it’s part of the firmware update validation).

service: zha.issue_zigbee_cluster_command
  ieee: "xx:xx:xx:xx:xx:xx:xx:xx"
  endpoint_id: 1
  cluster_id: 25
  cluster_type: out
  command: 0
  command_type: client
    payload_type: 0x00
    query_jitter: 100
    manufacturer_code: 4655
    image_type: 257
    new_file_version: 16908815
1 Like

In case it helps anyone, I was able to trigger my Blue 2-1 switches to check for firmware updates using ZHA Toolkit (installed via HACS), which was easier than typing in the parameters.

  1. Set up the zha > zigpy_config > ota settings in configuration.yaml as described above. (You can use inovelli_provider: false if you intend to put the new firmware in the zigpy_ota folder yourself manually. The inovelli_provider setting is for automatically pulling the updates from Inovelli servers, and last I checked a while ago, the servers were not offering the 2.15 firmware for ZHA.)
  2. Go to Developer Tools > Services and select the zha_toolkit.ota_notify service (“Trigger Device’s Firmware Update”).
  3. For “Device Reference” field, select the light.[your_switch_name]_light entity.
  4. Click “Call Service”.

No other settings or parameter changes were needed (I didn’t have to enter the image type, file version, etc.)

1 Like

Another approach which worked for me (via the zigpy GitHub docs):

From device card right from “reconfigure” the three dots, manage zigbee device, select OTA cluster (id: 0x0019), click commands, select image_notify (id: 0x0000), and mark payload_type: QueryJitter and move the query_jitter slider so its not being at default zero.

Note: Ignore “mandatory” manufacturer_code/image_type/new_file_version fields and still click grayed out “Issue Zigbee command” button.

Click Issue Zigbee command and waking up the device by clicking one button if its one sleeping device so it can receiving the command.

As of last night, firmware upgrades for Inovelli Zigbee Devices on ZHA will show on an update entity! Neat!

Is there anyway to upload local firmware vs what I’m assuming is cloud firmware with the recent home assistant update? I’m trying to upload beta firmware but getting “no ota image available” in the logs

1 Like

The devs for zigpy (what ZHA is built on) added another key/value pair to make it more difficult to enable local OTA for the time being. Not certain when that’s expected to change unfortunately, but would lean towards sticking with the more ‘official’ method for now.

This configuration still works…

      otau_directory: /some/directory/you/created 

It will consider firmware files you put in that directory

Are you updated to 2024.2.0?

Yes, but I’m not totally sure if I put the beta firmware on my fan switches before or after the update yesterday.

I’m pretty sure it would’ve been before if you aren’t certain. If you do have something else pending being updated though I’d be curious :slight_smile:

Everything is up to date for me, I’m willing to try stuff though. Just got a zigpy dev environment mostly setup too

I just installed another (older stock firmware) switch tonight. Yeah, the new ZHA upgrade support seems to have regressed the ability to flash local firmwares.


You lie, ZHA: that’s 2.08 and latest production firmware is 2.15, which is present in my zigpy_ota directory and used to trigger OTA update just fine. So yeah, the guide in the OP in this thread is likely no longer applicable and useful and we need something new to actually update to latest prod firmwares via ZHA.

I’m having exactly the same problem. I’ve tried every firmware update guide out there, and none will work through ZHA for me. I’ve got one switch on 2.15 (and five more of those to install), 22 on 2.14, and 3 on 2.08. Every one of them indicates that they’re up to date.

I’ve tried adding the firmware to the zigpy_ota directory as per the guide and got nothing. Tried renaming the firmware to VZM31-SN_2.15.ota to make sure the syntax matched exactly and got nothing. Made sure the file was the right size. Changed the true/false flag for inovelli_provider. Rebooted after every step–no luck. Tried forcing the update with ZHA Toolkit, tried forcing through the Manage Zigbee Device dialog…no luck.

At this point, I’m either really doing something wrong, or I’m running into a software configuration problem that I’m just not seeing. Just checked my HA version, and I’m current at 2024.2.2.

…so I’m definitely watching to see what others are doing, because I seem to be striking out.

I saw this earlier today and I feel that maybe it’s a bug. This is what I see when I click on the Firmware Update for a switch:

But when I look at this in the Manage Zigbee Device page, it shows we are still out of date.

The firmware image available for ZHA is still set to 2.08, anything at or past that will appear as up-to-date until it’s updated.

1 Like

Do you know where that check lives, offhand? I was thinking about trying to just bypass this for now. I assume there’s some kind of a “registry” somewhere that defines latest versions that I could hack around.