Client Functions

The following OTA Upgrade cluster functions can be used on the cluster client only:

  1. eOTA_SetServerAddress

  2. eOTA_ClientQueryNextImageRequest

  3. eOTA_ClientImageBlockRequest

  4. eOTA_ClientImagePageRequest

  5. eOTA_ClientUpgradeEndRequest

  6. eOTA_HandleImageVerification

  7. eOTA_UpdateClientAttributes

  8. eOTA_RestoreClientData

  9. vOTA_SetImageValidityFlag

  10. eOTA_ClientQuerySpecificFileRequest

  11. eOTA_SpecificFileUpgradeEndRequest

  12. vOTA_SetLowVoltageFlag

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