Structures

tsOTA_ImageHeader

The following structure contains information for the OTA header:

typedef struct
{
            uint32 u32FileIdentifier;
    uint16 u16HeaderVersion;
    uint16 u16HeaderLength;
    uint16 u16HeaderControlField;
    uint16 u16ManufacturerCode;
    uint16 u16ImageType;
    uint32 u32FileVersion;
    uint16 u16StackVersion;
    uint8  stHeaderString[OTA_HEADER_STRING_SIZE];
            uint32 u32TotalImage;
    uint8  u8SecurityCredVersion;
    uint64 u64UpgradeFileDest;
    uint16 u16MinimumHwVersion;
    uint16 u16MaxHwVersion;
}tsOTA_ImageHeader;

where:

  • u32FileIdentifier is a 4-byte value equal to 0x0BEEF11E which indicates that the file contains an OTA upgrade image

  • u16HeaderVersion is the version of the OTA header expressed as a 2-byte value in which the most significant byte contains the major version number and the least significant byte contains the minor version number

  • u16HeaderLength is the full length of the OTA header, in bytes

  • u16HeaderControlField is a bitmap indicating certain information about the file, as detailed in table below.

Bit

Information

0

Security credential version (in OTA header):

1: Field present in header

0: Field not present in header

| |1|Device-specific file (also see u64UpgradeFileDest):

1: File is device-specific

0: File is not device-specific

| |2|Maximum and minimum hardware version (in OTA header):

1: Field present in header

0: Field not present in header

| |3-15|Reserved|

  • u16ManufacturerCode is the ZigBee-assigned manufacturer code (0xFFFF is a wildcard value, representing any manufacturer)

  • u16ImageType is a unique value representing the image type, where this value is normally manufacturer-specific but certain values have been reserved for specific file types, as indicated below (the wildcard value of 0xFFFF represents any file type):

Value

File Type

0x0000 – 0xFFBF

Manufacturer-specific

0xFFC0

Security credential

0xFFC1

Configuration

0xFFC2

Log

0xFFC3 – 0xFFFE

Reserved

0xFFFF

Wildcard

  • u32FileVersion contains the release and build numbers of the application and stack used to produce the application image - for details of the file version format, refer to         the ZigBee Over-the-Air Upgrading Cluster Specification (095264)

  • u16StackVersion contains ZigBee stack version that is used by the application (this is 0x0002 for ZigBee PRO)

  • stHeaderString[] is a manufacturer-specific string that can be used to store any useful human-readable information

  • u32TotalImage is the total size, in bytes, of the image that will be transferred over-the air (including the OTA header and any optional data)

  • u8SecurityCredVersion indicates the security credential version type that is required by the client in order to install the image - the possibilities are SE1.0 (0x0), SE1.1 (0x1) and SE2.0 (0x2)

  • u64UpgradeFileDest contains the IEEE/MAC address of the destination device for the file, in the case when the file is device-specific (as indicated by bit 1 of u16HeaderControlField)

  • u16MinimumHwVersion indicates the earliest hardware platform on which the image should be used, expressed as a 2-byte value in which the most significant byte contains the hardware version number and the least significant byte contains the revision number

  • u16MaxHwVersion indicates the latest hardware platform on which the image should be used, expressed as a 2-byte value in which the most significant byte contains the hardware version number and the least significant byte contains the revision number

Parent topic:Structures

tsOTA_Common

The following structure contains data relating to an OTA message received by the cluster (server or client) - this data is used for callback functions and the local OTA state machine:

typedef struct
{
    tsZCL_ReceiveEventAddress  sReceiveEventAddress;
    tsZCL_CallBackEvent        sOTACustomCallBackEvent;
    tsOTA_CallBackMessage      sOTACallBackMessage;
} tsOTA_Common;

The fields are for internal use and no knowledge of them is required. The tsOTA_CallBackMessage structure is described in Section 49.11.21.

Parent topic:Structures

tsOTA_HwFncTable

The following structure contains pointers to callback functions to be used by the OTA Upgrade cluster to perform initialization, erase, write and read operations on Flash memory (if these functions are not specified, standard NXP functions will be used):

typedef struct
{
     void (*prInitHwCb)(uint8, void*);
     void (*prEraseCb) (uint8 u8Sector);
     void (*prWriteCb) (uint32 u32FlashByteLocation,
                        uint16 u16Len,
                        uint8 *pu8Data);
     void (*prReadCb)  (uint32 u32FlashByteLocation,
                        uint16 u16Len,
                        uint8 *pu8Data);
} tsOTA_HwFncTable;

where:

  • prInitHwCb is a pointer to a callback function that is called after a cold or warm start to perform any initialization required for the Flash memory device

  • prEraseCb is a pointer to a callback function that is called to erase a specified sector of Flash memory

  • prWriteCb is a pointer to a callback function that is called to write a block of data to a sector, starting the write at a specified byte location in the sector (address zero is the start of the sector)

  • prReadCb is a pointer to a callback function that is called to read a block of data from a sector, starting the read at a specified byte location in the sector (address zero is the start of the sector)

Parent topic:Structures

tsNvmDefs

The following structure contains information used to configure access to Flash memory:

typedef struct
{
    tsOTA_HwFncTable sOtaFnTable;
    uint32           u32SectorSize;
    uint8            u8FlashDeviceType;
}tsNvmDefs;

where:

  • sOtaFnTable is a structure specifying the callback functions to be used by the cluster to perform initialization, erase, write and read operations on the Flash memory device (see Section 49.11.3) - if user-defined callback functions are not specified, standard NXP functions will be used

  • u32SectorSize is the size of a sector of the Flash memory device, in bytes

  • u8FlashDeviceType is a value indicating the type of Flash memory device, one of:

    • E_FL_CHIP_INTERNAL (Device internal Flash- default)

Parent topic:Structures

tsOTA_ImageNotifyCommand

The following structure contains the payload data for an Image Notify message issued by the server when a new upgrade image is available for download:

typedef struct
{
            teOTA_ImageNotifyPayloadType ePayloadType;
            uint32                       u32NewFileVersion;
            uint16                       u16ImageType;
            uint16                       u16ManufacturerCode;
            uint8                        u8QueryJitter;
}tsOTA_ImageNotifyCommand;

where:

  • ePayloadType is a value indicating the type of payload of the command (enumerations are available - see Section 49.12.4)

  • u32NewFileVersion is the file version of the client upgrade image that is currently available for download (the wild card of 0xFFFFFFFF is used to indicate that all clients should upgrade to this image)

  • u16ImageType is a number indicating the type of image that is available for download (the wild card of 0xFFFF is used to indicate that all image types are involved)

  • u16ManufacturerCode is a ZigBee-assigned number identifying the manufacturer to which the available image is connected (if all manufacturers are involved, this value should not be set)

  • u8QueryJitter is a value between 1 and 100 (inclusive) which is used by the receiving client to decide whether to reply to this Image Notify message - for information on ‘Query Jitter’, refer to Section 49.7

Parent topic:Structures

tsOTA_QueryImageRequest

The following structure contains payload data for a Query Next Image Request issued by a client to poll the server for an upgrade image or to respond to an Image Notify message from the server:

typedef struct
{
    uint32 u32CurrentFileVersion;
    uint16 u16HardwareVersion;
    uint16 u16ImageType;
    uint16 u16ManufacturerCode;
    uint8  u8FieldControl;
}tsOTA_QueryImageRequest;

where:

  • u32CurrentFileVersion is the file version of the application image that is currently running on the client that sent the request

  • u16HardwareVersion is the hardware version of the client device (this information is optional - see u8FieldControl below)

  • u16ImageType is a value in the range 0x0000-0xFFBF which identifies the type of image currently running on the client

  • u16ManufacturerCode is the ZigBee-assigned number identifying the manufacturer of the client device

  • u8FieldControl is a bitmap indicating whether certain optional information about the client is included in this Query Next Image Request message. Currently, this optional information consists only of the hardware version (contained in u16HardwareVersion above) - bit 0 is set to ‘1’ if the hardware version is included or to ‘0’ otherwise (all other bits are reserved)

Parent topic:Structures

tsOTA_QueryImageResponse

The following structure contains payload data for a Query Next Image Response issued by the server (as the result of a Query Next Image Request from a client):

typedef struct
{
    uint32 u32ImageSize;
    uint32 u32FileVersion;
    uint16 u16ManufacturerCode;
    uint16 u16ImageType;
    uint8  u8Status;
}tsOTA_QueryImageResponse;

where:

  • u32ImageSize is the total size of the available image, in bytes

  • u32FileVersion is the file version of the available image

  • u16ManufacturerCode is the manufacturer code that was received from the client in the Query Next Image Request message

  • u16ImageType is the image type that was received from the client in the Query Next Image Request message

  • u8Status indicates whether a suitable image is available for download:

    • OTA_STATUS_SUCCESS: A suitable image is available

    • OTA_STATUS_NO_IMAGE_AVAILABLE: No suitable image is available

      • The other elements of the structure are only included in the case of success.

Parent topic:Structures

tsOTA_BlockRequest

The following structure contains payload data for an Image Block Request issued by a client to request an image data block from the server:

typedef struct
{
    uint64 u64RequestNodeAddress;
    uint32 u32FileOffset;
    uint32 u32FileVersion;
    uint16 u16ImageType;
    uint16 u16ManufactureCode;
    uint16 u16BlockRequestDelay;
    uint8 u8MaxDataSize;
    uint8 u8FieldControl;
}tsOTA_BlockRequest;

where:

  • u64RequestNodeAddress is the IEEE/MAC address of the client device from which the request originates (this information is optional - see u8FieldControl below)

  • u32FileOffset specifies the offset from the beginning of the upgrade image, in bytes, of the requested data block (this value is therefore determined by the amount of image data previously received)

  • u32FileVersion is the file version of the upgrade image for which a data block is being requested

  • u16ImageType is a value in the range 0x0000-0xFFBF which identifies the type of image for which a data block is being requested

  • u16ManufactureCode is the ZigBee-assigned number identifying the manufacturer of the client device from which the request originates

  • u16BlockRequestDelay is used in ‘rate limiting’ to specify the value of the ‘block request delay’ attribute for the client - this is minimum time, in milliseconds, that the client must wait between consecutive block requests (the client will update the local attribute with this value). If the server does not support rate limiting or does not need to limit the download rate to the client, this field will be set to 0

  • u8MaxDataSize specifies the maximum size, in bytes, of the data block that the client can receive in one transfer (the server must therefore not send a data block that is larger than indicated by this value)

  • u8FieldControl is a bitmap indicating whether certain optional information about the client is included in this Image Block Request message. Currently, this optional information consists only of the IEEE/MAC address of the client (contained in 64RequestNodeAddress above) - bit 0 is set to ‘1’ if this address is included or to ‘0’ otherwise (all other bits are reserved)

Parent topic:Structures

tsOTA_ImagePageRequest

The following structure contains payload data for an Image Page Request issued by a client to request a page of image data (multiple blocks) from the server:

typedef struct
{
    uint64 u64RequestNodeAddress;
    uint32 u32FileOffset;
    uint32 u32FileVersion;
    uint16 u16PageSize;
    uint16 u16ResponseSpacing;
    uint16 u16ImageType;
    uint16 u16ManufactureCode;
    uint8 u8MaxDataSize;
    uint8 u8FieldControl;
}tsOTA_ImagePageRequest;

where:

  • u64RequestNodeAddress is the IEEE/MAC address of the client device from which the request originates (this information is optional - see u8FieldControl below)

  • u32FileOffset specifies the offset from the beginning of the upgrade image, in bytes, of the first data block of the requested page (this value is therefore determined by the amount of image data previously received)

  • u32FileVersion is the file version of the upgrade image for which data is being requested

  • u16PageSize is the total number of data bytes (in the page) to be returned by the server before the next Image Page Request can be issued (this must be larger than the value of u8MaxDataSize below)

  • u16ResponseSpacing specifies the time-interval, in milliseconds, that the server should introduce between consecutive transmissions of Image Block Responses (which is sent in response to the Image Page Request)

  • u16ImageType is a value in the range 0x0000-0xFFBF which identifies the type of image for which data is being requested

  • u16ManufactureCode is the ZigBee-assigned number identifying the manufacturer of the client device from which the request originates

  • u8MaxDataSize specifies the maximum size, in bytes, of the data block that the client can receive in one transfer (the server must therefore not send a data block in an Image Block Response that is larger than indicated by this value)

  • u8FieldControl is a bitmap indicating whether certain optional information about the client is included in this Image Page Request message. Currently, this optional information consists only of the IEEE/MAC address of the client (contained in 64RequestNodeAddress above) - bit 0 is set to ‘1’ if this address is included or to ‘0’ otherwise (all other bits are reserved)

Parent topic:Structures

tsOTA_ImageBlockResponsePayload

The following structure contains payload data for an Image Block Response issued by the server (as the result of an Image Block Request from a client):

typedef struct
{
            uint8 u8Status;
            union
            {
                         tsOTA_WaitForData                   sWaitForData;
         tsOTA_SuccessBlockResponsePayload   sBlockPayloadSuccess;
            }uMessage;
}tsOTA_ImageBlockResponsePayload;

where:

  • u8Status indicates whether a data block is included in the response:

    • OTA_STATUS_SUCCESS: A data block is included

    • OTA_STATUS_WAIT_FOR_DATA: No data block is included - client should re-request a data block after a waiting time

  • The element used from the union depends on the status reported above:

    • sWaitForData is a structure containing information used to instruct the requesting client to wait for a time before requesting the data block again or requesting the next data block (see Section 49.11.15) - this information is only provided in the case of the status OTA_STATUS_WAIT_FOR_DATA

    • sBlockPayloadSuccess is a structure containing a requested data block and associated information (see Section 49.11.13) - this data is only provided in the case of the status OTA_STATUS_SUCCESS

Parent topic:Structures

tsOTA_UpgradeEndRequestPayload

The following structure contains payload data for an Upgrade End Request issued by a client to terminate/close an image download from the server:

typedef struct
{
    uint32 u32FileVersion;
    uint16 u16ImageType;
    uint16 u16ManufacturerCode;
            uint8  u8Status;
}tsOTA_UpgradeEndRequestPayload;

where:

  • u32FileVersion is the file version of the upgrade image which has been downloaded

  • u16ImageType is the type of the upgrade image which has been downloaded

  • u16ManufacturerCode is the ZigBee-assigned number identifying the manufacturer of the client device from which the request originates

  • u8Status is the reported status of the image download, one of:

    • OTA_STATUS_SUCCESS (successfully downloaded and verified)

    • OTA_STATUS_INVALID_IMAGE (downloaded but failed verification)

    • OTA_REQUIRE_MORE_IMAGE (other images needed)

    • OTA_STATUS_ABORT (download in progress is to be aborted)

Parent topic:Structures

tsOTA_UpgradeEndResponsePayload

The following structure contains payload data for an Upgrade End Response issued by the server (as the result of an Upgrade End Request from a client):

typedef struct
{
    uint32 u32UpgradeTime;
    uint32 u32CurrentTime;
    uint32 u32FileVersion;
    uint16 u16ImageType;
    uint16 u16ManufacturerCode;
}tsOTA_UpgradeEndResponsePayload;

where:

  • u32UpgradeTime is the UTC time, in seconds, at which the client should upgrade the running image with the downloaded image. If the server does not support UTC time (indicated by a zero value for u32CurrentTime), the client should interpret this value as a time delay before performing the image upgrade

  • u32CurrentTime is the current UTC time, in seconds, on the server. If UTC time is not supported by the server, this value should be set to zero. If this value is set to 0xFFFFFFFF, this indicates that the client should wait for an upgrade command from the server before performing the image upgrade

Note: If the client does not support UTC time but both of the above time values are non-zero, the client will take the difference between the two times as a time delay before performing the image upgrade.

  • u32FileVersion is the file version of the downloaded application image (a wild card value of 0xFFFFFFFF can be used when the same response is sent to client devices from different manufacturers)

  • u16ImageType is the type of the downloaded application image (a wild card value of 0xFFFF can be used when the same response is sent to client devices from different manufacturers)

  • u16ManufacturerCode is the manufacturer code that was received from the client in the Upgrade End Request message (a wild card value of 0xFFFF can be used when the same response is sent to client devices from different manufacturers)

Parent topic:Structures

tsOTA_SuccessBlockResponsePayload

The following structure contains payload data for an Image Block Response which reports ‘success’ and therefore contains a block of image data (see Section 49.11.10):

typedef struct
{
    uint8* pu8Data;
            uint32 u32FileOffset;
            uint32 u32FileVersion;
            uint16 u16ImageType;
            uint16 u16ManufacturerCode;
    uint8  u8DataSize;
}tsOTA_SuccessBlockResponsePayload;

where:

  • pu8Data is a pointer to the start of the data block being transferred

  • u32FileOffset is the offset, in bytes, of the start of the data block from the start of the image (normally, the same offset as specified in the Image Block Request)

  • u32FileVersion is the file version of the upgrade image to which the included data block belongs

  • u16ImageType is the type of the upgrade image to which the included data block belongs

  • u16ManufacturerCode is the manufacturer code that was received from the client in the Image Block Request

  • u8DataSize is the length, in bytes, of the included data block (this must be less than or equal to the maximum data block length for the client, specified in the Image Block Request)

Parent topic:Structures

tsOTA_BlockResponseEvent

The following structure contains payload data for an Image Block Response containing data other than upgrade image data.

typedef struct
{
    uint8    u8Status;
    uint8   *pu8Data;
    uint8    u8DataSize;
}tsOTA_BlockResponseEvent;

where:

  • u8Status indicates whether a suitable upgrade image is available:

    • OTA_STATUS_SUCCESS: A suitable image is available

    • OTA_STATUS_NO_IMAGE_AVAILABLE: No suitable image is available

  • pu8Data is a pointer to the start of the data block being transferred

  • u8DataSize is the length, in bytes, of the included data block (this must be less than or equal to the maximum data block length for the client, specified in the Image Block Request)

Parent topic:Structures

tsOTA_WaitForData

The following structure contains time information for an Image Block Response. It can be used by a response which reports ‘failure’, to instruct the client to re-request the data block after a certain waiting time (see Section 49.11.10). It can also be used in ‘rate limiting’ to specify a new value for the ‘block request delay’ attribute on the client.

typedef struct
{
    uint32 u32CurrentTime;
    uint32 u32RequestTime;
    uint16 u16BlockRequestDelayMs;
}tsOTA_WaitForData;

where:

  • u32CurrentTime is the current UTC time, in seconds, on the server. If UTC time is not supported by the server, this value should be set to zero

  • u32RequestTime is the UTC time, in seconds, at which the client should re-issue an Image Block Request. If the server does not support UTC time (indicated by a zero value for u32CurrentTime), the client should interpret this value as a time delay before re-issuing an Image Block Request

Note: If the client does not support UTC time but both of the above values are non-zero, the client will take the difference between the two times as a time delay before re-issuing an Image Block Request.

  • u16BlockRequestDelayMs is used in ‘rate limiting’ to specify the value of the ‘block request delay’ attribute for the client - this is minimum time, in milliseconds, that the client must wait between consecutive block requests (the client will update the local attribute with this value). If the server does not support rate limiting or does not need to limit the download rate to the client, this field must be set to 0

Parent topic:Structures

tsOTA_WaitForDataParams

The following structure is used in the tsOTA_CallBackMessage structure (see Section 49.11.21) on an OTA Upgrade server. It contains the data needed to notify a client that rate limiting is required or the client must wait to receive an upgrade image.

typedef struct
{
   bool_t             bInitialized;
   uint16             u16ClientAddress;
   tsOTA_WaitForData  sWaitForDataPyld;
}tsOTA_WaitForDataParams;

where:

  • bInitialized is a boolean flag indicating the server’s request to the client:

    • TRUE - Implement rate limiting or wait to receive upgrade image

    • FALSE - Otherwise

  • u16ClientAddress contains the 16-bit network address of the client

  • sWaitForDataPyld is a structure containing the payload for an Image Block Response with status OTA_STATUS_WAIT_FOR_DATA (see Section49.11.15)

Parent topic:Structures

tsOTA_PageReqServerParams

The following structure is used in the tsOTA_CallBackMessage structure (see Section 49.11.21) on an OTA Upgrade server. It contains the data from an Image Page Request received from a client.

typedef struct
{
    uint8                      u8TransactionNumber;
    bool_t                     bPageReqRespSpacing;
    uint16                     u16DataSent;
    tsOTA_ImagePageRequest     sPageReq;
    tsZCL_ReceiveEventAddress  sReceiveEventAddress;
}tsOTA_PageReqServerParams;

where:

  • u8TransactionNumber is the Transaction Sequence Number (TSN) which is used in the Image Page Request

  • bPageReqRespSpacing is a boolean used to request a spacing between consecutive Image Block Responses:

    • TRUE - Implement spacing

    • FALSE - Otherwise

  • u16DataSent indicates the number of data bytes contained in the Image Page Request

  • sPageReq is a structure containing the payload data from the Image Page Request (see Section 49.11.9)

  • sReceiveEventAddress contains the address of the OTA Upgrade client that made the page request

Parent topic:Structures

tsOTA_PersistedData

The following structure contains the persisted data that is stored in Flash memory using the NVM module:

typedef struct
{
    tsCLD_AS_Ota sAttributes;
    uint32 u32FunctionPointer;
    uint32 u32RequestBlockRequestTime;
    uint32 u32CurrentFlashOffset;
    uint32 u32TagDataWritten;
    uint32 u32Step;
    uint16 u16ServerShortAddress;
#ifdef OTA_CLD_ATTR_REQUEST_DELAY
    bool_t bWaitForBlockReq;
#endif
    uint8 u8ActiveTag[OTA_TAG_HEADER_SIZE];
    uint8 u8PassiveTag[OTA_TAG_HEADER_SIZE];
    uint8 au8Header[OTA_MAX_HEADER_SIZE];
    uint8 u8Retry;
    uint8 u8RequestTransSeqNo;
    uint8 u8DstEndpoint;
    bool_t bIsCoProcessorImage;
    bool_t bIsSpecificFile;
    bool_t bIsNullImage;
    uint8  u8CoProcessorOTAHeaderIndex;
    uint32 u32CoProcessorImageSize;
    uint32 u32SpecificFileSize;
#ifdef OTA_PAGE_REQUEST_SUPPORT
    tsOTA_PageReqParams sPageReqParams;
#endif
#if (OTA_MAX_CO_PROCESSOR_IMAGES != 0)
    uint8 u8NumOfDownloadableImages;
#endif
#ifdef OTA_INTERNAL_STORAGE
    uint8 u8Buf[4];
#endif
}tsOTA_PersistedData;

The fields are for internal use and no knowledge of them is required.

Parent topic:Structures

tsOTA_QuerySpecificFileRequestPayload

The following structure contains the payload for a Query Specific File Request which is issued by an OTA Upgrade client to request a device-specific file from the server.

typedef struct
{
    uint64 u64RequestNodeAddress;
    uint16 u16ManufacturerCode;
    uint16 u16ImageType;
    uint32 u32FileVersion;
    uint16 u16CurrentZibgeeStackVersion;
}tsOTA_QuerySpecificFileRequestPayload;

where:

  • u64RequestNodeAddress is the IEEE/MAC address of the node requesting the device-specific file from the server

  • u16ManufactuerCode is the ZigBee-assigned manufacturer code of the requesting node (0xFFFF is used to indicate any manufacturer)

  • u16ImageType indicates the requested file type - one of the reserved values that are assigned to the device-specific file types (the value should be in the range 0xFFC0 to 0xFFFE, but only 0xFFC0 to 0xFFC2 are currently in use)

  • 32FileVersion contains the release and build numbers of the application and stack that correspond to the device-specific file - for details of the format, refer to the ZigBee Over-the-Air Upgrading Cluster Specification (095264)

  • u16CurrentZ``ig``beeStackVersion contains the version of ZigBee stack that is currently running on the client

Parent topic:Structures

tsOTA_QuerySpecificFileResponsePayload

The following structure contains the payload for a Query Specific File Response which is issued by an OTA Upgrade server in response to a request for a device-specific file.

typedef struct
{
    uint32 u32FileVersion;
    uint32 u32ImageSize;
    uint16 u16ImageType;
    uint16 u16ManufacturerCode;
    uint8 u8Status;
}tsOTA_QuerySpecificFileResponsePayload;

where:

  • 32FileVersion contains the release and build numbers of the application and stack that correspond to the device-specific file - this field will take the same value as the equivalent field in the corresponding Query Specific File Request (see Section 49.11.19)

  • u32ImageSize is the size of the requested file, in bytes

  • u16ImageType indicates the requested file type - this field will take the same value as the equivalent field in the corresponding Query Specific File Request (see Section 49.11.19)

  • u16ManufactuerCode is the ZigBee-assigned manufacturer code of the requesting node - this field will take the same value as the equivalent field in the corresponding Query Specific File Request (see Section 49.11.19)

  • u8Status indicates whether a suitable file is available for download:

    • OTA_STATUS_SUCCESS: A suitable file is available

    • OTA_STATUS_NO_IMAGE_AVAILABLE: No suitable file is available

      • The other elements of the structure are only included in the case of success.

Parent topic:Structures

tsOTA_CallBackMessage

For an OTA event, the eEventType field of the tsZCL_CallBackEvent structure is set to E_ZCL_CBET_CLUSTER_CUSTOM. This event structure also contains an element sClusterCustomMessage, which is itself a structure containing a field pvCustomData. This field is a pointer to the following tsOTA_CallBackMessage structure:

typedef struct
{
    teOTA_UpgradeClusterEvents     eEventId;
#ifdef OTA_CLIENT
    tsOTA_PersistedData sPersistedData;
    uint8 au8ReadOTAData[OTA_MAX_BLOCK_SIZE];
    uint8 u8NextFreeImageLocation;
    uint8 u8CurrentActiveImageLocation;
#endif
#ifdef OTA_SERVER
    tsCLD_PR_Ota aServerPrams[OTA_MAX_IMAGES_PER_ENDPOINT+OTA_MAX_CO_PROCESSOR_IMAGES];
    tsOTA_AuthorisationStruct               sAuthStruct;
    uint8  u8ServerImageStartSector;
    bool bIsOTAHeaderCopied;
    uint8 au8ServerOTAHeader[OTA_MAX_HEADER_SIZE+OTA_TAG_HEADER_SIZE];
    tsOTA_WaitForDataParams  sWaitForDataParams;
#ifdef OTA_PAGE_REQUEST_SUPPORT
    tsOTA_PageReqServerParams  sPageReqServerParams;
#endif
#endif
    uint8  u8ImageStartSector[OTA_MAX_IMAGES_PER_ENDPOINT];
    uint8 au8CAPublicKey[22];
    uint8 u8MaxNumberOfSectors;
    union
    {
        tsOTA_ImageNotifyCommand              sImageNotifyPayload;
        tsOTA_QueryImageRequest               sQueryImagePayload;
        tsOTA_QueryImageResponse              sQueryImageResponsePayload;
        tsOTA_BlockRequest                    sBlockRequestPayload;
        tsOTA_ImagePageRequest                sImagePageRequestPayload;
        tsOTA_ImageBlockResponsePayload       sImageBlockResponsePayload;
        tsOTA_UpgradeEndRequestPayload        sUpgradeEndRequestPayload;
        tsOTA_UpgradeEndResponsePayload       sUpgradeResponsePayload;
        tsOTA_QuerySpecificFileRequestPayload sQuerySpFileRequestPayload;
        tsOTA_QuerySpecificFileResponsePayload
                sQuerySpFileResponsePayload;
        teZCL_Status                          eQueryNextImgRspErrStatus;
        tsOTA_SignerMacVerify                 sSignerMacVerify;
        tsOTA_ImageVersionVerify              sImageVersionVerify;
        tsOTA_UpgradeDowngradeVerify          sUpgradeDowngradeVerify;
    }uMessage;
}tsOTA_CallBackMessage;

where:

  • eEventId is the OTA event type (enumerations are detailed in Section49.12.2)

  • sPersistedData is the structure (see Section 49.11.18) which contains the persisted data that is stored in Flash memory using the NVM module on the client

  • au8ReadOTAData is an array containing the payload data from an Image Block Response

  • u8NextFreeImageLocation identifies the next free image location where a new upgrade image can be stored

  • u8CurrentActiveImageLocation identifies the location of the currently active image on the client

  • aServerPrams is an array containing the server data for each image which can be updated by application

  • sAuthStruct is a structure which stores the authorisation state and list of client devices that are authorised for OTA upgrade

  • u8ServerImageStartSector identifies the server self-image start-sector

  • bIsOTAHeaderCopied specifies whether the new OTA header is copied (TRUE) or not (FALSE)

  • au8ServerOTAHeader specifies the current server OTA header

  • sWaitForDataParams is a structure containing time information that may need to be modified by the server for inclusion in an Image Block Response (for more information, refer to Section 49.11.15)

  • sPageReqServerParams is a structure containing page request information that may need to be modified by the server

  • u8ImageStartSector is used to store the image start-sector for each image which is stored or will be stored in the devices internal Flash memory - note that this variable assumes a 32-Kbyte sector size and so, for example, if

    64-Kbyte sectors are used, its value will be twice the actual start-sector value

  • au8CAPublicKey specifies the CA public key

  • u8MaxNumberOfSectors specifies the maximum number of sectors to be used per image

  • uMessage is a union containing the command payload in one of the following forms (depending on the command specified by eEventId):

    • sImageNotifyPayload is a structure containing the payload of an Image Notify command

    • sQueryImagePayload is a structure containing the payload of a Query Next Image Request

    • sQueryImageResponsePayload is a structure containing the payload of a Query Next Image Response

    • sBlockRequestPayload is a structure containing the payload of an Image Block Request

    • sImagePageRequestPayload is a structure containing the payload of an Image Page Request

    • sImageBlockResponsePayload is a structure containing the payload of an Image Block Response

    • sUpgradeEndRequestPayload is a structure containing the payload of an Upgrade End Request

    • sUpgradeResponsePayload is a structure containing the payload of an Upgrade End Response

    • sQuerySpFileRequestPayload is a structure containing the payload of a Query Specific File Request

    • sQuerySpFileResponsePayload is a structure containing the payload of a Query Specific File Response

    • eQueryNextImgRspErrStatus is the status returned from the query image response command handler and can be passed up to the application when there is an error via the callback event E_CLD_OTA_COMMAND_QUERY_NEXT_IMAGE_RESPONSE_

      ERROR. The returned status value will be either E_ZCL_ERR_INVALID_IMAGE_SIZE or E_ZCL_ERR_INVALID_IMAGE_VERSION

    • sSignerMacVerify is a structure containing the signer’s IEEE/MAC address from a new upgrade image and a status field (which is set by the application after verifying the signer’s address)

    • sImageVersionVerify is a structure containing the image version received in the query next image response and status field (which is set by the application after verifying the image version)

    • sUpgradeDowngradeVerify is a structure containing the image version received in the upgrade end response and a status field (which is set by the application after verifying the image version)

Parent topic:Structures

tsCLD_PR_Ota

The following structure contains server parameter data that can be pre-set using the function eOTA_SetServerParams() and obtained using eOTA_GetServerData():

typedef struct
{
    uint8* pu8Data;
    uint32 u32CurrentTime;
    uint32 u32RequestOrUpgradeTime;
    uint8  u8QueryJitter;
    uint8  u8DataSize;
} tsCLD_PR_Ota;

where:

  • pu8Data is a pointer to the start of a block of data

  • u32CurrentTime is the current UTC time, in seconds, on the server. If UTC time is not supported by the server, this value should be set to zero

  • u32RequestOrUpgradeTime is used by the server as the ‘request time’ and the ‘upgrade time’ when sending responses to clients:

  • u8QueryJitteris a value between 1 and 100 (inclusive) which is used by a receiving client to decide whether to reply to an Image Notify message - for information on ‘Query Jitter’, refer to Section 49.7

  • u8DataSize is the length, in bytes, of the data block pointed to by pu8Data

Parent topic:Structures

tsCLD_AS_Ota

This structure contains attribute values which are stored as part of the persisted data in Flash memory:

typedef struct
{
    uint64 u64UgradeServerID;
    uint32 u32FileOffset;
    uint32 u32CurrentFileVersion;
    uint16 u16CurrentStackVersion;
    uint32 u32DownloadedFileVersion;
    uint16 u16DownloadedStackVersion;
    uint8  u8ImageUpgradeStatus;
    uint16 u16ManfId;
    uint16 u16ImageType;
    uint16 u16MinBlockRequestDelay;
} tsCLD_AS_Ota;
where the structure elements are OTA Upgrade cluster attribute values, as described in [Section 49.3](ota_upgrade_cluster_structure_and_attributes.md#id_accc84e1-e4af-4078-b61f-af69b4b4314c).

Parent topic:Structures

tsOTA_ImageVersionVerify

The following structure contains the data for an event of the type E_CLD_OTA_INTERNAL_COMMAND_VERIFY_IMAGE_VERSION.

typedef struct
{
    uint32 u32NotifiedImageVersion;
    uint32 u32CurrentImageVersion;
    teZCL_Status eImageVersionVerifyStatus;
}tsOTA_ImageVersionVerify;

where:

  • u32NotifiedImageVersion is the version received in the query next image response

  • u32CurrentImageVersion is the version of the running image

  • eImageVersionVerifyStatus is a status field which should be updated to E_ZCL_SUCCESS or E_ZCL_FAIL by the application after checking the received image version, to indicate whether the upgrade image has a valid image version

Parent topic:Structures

tsOTA_UpgradeDowngradeVerify

The following structure contains the data for an event of the type E_CLD_OTA_INTERNAL_COMMAND_SWITCH_TO_UPGRADE_DOWNGRADE.

typedef struct
{
    uint32 u32DownloadImageVersion;
    uint32 u32CurrentImageVersion;
    teZCL_Status eUpgradeDowngradeStatus;
}tsOTA_UpgradeDowngradeVerify;

where:

  • u32DownloadImageVersion is the version received in upgrade end response

  • u32CurrentImageVersion is the version of running image

  • eImageVersionVerifyStatus is a status field which should be updated to E_ZCL_SUCCESS or E_ZCL_FAIL by the application after checking the received image version, to indicate whether the upgrade image has a valid image version

Parent topic:Structures

Parent topic:OTA Upgrade cluster