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