Functions

The following Simple Metering cluster functions are provided:

eSE_SMCreate

teZCL_Status eSE_SMCreate(
    uint8 u8Endpoint,
    bool_t bIsServer,
    uint8 *pu8AttributeControlBits,
    tsZCL_ClusterInstance *psClusterInstance,
    tsZCL_ClusterDefinition *psClusterDefinition,
    tsSM_CustomStruct *psCustomDataStruct,
    void *pvEndPointSharedStructPtr);

Description

This function creates an instance of the Simple Metering 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 Simple Metering 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 (for example, an IPD) is 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 Simple Metering 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 Simple Metering cluster, which can be obtained by using the macro SM_NUM_OF_ATTRIBUTES.

The array declaration should be as follows:

uint8 au8AppSMClusterAttributeControlBits[SM_NUM_OF_ATTRIBUTES];

The function initializes the array elements to zero.

Parameters

u8Endpoint: Number of local endpoint on which the cluster instance is to be created, in the range 1 to 240.
bIsServer : Type of cluster instance (server or client) to be created:
: TRUE - server
: FALSE - client
pu8AttributeControlBits: Pointer to an array of uint8 values, with one element for each attribute in the cluster (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 Simple Metering cluster. This parameter can refer to a pre-filled structure called sCLD_SimpleMetering which is provided in the SimpleMetering.h file.
psCustomDataStructure: Pointer to structure which contains custom data for the Simple Metering cluster. This structure is used for internal data storage and also contains data relating to a received command/message. 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_SimpleMetering which defines the attributes of Simple Metering cluster. The function will initialize 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_ReadMeterAttributes

teZCL_Status eSE_ReadMeterAttributes(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber);

Description

This function can be used to send a ‘read attributes’ request to the Simple Metering cluster on a remote endpoint. The function requests all Simple Metering attributes to be read - alternatively, the function eZCL_SendReadAttributesRequest() can be used if only specific attributes are required. Note that read access to cluster attributes on the remote node (server) and local node (client) must be enabled at compile-time, as described in Section 1.3.

You must specify the endpoint on the local node from which the request is to be sent. This is also used to identify the instance of the local shared device structure which holds the relevant attributes. The obtained attribute values are written to this shared structure by the function.

You must also specify the address of the destination node and the destination endpoint number. It is possible to use this function to send a request to bound endpoints or to a group of endpoints on remote nodes - in the latter case, a group address must be specified. Note that when sending requests to multiple endpoints through a single call to this function, multiple responses will subsequently be received from the remote endpoints.

You are also required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request. The TSN in the response is set to match the TSN in the request, allowing an incoming response to be paired with a request. This is useful when sending more than one request to the same destination endpoint.

Following the first response to this function call, your application should call the function eSE_HandleReadAttributesResponse() to ensure that all the Simple Metering attributes are received from the remote endpoint.

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. Note that this parameter is ignored when sending to address types E_ZCL_AM_BOUND and E_ZCL_AM_GROUP
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

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_CLUSTER_ID_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_ATTRIBUTE_WO
E_ZCL_ERR_ATTRIBUTES_ACCESS
E_ZCL_ERR_ATTRIBUTE_NOT_FOUND
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_PARAMETER_RANGE

Parent topic:Functions

eSE_HandleReadMeterAttributesResponse

teSE_Status eSE_HandleReadAttributesResponse(
    tsZCL_CallBackEvent *psEvent,
    uint8 *puTransactionSequenceNumber);

Description

This function should be called after eSE_ReadMeterAttributes(). The function examines the response to a ‘read attributes’ request for the Simple Metering cluster and determines whether the response is complete - that is, whether it contains all the Simple Metering attributes (the response may be incomplete if the returned data is too large to fit into a single APDU). If the response is not complete, the function will re-send ‘read attributes’ requests until all attribute values have been obtained. Any further attribute values obtained are written to the local shared device structure containing the attributes.

This function call should normally be included in the user-defined callback function that is invoked when the event E_ZCL_CBET_READ_ATTRIBUTES_RESPONSE is generated. This is the callback function which is specified when the (requesting) endpoint is registered using the appropriate endpoint registration function. The callback function must pass the generated event into eSE_HandleReadAttributesResponse().

You are also required to provide a pointer to a location to receive a Transaction Sequence Number (TSN) for the request/response.

Parameters

psEvent: Pointer to the generated event E_ZCL_CBET_READ_ATTRIBUTES_RESPONSE
pu8TransactionSequenceNumber: Pointer to a location to store the Transaction Sequence Number (TSN) of the request/response

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_CLUSTER_ID_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_EP_RANGE
E_ZCL_ERR_ATTRIBUTE_WO
E_ZCL_ERR_ATTRIBUTES_ACCESS
E_ZCL_ERR_ATTRIBUTE_NOT_FOUND
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_PARAMETER_RANGE

Parent topic:Functions

eSM_ServerRequestMirrorCommand

teZCL_Status eSM_ServerRequestMirrorCommand(
    uint8 u8SourceEndpoint,
    uint8 u8DestinationEndpoint,
    tsZCL_Address *psDestinationAddress);

Description

This function can be used by a Metering Device to request a mirror on the ESP, for the central storage of its metering data. A mirror is useful for a Metering Device which sleeps, in order to allow access to its metering data while the device is sleeping.

The function sends an ‘Add Mirror’ request to the ESP. The address of the ESP device must be specified as well as the endpoint that will receive and process the request - this is the main endpoint on which the ESP is registered on the Co-ordinator. If successful, the request will result in the allocation of a mirror endpoint (on the ESP) to the Metering Device.

Note: Before using this function to send an ‘Add Mirror’ request, the Metering Device application should check whether the ESP is currently accepting these requests by calling the function eZCL_SendReadAttributesRequest() to obtain the value of the u8PhysicalEnvironment attribute of the Basic cluster on the ESP. This attribute value will be non-zero if ‘Add Mirror’ requests are being accepted.

eSM_ServerRequestMirrorCommand() is a non-blocking function and so returns immediately after the request has been sent. The application must then wait for a response, indicated by the event E_CLD_SM_SERVER_RECEIVED_COMMAND containing the command E_CLD_SM_REQUEST_MIRROR_RESPONSE. If a mirror was successfully created, the number of the allocated mirror endpoint on the ESP is included in the event.

Mirroring and mirror set-up are fully described in Section 42.5.

Parameters

u8SourceEndpoint: Number of local endpoint through which request is sent
u8DestinationEndpoint: Number of ESP endpoint to which request is sent (main endpoint of ESP)
psDestinationAddress: Pointer to a structure containing the address of the ESP device (to which the request is sent)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_ZTRANSMIT_FAIL
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_CLUSTER_ID_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_EP_RANGE

Parent topic:Functions

eSM_ServerRemoveMirrorCommand

teZCL_Status eSM_ServerRemoveMirrorCommand(
    uint8 u8SourceEndpoint,
    uint8 u8DestinationEndpoint,
    tsZCL_Address *psDestinationAddress);

Description

This function can be used on a Metering Device to request the removal of the corresponding mirror on the ESP. The function should only be used to remove a mirror that has been previously set up by the Metering Device application using the function eSM_ServerRequestMirrorCommand().

The function sends a ‘Remove Mirror’ request to the ESP. The address of the ESP must be specified as well as the endpoint number of the mirror to be removed.

This is a non-blocking function and so returns immediately after the request has been sent. The application must then wait for a response.

If the request was successful, a response will be received from the ESP resulting in the generation of the event E_CLD_SM_SERVER_RECEIVED_COMMAND containing the command E_CLD_SM_MIRROR_REMOVED
If the request was unsuccessful, a ZCL default response will be received from the ESP to indicate that the request was not authorised (E_ZCL_CMDS_NOT_AUTHORIZED)

Mirror removal is fully described in Section 42.5.5.

Parameters

u8SourceEndpoint: Number of local endpoint through which request is sent
u8DestinationEndpoint: Number of ESP endpoint which contains the mirror to be removed
psDestinationAddress: Pointer to a structure containing the address of the ESP device (to which the request is sent)

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_ZTRANSMIT_FAIL
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_CLUSTER_ID_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_EP_RANGE

Parent topic:Functions

eSM_CreateMirror

teSM_Status eSM_CreateMirror(
    uint8 u8MirrorEndpoint,
    uint64 u64RemoteIeeeAddress);

Description

This function can be used on the mirroring server (ESP) to create a mirror with the specified endpoint number for the Metering Device with the specified IEEE address. The endpoint number must be within the valid range for mirror endpoints on the ESP.

An error will be returned if there is no free mirror endpoint on which to create a mirror.

The function is normally used by an ESP application following a device reset, in order to recreate mirrors that were lost during the reset. This recovery assumes that the relevant IEEE addresses (for Metering Devices) associated with the mirror endpoints can be retrieved from non-volatile memory, where they were saved before the reset.

Parameters

u8MirrorEndpoint: Number of endpoint on which mirror will be created (must be within valid range for mirror endpoints)
u64RemoteIeeeAddress: IEEE address of Metering Device to be mirrored

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_RANGE
E_CLD_SM_STATUS_EP_NOT_AVAILABLE

Parent topic:Functions

eSM_RemoveMirror

teSM_Status eSM_RemoveMirror(
    uint8 u8MirrorEndpoint,
    uint64 u64RemoteIeeeAddress);

Description

This function can be used on the mirroring server (ESP) to remove the mirror with the specified endpoint number for the Metering Device with the specified IEEE address. The endpoint will then become free to be re-allocated for another mirror.

An error will be returned if the specified mirror endpoint cannot be found.

Parameters

u8MirrorEndpoint: Number of endpoint which hosts mirror to be removed (must be within valid range for mirror endpoints)
u64RemoteIeeeAddress: : IEEE address of mirrored Metering Device

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_PARAMETER_RANGE
E_CLD_SM_STATUS_EP_NOT_AVAILABLE
E_ZCL_FAIL

Parent topic:Functions

eSM_GetFreeMirrorEndPoint

teZCL_Status eSM_GetFreeMirrorEndPoint(
    uint16 *pu16FreeEP);

Description

This function can be used on the mirroring server (ESP) to obtain the number of the next available mirror endpoint. If there are no free mirror endpoints, the function sets the returned endpoint number to 0xFFFF.

The function is normally used in the ESP callback function to check the availability of mirror endpoints before updating the u8PhysicalEnvironment attribute of the Basic cluster (this attribute is set to zero if no more mirror endpoints are available).

Use of this function is described in Section 42.5.1.

Parameters

pu16FreeEP: Pointer to location to receive next free endpoint number

Returns

E_ZCL_SUCCESS

Parent topic:Functions

eSM_IsMirrorSourceAddressValid

eSM_IsMirrorSourceAddressValid(
tsZCL_ReportAttributeMirror *psZCL_ReportAttributeMirror);

Description

This function can be used on the ESP to handle mirroring data reported from a Metering Device. If mirroring is enabled, the function should be included in the callback function on the ESP.

When the ESP receives mirroring data from a Metering Device, the event E_ZCL_CBET_ATTRIBUTE_REPORT_MIRROR is generated, causing the callback function to be invoked. The callback function should call this function to deal with the event.

The function first checks that the data comes from a Metering Device which has a mirror on the ESP (the source IEEE address of the data is used for this check) and then updates the event status accordingly:

sZCL_CallBackEvent.uMessage.sReportAttributeMirror.eStatus

If the source device is valid then this status is set to E_ZCL_ATTR_REPORT_OK and the metering data is automatically stored on the relevant mirror endpoint. Otherwise, a ZCL default response is returned to the Metering Device to indicate that mirroring is not authorised for this device (E_ZCL_CMDS_NOT_AUTHORIZED).

The mirroring of metering data is fully described in Section 42.5.3.

Parameters

psZCL_ReportAttributeMirror: Pointer to sReportAttributeMirror element of the event

Returns

E_ZCL_SUCCESS

Parent topic:Functions

eSM_ServerUpdateConsumption

teZCL_Status eSM_ServerUpdateConsumption(
    uint8 u8SourceEndPointId,
    uint32 u32UtcTime);

Description

This function can be used on a Simple Metering cluster server (with the ‘Get Profile’ feature enabled) to add a new entry to the circular buffer used to store historical consumption data. The buffer stores a sequence of entries containing consumption data for consecutive time intervals, identified by their end-times.

Before this function is called, the application must update one or both of the following Simple Metering cluster attributes with the relevant consumption(s) over the last time interval (since the last readings were made):

u24CurrentPartialProfileIntervalValueDelivered
u24CurrentPartialProfileIntervalValueReceived

An attribute only needs to be updated if the corresponding consumption has been implemented.

The function takes the current time (UTC time) as an input and adds a buffer entry containing the consumption measurements together with the supplied UTC time, which is saved as the end-time of the interval

The entry is stored as a tsSEGetProfile structure, described in Section 42.11.5.

The buffer can contain a limited number of entries, determined at compile-time (see Section 42.12), and operates on a FIFO basis so that a new entry added to a full buffer will over-write the oldest entry.

The function should be called periodically by the application. The period must match the value to which the Simple Metering eProfileIntervalPeriod attribute has been set (see Section 42.2). Standard periods, ranging from 2.5 minutes to one day, are provided as a set of enumerations (see Section 42.10.10).

Parameters

u8SourceEndPointId: Number of local endpoint on which the Simple Metering cluster server operates
u32UtcTime: Current time (as UTC time which can be obtained using u32ZCL_GetUTCTime())

Returns

E_ZCL_SUCCESS

Parent topic:Functions

eSM_ClientGetProfileCommand

teZCL_Status eSM_ClientGetProfileCommand(
    uint8 u8SourceEndpoint,
    uint8 u8DestinationEndpoint,
    tsZCL_Address *psDestinationAddress,
    uint8 u8IntervalChannel,
    uint32 u32EndTime,
    uint8 u8NumberOfPeriods);

Description

This function can be used on a Simple Metering cluster client (with the ‘Get Profile’ feature enabled) to send a ‘Get Profile’ request to the Simple Metering cluster server in order to retrieve historical consumption data.

The server contains a circular buffer which stores a sequence of data entries containing consumption data for consecutive time intervals, identified by their end-times. This function can request a number of entries from the buffer, containing the consumption data over multiple intervals.

The function parameters include:

The number of buffer entries (corresponding to consumption intervals) requested
The most recent end-time for which a buffer entry will be reported - the most recent consumption data will be reported which has an end-time equal to or earlier than this end-time (a specified end-time of zero will result in the most recent consumption data)
A value indicating whether the units delivered or units received are being requested

This is a non-blocking function and so returns immediately after the request has been sent. The application must then wait for a response, which is accessed using the function u32SM_GetReceivedProfileData().

Parameters

u8SourceEndpoint: Number of local endpoint through which request is sent
u8DestinationEndpoint: Number of endpoint to which request is sent on the destination device
psDestinationAddress: : Pointer to a structure containing the address of the destination device
u8IntervalChannel: Required consumption data - received or delivered:
E_CLD_SM_CONSUMPTION_RECEIVED
E_CLD_SM_CONSUMPTION_DELIVERED
u32EndTime: A UTC time representing the most recent interval end-time for which data will be reported (a zero value means report data for the most recent interval)
u8NumberOfPeriods: Number of consumption intervals to be reported

Returns

E_ZCL_SUCCESS
E_ZCL_ERR_ZTRANSMIT_FAIL
E_ZCL_ERR_CLUSTER_NOT_FOUND
E_ZCL_ERR_CLUSTER_ID_RANGE
E_ZCL_ERR_EP_UNKNOWN
E_ZCL_ERR_EP_RANGE

Parent topic:Functions

u32SM_GetReceivedProfileData

uint32 u32SM_GetReceivedProfileData(
    tsSM_GetProfileResponseCommand
    *psSMGetProfileResponseCommand);

Description

This function is used on a Simple Metering cluster client to obtain the consumption data received in a ‘Get Profile’ response. The response is obtained from the Simple Metering cluster server (and previously requested by the client through a call to eSM_ClientGetProfileCommand()).

When a ‘Get Profile’ response from the server arrives, the event E_CLD_SM_CLIENT_RECEIVED_COMMAND containing the command E_CLD_SM_GET_PROFILE_RESPONSE is generated on the client. This response causes the callback function on the device to be invoked (for an IPD, this is the callback function registered through eSE_RegisterIPDEndPoint()). The callback function should deal with the response.

This function can be called within the callback function to extract consumption data from the event. It is necessary to provide the function with a pointer to the response within the event. The function returns the data corresponding to one consumption interval on each call. Therefore, if the response contains data for multiple intervals, the function must be called multiple times to extract all of this data. The number of intervals contained in the response is also included in the response:

sSMCallBackMessage.uMessage.sGetProfileResponseCommand.u8NumberOfPeriodsDelivered 

When there is no more data to be extracted from the event, the function returns 0xFFFFFFFF.

Parameters

psSMGetProfileResponseCommand: Pointer to sGetProfileResponseCommand element of the event

Returns

32-bit value corresponding to consumption data for one interval

0xFFFFFFFF indicates that there is no more data to be read from the event.

Parent topic:Functions

Parent topic:Simple Metering Cluster