Zigbee OTA Upgrade Cluster Interface¶
The following are the RPC requests and responses added by the RPC_OTA_Interface class and correspond to upgrade server functionality detailed in the Zigbee OTA Upgrade Cluster Specification. These methods allow Over-the-air (OTA) updating of client devices which implement the client side of that specification.
The interface is able to track multiple OTA images across many devices simultaneously. Policies can be set for each image to provide fine-grained control over how and when the images can be downloaded and installed.
The basic flow of a ZigBee OTA Image Upgrade is as follows.
Upload image to gateway.
Add image to an OTA Cluster server with ota_image_add.
- Depending on policies set in ota_image_add the following RPC requests may be necessary to manage the upgrade process.
- ota_image_notify notify OTA Cluster clients that an image is available.
- ota_device_allow allow a device to download an image.
- ota_device_disallow disallow a device from downloading an image.
- ota_image_upgrade_response instruct a device which has downloaded an image when to upgrade.
When clients have successfully upgraded the image can be removed with ota_image_remove and deleted from the gateway.
Current status of images and clients known by the OTA Cluster server can be checked through ota_image_status and ota_device_status respectively.
ota_image_add¶
Add a source image to a local OTA server for download by remote devices. The source image must already have been uploaded to the gateway’s filesystem.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing the firmware image. |
| source_endpoint_id | string | 8-bit identifier of the endpoint on the local device which will host the firmware image. |
| destination_address | MAC, list | 64-bit extended address of the device(s) which will be allowed to download the firmware image if require_explicit_allow is set to TRUE. May be either a MAC parameter or a list of MAC parameters. |
| disallow_destination_address | MAC, list | 64-bit extended address of the device(s) which will not be allowed to download the firmware image. May be either a MAC parameter or a list of MAC parameters. |
| require_explicit_allow* | bool | Defaults to FALSE. If TRUE, the server will only respond to devices which have been explicitly allowed through ota_image_allow or ota_image_notify. If False, the server will respond to any device which requests this firmware. |
| upgrade_when_finished* | bool | Defaults to TRUE. If TRUE, when the server detects that a device has finished downloading the firmware image it will be instructed to upgrade. If FALSE, when the server detects that a device has finished downloading it will be instructed to wait. |
| verify_file_version* | int | Controls whether and how the file version in requests will be checked to determine if a client can download and install an image. If 0, no verification of file version will be performed. If 1, file version is a single integer and the server will only respond to devices with an older version. If 2, file version is in ZCL OTA recommended format with separate Application and Stack release/build versions and checked accordingly. |
| current_time* | int | Used when generating Upgrade End Response payload if upgrade_when_finished is TRUE. Current time to encode in payload of the Image Upgrade Response. Defaults to current time on the local device when the Image Upgrade Response is generated. |
| upgrade_time_offset* | int | Used when generating Upgrade End Response payload if upgrade_when_finished is TRUE and upgrade_time is not provided. Offset from current_time to install firmware image. Defaults to 0 to install immediately. |
| upgrade_time* | int | Used when generating Upgrade End Response payload if upgrade_when_finished is TRUE. If not provided upgrade_time_offset will be used to calculate upgrade_time. Requested upgrade time to install the specified firmware image and overrides upgrade_time_offset. No default, only used when explicitly provided. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing the firmware image. |
| source_endpoint_id | string | 8-bit identifier of the endpoint on the local device hosting the firmware image. |
| destination_address | list | 64-bit extended address of the device(s) allowed to download the firmware image if require_explicit_allow is set to TRUE. List of MAC parameters. |
| disallow_destination_address | list | 64-bit extended address of the device(s) not allowed to download the firmware image. List of MAC parameters. |
Additional response parameters are returned matching policies set in the request.
Example
Add update.ota to be managed by endpoint 0x5E.
<ota_image_add>
<source type="string">/WEB/python/update.ota</source>
<require_explicit_notify type="bool">FALSE</require_explicit_notify>
<upgrade_when_finished type="bool">TRUE</upgrade_when_finished>
<endpoint_id>0x5E</endpoint_id>
</ota_image_add>
<ota_image_add_response>
<source type="string">/WEB/python/update.ota</source>
<source_endpoint_id type="int">0x5E</source_endpoint_id>
<upgrade_when_finished type="bool">TRUE</upgrade_when_finished>
<endpoint_id type="int">0x5E</endpoint_id>
<require_explicit_notify type="bool">FALSE</require_explicit_notify>
</ota_image_add_response>
ota_image_remove¶
Remove a source image from a local OTA server. Any downloads currently in process by remote devices will fail on the next request. This request does not remove the source image from the gateway’s filesystem.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing a firmware image hosted by an OTA server. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing a firmware image removed from the OTA server. |
| source_endpoint_id | int | 8-bit identifier of the endpoint which hosted the firmware image prior to removal. |
Example
Remove update.ota managed by endpoint 0x5E.
<ota_image_remove>
<source type="string">/WEB/python/update.ota</source>
</ota_image_remove>
<ota_image_remove_response>
<source_endpoint_id type="int">0x5E</source_endpoint_id>
<source type="string">/WEB/python/update.ota</source>
</ota_image_remove_response>
ota_device_allow¶
Adds one or more devices to the allowed list for the specified firmware image. Some firmware image policies restrict access to the firmware image. Explicitly adding a device will allow it to query and request the firmware image from the OTA server.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing a firmware image hosted by an OTA server. |
| destination_address | MAC, list | 64-bit extended address of the device(s) allowed to download the firmware image if require_explicit_allow is set to TRUE. May be either a MAC parameter or a list of MAC parameters. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing a firmware image hosted by an OTA server. |
| source_endpoint_id | string | 8-bit identifier of the endpoint on the local device hosting the firmware image. |
| destination_address | MAC, list | 64-bit extended address of the device(s) allowed to download the firmware image if require_explicit_allow is set to TRUE. May be either a MAC parameter or a list of MAC parameters. |
Example
Add 00:11:22:33:44:55:66:77 to allowed list for update.ota managed by endpoint 0x5E.
<ota_device_allow>
<source type="string">/WEB/python/update.ota</source>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
</ota_device_allow>
<ota_device_allow_response>
<source_endpoint_id type="int">0x5E</source_endpoint_id>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
<source type="string">/WEB/python/update.ota</source>
</ota_device_allow_response>
ota_device_disallow¶
Add one or more devices to the disallowed list for the specified image. Some firmware policies allow any device access to the firmware image. Explicitly adding a device will prevent it from querying or requesting the firmware image from the OTA server.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing a firmware image hosted by an OTA server. |
| destination_address | MAC, list | 64-bit extended address of the device(s) not allowed to download the firmware image. May be either a MAC parameter or a list of MAC parameters. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing a firmware image hosted by an OTA server. |
| source_endpoint_id | string | 8-bit identifier of the endpoint on the local device hosting the firmware image. |
| destination_address | MAC, list | 64-bit extended address of the device(s) not allowed to download the firmware image. May be either a MAC parameter or a list of MAC parameters. |
Example
Add 00:11:22:33:44:55:66:77 to disallowed list for update.ota managed by endpoint 0x5E.
<ota_device_disallow>
<source type="string">/WEB/python/update.ota</source>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
</ota_device_disallow>
<ota_device_disallow_response timestamp="1316727916">
<source_endpoint_id type="int">0x5E</source_endpoint_id>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
<source type="string">/WEB/python/update.ota</source>
</ota_device_disallow_response>
ota_image_notify¶
Send an Image Notify to OTA clients on the network. Image Notify commands can be unicast to a set of devices or broadcast to all devices. By default the Image Notify will be unicast to each destination device and an optional jitter parameter can be provided to send as broadcast instead. Fields of the Image Notify command can be provided explicitly, defaulted from a hosted firmware image, or included to match all.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| source* | string | Name of file containing a firmware image hosted by an OTA server. If provided, the firmware image can be used to default source_endpoint_id, manufacturer_id, image_type, and file_version. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device hosting the firmware image. Defaults to the source firmware image or default OTA Endpoint (0x5E). |
| destination_address* | MAC, list | 64-bit extended address of the device(s) targeted to receive the Image Notify command. If a source firmware image is provided and that image has require_explict_allow=TRUE then all specified devices will be added to the allow list. May be either a MAC parameter or a list of MAC parameters. |
| jitter* | int | Corresponds to jitter as defined in the Image Notify command and must be a value 1-100, inclusive. If provided then Image Notify will be sent as a broadcast. If not provided then Image Notify will be unicast to each destination device. Clients receiving an Image Notify with jitter are required to generate a random number between 1 and 100 and ignore the Image Notify if that random number is greater than jitter. |
| manufacturer_id* | int | 16-bit manufacturer identifier. Defaults to firmware image specified in source if available. Can be set to 0xFFFF to match all. Not included in unicasts. |
| image_type* | int | 16-bit image type. Defaults to firmware image specified in source if available. Can be set to 0xFFFF to match all. Not included in unicasts. |
| file_version* | int | 32-bit file version. Defaults to firmware image specified in source if available. Can be set to 0xFFFFFFFF to match all. Not included in unicasts. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source* | string | Name of file containing a firmware image hosted by an OTA server. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device hosting the firmware image or from which the Image Notify command(s) was sent. |
| destination_address* | MAC, list | 64-bit extended address of the device(s) targeted to receive the Image Notify command. |
| jitter* | int | If jitter value is provided then Image Notify command will be broadcast with the specified jitter. |
| manufacturer_id* | int | 16-bit manufacturer identifier as sent in the Image Notify command. |
| image_type* | int | 16-bit image type as sent in the Image Notify command. |
| file_version* | int | 32-bit file version as sent in the Image Notify command. |
Example
Broadcast an Image Notify from endpoint 0x5E. Approximately 50% of devices with a 0x1234 manufacturer identifier should respond with Query Next Image.
<ota_image_notify>
<jitter type="int">50</jitter>
<manufacturer_id type="int">0x1234</manufacturer_id>
</ota_image_notify>
<ota_image_notify_response>
<jitter type="int">0x32</jitter>
<source_endpoint_id type="int">0x5E</source_endpoint_id>
<manufacturer_id type="int">0x1234</manufacturer_id>
</ota_image_notify_response>
Unicast an Image Notify to several devices. The source endpoint 0x5E is determined from source.
<ota_image_notify>
<source type="string">/WEB/python/update.ota</source>
<destination_address type="list">
<item type="MAC">00:11:22:33:44:55:66:77</item>
<item type="MAC">11:22:33:44:55:66:77:88</item>
<item type="MAC">22:33:44:55:66:77:88:99</item>
</destination_address>
</ota_image_notify>
<ota_image_notify_response>
<source type="string">/WEB/python/update.ota</source>
<destination_address type="list">
<item type="MAC">00:11:22:33:44:55:66:77</item>
<item type="MAC">11:22:33:44:55:66:77:88</item>
<item type="MAC">22:33:44:55:66:77:88:99</item>
</destination_address>
<source_endpoint_id type="int">0x5E</source_endpoint_id>
</ota_image_notify_response>
recevied_upgrade_end_request*¶
Response only. An Upgrade End Request command is generated by OTA clients when they complete downloading an image and request permission to install. Behavior of the local OTA Server depends on value of the upgrade_when_finished policy. If FALSE, an Upgrade End Response telling the OTA Client to wait will be sent immediately and the ota_recevied_upgrade_end_request RPC reponse generated. If TRUE, an Upgrade End Response is sent according to the image configuration and no RPC response is generated.
If ota_recevied_upgrade_end_request is generated then ota_image_upgrade_response should be used to instruct the OTA client on when to install.
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing a firmware image hosted by an OTA server that an OTA client is requesting permission to install. |
| device | OTA_Device | Record describing the device which has downloaded source image. |
| payload | Upgrade_End_Request_payload | Payload of the Upgrade End Request indicating status of the downloaded image. |
Example
Device 00:11:22:33:44:55:66:77:88 sent an Upgrade End Request indicating a successful download of /WEB/python/update.ota and requests permission to upgrade. Response should be sent to endpoint 0xA.
<received_upgrade_end_request>
<source type="string">/WEB/python/update.ota</source>
<device type="OTA_Device">
<status type="int">0x2</status>
<addr_extended type="MAC">00:11:22:33:44:55:66:77:88</addr_extended>
<endpoint_id type="int">0xA</endpoint_id>
<bytes_downloaded type="int">0x5678</bytes_downloaded>
</device>
<payload type="Upgrade_End_Request_payload">
<status type="int">0x0</status>
<image_type type="int">0xABCD</image_type>
<manufacturer_id type="int">0x1234</manufacturer_id>
<file_version type="int">0x1</file_version>
</payload>
</received_upgrade_end_request>
ota_image_upgrade_response¶
Send an Image Upgrade Response command to an OTA client on the network instructing it when to upgrade to a downloaded firmware image.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| source* | string | Name of file containing a firmware image hosted by an OTA server. If provided, the firmware image can be used to default source_endpoint_id, manufacturer_id, image_type, and file_version. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device hosting the firmware image. Defaults to the source firmware image or default OTA Endpoint (0x5E). |
| destination_address* | MAC | 64-bit extended address of the device to which the Upgrade End Response command will be sent. Defaults to the broadcast address. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on remote device to which the Upgrade End Response command will be sent. Defaults to broadcast endpoint. |
| current_time* | int | Current time to encode in payload of the Image Upgrade Response. Defaults to current time on the local device. |
| upgrade_time_offset* | int | Offset to current time to install firmware image. Defaults to 0 to install immediately. |
| upgrade_time* | int | Requested upgrade time to install the specified firmware image and overrides upgrade_time_offset. No default, only used when explicitly provided. |
| manufacturer_id* | int | 16-bit manufacturer identifier. Defaults to firmware image specified in source if available. |
| image_type* | int | 16-bit image type. Defaults to firmware image specified in source if available. |
| file_version* | int | 32-bit file version. Defaults to firmware image specified in source if available. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source* | string | Name of file containing a firmware image hosted by an OTA server. If provided, the firmware image can be used to default source_endpoint_id, manufacturer_id, image_type, and file_version. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device hosting the firmware image. Defaults to the source firmware image or default OTA Endpoint (0x5E). |
| destination_address* | MAC | 64-bit extended address of the device to which the Upgrade End Response command was sent. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on remote device to which the Upgrade End Response command was sent. |
| current_time* | int | Included per the request. |
| upgrade_time_offset* | int | Included per the request. |
| upgrade_time* | int | Included per the request. |
| manufacturer_id* | int | 16-bit manufacturer identifier as sent in the Image Upgrade Response command. |
| image_type* | int | 16-bit image type as sent in the Image Upgrade Response command. |
| file_version* | int | 32-bit file version as sent in the Image Upgrade Response command. |
Example
Instruct device 00:11:22:33:44:55:66:77 to install /WEB/python/update.ota immediately.
<ota_image_upgrade_response>
<source type="string">/WEB/python/update.ota</source>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
</ota_image_upgrade_response>
<ota_image_upgrade_response_response timestamp="1316744228">
<source type="string">/WEB/python/update.ota</source>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
<destination_endpoint_id type="int">0xA</destination_endpoint_id>
</ota_image_upgrade_response_response>
ota_image_status¶
Return information on all firmware images currently hosted on a local OTA server(s). The optional source parameter can be provided to restrict results.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| source* | string | Name of file containing a firmware image for which status is requested. Defaults to all images. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| image | list | A list of image dictionaries where each item is formatted as specified in the below table. |
Image Dictionary
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing the firmware image hosted by an OTA server. |
| endpoint_id | int | 8-bit identifier of the endpoint on the local device hosting the firmware image. |
| header | OTA_Header | Header information contained in the firmware image. |
| devices | list | A list of records of type OTA_Device describing status of devices in the process of downloading the firmware image. |
Additional response parameters are returned in the Image Dictionay matching policies set when the image was added.
Example
Get status of /WEB/python/update.ota.
<ota_image_status>
<source type="string">/WEB/python/update.ota</source>
</ota_image_status>
<ota_image_status_response timestamp="1316744246">
<source type="string">/WEB/python/update.ota</source>
<image type="list">
<item type="dict">
<source type="string">/WEB/python/update.ota</source>
<endpoint_id type="int">0x5E</endpoint_id>
<header type="OTA_Header">
<total_image_size type="int">0x6D</total_image_size>
<header_length type="int">0x38</header_length>
<image_type type="int">0xFFFF</image_type>
<file_version type="int">0x0</file_version>
<header_version type="int">0x100</header_version>
<zigbee_stack_version type="int">0x2</zigbee_stack_version>
<header_string type="string">********************************</header_string>
<manufacturer_id type="int">0xFFFF</manufacturer_id>
<field_control type="int">0x0</field_control>
</header>
<devices type="list">
<item type="OTA_Device">
<status type="int">0x0</status>
<addr_extended type="MAC">00:11:22:33:44:55:66:77</addr_extended>
<endpoint_id type="int">0x5E</endpoint_id>
<bytes_downloaded type="int">0x0</bytes_downloaded>
</item>
</devices>
<require_explicit_allow type="bool">FALSE</require_explicit_allow>
<upgrade_when_finished type="bool">TRUE</upgrade_when_finished>
<upgrade_time />
<current_time />
<upgrade_time_offset type="int">0x0</upgrade_time_offset>
<verify_file_version type="int">0x0</verify_file_version>
<verify_image_type type="bool">TRUE</verify_image_type>
<verify_manufacturer_id type="bool">TRUE</verify_manufacturer_id>
<verify_hardware_version type="bool">TRUE</verify_hardware_version>
<verify_zigbee_stack_version type="bool">TRUE</verify_zigbee_stack_version>
</item>
</image>
</ota_image_status_response>
ota_device_status¶
Return device status from any firmware images a specified device may be in the process of downloading.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| destination_address | MAC | 64-bit extended address of the device for which status is requested. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| destination_address | MAC | 64-bit extended address of the device. |
| device_list | list | A list of device dictionaries where each item is formatted as specified in the below table. |
Device Dictionary
| Parameter | Type | Description |
|---|---|---|
| source | string | Name of file containing the firmware image hosted by an OTA server. |
| endpoint_id | int | 8-bit identifier of the endpoint on the local device hosting the firmware image. |
| device | OTA_Device | Status of device in the process of downloading the firmware image. |
Example
Get status of device 00:11:22:33:44:55:66:77.
<ota_device_status>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
</ota_device_status>
<ota_device_status_response>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address>
<device_list type="list">
<item type="dict">
<source type="string">/WEB/python/update.ota</source>
<endpoint_id type="int">0x5E</endpoint_id>
<device type="OTA_Device">
<status type="int">0x0</status>
<addr_extended type="MAC">00:11:22:33:44:55:66:77</addr_extended>
<endpoint_id type="int">0x5E</endpoint_id>
<bytes_downloaded type="int">0x0</bytes_downloaded>
</device>
</item>
</device_list>
<ota_device_status_response>