General Structures

tsZCL_EndPointDefinition

This structure defines the endpoint for an application:

struct tsZCL_EndPointDefinition
{
    uint8                       u8EndPointNumber;
    uint16                      u16ManufacturerCode;
    uint16                      u16ProfileEnum;
    bool_t                      bIsManufacturerSpecificProfile;
    uint16                      u16NumberOfClusters;
    tsZCL_ClusterInstance      *psClusterInstance;
    bool_t                      bDisableDefaultResponse;
    tfpZCL_ZCLCallBackFunction  pCallBackFunctions;
};

Where:

  • u8EndPointNumber is the endpoint number between 1 and 240 (0 is reserved)

  • u16ManufacturerCode is the manufacturer code (only valid when bIsManufacturerSpecificProfile is set to TRUE)

  • u16ProfileEnum is the ZigBee application profile ID

  • bIsManufacturerSpecificProfile indicates whether the application profile is proprietary (TRUE) or from the ZigBee Alliance (FALSE)

  • u16NumberOfClusters is the number of clusters on the endpoint

  • psClusterInstance is a pointer to an array of cluster instance structures

  • bDisableDefaultResponse can be used to disable the requirement for default responses to be returned for commands sent from the endpoint (TRUE=disable, FALSE=enable)

  • pCallBackFunctions is a pointer to the callback functions for the endpoint

Parent topic:General Structures

tsZCL_ClusterDefinition

This structure defines a cluster used on a device:

typedef struct
{
    uint16                      u16ClusterEnum;
    bool_t                      bIsManufacturerSpecificCluster;
    uint8                       u8ClusterControlFlags;
    uint16                      u16NumberOfAttributes;
    tsZCL_AttributeDefinition  *psAttributeDefinition;
    tsZCL_SceneExtensionTable  *psSceneExtensionTable;
#ifdef ZCL_COMMAND_DISCOVERY_SUPPORTED    
    uint8                       u8NumberOfCommands;
    tsZCL_CommandDefinition    *psCommandDefinition;
#endif 
}  tsZCL_ClusterDefinition;

Where:

  • u16ClusterEnum is the Cluster ID.

  • bIsManufacturerSpecificCluster indicates whether the cluster is specific to a manufacturer (proprietary):

    • TRUE - proprietary cluster

    • FALSE - ZigBee cluster

u8ClusterControlFlags is a bitmap containing control bits in two parts, as follows:

Bits

Description

Values

0 - 3

Type of security

Indicates the type of security key used via one of the following teZCL_ZCLSendSecurity enumerations (see Section 7.1.6):

Bits

Description

Values

0 - 3

Type of security

Indicates the type of security key used via one of the following teZCL_ZCLSend Security enumerations (see Section 7.1.6):   E_ZCL_SECURITY_NETWORK, E_ZCL_SECURITY_APPLINK
•  E_ZCL_SECURITY_TEMP_APPLINK
(this option is for internal use only)

4 - 7

Cluster mirror

Used internally to indicate whether the cluster is mirrored, as follows:
•  0000b - Not mirrored,1000b - Mirrored, All other values are reserved

  • u16NumberOfAttributes indicates the number of attributes in the cluster.

  • psAttributeDefinition is a pointer to an array of attribute definition structures - see Section 6.1.3.

  • psSceneExtensionTable is a pointer to a structure containing a Scene Extension table - see Section 6.1.20.

  • The following optional pair of fields are related to the Command Discovery feature (see Section 2.9):

    • u8NumberOfCommands is the number of supported commands in the Command Definition table (see below).

    • psCommandDefinition is a pointer to a Command Definition table which contains a list of the commands supported by the cluster - each entry of the table contains the details of a supported command in a tsZCL_CommandDefinition structure (see Section 6.1.19).

Parent topic:General Structures

tsZCL_AttributeDefinition

This structure defines an attribute used in a cluster:

struct tsZCL_AttributeDefinition
{
    uint16                  u16AttributeEnum;
    uint8                   u8AttributeFlags;
    teZCL_ZCLAttributeType  eAttributeDataType;
    uint16                  u16OffsetFromStructBase;
    uint16                  u16AttributeArrayLength;
};

Where:

  • u16AttributeEnum is the Attribute ID.

  • u8AttributeFlags is a 5-bit bitmap indicating the accessibility of the attribute (for details of the access types, refer to Section 2.3.1) - a bit is set to ‘1’ if the corresponding access type is supported, as follows:

Bit

Access Type

0

Read

1

Write

2

Reportable

3

Scene

4

Global

5-7

Reserved

  • eAttributeDataType is the data type of the attribute - see Section 7.1.3.

  • u16O``ffsetFromStructBase is the offset of the attribute’s location from the start of the cluster.

  • u16AttributeArrayLength is the number of consecutive attributes of the same type.

Parent topic:General Structures

tsZCL_Address

This structure is used to specify the addressing mode and address for a communication with a remote node:

typedef struct PACK
{
  teZCL_AddressMode           eAddressMode;
  union {
        zuint16               u16GroupAddress;
        zuint16               u16DestinationAddress;
        zuint64               u64DestinationAddress;
        teAplAfBroadcastMode  eBroadcastMode;
    } uAddress;
} tsZCL_Address;

Where:

  • eAddressMode is the addressing mode to be used (see Section 7.1.1).

  • uAddress is a union containing the necessary address information (only one of the following must be set, depending on the addressing mode selected):

    • u16GroupAddress is the 16-bit group address for the target nodes.

    • u16DestinationAddress is the 16-bit network address of the target.

    • u64DestinationAddress is the 64-bit IEEE/MAC address of the target.

    • eBroadcastMode is the required broadcast mode (see Section 7.1.2).

Parent topic:General Structures

tsZCL_AttributeReportingConfigurationRecord

This structure contains the configuration record for automatic reporting of an attribute.

typedef struct
{
    uint8                u8DirectionIsReceived;
    teZCL_ZCLAttributeType          eAttributeDataType;
    uint16                u16AttributeEnum;
    uint16                u16MinimumReportingInterval;
    uint16                u16MaximumReportingInterval;
    uint16                u16TimeoutPeriodField;
    tuZCL_AttributeReportable       uAttributeReportableChange;
} tsZCL_AttributeReportingConfigurationRecord;

Where:

  • u8DirectionIsReceived indicates whether the record configures how attribute reports can be received or sent:

    • 0x00: Configures how attribute reports are sent by the server - the following fields are included in the message payload:

      eAttributeDataType, u16MinimumReportingInterval, u16MaximumReportingInterval, uAttributeReportableChange

    • 0x01: Configures how attribute reports are received by the client - u16TimeoutPeriodField is included in the message payload.

  • eAttributeDataType indicates the data type of the attribute.

  • u16AttributeEnum is the identifier of the attribute to which the configuration record relates.

  • u``16MinimumReportingInterval is the minimum time-interval, in seconds, between consecutive reports for the attribute - the value 0x0000 indicates no minimum (REPORTING_MINIMUM_LIMIT_NONE).

  • u16MaximumReportingInterval is the time-interval, in seconds, between consecutive reports for periodic reporting - the following special values can also be set:

    • 0x0000 indicates that periodic reporting is to be disabled for the attribute (REPORTING_MAXIMUM_PERIODIC_TURNED_OFF).

    • 0xFFFF indicates that automatic reporting is to be completely disabled for the attribute (REPORTING_MAXIMUM_TURNED_OFF).

  • u16TimeoutPeriodField is the timeout value, in seconds, for an attribute report - if the time elapsed since the last report exceeds this value (without receiving another report), it may be assumed that there is a problem with the attribute reporting - the value 0x0000 indicates that no timeout will be applied (REPORTS_OF_ATTRIBUTE_NOT_SUBJECT_TO_TIMEOUT).

  • uAttributeReportableChange is the minimum change in the attribute value that causes an attribute report to be issued.

Note: For successful attribute reporting, the timeout on the receiving client must be set to a higher value than the maximum reporting interval for the attribute on the sending server.

Parent topic:General Structures

tsZCL_AttributeReportingConfigurationResponse

This structure contains information from a ‘configure reporting’ response.

typedef struct
{
    teZCL_CommandStatus  eCommandStatus;
    tsZCL_AttributeReportingConfigurationRecord
                  sAttributeReportingConfigurationRecord;
}tsZCL_AttributeReportingConfigurationResponse;

Where:

  • eCommandStatus is an enumeration representing the status from the response (see Section 7.1.4).

  • sAttributeReportingConfigurationRecord is a configuration record structure (see Section 6.1.5), but only the fields u16AttributeEnum and u8DirectionIsReceived are used in the response.

Parent topic:General Structures

tsZCL_AttributeReadReportingConfigurationRecord

This structure contains the details of a reporting configuration query for one attribute, to be included in a ‘read reporting configuration’ command:

typedef struct
{
    uint8      u8DirectionIsReceived;
    uint16     u16AttributeEnum;
} tsZCL_AttributeReadReportingConfigurationRecord;

Where:

  • u8DirectionIsReceived specifies whether the required reporting configuration information details how the attribute reports are received or sent.

    • 0x00: Specifies that required information details how a report is sent by the server.

    • 0x01: Specifies that required information details how a report is received by the client.

  • u16AttributeEnum is the identifier of the attribute to which the required reporting configuration information relates.

Parent topic:General Structures

tsZCL_IndividualAttributesResponse

This structure is contained in a ZCL event of type E_ZCL_CBET_READ_INDIVIDUAL_ATTRIBUTE_RESPONSE (see Section):

typedef struct PACK {
    uint16               u16AttributeEnum;
    teZCL_ZCLAttributeType         eAttributeDataType;
    teZCL_CommandStatus          eAttributeStatus;
    void               *pvAttributeData;
} tsZCL_IndividualAttributesResponse;

Where:

  • u16AttributeEnum identifies the attribute that has been read (the relevant enumerations are listed in the ‘Enumerations’ section of each cluster-specific chapter).

  • eAttributeDataType is the ZCL data type of the read attribute (see Section 7.1.3).

  • eAttributeStatus is the status of the read operation (0x00 for success or an error code - see Section 7.1.4 for enumerations).

  • pvAttributeData is a pointer to the read attribute data which (if the read was successful) has been inserted by the ZCL into the shared device structure.

The above structure is contained in the tsZCL_CallBackEvent event structure, detailed in Section 6.2, when the field eEventType is set to E_ZCL_CBET_READ_INDIVIDUAL_ATTRIBUTE_RESPONSE.

Parent topic:General Structures

tsZCL_DefaultResponse

This structure is contained in a ZCL event of type E_ZCL_CBET_DEFAULT_RESPONSE (see Section):

 typedef struct PACK {
     uint8  u8CommandId; 
     uint8  u8StatusCode;
} tsZCL_DefaultResponse;

Where:

  • u8CommandId is the ZCL identifier of the command that triggered the default response message

  • u8StatusCode is the status code from the default response message (0x00 for OK or an error code defined in the ZCL Specification - see Section 4.2)

The above structure is contained in the tsZCL_CallBackEvent event structure, detailed in Section 6.2, when the field eEventType is set to E_ZCL_CBET_DEFAULT_RESPONSE.

Parent topic:General Structures

tsZCL_AttributeDiscoveryResponse

This structure contains details of an attribute reported in a ‘discover attributes’ response. It is contained in a ZCL event of type E_ZCL_CBET_DISCOVER_INDIVIDUAL_ATTRIBUTE_RESPONSE.

typedef struct
{
    bool_t                bDiscoveryComplete;
    uint16                u16AttributeEnum;
     teZCL_ZCLAttributeType          eAttributeDataType;
} tsZCL_AttributeDiscoveryResponse;

where:

  • bDiscoveryComplete indicates whether this is the final attribute from a ‘discover attributes’ to be reported:

    • TRUE - final attribute

    • FALSE - not final attribute

  • u16AttributeEnum is the identifier of the attribute being reported

  • eAttributeDataType indicates the data type of the attribute being reported (see Section 7.1.3)

The above structure is contained in the tsZCL_CallBackEvent event structure, detailed in Section 6.2, when the field eEventType is set to E_ZCL_CBET_DISCOVER_INDIVIDUAL_ATTRIBUTE_RESPONSE.

Parent topic:General Structures

tsZCL_AttributeDiscoveryExtendedResponse

This structure contains details of an attribute reported in a ‘discover attributes extended’ response. It is contained in a ZCL event of type E_ZCL_CBET_DISCOVER_INDIVIDUAL_ATTRIBUTE_EXTENDED_RESPONSE.

typedef struct
{
    bool_t                  bDiscoveryComplete;
    uint16                  u16AttributeEnum;
    teZCL_ZCLAttributeType  eAttributeDataType;
    uint8                   u8AttributeFlags;
}tsZCL_AttributeDiscoveryExtendedResponse;

where:

  • bDiscoveryComplete indicates whether this is the final attribute from a ‘discover attributes’ to be reported:

    • TRUE - final attribute

    • FALSE - not final attribute

  • u16AttributeEnum is the identifier of the attribute being reported

  • eAttributeDataType indicates the data type of the attribute being reported (see Section 7.1.3)

  • u8AttributeFlags is a 5-bit bitmap indicating the accessibility of the reported attribute (for details of the access types, refer to Section 2.3.1) - a bit is set to ‘1’ if the corresponding access type is supported, as follows:

Bit

Access Type

0

Read

1

Write

2

Reportable

3

Scene

4

Global

5-7

Reserved

The above structure is contained in the tsZCL_CallBackEvent event structure, detailed in Section 6.2, when the field eEventType is set to E_ZCL_CBET_DISCOVER_INDIVIDUAL_ATTRIBUTE_EXTENDED_RESPONSE.

Parent topic:General Structures

tsZCL_ReportAttributeMirror

This structure contains information relating to a report attribute command:

typedef struct
{
    uint8                       u8DestinationEndPoint;
    uint16                      u16ClusterId;
    uint64                      u64RemoteIeeeAddress;
    teZCL_ReportAttributeStatus eStatus;
}tsZCL_ReportAttributeMirror;

where:

  • u8DestinationEndPoint is the number of target endpoint for the attribute report (this is the endpoint on which the mirror for the device resides)

  • u16ClusterId is the ID of the cluster for which information is to be mirrored

  • u64RemoteIeeeAddress is the IEEE/MAC address of the target device for the attribute report (which contains the mirror for the device)

  • eStatus indicates the status of the attribute report (see Section 7.1.5)

Parent topic:General Structures

tsZCL_OctetString

This structure contains information on a ZCL octet (byte) string. This string is of the format:

|Octet Count, N

(1 octet)

|Data

(N octets)

|

which contains N+1 octets, where the leading octet indicates the number of octets (N) of data in the remainder of the string (valid values are from 0x00 to 0xFE).

The tsZCL_OctetString structure incorporates this information as follows:

typedef struct
{
    uint8    u8MaxLength;
    uint8    u8Length;
    uint8   *pu8Data;
} tsZCL_OctetString;

Where:

  • u8MaxLength is the maximum number of data octets in an octet string

  • u8Length is the actual number of data octets (N) in this octet string

  • pu8Data is a pointer to the first data octet of this string

Note that there is also a tsZCL_LongOctetString structure in which the octet count (N) is represented by two octets, thus allowing double the number of data octets.

Parent topic:General Structures

tsZCL_CharacterString

This structure contains information on a ZCL character string. This string is of the format:

Character Data Length, L

Character Data

(1 byte)

(L bytes)

which contains L+1 bytes, where the leading byte indicates the number of bytes (L) of character data in the remainder of the string (valid values are from 0x00 to 0xFE). This value represents the number of characters in the string only if the character set used encodes each character using one byte (this is the case for ISO 646 ASCII but not in all character sets, for example, UTF8).

The tsZCL_CharacterString structure incorporates this information as follows:

typedef struct 
{
    uint8    u8MaxLength;
    uint8    u8Length;
    uint8   *pu8Data;
} tsZCL_CharacterString;

where:

  • u8MaxLength is the maximum number of character data bytes

  • u8Length is the actual number of character data bytes (L) in this string

  • pu8Data is a pointer to the first character data byte of this string

The string is not null-terminated and may therefore contain null characters mid-string.

Note that there is also a sZCL_LongCharacterString structure in which the character data length (L) is represented by two bytes, thus allowing double the number of characters.

Parent topic:General Structures

tsZCL_ClusterCustomMessage

This structure contains a cluster custom message:

typedef struct {
     uint16                     u16ClusterId;
     void                       *pvCustomData;
} tsZCL_ClusterCustomMessage;

Where:

  • u16ClusterId is the Cluster ID.

  • pvCustomData is a pointer to the start of the data contained in the message.

Parent topic:General Structures

tsZCL_ClusterInstance

This structure contains information about an instance of a cluster on a device:

struct tsZCL_ClusterInstance
{
    bool_t                      bIsServer;
    tsZCL_ClusterDefinition    *psClusterDefinition;
    void                       *pvEndPointSharedStructPtr;
    uint8                      *pu8AttributeControlBits;
    void                       *pvEndPointCustomStructPtr;
    tfpZCL_ZCLCustomcallCallBackFunction
                                pCustomcallCallBackFunction;
};

where:

  • bIsServer indicates whether the cluster instance is a server or client:

    • TRUE - server

    • FALSE - client

  • psClusterDefinition is a pointer to the cluster definition structure - see Section 6.1.2

  • pvEndPointSharedStructPtr is a pointer to the shared device structure that contains the cluster’s attributes

  • pu8AttributeControlBits is a pointer to an array of bitmaps, one for each attribute in the relevant cluster - for internal cluster definition use only, array should be initialized to 0

  • pvEndPointCustomStructPtr is a pointer to any custom data (only relevant to a user-defined cluster)

  • pCustomcallCallBackFunction is a pointer to a custom callback function (only relevant to a user-defined cluster)

Parent topic:General Structures

tsZCL_CommandDiscoveryIndividualResponse

This structure contains information about an individual command reported in a Command Discovery response (see Section 2.9).

typedef struct
{
    uint8  u8CommandEnum;
    uint8  u8CommandIndex;
} tsZCL_CommandDiscoveryIndividualResponse;

where:

  • u8CommandEnum is the Command ID of the reported command

  • u8CommandIndex is the index of the reported command in the response payload

The above structure is contained in the tsZCL_CallBackEvent event structure, detailed in Section 6.2, when the field eEventType is set to E_ZCL_CBET_DISCOVER_INDIVIDUAL_COMMAND_RECEIVED_RESPONSE or E_ZCL_CBET_DISCOVER_INDIVIDUAL_COMMAND_GENERATED_RESPONSE.

Parent topic:General Structures

tsZCL_CommandDiscoveryResponse

This structure contains information about a Command Discovery response (see Section 2.9).

typedef struct
{
    bool_t bDiscoveryComplete;
    uint8  u8NumberOfCommands;
} tsZCL_CommandDiscoveryResponse;

Where:

  • bDiscoveryComplete is a Boolean flag which indicates whether the Command Discovery is complete, i.e. whether there are any commands remaining to be discovered:

    • TRUE - all commands have been discovered

    • FALSE - there are further commands to be discovered

  • u8NumberOfCommands is the number of discovered commands reported in the response (the individual commands are reported in a structure of the type tsZCL_CommandDiscoveryIndividualResponse - see Section 6.1.17)

The above structure is contained in the tsZCL_CallBackEvent event structure, detailed in Section 6.2, when the field eEventType is set to E_ZCL_CBET_DISCOVER_COMMAND_RECEIVED_RESPONSE or E_ZCL_CBET_DISCOVER_COMMAND_GENERATED_RESPONSE.

Parent topic:General Structures

tsZCL_CommandDefinition

This structure contains the details of a command which is supported by the cluster (and can be reported in Command Discovery).

struct tsZCL_CommandDefinition
{
     uint8   u8CommandEnum;
     uint8   u8CommandFlags;
};

Where:

  • u8CommandEnum is the Command ID within the cluster

  • u8CommandFlags is a bitmap containing a set of control flags, as follows:

Bits

Enumeration

Description

0

E_ZCL_CF_RX

Command is generated by the client and received by the server

1

E_ZCL_CF_TX

Command is generated by the server and received by the client

2

-

Reserved

3

E_ZCL_CF_MS

Command is manufacturer-specific

4 - 7

-

Reserved

Parent topic:General Structures

tsZCL_SceneExtensionTable

This structure contains a Scenes Extension table.

typedef struct
{
    tfpZCL_SceneEventHandler    pSceneEventHandler;
    uint16                      u16NumberOfAttributes;
    uint16                      au16Attributes[];
} tsZCL_SceneExtensionTable;

Where:

  • pSceneEventHandler is a pointer a Scenes event handler function

  • u16NumberOfAttributes is the number of attributes in the Scene extension

  • au16Attributes is an array of the attribute IDs of the attributes in the Scene extension

Parent topic:General Structures

tsZCL_WriteAttributeRecord

The is structure contains the details for a ‘write attribute’ operation.

typedef struct
{
           teZCL_ZCLAttributeType   eAttributeDataType;  
           uint16                   u16AttributeEnum;
           uint8                                                                   *pu8AttributeData;
}tsZCL_WriteAttributeRecord;

Where:

  • eAttributeDataType is an enumeration indicating the attribute data type (for the enumerations, refer to Section 7.1.3).

  • u16AttributeEnum is an enumeration for the attribute identifier (for the relevant ‘Attribute ID’ enumerations, refer to the ‘Enumerations’ section of each cluster-specific chapter).

  • pu8AttributeData is a pointer to the attribute data to be written.

Parent topic:General Structures

Parent topic:ZCL Structures