Functions

The following Price cluster functions are provided:

• eSE_PriceCreate

• eSE_PriceGetCurrentPriceSend

• eSE_PriceGetScheduledPricesSend

• eSE_PriceAddPriceEntry

• eSE_PriceAddPriceEntryToClient

• eSE_PriceGetPriceEntry

• eSE_PriceDoesPriceEntryExist

• eSE_PriceRemovePriceEntry

• eSE_PriceClearAllPriceEntries

• eSE_PriceAddConversionFactorEntry

• eSE_PriceGetConversionFactorSend

• eSE_PriceGetConversionFactorEntry

• eSE_PriceDoesConversionFactorEntryExist

• eSE_PriceRemoveConversionFactorEntry

• eSE_PriceClearAllConversionFactorEntries

• eSE_PriceAddCalorificValueEntry

• eSE_PriceGetCalorificValueSend

• eSE_PriceGetCalorificValueEntry

• eSE_PriceDoesCalorificValueEntryExist

• eSE_PriceRemoveCalorificValueEntry

• eSE_PriceClearAllCalorificValueEntries

eSE_PriceCreate

teSE_PriceStatus eSE_PriceCreate(
        bool_t bIsServer,
        uint8 u8NumberOfRecordEntries,
        uint8 *pu8AttributeControlBits,
        uint8 *pau8RateLabel,
        tsZCL_ClusterInstance *psClusterInstance,
        tsZCL_ClusterDefinition *psClusterDefinition,
        tsSE_PriceCustomDataStructure
        *psCustomDataStructure,
        tsSE_PricePublishPriceRecord
        *psPublishPriceRecord,
        void *pvEndPointSharedStructPtr);

Description

This function creates an instance of the Price cluster on an endpoint. The cluster instance is created on the endpoint which is associated with the supplied tsZCL_ClusterInstance structure and can act as a server or a client, as specified.

The function should only be called when setting up a custom endpoint containing one or more selected clusters (rather than the whole set of clusters supported by a standard ZigBee device). This function will create a Price cluster instance on the endpoint, but instances of other clusters may also be created on the same endpoint by calling their corresponding creation functions. For more details of creating cluster instances on custom endpoints, refer to Appendix D.

Note: This function must not be called for an endpoint on which a standard ZigBee device (e.g. IPD) will be used. In this case, the device and its supported clusters must be registered on the endpoint using the relevant device registration function from those described in the ZigBee Devices User Guide (JNUG3131)

When used, this function must be the first Price cluster function called in the application, and must be called after the stack has been started and after the ZCL has been initialized.

The function requires an array to be declared for internal use, which contains one element (of type uint8) for each attribute of the cluster. The array length should therefore equate be the total number of attributes supported by the Price cluster, which can be obtained by using the macro PRICE_NUM_OF_ATTRIBUTES.

The array declaration should be as follows:

uint8 au8AppPriceClusterAttributeControlBits[PRICE_NUM_OF_ATTRIBUTES];

The function initializes the array elements to zero.

The function also requires an array of price labels to be declared, in which each array element is a label (string) for each price in the price list. The required declarations are different for a cluster server and client, as follows:

uint8 au8RateLabel[SE_PRICE_NUMBER_OF_CLIENT_PRICE_RECORD_ENTRIES][SE_PRICE_CLIENT_MAX_STRING_LENGTH];
uint8 au8RateLabel[SE_PRICE_NUMBER_OF_CLIENT_PRICE_RECORD_ENTRIES][SE_PRICE_CLIENT_MAX_STRING_LENGTH];

Parameters

• bIsServer Type of cluster instance (server or client) to be created:

• TRUE - server

• FALSE - client

• u8NumberOfRecordEntries Number of prices that can be stored in the price list, one of:

• SE_PRICE_NUMBER_OF_SERVER_PRICE_RECORD_ENTRIES

• SE_PRICE_NUMBER_OF_CLIENT_PRICE_RECORD_ENTRIES

• pu8AttributeControlBits Pointer to an array of uint8 values, with one element for each attribute in the cluster (see above).

• pau8RateLabel Pointer to an array of price labels (strings), with one element for each price in the price list (see above).

• psClusterInstance Pointer to structure containing information about the cluster instance to be created (see Section 6.1.16). This structure is updated by the function by initialising individual structure fields.

• psClusterDefinition Pointer to structure indicating the type of cluster to be created (see Section 6.1.2). In this case, this structure must contain the details of the Price cluster. This parameter can refer to a pre-filled structure called sCLD_Price which is provided in the Price.h file.

• psCustomDataStructure Pointer to structure which contains custom data for the Price cluster. This structure is used for internal data storage. No knowledge of the fields of this structure is required

• pvEndPointSharedStructPtr Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_Price which defines the attributes of Price cluster. The function initializes the attributes with default values.

Returns

• E_ZCL_SUCCESS

• E_ZCL_FAIL

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eSE_PriceGetCurrentPriceSend

teZCL_Status eSE_PriceGetCurrentPriceSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    teSE_PriceCommandOptions ePriceCommandOptions);

Description

This function can be used on a Price cluster client to send a Get Current Price command to the Price cluster server. Therefore, it is used by a device (such as an IPD) to obtain the currently active price from the ESP.

The ESP should respond with a Publish Price command containing the active price. This response is processed by the Price cluster. The obtained price is checked against the prices currently in the price list on the client. If the price is not currently in the list, it is added to the list and an E_SE_PRICE_TABLE_ADD event is generated to indicate that a price has been added.

A pointer must be specified 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.

Parameters

• u8SourceEndPointId Number of the local endpoint through which the request is sent

• u8DestinationEndPointId Number of the remote endpoint to which the request is sent

• psDestinationAddress Pointer to a structure containing the address of the remote node to which the request is sent

• pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request

• ePriceCommandOptions Indicates whether the radio receiver on client remains on when the device is idle (for example, asleep):

  • 0x01 - receiver on when idle

  • 0x00 - receiver off when idle

• An enumeration is provided for the ‘on’ case:

• E_SE_PRICE_REQUESTOR_RX_ON_IDLE

Returns

• E_ZCL_SUCCESS

• E_ZCL_FAIL

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_EP_RANGE

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_ZCL_ERR_ZBUFFER_FAIL

Parent topic:Functions

eSE_PriceGetScheduledPricesSend

teZCL_Status eSE_PriceGetScheduledPricesSend(
        uint8 u8SourceEndPointId,
        uint8 u8DestinationEndPointId,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        uint32 u32StartTime,
        int8 u8NumberOfEvents);

Description

This function can be used on a Price cluster client to send a Get Scheduled Prices command to the Price cluster server. Therefore, it is used by a device (such as an IPD) to obtain the current price schedule from the ESP, either to check that its own price schedule is up-to-date or to recover the price schedule following a device reset.

You must specify the earliest start-time for the scheduled prices to be included in the results. This is normally set to zero or the current time (UTC). Note that you are not advised to specify the last time in the client price list, since the server may contain updates for prices covering an earlier time-period that are already in the client price list. You must also specify the maximum number of scheduled prices to be returned in the results.

The ESP should respond with multiple Publish Price commands containing the scheduled prices. Each response is processed by the Price cluster. The obtained price is checked against the prices currently in the price list on the client. If the price is not currently in the list, it is added to the list and an E_SE_PRICE_TABLE_ADD event is generated to indicate that a price has been added.

A pointer must be specified 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.

Parameters

• u8SourceEndPointId Number of the local endpoint through which the request is sent

• u8DestinationEndPointId Number of the remote endpoint to which the request is sent

• psDestinationAddress Pointer to a structure containing the address of the remote node to which the request is sent

• pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request

• u32StartTime The earliest start-time of any prices to be returned - this is normally set to zero or the current time (UTC)

• u8NumberOfEvents The maximum number of scheduled prices to be returned in the results - this should normally be set to: SE_PRICE_NUMBER_OF_CLIENT_PRICE_RECORD_ENTRIES

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_ZBUFFER_FAIL

Parent topic:Functions

eSE_PriceAddPriceEntry

teSE_PriceStatus eSE_PriceAddPriceEntry(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    bool_t bOverwritePrevious,
    tsSE_PricePublishPriceCmdPayload *psPricePayload,
    uint8 *pu8TransactionSequenceNumber);

Description

This function can be used on the Price cluster server to add a price to the local price list. The function also sends an unsolicited Publish Price command containing the new price information to one or more remote endpoints. The function should be called on the ESP when a new price is received from the utility company.

On receiving the Publish Price command, a remote client will automatically add the new price to the local price list. However, you must specify the action to be taken if the time-period of the new price overlaps with the time-period of a price that is already in the client’s price list. You can choose to delete the existing price and add the new price, or leave the existing price in place and not add the new price. The rules on overlapping prices are defined in the ZigBee Smart Energy Profile specification.

A pointer must be specified 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.

Parameters

• u8SourceEndPointId Number of the local endpoint through which the request is sent

• u8DestinationEndPointId Number of the remote endpoint to which the request is sent

• psDestinationAddress Pointer to a structure containing the address of the remote node to which the Publish Price command is sent. It is recommended that the command is sent to all bound clients using a ZCL address mode of E_ZCL_AM_BOUND. If the stack has not been started, the E_ZCL_AM_NO_TRANSMIT address mode should be used

• bOverwritePrevious Action to be taken if the new price overlaps (in time) a price which is already in the price list:

  • TRUE - existing price deleted, new price added

  • FALSE - new price not added and error returned

• psPricePayload Pointer to a structure containing the price information to be added (see Section 40.11.1). This parameter only needs to remain in scope for the duration of this function call

• pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the command

Returns

• E_ZCL_SUCCESS

• E_ZCL_FAIL

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_INVALID_VALUE

• E_ZCL_ERR_TIME_NOT_SYNCHRONISED

• E_ZCL_ERR_INSUFFICIENT_SPACE

• E_ZCL_ERR_EP_RANGE

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_ZCL_ERR_ZBUFFER_FAIL

• E_SE_PRICE_OVERFLOW

• E_SE_PRICE_DUPLICATE

• E_SE_PRICE_DATA_OLD

Parent topic:Functions

eSE_PriceAddPriceEntryToClient

teSE_PriceStatus eSE_PriceAddPriceEntryToClient(
    uint8 u8SourceEndPointId,
    bool_t bOverwritePrevious,
    tsSE_PricePublishPriceCmdPayload *psPricePayload);
    

Description

This function can be used on a Price cluster client to add a price to the local price list directly.

Normally, price entries are automatically added to the price list on a client when a Publish Price command is received from the server (e.g. the ESP). However, this function can be used by the local application to directly add a price entry to the price list on the client. The function should therefore only be used on a device which does not receive price information from the server (but by some other means, such as via the Internet).

Parameters

• u8SourceEndPointId Number of the local endpoint through which the request is sent

• bOverwritePrevious Action to be taken if the new price overlaps (in time) a price which is already in the price list:

  • TRUE - existing price deleted, new price added

  • FALSE - new price not added and error returned

• psPricePayload Pointer to a structure containing the price information to be added (see Section 40.11.1). This parameter only needs to remain in scope for the duration of this function call

Returns

• E_ZCL_SUCCESS

• E_ZCL_FAIL

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_INVALID_VALUE

• E_ZCL_ERR_TIME_NOT_SYNCHRONISED

• E_ZCL_ERR_INSUFFICIENT_SPACE

• E_ZCL_ERR_EP_RANGE

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_ZCL_ERR_ZBUFFER_FAIL

• E_SE_PRICE_OVERFLOW

• E_SE_PRICE_DUPLICATE

• E_SE_PRICE_DATA_OLD

Parent topic:Functions

eSE_PriceGetPriceEntry

teSE_PriceStatus eSE_PriceGetPriceEntry(
    uint8 u8SourceEndPointId,
    bool_t bIsServer,
    uint8 u8TableIndex,
    tsSE_PricePublishPriceCmdPayload **psPricePayload);

Description

This function can be used to obtain the entry with specified index from a price list on the local device. For example, the function can be used on an IPD to obtain a price to display.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

Parameters

• u8SourceEndPointId Number of the local endpoint for the price list to be accessed

• bIsServer Nature of the Price cluster instance containing the price list:

  • TRUE - server (for example, on ESP)

  • FALSE - client (for example, on IPD)

• u8TableIndex The index of the price entry to obtain from the price list (index 0 is the entry with the oldest start-time and may contain the currently active price)

• psPricePayload Pointer to a pointer to a structure which will be used to store the obtained price information (see Section 40.11.1), if found. The pointer value that is returned in this parameter points to the structure in the internal storage associated with the list. The data in the structure will be valid as long as the item remains in the list

Returns

• E_ZCL_SUCCESS

• E_ZCL_FAIL

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_SE_PRICE_TABLE_NOT_FOUND

Parent topic:Functions

eSE_PriceDoesPriceEntryExist

teSE_PriceStatus eSE_PriceDoesPriceEntryExist(
    uint8 u8SourceEndPointId,
    bool_t bIsServer,
    uint32 u32StartTime);

Description

This function can be used to check whether a price entry with the specified start-time is present in a price list on the local device.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

For a price entry to be successfully found, the specified start-time must exactly match the start-time of an entry in the price list, otherwise the status code E_SE_PRICE_NOT_FOUND will be returned.

Parameters

• u8SourceEndPointId Number of the local endpoint for the price list to be accessed

• bIsServer Nature of the Price cluster instance containing the price list:

  • TRUE - server

  • FALSE - client

• u32StartTime Start-time of the price entry to search for

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_SE_PRICE_NOT_FOUND

Parent topic:Functions

eSE_PriceRemovePriceEntry

teSE_PriceStatus eSE_PriceRemovePriceEntry(
    uint8 u8SourceEndPointId,
    bool_t bIsServer,
    uint32 u32StartTime);

Description

This function can be used to delete a price entry with specified start-time from a price list on the local device.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

For the successful deletion of a price entry, the specified start-time must exactly match the start-time of an entry in the price list, otherwise the status code E_SE_PRICE_NOT_FOUND will be returned.

Parameters

• u8SourceEndPointId Number of the local endpoint on which Price cluster resides

• bIsServer Nature of the Price cluster instance containing the price list:

  • TRUE - server

  • FALSE - client

• u32StartTime The start-time of the price entry to delete

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_SE_PRICE_NOT_FOUND

• E_SE_PRICE_TABLE_NOT_FOUND

Parent topic:Functions

eSE_PriceClearAllPriceEntries

teSE_PriceStatus eSE_PriceClearAllPriceEntries(
    uint8 u8SourceEndPointId,
    bool_t bIsServer);

Description

This function can be used to delete all entries in a price list on the local device.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

Parameters

• u8SourceEndPointId Number of the local endpoint for the price list to be cleared

• bIsServer Nature of the Price cluster instance containing the price list:

  • TRUE - server

  • FALSE - client

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_CLUSTER_NOT_FOUND

Parent topic:Functions

eSE_PriceAddConversionFactorEntry

teZCL_Status eSE_PriceAddConversionFactorEntry(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    bool_t bOverwritePrevious,
    tsSE_PricePublishConversionCmdPayload
    *psPublishConversionCmdPayload,
    uint8 *pu8TransactionSequenceNumber);

Description

The function can be used on a Price cluster server to add a new conversion factor entry to the internal list of scheduled conversion factors maintained by the cluster. The function also sends an unsolicited Publish Conversion Factor command to the Price cluster client nodes in the network, to advertise the new conversion factor. Therefore, the function should be called on the ESP when a new conversion factor is received from the utility company.

On receiving the Publish Conversion Factor command, a remote client automatically adds the new conversion factor to the local conversion factor list. However, if the new entry has the same start-time as an existing entry in the list, the outcome depends on the setting of the boolean parameter bOverwritePrevious in this function:

• If this parameter is set to TRUE then the existing entry is removed and the new entry is added

• If this parameter is set to FALSE then the Issuer Event IDs of the two conversion factor entries are compared:

  • If the Event ID of the new entry is the greater, the existing entry is removed and the new entry is added

  • If the Event ID of the existing entry is the greater, E_ZCL_FAIL is returned and the list is not modified

A pointer must be specified 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.

Parameters

• u8SourceEndPointId Number of the local endpoint through which the request is sent

• u8DestinationEndPointId Number of the remote endpoint to which the request is sent

• psDestinationAddress Pointer to a structure containing the address of the remote node to which the request is sent

• bOverwritePrevious Determines whether an existing conversion factor with the same start-time on the clients will be over-written without comparing Event IDs (see above):

  • TRUE - over-write existing entry

  • FALSE - compare Event IDs first

• psPublishConversionCmdPayload Pointer to conversion factor entry to be added to list on server and advertised to clients

• pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_TIME_NOT_SYNCHRONISED

Parent topic:Functions

eSE_PriceGetConversionFactorSend

teZCL_Status eSE_PriceGetConversionFactorSend(
        uint8 u8SourceEndPointId,
        uint8 u8DestinationEndPointId,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        uint32 u32StartTime,
        uint8 u8NumberOfEvents);

Description

The function can be used on a Price cluster client to send a Get Conversion Factor request to the Price cluster server. Therefore, it is used by a device (such as an IPD) to obtain scheduled conversion factor values from the ESP. The function allows scheduled conversion factors to be obtained with start-times greater than or equal to a specified time, u32StartTime.

The ESP should respond with a Publish Conversion Factor command containing up to u8NumberOfEvent scheduled conversion factor values. The Price cluster on the receiving client processes the response by updating the local conversion factor list, as follows. For each conversion factor received in the response, the event E_SE_PRICE_CONVERSION_FACTOR_ADD is generated.

A pointer must be specified 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.

Parameters

• u8SourceEndPointId Number of the local endpoint through which the request is sent

• u8DestinationEndPointId Number of the remote endpoint to which the request is sent

• psDestinationAddress Pointer to a structure containing the address of the remote node to which the request is sent

• pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request

• u32StartTime Earliest start-time of scheduled conversion factors to be returned - a setting of 0 returns the factor that is currently active and factors with start-times in the future

• u8NumberOfEvents Maximum number of conversion factors to be returned as a result of this request

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_EP_UNKNOWN

• E_ZCL_ERR_ZBUFFER_FAIL

• E_ZCL_ERR_EP_RANGE

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_ZCL_ERR_ZTRANSMIT_FAIL

Parent topic:Functions

eSE_PriceGetConversionFactorEntry

teSE_PriceStatus eSE_PriceGetConversionFactorEntry(
    uint8 u8SourceEndPointId,
    bool_t bIsServer,
    uint8 u8TableIndex,
    sSE_PricePublishConversionCmdPayload
    **ppsPublishConversionCmdPayload);

Description

This function can be used to obtain the entry with the specified index from the conversion factor list on the local device. For example, the function can be used on an IPD to obtain a conversion factor to display.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

Parameters

• u8SourceEndPointId: Number of the local endpoint for the conversion factor list to be accessed

• bIsServer: Nature of the Price cluster instance containing the list:

  • TRUE - server (example on ESP)

  • FALSE - client (example on IPD)

• u8TableIndex: The index of the entry to obtain from the conversion factor list (index 0 is the entry with the oldest start-time and may contain the currently active conversion factor)

• ppsPublishConversionCmdPayload: Pointer to a pointer to a structure which will be used to store the obtained conversion factor information (see Section40.11.2), if found. The pointer value that is returned in this parameter points to the structure in the internal storage associated with the list. The data in the structure will be valid as long as the item remains in the list

Returns

• E_ZCL_SUCCESS

• E_ZCL_FAIL

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_SE_PRICE_TABLE_NOT_FOUND

Parent topic:Functions

eSE_PriceDoesConversionFactorEntryExist

teSE_PriceStatus eSE_PriceDoesConversionFactorEntryExist(
    uint8 u8SourceEndPointId,
    bool_t bIsServer,
    uint32 u32StartTime);

Description

This function can be used to check whether a conversion factor entry with the specified start-time is present in a conversion factor list on the local device.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

For a conversion factor entry to be successfully found, the specified start-time must exactly match the start-time of an entry in the conversion factor list, otherwise the status code E_SE_PRICE_NOT_FOUND will be returned.

Parameters

• u8SourceEndPointId Number of the local endpoint for the conversion factor list to be accessed

• bIsServer Nature of the Price cluster instance containing the price list:

• TRUE - server

• FALSE - client

• u32StartTime Start-time of the conversion factor entry to search for

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_SE_PRICE_NOT_FOUND

Parent topic:Functions

eSE_PriceRemoveConversionFactorEntry

teSE_PriceStatus eSE_PriceRemoveConversionFactorEntry(
    uint8 u8SourceEndPointId,
    bool_t bIsServer,
    uint32 u32StartTime);

Description

This function can be used to delete a conversion factor entry with specified start-time from conversion factor list on the local device.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

For the successful deletion of a conversion factor entry, the specified start-time must exactly match the start-time of an entry in the conversion factor list, otherwise the status code E_SE_PRICE_NOT_FOUND is returned.

Parameters

• u8SourceEndPointId Number of the local endpoint for the conversion factor list to be accessed

• bIsServer Nature of the Price cluster instance containing the list:

  • TRUE - server

  • FALSE - client

• u32StartTime The start-time of the conversion factor entry to delete

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_SE_PRICE_NOT_FOUND

• E_SE_PRICE_TABLE_NOT_FOUND

Parent topic:Functions

eSE_PriceClearAllConversionFactorEntries

teSE_PriceStatus eSE_PriceClearAllConversionFactorEntries(
    uint8 u8SourceEndPointId,
    bool_t bIsServer);

Description

This function can be used to delete all entries in a conversion factor list on the local device.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

Parameters

• u8SourceEndPointId Number of the local endpoint for the conversion factor list to be cleared

• bIsServer Nature of the Price cluster instance containing the price list:

• TRUE - server

• FALSE - client

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_CLUSTER_NOT_FOUND

Parent topic:Functions

eSE_PriceAddCalorificValueEntry

teZCL_Status eSE_PriceAddCalorificValueEntry(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    bool_t bOverwritePrevious,
    tsSE_PricePublishCalorificValueCmdPayload
    *psPublishCalorificValueCmdPayload,
    uint8 *pu8TransactionSequenceNumber);

Description

The function can be used on a Price cluster server to add a calorific value entry to the internal list of scheduled calorific values maintained by the cluster. The function also sends an unsolicited Publish Calorific Value command to the Price cluster client nodes in the network, to advertise the new calorific value. Therefore, the function should be called on the ESP when a new calorific value is received from the utility company.

On receiving the Publish Calorific Value command, a remote client automatically adds the new calorific value to the local calorific value list. However, if the new entry has the same start-time as an existing entry in the list, the outcome depends on the setting of the boolean parameter bOverwritePrevious in this function:

• If this parameter is set to TRUE then the existing entry is removed and the new entry is added

• If this parameter is set to FALSE then the Issuer Event IDs of the two calorific value entries are compared:

  • If the Event ID of the new entry is the greater, the existing entry is removed and the new entry is added

  • If the Event ID of the existing entry is the greater, E_ZCL_FAIL is returned and the list is not modified

A pointer must be specified 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.

Parameters

• u8SourceEndPointId: Number of the local endpoint through which the request is sent

• u8DestinationEndPointId: Number of the remote endpoint to which the request is sent

• psDestinationAddress: Pointer to a structure containing the address of the remote node to which the request is sent

• bOverwritePrevious: Determines whether an existing calorific value with the same start-time on the clients will be over-written without comparing Event IDs (see above):

  • TRUE - over-write existing entry

  • FALSE - compare Event IDs first

• psPublishCalorificValueCmdPayload Pointer to calorific value entry to be added to list on server and advertised to clients

• pu8TransactionSequenceNumber Pointer to a location to store the Transaction Sequence Number (TSN) of the request

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_TIME_NOT_SYNCHRONISED

Parent topic:Functions

eSE_PriceGetCalorificValueSend

teZCL_Status eSE_PriceGetCalorificValueSend(
        uint8 u8SourceEndPointId,
        uint8 u8DestinationEndPointId,
        tsZCL_Address *psDestinationAddress,
        uint8 *pu8TransactionSequenceNumber,
        uint32 u32StartTime,
        uint8 u8NumberOfEvents);

Description

The function can be used on a Price cluster client to send a Get Calorific Value request to the Price cluster server. Therefore, it is used by a device (such as an IPD) to obtain scheduled calorific values from the ESP. The function allows scheduled calorific values to be obtained with start-times greater than or equal to a specified time, u32StartTime.

The ESP should respond with a Publish Calorific Value command containing up to u8NumberOfEvent scheduled calorific values. The Price cluster on the receiving client processes the response by updating the local calorific value list, as follows. For each calorific value received in the response, the event E_SE_PRICE_CALORIFIC_VALUE_ADD is generated.

A pointer must be specified 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.

Parameters

• u8SourceEndPointId: Number of the local endpoint through which the request is sent

• u8DestinationEndPointId: Number of the remote endpoint to which the request is sent

• psDestinationAddress: Pointer to a structure containing the address of the remote node to which the request is sent

• pu8TransactionSequenceNumber: Pointer to a location to store the Transaction Sequence Number (TSN) of the request

• u32StartTime: Earliest start-time of scheduled calorific values to be returned - a setting of 0 returns the value that is currently active and values with start-times in the future

• u8NumberOfEvents: Maximum number of calorific values to be returned as a result of this request

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_EP_UNKNOWN

• E_ZCL_ERR_ZBUFFER_FAIL

• E_ZCL_ERR_EP_RANGE

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_ZCL_ERR_ZTRANSMIT_FAIL

Parent topic:Functions

eSE_PriceGetCalorificValueEntry

teSE_PriceStatus eSE_PriceGetCalorificValueEntry(
    uint8 u8SourceEndPointId,
    bool_t bIsServer,
    uint8 u8TableIndex,
    sSE_PricePublishCalorificValueCmdPayload
    **ppsPublishCalorificValueCmdPayload);

Description

This function can be used to obtain the entry with the specified index from the calorific value list on the local device. For example, the function can be used on an IPD to obtain a calorific value to display.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

Parameters

• u8SourceEndPointId Number of the local endpoint for the calorific value list to be accessed

• bIsServer Nature of the Price cluster instance containing the list:

  • TRUE - server (example on ESP)

  • FALSE - client (example on IPD)

• u8TableIndex The index of the entry to obtain from the calorific value list (index 0 is the entry with the oldest start-time and may contain the currently active calorific value)

• **ppsPublishCalorificValueCmdPayload: Pointer to a pointer to a structure which will be used to store the obtained calorific value information (see Section 40.11.3), if found. The pointer value that is returned in this parameter points to the structure in the internal storage associated with the list. The data in the structure will be valid as long as the item remains in the list

Returns

• E_ZCL_SUCCESS

• E_ZCL_FAIL

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_SE_PRICE_TABLE_NOT_FOUND

Parent topic:Functions

eSE_PriceDoesCalorificValueEntryExist

teSE_PriceStatus eSE_PriceDoesCalorificValueEntryExist(
    uint8 u8SourceEndPointId,
    bool_t bIsServer,
    uint32 u32StartTime);

Description

This function can be used to check whether a calorific value entry with the specified start-time is present in a calorific value list on the local device.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

For a calorific value entry to be successfully found, the specified start-time must exactly match the start-time of an entry in the calorific value list, otherwise the status code E_SE_PRICE_NOT_FOUND will be returned.

Parameters

• u8SourceEndPointId Number of the local endpoint for the calorific value list to be accessed

• bIsServer Nature of the Price cluster instance containing the price list:

  • TRUE - server

  • FALSE - client

• u32StartTime Start-time of the calorific value entry to search for

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_SE_PRICE_NOT_FOUND

Parent topic:Functions

eSE_PriceRemoveCalorificValueEntry

teSE_PriceStatus eSE_PriceRemoveCalorificValueEntry(
    uint8 u8SourceEndPointId,
    bool_t bIsServer,
    uint32 u32StartTime);

Description

This function can be used to delete a calorific value entry with specified start-time from calorific value list on the local device.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

For the successful deletion of a calorific value entry, the specified start-time must exactly match the start-time of an entry in the calorific value list, otherwise the status code E_SE_PRICE_NOT_FOUND will be returned.

Parameters

• u8SourceEndPointId Number of the local endpoint for the calorific value list to be accessed

• bIsServer Nature of the Price cluster instance containing the list:

• TRUE - server

• FALSE - client

• u32StartTime Start-time of the calorific value entry to delete

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_CLUSTER_NOT_FOUND

• E_SE_PRICE_NOT_FOUND

• E_SE_PRICE_TABLE_NOT_FOUND

Parent topic:Functions

eSE_PriceClearAllCalorificValueEntries

teSE_PriceStatus eSE_PriceClearAllCalorificValueEntries(
    uint8 u8SourceEndPointId,
    bool_t bIsServer);

Description

This function can be used to delete all entries in a calorific value list on the local device.

You must specify the endpoint on which the local Price cluster resides and whether this cluster instance is a server or a client.

Parameters

• u8SourceEndPointId Number of the local endpoint for the calorific value list to be cleared

• bIsServer Nature of the Price cluster instance containing the price list:

  • TRUE - server

  • FALSE - client

Returns

• E_ZCL_SUCCESS

• E_ZCL_ERR_CLUSTER_NOT_FOUND

Parent topic:Functions

Parent topic:Price Cluster