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.
1. ota_image_notify notify OTA Cluster clients that an image is available.
2. ota_device_allow allow a device to download an image.
3. ota_device_disallow disallow a device from downloading an image.
4. 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>

Quick search

Table Of Contents

Zigbee OTA Upgrade Cluster Interface

ota_image_add

ota_image_remove

ota_device_allow

ota_device_disallow

ota_image_notify

recevied_upgrade_end_request*

ota_image_upgrade_response

ota_image_status

ota_device_status