ZCL Over-the-Air Upgrade Cluster

Files
file	zcl_ota_server.h
	Support for a ZCL OTA Upgrade Cluster Server.
file	zcl_ota_upgrade.h
	Based on ZigBee document 095264r23.
file	zcl_ota_server.c
	Support for a ZCL OTA Upgrade Cluster Server.
file	zcl_ota_upgrade.c
	Support for ZCL Over-the-Air Upgrade Cluster.

Data Structures
struct	zcl_ota_upgrade_source_t
	Datatype for providing an OTA Upgrade Image to a client. More...
struct	zcl_ota_image_id_t
	Common sequence of fields appearing in multiple frame formats. More...
struct	zcl_ota_file_header_t
	OTA Upgrade File Header. More...
struct	zcl_ota_element_t
	Header of sub-elements in OTA Upgrade File following zcl_ota_file_header_t. More...
struct	zcl_ota_element_ecdsa_signature_t
	Sub-element with signature for the entire file, must be last in the file. More...
struct	zcl_ota_element_ecdsa_cert_t
	Sub-element with the certificate used to generate the OTA file's signature. More...
struct	zcl_ota_element_integrity_code_t
	Sub-element with a hash value to verify the integrity of the OTA file. More...
struct	zcl_ota_image_notify_t
	< new image identification More...
struct	zcl_ota_query_next_image_req_t
	< current image identification More...
struct	zcl_ota_query_next_image_resp_t
	< new image identification More...
struct	zcl_ota_image_block_req_t
	< upgrade image identification More...
struct	zcl_ota_image_page_req_t
	< upgrade image identification More...
struct	zcl_ota_image_block_resp_t
	< upgrade image identification More...
struct	zcl_ota_upgrade_end_req_t
	< upgrade image identification More...
struct	zcl_ota_upgrade_end_resp_t
	< upgrade image identification More...

Macros
#define	ZCL_OTA_UPGRADE_CLUSTER_ENTRY
	Macro to include an OTA Upgrade Server in an endpoint's cluster table. More...
#define	ZCL_CLUST_OTA_UPGRADE   0x0019
#define	ZCL_OTA_FILE_ID   0x0BEEF11E
	value for file_id_le element of zcl_ota_file_header_t
#define	ZCL_OTA_HEADER_VER   0x0100
	value for header_ver_le element of zcl_ota_file_header_t
#define	ZCL_OTA_FIELD_CONTROL_SECURITY_CRED   (1<<0)
#define	ZCL_OTA_FIELD_CONTROL_DEVICE_SPECIFIC   (1<<1)
#define	ZCL_OTA_FIELD_CONTROL_HARDWARE_VERSIONS   (1<<2)
#define	ZCL_OTA_IMAGE_TYPE_CLIENT_SECURITY_CREDS   0xFFC0
#define	ZCL_OTA_IMAGE_TYPE_CLIENT_CONFIG   0xFFC1
#define	ZCL_OTA_IMAGE_TYPE_SERVER_LOG   0xFFC2
#define	ZCL_OTA_IMAGE_TYPE_WILDCARD   0xFFFF
#define	ZCL_OTA_ZIGBEE_STACK_2006   0x0000
#define	ZCL_OTA_ZIGBEE_STACK_2007   0x0001
#define	ZCL_OTA_ZIGBEE_STACK_PRO   0x0002
#define	ZCL_OTA_ZIGBEE_STACK_IP   0x0003
#define	ZCL_OTA_SECURITY_CRED_SE_10   0x00
#define	ZCL_OTA_SECURITY_CRED_SE_11   0x01
#define	ZCL_OTA_SECURITY_CRED_SE_20   0x02
#define	ZCL_OTA_TAG_ID_UPGRADE_IMAGE   0x0000
#define	ZCL_OTA_TAG_ID_ECDSA_SIGNATURE   0x0001
#define	ZCL_OTA_TAG_ID_ECDSA_CERTIFICATE   0x0002
#define	ZCL_OTA_TAG_ID_IMAGE_INTEGRITY_CODE   0x0003
#define	ZCL_OTA_ATTR_UPGRADE_SERVER_ID   0x0000
#define	ZCL_OTA_ATTR_FILE_OFFSET   0x0001
#define	ZCL_OTA_ATTR_CURRENT_FILE_VER   0x0002
#define	ZCL_OTA_ATTR_CURRENT_ZIGBEE_STACK_VER   0x0003
#define	ZCL_OTA_ATTR_DOWNLOAD_FILE_VER   0x0004
#define	ZCL_OTA_ATTR_DOWNLOAD_ZIGBEE_STACK_VER   0x0005
#define	ZCL_OTA_ATTR_IMAGE_UPGRADE_STATUS   0x0006
#define	ZCL_OTA_ATTR_MANUFACTURER_ID   0x0007
#define	ZCL_OTA_ATTR_IMAGE_TYPE_ID   0x0008
#define	ZCL_OTA_ATTR_MIN_BLOCK_REQUEST_DELAY   0x0009
#define	ZCL_OTA_ATTR_IMAGE_STAMP   0x000A
#define	ZCL_OTA_CMD_IMAGE_NOTIFY   0x00
#define	ZCL_OTA_CMD_QUERY_NEXT_IMAGE_RESP   0x02
#define	ZCL_OTA_CMD_IMAGE_BLOCK_RESP   0x05
#define	ZCL_OTA_CMD_UPGRADE_END_RESP   0x07
#define	ZCL_OTA_CMD_QUERY_SPECIFIC_FILE_RESP   0x09
#define	ZCL_OTA_CMD_QUERY_NEXT_IMAGE_REQ   0x01
#define	ZCL_OTA_CMD_IMAGE_BLOCK_REQ   0x03
#define	ZCL_OTA_CMD_IMAGE_PAGE_REQ   0x04
#define	ZCL_OTA_CMD_UPGRADE_END_REQ   0x06
#define	ZCL_OTA_CMD_QUERY_SPECIFIC_FILE_REQ   0x08
#define	debug_printf(...)
#define	ZCL_OTA_SERVER_MAX_BLOCK_SIZE   256

Typedefs
typedef int(*	zcl_ota_upgrade_read_fn) (const struct zcl_ota_upgrade_source_t *source, void *buffer, uint32_t offset, size_t bytes, const addr64 *client_ieee_be)
	Callback for ZCL OTA Upgrade Server to supply data to Image Block Requests. More...

Functions
int	zcl_ota_upgrade_cluster_handler (const wpan_envelope_t FAR *envelope, void FAR *context)
	Handler for an OTA Upgrade Server's wpan_cluster_table_entry_t.
int	zcl_ota_upgrade_image_notify (wpan_dev_t *wpan_dev, const zcl_ota_image_id_t *image_id, const wpan_endpoint_table_entry_t *src_ep, uint8_t dest_ep, const addr64 *ieee_addr_be, uint16_t network_addr)
	Send at OTA Upgrade Image Notify command. More...
const zcl_ota_upgrade_source_t *	zcl_ota_get_upgrade_source (const addr64 *client_ieee_be, const zcl_ota_image_id_t *id, uint8_t zcl_command)
	Application-provided callback from ZCL OTA Upgrade cluster handler to retrieve a structure with details and callbacks/content for responses. More...
uint32_t	zcl_ota_get_upgrade_time (const addr64 *client_ieee_be, const zcl_ota_upgrade_source_t *source)
	Application-provided callback from ZCL OTA Upgrade cluster handler to retrieve the upgrade time to respond to client's Upgrade End Request. More...
const char *	zcl_ota_zigbee_stack_ver_str (uint16_t v)
	Return a description for an OTA header's Zigbee Stack Version.
const char *	zcl_ota_security_credential_ver_str (uint8_t v)
	Return a description for an OTA header's Security Credential Version.
const char *	zcl_ota_tag_identifier_str (uint16_t id)
	Return a description for an OTA header's Sub-Element Tag.
uint32_t	zcl_ota_tag_identifier_length (uint16_t id)
	The expected length (or 0 for variable) of an OTA file's Sub-Element Tag. More...
int	zcl_ota_next_image_resp (zcl_command_t *zcl_req)
	Respond to an OTA Upgrade Next Image Request.
int	zcl_ota_image_block_resp (zcl_command_t *zcl_req)
	Respond to an OTA Upgrade Image Block Request.
int	zcl_ota_upgrade_end_resp (zcl_command_t *zcl_req)
	Respond to an OTA Upgrade End Request.

Detailed Description

Macro Definition Documentation

#define ZCL_OTA_UPGRADE_CLUSTER_ENTRY

Value:

{ ZCL_CLUST_OTA_UPGRADE, zcl_ota_upgrade_cluster_handler, \
      NULL, WPAN_CLUST_FLAG_SERVER }

Macro to include an OTA Upgrade Server in an endpoint's cluster table.

Typedef Documentation

typedef int(* zcl_ota_upgrade_read_fn) (const struct zcl_ota_upgrade_source_t *source, void *buffer, uint32_t offset, size_t bytes, const addr64 *client_ieee_be)

Callback for ZCL OTA Upgrade Server to supply data to Image Block Requests.

Parameters

[in]	context	Context field of zcl_ota_upgrade_source_t.
[out]	buffer	Location for requested data.
[in]	offset	Offset into image for reading data.
[in]	bytes	Number of bytes to store in buffer.
[in]	client_ieee_be	Client's IEEE address (if necessary to customize OTA image content).

Returns

Number of bytes actually read.

Function Documentation

const zcl_ota_upgrade_source_t* zcl_ota_get_upgrade_source	(	const addr64 *	client_ieee_be,
		const zcl_ota_image_id_t *	id,
		uint8_t	zcl_command
	)

Application-provided callback from ZCL OTA Upgrade cluster handler to retrieve a structure with details and callbacks/content for responses.

Parameters

[in]	client_ieee_be	Client's 64-bit IEEE address (big-endian).
[in]	id	Key fields (Mfg Code, Image Type, File Version) from request frame to match against available updates.
[in]	zcl_command	ZCL Command (ZCL_OTA_CMD_xxx)

Return values

NULL	Respond to client with NO_IMAGE_AVAILABLE.
non-NULL	Source with image to send to client.

Referenced by zcl_ota_image_block_resp(), zcl_ota_next_image_resp(), and zcl_ota_upgrade_end_resp().

uint32_t zcl_ota_get_upgrade_time	(	const addr64 *	client_ieee_be,
		const zcl_ota_upgrade_source_t *	source
	)

Application-provided callback from ZCL OTA Upgrade cluster handler to retrieve the upgrade time to respond to client's Upgrade End Request.

Parameters

[in]	client_ieee_be	Client's 64-bit IEEE address (big-endian).
[in]	source	Source of OTA Update Image (as returned from zcl_ota_get_upgrade_source).

Return values

NULL	Respond to client with NO_IMAGE_AVAILABLE.
non-NULL	Source with image to send to client.

Referenced by zcl_ota_upgrade_end_resp().

uint32_t zcl_ota_tag_identifier_length

(

uint16_t

id

)

The expected length (or 0 for variable) of an OTA file's Sub-Element Tag.

Return expected length for a given sub-element Tag Identifier, or 0 if variable-length.

Parameters

[in]

id

Tag Identifier from Sub-element in OTA file.

Return values

0	Unknown or variable size.
>0	Expected value of sub-element's length field.

int zcl_ota_upgrade_image_notify	(	wpan_dev_t *	wpan_dev,
		const zcl_ota_image_id_t *	image_id,
		const wpan_endpoint_table_entry_t *	src_ep,
		uint8_t	dest_ep,
		const addr64 *	ieee_addr_be,
		uint16_t	network_addr
	)

Send at OTA Upgrade Image Notify command.

Parameters

[in]	wpan_dev	Device used to send.
[in]	image_id	Image ID for Mfg. Code, Image Type and File Version.
[in]	src_ep	Source endpoint structure to send from.
[in]	dest_ep	Target device's endpoint.
[in]	ieee_addr_be	Target device's 64-bit IEEE address.
[in]	network_addr	Target device's 16-bit network address.

Return values

0	Request Sent
<0	Error returned from wpan_dev->endpoint_send().

References wpan_envelope_t::cluster_id, wpan_envelope_t::dest_endpoint, wpan_endpoint_table_entry_t::endpoint, zcl_command_t::frame_control, wpan_envelope_t::length, wpan_envelope_t::payload, wpan_envelope_t::profile_id, wpan_endpoint_table_entry_t::profile_id, zcl_command_t::sequence, wpan_envelope_t::source_endpoint, wpan_endpoint_next_trans(), wpan_envelope_create(), wpan_envelope_send(), zcl_envelope_payload_dump(), ZCL_FRAME_DIRECTION, ZCL_FRAME_DISABLE_DEF_RESP, ZCL_FRAME_SERVER_TO_CLIENT, ZCL_FRAME_TYPE_CLUSTER, and ZCL_FRAME_TYPE_MASK.