Functions
The OTA Upgrade cluster functions that are provided in the NXP implementation of the ZCL are divided into the following three categories:
General functions (used on server and client) - see Section 49.10.1
Server functions - see Section 49.10.2
Client functions - see Section 49.10.3
General Functions
The following OTA Upgrade cluster functions can be used on the cluster server and the cluster client:
eOTA_Create
teZCL_Status eOTA_Create(
tsZCL_ClusterInstance *psClusterInstance,
bool_t bIsServer,
tsZCL_ClusterDefinition *psClusterDefinition,
void *pvEndPointSharedStructPtr,
uint8 u8Endpoint,
uint8 *pu8AttributeControlBits,
tsOTA_Common *psCustomDataStruct);
Description
This function creates an instance of the OTA Upgrade cluster on the specified endpoint. The cluster instance can act as a server or a client, as specified. The shared structure of the device associated with cluster must also be specified.
The function must be the first OTA function called in the application, and must be called after the stack has been started and after the ZCL has been initialized.
Parameters
psClusterInstance: Pointer to structure containing information about the cluster instance to be created (see Section 6.1.16)
bIsServer: Side of cluster to be implemented on this device:
TRUE - Server
FALSE - Client
psClusterDefinition: Pointer to structure indicating the type of cluster (see Section 6.1.2) - this structure must contain the details of the OTA Upgrade cluster
pvEndPointSharedStructPtr: Pointer to shared device structure for relevant endpoint (depends on device type, e.g. Door Lock)
u8Endpoint: Number of endpoint with which cluster will be associated
pu8AttributeControlBits: Pointer to an array of bitmaps, one for each attribute in the relevant cluster - for internal cluster definition use only, array should be initialised to 0
tpsCustomDataStruct: Pointer to structure containing custom data for OTA Upgrade cluster (see Section 49.11.2)
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:General Functions
vOTA_FlashInit
void vOTA_FlashInit(void *pvFlashTable,
tsNvmDefs *psNvmStruct);
Description
This function initializes the Flash memory device to be used by the OTA Upgrade cluster. Information about the device must be provided, such as the device type and sector size.
If a custom or unsupported Flash memory device is used then user-defined callback functions must be provided to perform Flash memory read, write, erase and initialization operations (if an NXP-supported device is used, standard callback functions will be used):
A general set of functions (for use by all software components) can be specified through pvFlashTable.
Optionally, an additional set of functions specifically for use by the OTA Upgrade cluster can be specified in the structure referenced by psNvmStruct.
This function must be called after the OTA Upgrade cluster has been created (after eOTA_Create() has been called either directly or indirectly) and before any other OTA Upgrade functions are called.
Parameters
pvFlashTable: Pointer to general set of callback functions to perform Flash memory read, write, erase and initialization operations. If using an NXP-supported Flash memory device, set a null pointer to use standard callback functions
psNvmStruct: Pointer to structure containing information on Flash memory device - see Section 49.11.4
Returns
None
Parent topic:General Functions
eOTA_AllocateEndpointOTASpace
teZCL_Status eOTA_AllocateEndpointOTASpace(
uint8 u8Endpoint,
uint8 *pu8Data,
uint8 u8NumberOfImages,
uint8 u8MaxSectorsPerImage,
bool_t bIsServer,
uint8 *pu8CAPublicKey);
Description
This function is used to allocate Flash memory space to store application images as part of the OTA upgrade process for the specified endpoint. The maximum number of images that are held at any one time must be specified as well the Flash memory start sector of every image. The maximum number of sectors used to store an image must also be specified.
The start sectors of the image space allocations are provided in an array. The index of an element of this array will subsequently be used to identify the stored image in other function calls.
Advice about the allocation of internal Flash memory space to OTA upgrade images on the client is provided in Appendix E.2
Parameters
u8Endpoint: Number of endpoint for which Flash memory space is to be allocated
pu8Data: Pointer to array containing the Flash memory start sector of each image (array index identifies image)
u8NumberOfImages: Maximum number of application images that are stored in Flash memory at any one time
u8MaxSectorsPerImage: Maximum number of sectors to be used to store an individual application image
bIsServer: Side of cluster implemented on this device:
TRUE - Server
FALSE - Client
pu8CAPublicKey: Pointer to Certificate Authority public key (provided in the security certificate from a company such as Certicom)
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_INVALID_VALUE
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_PARAMETER_NULL
Parent topic:General Functions
vOTA_GenerateHash
void vOTA_GenerateHash(
tsZCL_EndPointDefinition *psEndPointDefinition,
tsOTA_Common *psCustomData,
bool bIsServer,
bool bHeaderPresent,
AESSW_Block_u *puHash,
uint8 u8ImageLocation);
Description
This function can be used to generate a hash checksum for an application image in Flash memory, using the Matyas-Meyer-Oseas cryptographic hash.
Parameters
psEndPointDefinition Pointer to structure which defines endpoint corresponding to the application (see Section 6.1.1)
psCustomData Pointer to data structure connected with event associated with the checksum (see Section 49.11.2)
bIsServer Side of cluster implemented on this device:
TRUE - Server
FALSE - Client
bHeaderPresent Presence of image header:
TRUE - Present
FALSE - Absent
puHash Pointer to structure to receive calculated hash checksum
u8ImageLocation Number of sector where image starts in Flash memory
Returns
None
Parent topic:General Functions
eOTA_GetCurrentOtaHeader
teZCL_Status eOTA_GetCurrentOtaHeader(
uint8 u8Endpoint,
bool_t bIsServer,
tsOTA_ImageHeader *psOTAHeader);
Description
This function can be used to obtain the OTA header of the application image which is currently running on the local node.
The obtained parameter values are received in a tsOTA_ImageHeader structure.
Parameters
u8Endpoint Number of endpoint on which cluster operates
bIsServer Side of the cluster implemented on this device:
TRUE - Server
FALSE - Client
psOTAHeader Pointer to structure to receive the current OTA header (see Section 49.11.1)
Returns
E_ZCL_SUCCESS
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_PARAMETER_NULL
Parent topic:General Functions
Parent topic:Functions
Server Functions
The following OTA Upgrade cluster functions can be used on the cluster server only:
eOTA_SetServerParams
teZCL_Status eOTA_SetServerParams(
uint8 u8Endpoint,
uint8 u8ImageIndex,
tsCLD_PR_Ota *psOTAData);
Description
This function can be used to set server parameter values (including query jitter, data size, image data, current time and upgrade time) for a particular image stored on the server. The parameter values to be set are specified in a structure, described in Section 49.11.22. For detailed descriptions of these parameters, refer to the *ZigBee Over-the-Air Upgrading Cluster Specification (095264)*from the ZigBee Alliance.
If this function is not called, default values are used for these parameters.
The current values of these parameters can be obtained using the function eOTA_GetServerData().
The index of the image for which server parameter values are to be set must be specified. For an image stored in Flash memory, this index will take a value in the range 0 to (OTA_MAX_IMAGES_PER_ENDPOINT - 1).
Parameters
u8Endpoint: Number of endpoint (on server) on which cluster operates
u8ImageIndex: Index number of image
psOTAData: Pointer to structure containing parameter values to be set (see Section 49.11.22)
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Server Functions
eOTA_GetServerData
teZCL_Status eOTA_GetServerData(
uint8 u8Endpoint,
uint8 u8ImageIndex,
tsCLD_PR_Ota *psOTAData);
Description
This function can be used to obtain server parameter values (including query jitter, data size, image data, current time and upgrade time). The obtained parameter values are received in a structure, described in Section 49.11.22. For detailed descriptions of these parameters, refer to the *ZigBee Over-the-Air Upgrading Cluster Specification (095264)*from the ZigBee Alliance.
The values of these parameters can be set by the application using the function eOTA_SetServerParams().
The index of the image for which server parameter values are to be obtained must be specified. For an image stored in the Flash memory, this index will take a value in the range 0 to (OTA_MAX_IMAGES_PER_ENDPOINT - 1).
Parameters
u8Endpoint: Number of endpoint (on server) on which cluster operates
u8ImageIndex: Index number of image
psOTAData: Pointer to structure to receive parameter values (see Section 49.11.22)
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Server Functions
eOTA_EraseFlashSectorsForNewImage
teZCL_Status eOTA_EraseFlashSectorsForNewImage(
uint8 u8Endpoint,
uint8 u8ImageIndex);
Description
This function can be used to erase certain sectors of the Flash memory of the device in the OTA server node. The sectors allocated to the specified image index number will be erased so that the sectors (and index number) can be re-used. The function is normally called before writing a new upgrade image to Flash memory.
The specified image index number must be in the range 0 to (OTA_MAX_IMAGES_PER_ENDPOINT - 1).
Parameters
u8Endpoint: Number of endpoint (on server) on which cluster operates
u8ImageIndex: Index number of image
Returns
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_SUCCESS
Parent topic:Server Functions
eOTA_FlashWriteNewImageBlock
teZCL_Status eOTA_FlashWriteNewImageBlock(
uint8 u8Endpoint,
uint8 u8ImageIndex,
bool bIsServerImage,
uint8 *pu8UpgradeBlockData,
uint8 u8UpgradeBlockDataLength,
uint32 u32FileOffSet);
Description
This function can be used to write a block of an upgrade image to the devices internal Flash memory in the OTA server node. The image may be either of the following:
An upgrade image for the server itself (the server will later be rebooted from this image)
An upgrade image for one or more clients, which will later be made available for OTA distribution through the wireless network
The image in Flash memory to which the block belongs is identified by its index number. The specified image index number must be in the range 0 to (OTA_MAX_IMAGES_PER_ENDPOINT - 1).
Note that for JN518x, K32W041, and K32W061, internal Flash memory, writes must be 512-byte aligned.
Parameters
u8Endpoint: Number of endpoint (on server) on which cluster operates
u8ImageIndex: Index number of image
bIsServerImage: Indicates whether new image is for the server or a client:
TRUE - Server image
FALSE - Client image
pu8UpgradeBlockData: Pointer to image block to be written
u8UpgradeBlockDataLength: Size, in bytes, of image block to be written
u32FileOffSet: Offset of block from start of image file (in terms of number of bytes)
Returns
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_FAIL
E_ZCL_SUCCESS
Parent topic:Server Functions
eOTA_NewImageLoaded
teZCL_Status eOTA_NewImageLoaded(
uint8 u8Endpoint,
bool bIsImageOnCoProcessorMedia,
tsOTA_CoProcessorOTAHeader
*psOTA_CoProcessorOTAHeader);
Description
This function can be used for two purposes which relate to a new application image and which depend on whether the image has been stored in the internal Flash memory of the device or in the external storage device of a co-processor (if any) within the server node:
For an image stored in internal Flash memory, the function can be used to notify the OTA Upgrade cluster server on the specified endpoint that a new application image has been loaded into Flash memory and is available for download to clients. The server then validates the new image.
For one or more images stored in the co-processor’s external storage device, the function can be used to provide OTA header information for the image(s) to the cluster server. In the case of more than one image stored in co-processor storage, this function may replicate OTA header information for older images already registered with the server.
Note: The co-processor option is currently not supported for JN518x, K32W041, or K32W061.
Parameters
u8Endpoint: Number of endpoint (on server) on which cluster operates
bIsImageOnCoProcessorMedia: Flag indicating whether image is stored in co-processor external storage device:
TRUE - Stored in co-processor
FALSE - Stored in internal Flash memory
psOTA_CoProcessorOTAHeader: Pointer to OTA headers of images which are held in co-processor storage device
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Server Functions
eOTA_ServerImageNotify
teZCL_Status eOTA_ServerImageNotify(
uint8 u8SourceEndpoint,
uint8 u8DestinationEndpoint,
tsZCL_Address *psDestinationAddress,
tsOTA_ImageNotifyCommand *psImageNotifyCommand);
Description
This function issues an Image Notify message to one or more clients to indicate that a new application image is available for download.
The message can be unicast to an individual client or multicast to selected clients (but cannot be broadcast to all clients, for security reasons).
Parameters
u8SourceEndpoint: Number of endpoint (on server) from which the message is sent
u8DestinationEndpoint: Number of endpoint (on client) to which the message is sent
psDestinationAddress: Pointer to structure containing the address of the target client for the message - a multicast to more than one client is also possible (see Section 6.1.4)
psImageNotifyCommand: Pointer to structure containing payload for message (see Section 49.11.5)
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Server Functions
eOTA_ServerQueryNextImageResponse
teZCL_Status eOTA_ServerQueryNextImageResponse(
uint8 u8SourceEndpoint,
uint8 u8DestinationEndpoint,
tsZCL_Address *psDestinationAddress,
tsOTA_QueryImageResponse
*psQueryImageResponsePayload,
uint8 u8TransactionSequenceNumber);
Description
This function issues a Query Next Image Response to a client which has sent a Query Next Image Request (the arrival of this request triggers the event E_CLD_OTA_COMMAND_QUERY_NEXT_IMAGE_REQUEST on the server).
The Query Next Image Response contains information on the latest application image available for download to the client, including the image size and file version.
Note: The cluster server responds automatically to a Query Next Image Request, so it is not normally necessary for the application to call this function.
You are also required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.
Parameters
u8SourceEndpoint: Number of endpoint (on server) from which the response is sent
u8DestinationEndpoint: Number of endpoint (on client) to which the response is sent
psDestinationAddress: Pointer to structure containing the address of the target client for the response (see Section 6.1.4)
psQueryImageResponsePayload: Pointer to structure containing payload for response (see Section 49.11.7)
u8TransactionSequenceNumber: Pointer to a location to store the Transaction Sequence Number (TSN) of the request
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Server Functions
eOTA_ServerImageBlockResponse
teZCL_Status eOTA_ServerImageBlockResponse(
uint8 u8SourceEndpoint,
uint8 u8DestinationEndpoint,
tsZCL_Address *psDestinationAddress,
tsOTA_ImageBlockResponsePayload
*psImageBlockResponsePayload,
uint8 u8BlockSize,
uint8 u8TransactionSequenceNumber);
Description
This function issues an Image Block Response, containing a block of image data, to a client to which the server is downloading an application image. The function is called after receiving an Image Block Request from the client, indicating that the client is ready to receive the next block of the application image (the arrival of this request triggers the event E_CLD_OTA_COMMAND_BLOCK_REQUEST on the server).
The size of the block, in bytes, is specified as part of the function call. This must be less than or equal to the maximum possible block size defined in the zcl_options.h file (see Section 49.13).
Note: The cluster server responds automatically to an Image Block Request, so it is not normally necessary for the application to call this function.
You are also required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.
Parameters
u8SourceEndpoint: Number of endpoint (on server) from which the response is sent
u8DestinationEndpoint: Number of endpoint (on client) to which the response is sent
psDestinationAddress: Pointer to structure containing the address of the target client for the response (see Section 6.1.4)
psImageBlockResponsePayload: Pointer to structure containing payload for response (see Section 49.11.10)
u8BlockSize: Size, in bytes, of block to be transferred
u8TransactionSequenceNumber: Pointer to a location to store the Transaction Sequence Number (TSN) of the request
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Server Functions
eOTA_SetWaitForDataParams
teZCL_Status eOTA_SetWaitForDataParams(
uint8 u8Endpoint,
uint16 u16ClientAddress,
tsOTA_WaitForData *sWaitForDataParams);
Description
This function can be used to send an Image Block Response with a status of OTA_STATUS_WAIT_FOR_DATA to a client, in response to an Image Block Request from the client.
The payload of this response includes a new value for the ‘block request delay’ attribute on the client. This value can be used by the client for ‘rate limiting’ -that is, to control the rate at which the client requests data blocks from the server and therefore the average OTA download rate from the server to the client.
Rate limiting is described in more detail in Section 49.8.1.
Parameters
u8Endpoint: Number of endpoint (on server) from which the response is sent
u16ClientAddress: Network address of client device to which the response is sent
sWaitForDataParams: Pointer to structure containing ‘Wait for Data’ parameter values for Image Block Response payload (see Section49.11.15)
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Server Functions
eOTA_ServerUpgradeEndResponse
teZCL_Status eOTA_ServerUpgradeEndResponse(
uint8 u8SourceEndpoint,
uint8 u8DestinationEndpoint,
tsZCL_Address *psDestinationAddress,
tsOTA_UpgradeEndResponsePayload
*psUpgradeResponsePayload,
uint8 u8TransactionSequenceNumber);
Description
This function issues an Upgrade End Response to a client to which the server has been downloading an application image. The function is called after receiving an Upgrade End Request from the client, indicating that the client has received the entire application image and verified it (the arrival of this request triggers the event E_CLD_OTA_COMMAND_UPGRADE_END_REQUEST on the server).
The Upgrade End Response includes the upgrade time for the downloaded image as well as the current time (the client will use this information to implement a delay before upgrading the running application image).
Note: The cluster server responds automatically to an Upgrade End Request, so it is not normally necessary for the application to call this function.
You are also required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.
Parameters
u8SourceEndpoint: Number of endpoint (on server) from which the response is sent
u8DestinationEndpoint: Number of endpoint (on client) to which the response is sent
psDestinationAddress: Pointer to structure containing the address of the target client for the response (see Section 6.1.4)
psUpgradeResponsePayload: Pointer to structure containing payload for response (see Section 49.11.12)
u8TransactionSequenceNumber: Pointer to a location to store the Transaction Sequence Number (TSN) of the request
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Server Functions
eOTA_ServerSwitchToNewImage
teZCL_Status eOTA_ServerSwitchToNewImage(
uint8 u8Endpoint,
uint8 u8ImageIndex);
Description
This function can be used to force a reset of the device in the OTA server node and, on reboot, run a new application image that has been saved in the attached Flash memory.
Before forcing the reset of the remove device, the function checks whether the version of the new image is greater than the version of the current image. If this is the case, the function invalidates the currently running image in Flash memory and initiates a software reset - otherwise, it returns an error.
The new application image is identified by its index number. The specified image index number must be in the range 0 to (OTA_MAX_IMAGES_PER_ENDPOINT - 1).
Parameters
u8Endpoint: Number of endpoint (on server) on which cluster operates
u8ImageIndex: Index number of image
Returns
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_FAIL
E_ZCL_SUCCESS
Parent topic:Server Functions
eOTA_InvalidateStoredImage
teZCL_Status eOTA_InvalidateStoredImage(
uint8 u8Endpoint,
uint8 u8ImageIndex);
Description
This function can be used to invalidate an application image that is held in the Flash memory of the device. Once the image has been invalidated, it will no longer to available for OTA upgrade.
The image to be invalidated is identified by its index number. The specified image index number must be in the range 0 to (OTA_MAX_IMAGES_PER_ENDPOINT - 1).
Parameters
u8Endpoint: Number of endpoint (on server) on which cluster operates
u8ImageIndex: Index number of image to be invalidated
Returns
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_SUCCESS
Parent topic:Server Functions
eOTA_ServerQuerySpecificFileResponse
teZCL_Status eOTA_ServerQuerySpecificFileResponse(
uint8 u8SourceEndpoint,
uint8 u8DestinationEndpoint,
tsZCL_Address *psDestinationAddress,
tsOTA_QuerySpecificFileResponsePayload
*psQuerySpecificFileResponsePayload,
uint8 u8TransactionSequenceNumber);
Description
This function can be used to issue a Query Specific File Response to a client which has sent a Query Specific File Request (the arrival of this request triggers the event E_CLD_OTA_COMMAND_QUERY_SPECIFIC_FILE_REQUEST on the server). The Query Specific File Response contains information on the latest device-specific file available for download to the client, including the file size and file version.
You are also required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.
Parameters
u8SourceEndpoint: Number of endpoint (on server) from which the response is sent
u8DestinationEndpoint: Number of endpoint (on client) to which the response is sent
psDestinationAddress: Pointer to structure containing the address of the target client
psQuerySpecificFileResponsePayload:
Pointer to structure containing payload for Query Specific File Response (see Section 49.11.20)
u8TransactionSequenceNumber: Pointer to a location to store the Transaction Sequence Number (TSN) of the request
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Server Functions
Parent topic:Functions
Client Functions
The following OTA Upgrade cluster functions can be used on the cluster client only:
eOTA_SetServerAddress
teZCL_Status eOTA_SetServerAddress(
uint8 u8Endpoint,
uint64 u64IeeeAddress,
uint16 u16ShortAddress);
Description
This function sets the addresses (64-bit IEEE/MAC address and 16-bit network address) of the OTA Upgrade cluster server that will be used to provide application upgrade images to the local client.
The function should be called after a server discovery has been performed to find a suitable server - this is done by sending out a Match Descriptor Request using the function ZPS_eAplZdpMatchDescRequest() described in theZigBee 3.0 Stack User Guide (JNUG3130). The server discovery must be completed and a server address set before any OTA-related message exchanges can occur (e.g. image request).
Parameters
u8Endpoint: Number of endpoint corresponding to application
u64IeeeAddress: IEEE/MAC address of server
u16ShortAddress: Network address of server
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Client Functions
eOTA_ClientQueryNextImageRequest
teZCL_Status eOTA_ClientQueryNextImageRequest(
uint8 u8SourceEndpoint,
uint8 u8DestinationEndpoint,
tsZCL_Address *psDestinationAddress,
tsOTA_QueryImageRequest
*psQueryImageRequest);
Description
This function issues a Query Next Image Request to the server and should be called in either of the following situations:
to poll for a new application image (typically used in this way by an End Device) - in this case, the function should normally be called periodically
to respond to an Image Notify message from the server, which indicated that a new application image is available for download - in this case, the function call should be prompted by the event E_CLD_OTA_COMMAND_IMAGE_NOTIFY
The payload of the request includes the relevant image type, current file version, hardware version and manufacturer code.
As a result of this function call, a Query Next Image Response will (eventually) be received from the server. The arrival of this response will trigger an E_CLD_OTA_COMMAND_QUERY_NEXT_IMAGE_RESPONSE event.
Parameters
u8SourceEndpoint: Number of endpoint (on client) from which the request is sent
u8DestinationEndpoint: Number of endpoint (on server) to which the request is sent
psDestinationAddress: Pointer to structure containing the address of the target server (see Section 6.1.4)
psQueryImageRequest: Pointer to structure containing payload for request (see Section 49.11.6)
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Client Functions
eOTA_ClientImageBlockRequest
teZCL_Status eOTA_ClientImageBlockRequest(
uint8 u8SourceEndpoint,
uint8 u8DestinationEndpoint,
tsZCL_Address *psDestinationAddress,
tsOTA_BlockRequest
*psOtaBlockRequest);
Description
This function can be used during an image download to send an Image Block Request to the server, in order to request the next block of image data.
As a result of this function call, an Image Block Response containing the requested data block will (eventually) be received from the server. The arrival of this response will trigger an E_CLD_OTA_COMMAND_QUERY_NEXT_IMAGE_RESPONSE event.
Note: The cluster client automatically sends Image Block Requests to the server during a download, so it is not normally necessary for the application to call this function.
Parameters
u8SourceEndpoint: Number of endpoint (on client) from which the request is sent
u8DestinationEndpoint: Number of endpoint (on server) to which the request is sent
psDestinationAddress: Pointer to structure containing the address of the target server (see Section 6.1.4)
psOtaBlockRequest: Pointer to structure containing payload for request (see Section 49.11.8)
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Client Functions
eOTA_ClientImagePageRequest
teZCL_Status eOTA_ClientImagePageRequest(
uint8 u8SourceEndpoint,
uint8 u8DestinationEndpoint,
tsZCL_Address *psDestinationAddress,
tsOTA_ImagePageRequest *psOtaPageRequest);
Description
This function can be used during an image download to send an Image Page Request to the server, in order to request the next page of image data. In this function call, a structure must be supplied which contains the payload data for the request. This data includes the page size, in bytes.
Note 1: Image Page Requests can be used instead of Image Block Requests if page requests have been enabled in the zcl_options.h file for the client and server (see Section 49.13).
Note 2: The cluster client automatically sends Image Page Requests (if enabled) to the server during a download, so it is not normally necessary for the application to call this function.
As a result of this function call, a sequence of Image Block Responses containing the requested data will (eventually) be received from the server. The arrival of each response will trigger an E_CLD_OTA_COMMAND_BLOCK_RESPONSE event on the client. If this function is used (rather than the stack) to issue Image Page Requests, it is the responsibility of the application to keep a count of the number of data bytes received since the Image Page Request was issued - when all the requested page data has been received, this count will equal the specified page size.
Page requests are described in more detail in Section 49.8.4.
Parameters
u8SourceEndpoint: Number of endpoint (on client) from which the request is sent
u8DestinationEndpoint: Number of endpoint (on server) to which the request is sent
psDestinationAddress: Pointer to structure containing the address of the target server (see Section 6.1.4)
psOtaPageRequest: Pointer to structure containing payload for request (see Section 49.11.9)
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Client Functions
eOTA_ClientUpgradeEndRequest
teZCL_Status eOTA_ClientUpgradeEndRequest(
uint8 u8SourceEndpoint,
uint8 u8DestinationEndpoint,
tsZCL_Address *psDestinationAddress,
tsOTA_UpgradeEndRequestPayload
*psUpgradeEndRequestPayload);
Description
This function can be used during an image download to send an Upgrade End Request to the server. This is normally used to indicate that all the image data has been received and that the image has been successfully verified - it is the responsibility of the client to determine when all the image data has been received (using the image size quoted in the original Query Next Image Response) and then to verify the image.
In addition to the status OTA_STATUS_SUCCESS described above, the function can be used by the client to report other conditions to the server:
OTA_REQUIRE_MORE_IMAGE: The downloaded image was successfully received and verified, but the client requires multiple images before performing an upgrade
OTA_STATUS_INVALID_IMAGE: The downloaded image failed the verification checks and will be discarded
OTA_STATUS_ABORT The image download that is currently in progress should be cancelled
In all three of the above cases, the client may then request another download.
When the function is called to report success, an Upgrade End Response will (eventually) be received from the server, indicating when the image upgrade should be implemented (a time delay may be indicated in the response). The arrival of this response will trigger an E_CLD_OTA_COMMAND_UPGRADE_END_RESPONSE event.
Note: The cluster client automatically sends an Upgrade End Request to the server on completion of a download, so it is not normally necessary for the application to call this function.
Parameters
u8SourceEndpoint: Number of endpoint (on client) from which the request is sent
u8DestinationEndpoint: Number of endpoint (on server) to which the request is sent
psDestinationAddress: Pointer to structure containing the address of the target server (see Section 6.1.4)
psUpgradeEndRequestPayload: Pointer to structure containing payload for request, including reported status (see Section49.11.11)
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Client Functions
eOTA_HandleImageVerification
teZCL_Status eOTA_HandleImageVerification(
uint8 u8SourceEndPointId,
uint8 u8DstEndpoint,
teZCL_Status eImageVerificationStatus);
Description
This function transmits an upgrade end request with the specified status.
Parameters
u8SourceEndPointId: Identifier of endpoint on which the cluster client operates
u8DstEndpoint: Identifier of endpoint (on the server) to which the upgrade end request is sent
eImageVerificationStatus: Image status code
Returns
E_ZCL_FAIL
E_ZCL_SUCCESS
Parent topic:Client Functions
eOTA_UpdateClientAttributes
teZCL_Status eOTA_UpdateClientAttributes(
uint8 u8Endpoint);
Description
This function can be used on a client to set the OTA Upgrade cluster attributes to their default values. It should be called during application initialization after the cluster instance has been created using eOTA_Create().
Following subsequent resets, provided that context data has been saved, the application should call eOTA_RestoreClientData() instead of this function.
Parameters
u8Endpoint: Number of endpoint corresponding to context data
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Client Functions
eOTA_RestoreClientData
teZCL_Status eOTA_RestoreClientData(
uint8 u8Endpoint,
tsOTA_PersistedData *psOTAData,
bool_t bReset);
Description
This function can be used to restore OTA Upgrade context data that has been previously saved to Flash memory (using the NVM) on the local client - for example, it restores the OTA Upgrade attribute values. The function can be used to restore the data in RAM following a device reset or simply to refresh the data in RAM.
Parameters
8Endpoint: Number of endpoint corresponding to context data
psOTAData: Pointer to structure containing the context data to be restored (see Section 49.11.13)
bReset: Indicates whether the data restoration follows a reset:
TRUE - Follows a reset
FALSE - Does not follow a reset
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Client Functions
vOTA_SetImageValidityFlag
void vOTA_SetImageValidityFlag(
uint8 u8Location,
tsOTA_Common *psCustomData,
bool bSet,
tsZCL_EndPointDefinition *psEndPointDefinition);
Description
This function can be used to set an image validity flag once a downloaded upgrade image has been received and verified by the client.
Parameters
u8Location: Number of sector where image starts in Flash memory
psCustomData: Pointer to custom data for image (see Section 49.11.2)
bSet: Flag state to be set:
TRUE - Reset
FALSE - No reset
psEndPointDefinition: Pointer to endpoint definition (see Section 6.1.1)
Returns
None
Parent topic:Client Functions
eOTA_ClientQuerySpecificFileRequest
eOTA_ClientQuerySpecificFileRequest(
uint8 u8SourceEndpoint,
uint8 u8DestinationEndpoint,
tsZCL_Address *psDestinationAddress,
tsOTA_QuerySpecificFileRequestPayload
*psQuerySpecificFileRequestPayload);
Description
This function can be used to issue a Query Specific File Request to the server. It should be called to request a device-specific file from the server. As a result of this function call, a Query Specific File Response will (eventually) be received in reply.
Parameters
u8SourceEndpoint: Number of endpoint (on client) from which the request is sent
u8DestinationEndpoint: Number of endpoint (on server) to which the request is sent
psDestinationAddress: Pointer to structure containing the address of the target server
psQuerySpecificFileRequestPayload: Pointer to structure containing payload for Query Specific File Request
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Client Functions
eOTA_SpecificFileUpgradeEndRequest
eOTA_SpecificFileUpgradeEndRequest(
uint8 u8SourceEndPointId,
uint8 u8Status);
Description
This function can be used to issue an Upgrade End Request for the device-specific file download that is in progress in order to indicate to the server that the download has completed. This request can be issued by the client optionally after the downloaded image has been verified and found to be valid.
Parameters
u8SourceEndPointId: Number of endpoint (on client) from which the request is sent
u8Status: Download status of device-specific file - if the file has been completely and successfully received, this parameter must be set to OTA_STATUS_SUCCESS
Returns
E_ZCL_SUCCESS
E_ZCL_FAIL
Parent topic:Client Functions
vOTA_SetLowVoltageFlag
void vOTA_SetLowVoltageFlag(bool bValue);
Description
This function can be used to configure the low-voltage flag on a node hosting an OTA Upgrade cluster client. This flag should be set when the supply voltage to the underlying hardware is below that required for normal operation and the node should not participate in an OTA upgrade.
When the flag is set, the client stops sending Image Block Requests to the server
When the flag is cleared, the client resumes sending Image Block Requests to the server
Use of the low-voltage flag must be enabled at compile-time by including the macro OTA_UPGRADE_VOLTAGE_CHECK in the zcl_options.h file.
Use of the low-voltage flag is described further in Section 49.8.7.
Parameters
bValue: Determines the state of the low-voltage flag, as follows:
TRUE - Sets the flag
FALSE - Clears the flag
Returns
None
Parent topic:Client Functions
Parent topic:Functions
Parent topic:OTA Upgrade cluster