Skip to content

OTA Device Firmware Updates

Jump to bottom Edit New page
TheJulianJES edited this page Feb 14, 2024 · 33 revisions

Note

The content of this page is no longer up-to-date for Home Assistant Core 2024.2.0 and later.
Updates can now be installed using Home Assistant firmware entities in the UI. It's currently not possible to provide your own OTA files.

Introduction

Zigpy via the Home Assistant ZHA component has the ability to automatically download and perform OTA (Over-The-Air) firmware updates of Zigbee devices if the OTA firmware provider source URL for updates is available.

The following OTA providers for firmware updates are included by default in zigpy/ZHA:

  • IKEA (Trådfri/Tradfri)
  • Inovelli
  • LEDVANCE/OSRAM
  • SALUS/Computime
  • Sonoff/ITead
  • ThirdReality (3reality)

OTA updates for other manufacturers may also be supported by ZHA in the future if these manufacturers publish their firmware publicly.

You can also manually download firmware from other providers from the Z2M-OTA repository or deconz firmware files. Place files in your specified otau_directory and zigpy will automatically scan and send any upgraded firmware files to your devices. You can automatically import all available firmware from zigbee-OTA by changing to your otau_directory and running this command curl https://raw.githubusercontent.com/Koenkk/zigbee-OTA/master/index.json | jq -r '.[] | .url' | xargs wget --no-clobber

Note: The otau_directory is disabled on Home Assistant Core 2024.2.0 and later. Another similar option will replace it in the future.

Enabling OTA Updates

The included OTA providers are enabled by default in Home Assistant Core 2024.2.0 and later.
OTA updates can be installed using the UI (firmware entities).

To enable OTA updates on older Home Assistant versions, edit your configuration.yaml and add the following:

zha:
  zigpy_config:
    ota:
      otau_directory: /config/zigpy_ota
      ikea_provider: true
      inovelli_provider: true
      ledvance_provider: true
      salus_provider: true
      sonoff_provider: true
      thirdreality_provider: true

The otau_directory is optional, and is the file provider for any firmware files you have locally on your system. Usually it's not required if you intend to use only official FW, they're monitored and downloaded automatically. Pick and choose as well if you want the ikea or ledvance provider enabled.

When the IKEA provider is enabled you can override the update URL to use a custom feed for example:

zha:
  zigpy_config:
    ota:
      ikea_provider: true
      ikea_update_url: http://fw.test.ota.homesmart.ikea.net/feed/version_info.json

(IKEA test feed is rolled back to one very old state and is not updated = DEAD)

Also turn up your logging configuration.yaml or use logger.set_level service in Home Assistant to temporarily increase logging level.

logger:
  default: info
  logs:  
    homeassistant.components.zha: debug
    zigpy: debug

Save file and restart Home Assistant.

Manually initiating OTA firmware update

Devices will periodically check in to request a firmware upgrade and also then being joined in the network. But you canproactively ask a device to update firmware using one of this methods:

New GUI method:

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.

Old Service method:

Developer Tools, Service, Zigbee Home Automation: Issue zigbee cluster command and these arguments in GUI or YAML mode:

ieee: <device_ieee>
endpoint_id: 1 # Endpoint id for the OTA cluster.
cluster_type: out
command_type: client
cluster_id: 25
command: 0
params:
  payload_type: 0
  query_jitter: 100

You can find the device IEEE from device card under Zigbee info.

Monitoring OTA Upgrades

Currently only OTA update feedback is via the home-assistant.log file, if desired watch your log file. If using tail/grep use:

$ tail -f /config/home-assistant.log | egrep 'zigpy.ota|zigpy.util|zigpy.*OTA'

Record your current firmware version prior to upgrade if desired - In the web UI go to Config > Integrations > ZHA > Basic Cluster > Cluster Attributes and look for date code, app version, stack version and sw_build_id (make sure to click "Get zigbee attribute" and not "Set Zigbee attribute")

Once a device OTA upgrade is in progress you will see log lines such as these:

2020-02-27 15:51:10 DEBUG (MainThread) [zigpy.zcl] [0x7813:1:0x0019] OTA query_next_image handler for 'IKEA of Sweden TRADFRI control outlet': field_control=1, manufacture_id=4476, image_type=4353, current_file_version=536974883, hardware_version=60
2020-02-27 15:51:10 DEBUG (MainThread) [zigpy.zcl] [0x7813:1:0x0019] OTA image version: 537011747, size: 204222. Update needed: True
2020-02-27 15:51:18 DEBUG (MainThread) [zigpy.zcl] [0x7813:1:0x0019] OTA image_block handler for 'IKEA of Sweden TRADFRI control outlet': field_control=0, manufacturer_id=4476, image_type=4353, file_version=537011747, file_offset=0, max_data_size=63, request_node_addr=Noneblock_request_delay=None
2020-02-27 15:51:18 DEBUG (MainThread) [zigpy.zcl] [0x7813:1:0x0019] OTA upgrade progress: 0.0

and when finished:

2020-02-27 15:58:51 DEBUG (MainThread) [zigpy.zcl] [0x7813:1:0x0019] OTA upgrade_end handler for 'IKEA of Sweden TRADFRI control outlet': status=Status.SUCCESS, manufacturer_id=4476, image_type=4353, file_version=537011747

For some devices you may be required to factory reset and rejoin them to ZHA following upgrade.

Verify clusters after upgrade if desired:

Config > Integrations > ZHA > Basic Cluster > Cluster Attributes and look for date code, app version, stack version and sw_build_id (make sure to click "Get zigbee attribute" and not "Set Zigbee attribute)

After all upgrades are complete, you can remove the extra logging and also remove zigpy_ota folder if you don't want automatic firmware upgrades in the future.

Function changes during upgrades

If OTA upgrading changes the function of the device, you may need to remove it from your network, wait for a few minutes, and then add it again for the new functionality to be recognized and used by ZHA.

For example, when updating an IKEA wireless dimmer from an old Zigbee Light Link (ZLL) firmware to a new ZigBee 3.0 firmware, some clusters may not work correctly because ZHA may not recognize newly added or removed clusters, and it might continue using the original data saved in the system.

Downgrading your device's firmware

Sometimes, it can be good to have the possibility to downgrade the firmware of your device, for example, getting IKEA lights to restore their default scenes, or reverting to known good firmware versions.

ZHA does not explicitly support firmware downgrading, nonetheless, it is possible to change the version check logic in zigpy itself to override this.

Warning: This can lead to unwanted up/downgrades of devices, and may further lead to uncontrolled looping of up/downgrading your devices if you do not know what you are doing. ❗

Edit line 60 in zigpy/ota/__init__.py from if ver >= self.version: to if ver == self.version: (With suplemon in HA core container suplemon /usr/local/lib/python3.9/site-packages/zigpy/ota/__init__.py) (Please note these are subject to change, and this Wiki page might not get updated in real-time)

Disabling OTA updates from remote sources such as IKEA feeds and exclusively using locally stored files will give you better control over what the system is doing.

To use the firmware file of your choice for upgrading or downgrading, place it in the configured otau_directory folder, and restart Home Assistant.

You can initiate an OTA firmware update for your desired device by using the OTA trigger.

zha:
  zigpy_config:
    ota:
      otau_directory: /config/zigpy_ota

Remember to delete the files in your OTA directory and disable all OTA update functions in your configuration once you're done to prevent unwanted upgrades or downgrades of your devices.

Please note that not all devices support firmware downgrading, but IKEA router devices appear to be compatible, while IKEA controllers are not. To determine if a device supports it, you can refer to the Zigbee certificate test protocol.

A proposal has been made to the maintainers of this repository to implement more advanced functions in zigpy (e.g. forced firmware version, device IEEE), but for now, it is only possible to perform the actions described here.

Please note again that these steps are risky and users should exercise care and caution!

See also

External references

Add a custom footer
Add a custom sidebar
Clone this wiki locally