IAS Zone Cluster

This chapter describes the IAS Zone cluster which provides an interface to an IAS Zone device in an IAS (Intruder Alarm System).

The IAS Zone cluster has a Cluster ID of 0x0500.

Overview

The IAS Zone cluster provides an interface to an IAS Zone device, which provides security alarm triggers for a zone or region of a building (e.g. fire detection). The cluster allows an IAS Zone device to be configured/controlled from a CIE (Control and Indicating Equipment) device. The server side of the cluster is implemented on the IAS Zone device and the client side is implemented on the CIE device. The IAS Zone device is detailed in the ZigBee Devices User Guide (JNUG3131).

The cluster supports the following functionality:

• Up to two alarm types per zone, Alarm1 and Alarm2

• ‘Low battery’ reports

• Supervision of the IAS network

To use the functionality of this cluster, you must include the file IASZone.h in your application and enable the cluster by defining CLD_IASZONE in the zcl_options.h file.

The inclusion of the client or server software must be pre-defined in the application’s compile-time options (in addition, if the cluster is to reside on a custom endpoint then the role of client or server must also be specified when creating the cluster instance).

The compile-time options for the IAS Zone cluster are fully detailed in Section 37.7.

The information that can potentially be stored in this cluster is organised into the following attribute sets:

• Zone information

• Zone settings

Parent topic:IAS Zone Cluster

IAS Zone Structure and Attributes

The structure definition for the IAS Zone cluster is:

typedef struct
{
#ifdef IASZONE_SERVER    
    zenum8     e8ZoneState; 
    zenum16    e16ZoneType;
    zbmap16    b16ZoneStatus; 
    zuint64    u64IASCIEAddress; 
    zuint8     u8ZoneId;
#ifdef CLD_IASZONE_ATTR_ID_NUMBER_OF_ZONE_SENSITIVITY_LEVELS
    zuint8     u8NumberOfZoneSensitivityLevels;
#endif
#ifdef CLD_IASZONE_ATTR_ID_CURRENT_ZONE_SENSITIVITY_LEVEL
    zuint8     u8CurrentZoneSensitivityLevel;
#endif   
#endif
    zuint16    u16ClusterRevision;
} tsCLD_IASZone;

where:

‘Zone Information’ Attribute Set

• e8ZoneState is a mandatory attribute which indicates the membership status of the device in an IAS system (enrolled or not enrolled) - one of:

  • E_CLD_IASZONE_STATE_NOT_ENROLLED (0x00)

  • E_CLD_IASZONE_STATE_ENROLLED (0x01)

    • ‘Enrolled’ means that the cluster client will react to Zone State Change Notification commands from the cluster server.

• e16ZoneType is a mandatory attribute which indicates the zone type and the types of security detectors that can trigger the alarms, Alarm1 and Alarm2:

Enumeration	Value	Type	Alarm1	Alarm2
E_CLD_IASZONE_TYPE_STANDARD_CIE	0x0000	Standard CIE	System alarm	-
E_CLD_IASZONE_TYPE_MOTION _ SENSOR	0x000D	Motion sensor	Intrusion indication	Presence indica- tion
E_CLD_IASZONE_TYPE_CONTACT _ SWITCH	0x0015	Contact switch	First portal open close	Second portal open-close
E_CLD_IASZONE_TYPE_FIRE_SENSOR	0x0028	Fire sensor	Fire indication	-
E_CLD_IASZONE_TYPE_WATER_SENSOR	0x002A	Water sensor	Water overflow indication	-
E_CLD_IASZONE_TYPE_GAS_SENSOR	0x002B	Gas sensor	Carbon monoxide indication	Cooking indica- tion
E_CLD_IASZONE_TYPE_PERSONAL _ EMERGENCY_DEVICE	0x002C	Personal emergency device	Fall/concussion	Emergency but- ton
E_CLD_IASZONE_TYPE_VIBRATION _ MOVEMENT_SENSOR	0x002D	Vibration movement sensor	Movement indication	Vibration
E_CLD_IASZONE_TYPE_REMOTE _ CONTROL	0x010F	Remote control	Panic	Emergency
E_CLD_IASZONE_TYPE_KEY_FOB	0x0115	Key fob	Panic	Emergency
E_CLD_IASZONE_TYPE_KEYPAD	0x021D	Keypad	Panic	Emergency
E_CLD_IASZONE_TYPE_STANDARD _ WARNING_DEVICE	0x0225	Standard warning device	-	-
E_CLD_IASZONE_TYPE_INVALID_ZONE	0xFFFF	Invalid zone type	-	-

• b``16ZoneStatus is a mandatory attribute which is a 16-bit bitmap indicating the status of each of the possible notification triggers from the device:

Bit	Description
0	Alarm1: 1 - Opened or alarmed 0 - Closed or not alarned
1	Alarm2: 1 - Opened or alarmed 0 - Closed or not alarned
2	Tamper: 1 - Tampered with 0 - Not tampered with
3	Battery: 1 - Low 0 - OK
4	Supervision reports: 1 - Reports 0 - No reports (See the note below)
5	Restore reports: 1 - Reports 0 - No reports (See the note below)
6	Trouble: 1 - Trouble/failure 0 - OK
7	AC (mains): 1 - Fault 0 - OK
8	Test mode: 1 - Sensor in test mode 0 - Sensor in operational mode
9	Battery defect:   1 - Defective battery detected 0 - Battery OK
10-15	Reserved

• Bit 4 indicates whether the Zone device issues periodic Zone Status Change Notification commands that may be used by the CIE device as evidence that the Zone device is operational.

• Bit 5 indicates whether the Zone device issues a Zone Status Change Notification command to notify when an alarm is no longer present (some Zone devices do not have the ability to detect when the alarm condition has disappeared).

‘Zone Settings’ Attribute Set

• u64IASCIEAddress is a mandatory attribute containing the 64-bit IEEE/MAC address of the CIE device to which the cluster server must send commands/ notifications

• u8ZoneId is a mandatory attribute containing the 8-bit identifier for the zone allocated by the CIE device at the time of enrollment

• u8NumberOfZoneSensitivityLevels is an optional attribute containing the number of sensitivity levels (for the detectable quantity) for the zone - for devices that have only one sensitivity level, this attribute need not be enabled or can be set to 0x00 or 0x01

  Note: The definition of a sensitivity level is manufacturer-specific but detector ‘sensitivity’ should increase with higher values of this attribute.

• u16ClusterRevision is a mandatory attribute that specifies the revision of the cluster specification on which this cluster instance is based. The cluster specification in the ZCL r6 corresponds to a cluster revision of 1. The value is incremented by one for each subsequent revision of the cluster specification. This attribute is also described in Section 2.4

Parent topic:IAS Zone Cluster

Enrollment

An IAS Zone device hosting the IAS Zone cluster server must be paired with a CIE device hosting the cluster client. This pairing is implemented by the process of ‘enrollment’ which, for extra security, provides a layer of pairing in addition to ZigBee PRO binding - if required, binding is implemented as part of the enrollment process.

During enrollment, the CIE device sends its IEEE/MAC address to the Zone device as well as a Zone ID, which is a unique 8-bit identifier that the CIE device assigns to the Zone device. These values are stored in the u64IASCIEAddress and u8ZoneId attributes on the Zone device (cluster server) - see Section 37.2. In addition, once enrollment has completed, the e8ZoneState attribute is set to ‘enrolled’. Subsequently, the Zone device will only communicate with the paired CIE device.

Enrollment begins just after the Zone device joins the network. This device must then periodically poll for data (from the CIE device), ideally once every 2 seconds (or faster) but no slower than once every 7 seconds. This polling must continue until the e8ZoneState attribute has been updated to ‘enrolled’. However, if the IAS Zone device supports the Poll Control cluster, polling at the above rate should continue until the Poll Control cluster configuration is changed.

Three methods of enrollment are available:

• Trip-to-Pair, described in Section 37.3.1

• Auto-Enroll-Response, described in Section 37.3.2

• Auto-Enroll-Request, described in Section 37.3.3

A cluster server and client can each implement both Trip-to-Pair and Auto-Enroll-Response or just Auto-Enroll-Request.

Trip-to-Pair

The Trip-to-Pair method of enrollment is described below:

1. After the IAS Zone device joins the network, the CIE device performs a service discovery.

2. If the CIE device determines that it wants to enroll the Zone device, it sends a Write Attribute command to the Zone device in order to write its IEEE/MAC address to the relevant attribute.

3. The Zone device may optionally create a binding table entry for the CIE device and store the CIE device’s IEEE/MAC address there.

4. The Zone device waits for the authorization of the enrollment via a user input (for example, a button-press) and, on this input, sends a Zone Enroll Request command to the CIE device.

5. The CIE device assigns a Zone ID to the Zone device and sends a Zone Enroll Response command to it.

6. The Zone device updates its attributes to stored the assigned Zone ID and update its zone state to ‘enrolled’.

Parent topic:Enrollment

Auto-Enroll-Response

The Auto-Enroll-Response method of enrollment is described below:

1. After the IAS Zone device joins the network, the CIE device performs a service discovery.

2. If the CIE device determines that it wants to enroll the Zone device, it sends a Write Attribute command to the Zone device in order to write its IEEE/MAC address to the relevant attribute.

3. The Zone device may optionally create a binding table entry for the CIE device and store the CIE device’s IEEE/MAC address there.

4. The CIE device assigns a Zone ID to the Zone device and sends a Zone Enroll Response command to it.

5. The Zone device updates its attributes to stored the assigned Zone ID and update its zone state to ‘enrolled’.

Note: The above Auto-Enroll-Response process is similar to the Trip-to-Pair process (described in Section 37.3.2) except user authorization for the enrollment of the Zone device is not required and no Zone Enroll Request command needs to be sent to the CIE device.

Parent topic:Enrollment

Auto-Enroll-Request

The Auto-Enroll-Request method of enrollment is described below:

1. After the IAS Zone device joins the network, the CIE device performs a service discovery.

2. If the CIE device determines that it wants to enroll the Zone device, it sends a Write Attribute command to the Zone device in order to write its IEEE/MAC address to the relevant attribute.

3. The Zone device may optionally create a binding table entry for the CIE device and store the CIE device’s IEEE/MAC address there.

4. The Zone device sends a Zone Enroll Request command to the CIE device.

5. The CIE device assigns a Zone ID to the Zone device and sends a Zone Enroll Response command to it.

6. The Zone device updates its attributes to stored the assigned Zone ID and update its zone state to ‘enrolled’.

Note: The above Auto-Enroll-Request process is similar to the Trip-to-Pair process (described in Section 37.3.2) except that user authorization for the enrollment of the Zone device is not required.

Parent topic:Enrollment

Parent topic:IAS Zone Cluster

IAS Zone Events

The IAS Zone cluster has its own events that are handled through the callback mechanism outlined in Chapter 3. If a device uses the IAS Zone cluster then IAS Zone event handling must be included in the callback function for the associated endpoint, where this callback function is registered through the relevant endpoint registration function (for example, through eHA_RegisterIASZoneEndPoint() for a Zone device). The relevant callback function is then invoked when an IAS Zone event occurs.

For an IAS Zone 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 tsCLD_IASZoneCallBackMessage structure:

typedef struct
{
uint8 u8CommandId;
union
    {
     tsCLD_IASZone_TestModeUpdate                   *psTestModeUpdate; /* Internal */
     tsCLD_IASZone_EnrollRequestCallBackPayload     sZoneEnrollRequestCallbackPayload;
     tsCLD_IASZone_EnrollResponsePayload            *psZoneEnrollResponsePayload;
     tsCLD_IASZone_StatusChangeNotificationPayload  *psZoneStatusNotificationPayload;
     tsCLD_IASZone_InitiateTestModeRequestPayload   *psZoneInitiateTestModeRequestPayload;
    } uMessage;
} tsCLD_IASZoneCallBackMessage;

When an IAS Zone event occurs, one of several command types could have been received. The relevant command type is specified through the u8CommandId field of the tsSM_CallBackMessage structure. The possible command/event types are detailed in the table below (note that psTestModeUpdate is for internal use only).

u8CommandId Enumeration	Description
E_CLD_IASZONE_CMD_ZONE_ENROLL_RESP	An IAS Zone Enroll Response has been received by the cluster server
E_CLD_IASZONE_CMD_ZONE_STATUS_NOTIFICATION	An IAS Zone Status Change Notification has been received by the cluster client
E_CLD_IASZONE_CMD_ZONE_ENROLL_REQ	An IAS Zone Enroll Request has been received by the cluster client
E_CLD_IASZONE_CMD_INITIATE_NORMAL_OP_MODE_REQ	An IAS Zone Normal Operation Mode Initiation Request command has been received by the cluster server
E_CLD_IASZONE_CMD_INITIATE_TEST_MODE_REQ	An IAS Zone Initiate Test Mode Request has been received by the cluster server

Parent topic:IAS Zone Cluster

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

Structures

Custom Data Structure

The IAS Zone cluster requires extra storage space to be allocated to be used by internal functions. The structure definition for this storage is shown below:

typedef struct
{
    tsCLD_IASZone_InitiateTestModeRequestPayload sTestMode;
    tsZCL_ReceiveEventAddress     sReceiveEventAddress;
    tsZCL_CallBackEvent           sCustomCallBackEvent;
    tsCLD_IASZoneCallBackMessage  sCallBackMessage;   
} tsCLD_IASZone_CustomDataStructure;

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

Parent topic:Structures

Custom Command Payloads

The following structures contain the payloads for the IAS Zone cluster custom commands.

‘Enroll Request’ Payload

The following structure contains the payload of an Enroll Request command.

typedef struct
{
    zenum16    e16ZoneType;          
    uint16     u16ManufacturerCode;
}tsCLD_IASZone_EnrollRequestPayload;

where:

• e16ZoneType is the zone type of the local (sending) node, as specified in the e``16ZoneType attribute (see Section 37.2)

• u16ManufacturerCode is the manufacturer ID code that is held in the Node Descriptor of the local (sending) node

‘Enroll Response’ Payload

The following structure contains the payload of an Enroll Response command.

typedef struct
{
   teCLD_IASZoneZoneEnrollRspCode   e8EnrollResponseCode;          
   uint8                            u8ZoneID;
}tsCLD_IASZone_EnrollResponsePayload;

where:

• e8EnrollResponseCode is a code indicating the outcome of the corresponding Enroll Request, one of:

Enumeration	Description
E_CLD_IASZONE_ENROLL_RESP_SUCCESS	Requested enrollment successful
E_CLD_IASZONE_ENROLL_RESP_NOT_SUPPORTED	Zone type of requesting device is not known/sup-ported by the CIE device
E_CLD_IASZONE_ENROLL_RESP_NO_ENROLL_PERMIT	CIE device is not allowing new zones to be enrolled at the present time
E_CLD_IASZONE_ENROLL_RESP_TOO_MANY_ZONES	CIE device has reached its limit for the number of zones that it can enroll

• u8ZoneID is the index of the entry for the enrollment which has been added to the Zone table on the CIE device (only valid for a successful enrollment)

‘Zone Status Change Notification’ Payload

The following structure contains the payload of a Zone Status Change Notification command.

typedef struct
{
   zbmap16    b16ZoneStatus;            
   zbmap8     b8ExtendedStatus;
   zuint8     u8ZoneId;
   zuint16    u16Delay;
}tsCLD_IASZone_StatusChangeNotificationPayload;

where:

• b16ZoneStatus contains the new/current status of the (sending) zone device, as indicated in the e``8ZoneState attribute - one of:

  • E_CLD_IASZONE_STATE_NOT_ENROLLED (0x01)

  • E_CLD_IASZONE_STATE_ENROLLED (0x02)

• b8ExtendedStatus can be optionally used to indicate further status information, but otherwise should be set to zero

• u8ZoneId is the index of the entry for the (sending) device in the Zone table on the CIE device

• u16Delay is is the time-delay, in quarter-seconds, between the status change taking place in the e``8ZoneState attribute and the successful transmission of the Zone Status Change Notification (this value can be used in assessing network traffic congestion)

‘Initiate Test Mode Request’ Payload

The following structure contains the payload of an Initiate Test Mode Request command.

typedef struct
{
    uint8    u8TestModeDuration;          
    uint8    u8CurrentZoneSensitivityLevel;
}tsCLD_IASZone_InitiateTestModeRequestPayload;

where:

• u8TestModeDuration is the duration, in seconds, for which the device should remain in test mode

• u8CurrentZoneSensitivityLevel is the current sensitivity level for the zone, as indicated in the u8CurrentZoneSensitivityLevel attribute (see Section 37.2)

Parent topic:Structures

Parent topic:IAS Zone Cluster

Compile-time options

To enable the IAS Zone cluster in the code to be built, it is necessary to add the following to the zcl_options.h file:

#define CLD_IASZONE

In addition, to include the software for a cluster client or server or both, it is necessary to add one of the following to the same file:

#define IASZONE_SERVER
#define IASZONE_CLIENT

Optional Attributes

Add this line to enable the optional Number Of Zone Sensitivity Levels attribute:

#define CLD_IASZONE_ATTR_ID_NUMBER_OF_ZONE_SENSITIVITY_LEVELS

Add this line to enable the optional Current Zone Sensitivity Level attribute:

#define CLD_IASZONE_ATTR_ID_CURRENT_ZONE_SENSITIVITY_LEVEL

Global Attributes

Add this line to define the value (n) of the Cluster Revision attribute:

#define CLD_IASZONE_CLUSTER_REVISION <n>

The default value is 1, which corresponds to the revision of the cluster in the ZCL r6 specification (see Section 2.4).

Optional Commands

Add this line to enable the optional Initiate Normal Operation Mode command:

#define CLD_IASZONE_CMD_INITIATE_NORMAL_OPERATION_MODE

Add this line to enable the optional Initiate Test Mode command:

#define CLD_IASZONE_CMD_INITIATE_TEST_MODE

Disable APS Acknowledgements for Bound Transmissions

APS acknowledgements for bound transmissions from this cluster can be disabled by defining:

#define CLD_IASZONE_BOUND_TX_WITH_APS_ACK_DISABLED

Parent topic:IAS Zone Cluster