General Functions

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

  1. eOTA_Create

  2. vOTA_FlashInit

  3. eOTA_AllocateEndpointOTASpace

  4. vOTA_GenerateHash

  5. eOTA_GetCurrentOtaHeader

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