Functions

The following IAS Zone cluster functions are provided in the NXP implementation of the ZCL:

  1. eCLD_IASZoneCreateIASZone

  2. eCLD_IASZoneUpdateZoneStatus

  3. eCLD_IASZoneUpdateZoneState

  4. eCLD_IASZoneUpdateZoneType

  5. eCLD_IASZoneUpdateZoneID

  6. eCLD_IASZoneUpdateCIEAddress

  7. eCLD_IASZoneEnrollReqSend

  8. eCLD_IASZoneEnrollRespSend

  9. eCLD_IASZoneStatusChangeNotificationSend

  10. eCLD_IASZoneNormalOperationModeReqSend

  11. eCLD_IASZoneTestModeReqSend

eCLD_IASZoneCreateIASZone

teZCL_Status eCLD_IASZoneCreateIASZone(
    tsZCL_ClusterInstance *psClusterInstance,
    bool_t bIsServer,
    tsZCL_ClusterDefinition *psClusterDefinition,
    void *pvEndPointSharedStructPtr,
    uint8 *pu8AttributeControlBits,
    tsCLD_IASZone_CustomDataStructure *psCustomDataStructure);

Description

This function creates an instance of the IAS Zone 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 an IAS Zone cluster instance on the endpoint, but instances of other clusters may also be created on the same endpoint by calling their corresponding creation functions.

Note: This function must not be called for an endpoint on which a standard ZigBee device is used. In this case, the device and its supported clusters must be registered on the endpoint using the relevant device registration function.

When used, this function 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). This structure is updated by the function by initializing individual structure fields.

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

  • 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 IAS Zone cluster. This parameter can refer to a pre-filled structure called sCLD_``IASZone which is provided in the IASZone.h file.

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

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

  • psCustomDataStructure: Pointer to a structure containing the storage for internal functions of the cluster (see Section 37.6.1)

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eCLD_IASZoneUpdateZoneStatus

teZCL_Status eCLD_IASZoneUpdateZoneStatus(
    uint8 u8SourceEndPoint,
    uint16 u16StatusBitMask,
    bool_t bStatusState);

Description

This function can be used on an IAS Zone cluster server to update the zone status bitmap stored in the b16ZoneStatus attribute, described in Section 37.2.

In one call to this function, one or more selected bits in the b16ZoneStatus attribute bitmap can be to set to ‘1’ or ‘0’. The affected bits must themselves be specified in a bitmap and the value to be set must also be specified.

If the server is enrolled with a client on a CIE device, the function sends a notification of this update to the client, in a Zone Status Change Notification. Before sending the notification and returning, the function invokes a user-defined callback function to allow the application to validate the status change.

Parameters

  • u8SourceEndPointId: Number of the endpoint on which the IAS Zone cluster resides

  • u16StatusBitMask: 16-bit bitmap indicating the bits of the zb16ZoneStatus bitmap to be updated. There is a one-to-one correspondence between the bits of the two bitmaps and a bit should be set to ‘1’ if the corresponding attribute bit is to be updated. Enumerations are provided (which can be logical-ORed):

Bits

Enumeration

0

CLD_IASZONE_STATUS_MASK_ALARM1

1

CLD_IASZONE_STATUS_MASK_ALARM2

2

CLD_IASZONE_STATUS_MASK_TAMPER

3

CLD_IASZONE_STATUS_MASK_BATTERY

4

CLD_IASZONE_STATUS_MASK_SUPERVISION_REPORTS

5

CLD_IASZONE_STATUS_MASK_RESTORE_REPORTS

6

CLD_IASZONE_STATUS_MASK_TROUBLE

7

CLD_IASZONE_STATUS_MASK_AC_MAINS

8

CLD_IASZONE_STATUS_MASK_TEST

9

CLD_IASZONE_STATUS_MASK_BATTERY_DEFECT

10-15

Reserved

  • bStatusState: Boolean indicating the value to which the attribute bits to be updated must be set - enumerations are provided:

    • CLD_IASZONE_STATUS_MASK_SET (1)

    • CLD_IASZONE_STATUS_MASK_RESET (0)

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

Parent topic:Functions

eCLD_IASZoneUpdateZoneState

teZCL_Status eCLD_IASZoneUpdateZoneState(
    uint8 u8SourceEndPoint,
    teCLD_IASZoneState eZoneState);

Description

This function can be used on an IAS Zone cluster server to update the zone state value stored in the e8ZoneState attribute, described in Section 37.2. This attribute indicates whether or not the server is enrolled with a client on a CIE device. The function checks that the specified state is valid.

Parameters

  • u8SourceEndPointId: Number of the endpoint on which the IAS Zone cluster resides

  • eZoneState: Zone state value to be written to the attribute, one of:

    • E_CLD_IASZONE_STATE_NOT_ENROLLED (0x00)

    • E_CLD_IASZONE_STATE_ENROLLED (0x01)

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

Parent topic:Functions

eCLD_IASZoneUpdateZoneType

teZCL_Status eCLD_IASZoneUpdateZoneType(
    uint8 u8SourceEndPoint,
    teCLD_IASZoneType eIASZoneType);

Description

This function can be used on an IAS Zone cluster server to update the zone type value stored in the e16ZoneType attribute. The possible values are listed in Section 37.2 and the function checks that the specified type is one of these values.

Parameters

  • u8SourceEndPointId: Number of the endpoint on which the IAS Zone cluster resides eIASZoneType: Zone type value to be written to the attribute (for the possible values, refer to Section 37.2)

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

Parent topic:Functions

eCLD_IASZoneUpdateZoneID

teZCL_Status eCLD_IASZoneUpdateZoneID(
    uint8 u8SourceEndPoint,
    uint8 u8IASZoneId);

Description

This function can be used on an IAS Zone cluster server to update the zone ID value stored in the u8ZoneId attribute. This is an 8-bit user-defined identifier.

Parameters

  • u8SourceEndPointId: Number of the endpoint on which the IAS Zone cluster resides

  • u8IASZoneId: Zone ID value to be written to the attribute

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

Parent topic:Functions

eCLD_IASZoneUpdateCIEAddress

teZCL_Status eCLD_IASZoneUpdateCIEAddress(
    uint8 u8SourceEndPoint,
    u64IEEEAddress u64CIEAddress);

Description

This function can be used on an IAS Zone cluster server to update the 64-bit IEEE/MAC address stored in the u64IASCIEAddress attribute. This is the address of the CIE device to which the local device should send commands and notifications.

Parameters

  • u8SourceEndPointId: Number of the endpoint on which the IAS Zone cluster resides

  • u64CIEAddress: IEEE/MAC address to be written to the attribute

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_FAIL

Parent topic:Functions

eCLD_IASZoneEnrollReqSend

teZCL_Status eCLD_IASZoneEnrollReqSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_IASZone_EnrollRequestPayload *psPayload);

Description

This function can be used on an IAS Zone cluster server to send an IAS Zone Enroll Request to an IAS Zone client.

You are 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.

Parameters

  • u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the command and to identify the instance of the shared structure holding the required attribute values

  • u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP

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

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

  • psPayload: Pointer to a structure containing the payload for the command (see Section 37.6.2)

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_IASZoneEnrollRespSend

teZCL_Status eCLD_IASZoneEnrollRespSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_IASZone_EnrollResponsePayload *psPayload);

Description

This function can be used on an IAS Zone cluster client to send an IAS Zone Enroll Response to the IAS Zone server.

You are 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.

Parameters

  • u8SourceEndPointId        Number of the local endpoint through which to send the request. This parameter is used both to send the command and to identify the instance of the shared structure holding the required attribute values

  • u8DestinationEndPointId        Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP

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

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

  • psPayload        Pointer to a structure containing the payload for the command (see Section 37.6.2)

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_IASZoneStatusChangeNotificationSend

teZCL_Status eCLD_IASZoneStatusChangeNotificationSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_IASZone_StatusChangeNotificationPayload
    *psPayload);

Description

This function can be used on IAS Zone cluster server to send a Zone Status Change Notification to the IAS Zone client.

You are 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.

Parameters

  • u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the command and to identify the instance of the shared structure holding the required attribute values

  • u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP

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

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

  • psPayload: Pointer to a structure containing the payload for the command (see Section 37.6.2)

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_IASZoneNormalOperationModeReqSend

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

Description

This function can be used on IAS Zone cluster client to send a request the IAS Zone server to initiate normal operation mode. If required, this command must be enabled in the compile-time options, as described in Section 37.7.

You are 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.

Parameters

  • u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the command and to identify the instance of the shared structure holding the required attribute values

  • u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP

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

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

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

eCLD_IASZoneTestModeReqSend

teZCL_Status eCLD_IASZoneTestModeReqSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_IASZone_InitiateTestModeRequestPayload
    *psPayload);

Description

This function can be used on IAS Zone cluster client to send a request to the IAS Zone server to initiate test mode and operate in this mode for a specified time. If required, this command must be enabled in the compile-time options, as described in Section 37.7.

Test mode allows the target device to be temporarily isolated from the IAS to allow configuration/adjustment of the device. Alternatively, the whole IAS can be put into test mode for maintenance, but the command issued by this function only affects the individual target IAS Zone cluster server(s).

You are 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.

Parameters

  • u8SourceEndPointId: Number of the local endpoint through which to send the request. This parameter is used both to send the command and to identify the instance of the shared structure holding the required attribute values

  • u8DestinationEndPointId: Number of the endpoint on the remote node to which the request is sent. This parameter is ignored when sending to address types eZCL_AMBOUND and eZCL_AMGROUP

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

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

  • psPayload: Pointer to a structure containing the payload for the command (see Section 37.6.2)

Returns

  • E_ZCL_SUCCESS

  • E_ZCL_ERR_PARAMETER_NULL

  • E_ZCL_ERR_EP_RANGE

  • E_ZCL_ERR_EP_UNKNOWN

  • E_ZCL_ERR_CLUSTER_NOT_FOUND

  • E_ZCL_ERR_ZBUFFER_FAIL

  • E_ZCL_ERR_ZTRANSMIT_FAIL

If an error is returned by the ZigBee PRO stack function which is invoked by this function to transmit the data, this error may be obtained by calling eZCL_GetLastZpsError().

Parent topic:Functions

Parent topic:IAS Zone Cluster