Diagnostics Cluster

This chapter describes the Diagnostics cluster.

The Diagnostics cluster has a Cluster ID of 0x0B05.

Overview

The Diagnostics cluster allows the operation of the ZigBee PRO stack to be followed over time. It provides a tool for monitoring the performance of individual network nodes, including the routing of packets through these nodes.

Note: It is strongly recommended that Diagnostics cluster server attributes are stored in persistent memory to allow performance data to be preserved through a device reset or power interruption.

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

A Diagnostics cluster instance can act as a client or a server. 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 Diagnostics cluster are fully detailed in Section 22.5.

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

• Hardware information

• Stack/Network information

Currently, only three attributes from the Stack/Network Information attribute set are supported (see Section 22.2).

This cluster has no associated events. However, reads and writes of the cluster attributes may give rise to ZCL events (the application is responsible for checking that a written value is within the valid range for the target attribute).

Parent topic:Diagnostics Cluster

Diagnostics Structure and Attributes

The structure definition for the Diagnostics cluster is:

typedef struct
{
#ifdef DIAGNOSTICS_SERVER
 /* Hardware Information attribute set */
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_NUMBER_OF_RESETS
  uint16 u16NumberOfResets;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_PERSISTENT_MEMORY_WRITES
  uint16 u16PersistentMemoryWrites;
 #endif
 /* Stack/Network Information attribute set */
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_MAC_RX_BCAST
  uint32 u32MacRxBcast;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_MAC_TX_BCAST
  uint32 u32MacTxBcast;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_MAC_RX_UCAST
  uint32 u32MacRxUcast;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_MAC_TX_UCAST
  uint32 u32MacTxUcast;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_MAC_TX_UCAST_RETRY
  uint16 u16MacTxUcastRetry;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_MAC_TX_UCAST_FAIL
  uint16 u16MacTxUcastFail;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_APS_RX_BCAST
  uint16 u16ApsRxBcast;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_APS_TX_BCAST
  uint16 u16ApsTxBcast;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_APS_RX_UCAST
  uint16 u16ApsRxUcast;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_APS_TX_UCAST_SUCCESS
  uint16 u16ApsTxUcastSuccess;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_APS_TX_UCAST_RETRY
  uint16 u16ApsTxUcastRetry;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_APS_TX_UCAST_FAIL
  uint16 u16ApsTxUcastFail;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_ROUTE_DISC_INITIATED
  uint16 u16RouteDiscInitiated;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_NEIGHBOR_ADDED
  uint16 u16NeighborAdded;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_NEIGHBOR_REMOVED
  uint16 u16NeighborRemoved;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_NEIGHBOR_STALE
  uint16 u16NeighborStale;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_JOIN_INDICATION
  uint16 u16JoinIndication;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_CHILD_MOVED
  uint16 u16ChildMoved;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_NWK_FC_FAILURE
  uint16 u16NWKFCFailure;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_APS_FC_FAILURE
  uint16 u16APSFCFailure;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_APS_UNAUTHORIZED_KEY
  uint16 u16APSUnauthorizedKey;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_NWK_DECRYPT_FAILURE
  uint16 u16NWKDecryptFailure;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_APS_DECRYPT_FAILURE
  uint16 u16APSDecryptFailure;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_PACKET_BUFFER_ALLOCATE_FAILURE
  uint16 u16PacketBufferAllocateFailure;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_RELAYED_UCAST
  uint16 u16RelayedUcast;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_PHY_TO_MAC_QUEUE_LIMIT_REACHED
  uint16 u16PhyToMACQueueLimitReached;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_PACKET_VALIDATE_DROP_COUNT
  uint16 u16PacketValidateDropCount;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_AVERAGE_MAC_RETRY_PER_APS_MESSAGE_SENT
  uint16 u16AverageMACRetryPerAPSMessageSent;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_LAST_MESSAGE_LQI
  uint8 u8LastMessageLQI;
 #endif
 #ifdef CLD_DIAGNOSTICS_ATTR_ID_LAST_MESSAGE_RSSI
  int8 i8LastMessageRSSI;
 #endif
#endif 
 zuint16 u16ClusterRevision;
} tsCLD_Diagnostics;

where:

‘Hardware Information’ Attribute Set

The following two attributes can be maintained by the application using the Attribute Access functions detailed in Section 5.2.

• u16NumberOfResets is an optional attribute which acts as a counter of device resets/restarts (note that a factory reset clears this attribute) - thus, the attribute value must be incremented on each restart.

• u16PersistentMemoryWrites is an optional attribute which acts as a counter of the number of writes to persistent memory - thus, the attribute value must be incremented on each write.

‘Stack/Network Information’ Attribute Set

The following attributes must be updated by the application by calling the function eCLD_DiagnosticsUpdate() (see Section 22.3) either periodically (at the highest rate possible) or on receiving an appropriate event from the stack.

u32MacRxBcast is reserved for future use
u32MacTxBcast is reserved for future use
u32MacRxUcast is reserved for future use
u32MacTxUcast is reserved for future use
u16MacTxUcastRetry is reserved for future use
u16MacTxUcastFail is reserved for future use
u16ApsRxBcast is reserved for future use
u16ApsTxBcast is reserved for future use
u16ApsRxUcast is reserved for future use
u16ApsTxUcastSuccess is reserved for future use
u16ApsTxUcastRetry is reserved for future use
u16ApsTxUcastFail is reserved for future use
u16RouteDiscInitiated is reserved for future use
u16NeighborAdded is reserved for future use
u16NeighborRemoved is reserved for future use
u16NeighborStale is reserved for future use
u16JoinIndication is reserved for future use
u16ChildMoved is reserved for future use
u16NWKFCFailure is reserved for future use
u16APSFCFailure is reserved for future use
u16APSUnauthorizedKey is reserved for future use
u16NWKDecryptFailure is reserved for future use
u16APSDecryptFailure is reserved for future use
u16PacketBufferAllocateFailure is reserved for future use
u16RelayedUcast is reserved for future use
u16PhyToMACQueueLimitReached is reserved for future use
u16PacketValidateDropCount is reserved for future use

• u16AverageMACRetryPerAPSMessageSent is an optional attribute which is used to maintain a record of the average number of IEEE802.15.4 MAC-level retries needed to send a message from the APS layer of the stack.

• u8LastMessageLQI is an optional attribute containing the LQI (Link Quality Indicator) value for the last message received, as a value in the range 0 to 255 where 0 indicates the worst link quality and 255 indicates the best link quality.

• i8LastMessageRSSI is an optional attribute containing the RSSI (Receive Signal Strength Indication) value of the last message received.

Note: If the value of u8LastMessageLQI or i8LastMessageRSSI is read remotely, the returned value will relate to the received message that contained the instruction to read the attribute.

Global Attributes

• 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:Diagnostics Cluster

Functions

The following Diagnostics cluster functions are provided:

• eCLD_DiagnosticsCreateDiagnostics

• eCLD_DiagnosticsUpdate

The cluster attributes can also all be accessed using the general attribute read/write functions, as described in Section 2.3.

eCLD_DiagnosticsCreateDiagnostics

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

Description

This function creates an instance of the Diagnostics 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 creates a Diagnostics 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 Diagnostics cluster. This parameter can refer to a pre-filled structure called sCLD_Diagnostics which is provided in the Diagnostics.h file.

• pvEndPointSharedStructPtr: Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_Diagnostics which defines the attributes of Diagnostics 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 (see above).

Returns

• E_ZCL_SUCCESS

• E_ZCL_FAIL

• E_ZCL_ERR_PARAMETER_NULL

• E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eCLD_DiagnosticsUpdate

teZCL_Status eCLD_DiagnosticsUpdate(
    uint8 u8SourceEndPointId);

Description

This function updates the (three) Stack/Network Information attributes (see Section22.2). It should be called periodically by the application (on the cluster server) at the highest rate possible or when an appropriate stack event occurs.

The attributes can otherwise be accessed (for example, read) using the Attribute Access functions detailed in Section 5.2.

Parameters

• u8SourceEndPointId: Number of the local endpoint on which cluster server resides

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

Parent topic:Functions

Parent topic:Diagnostics Cluster

Enumerations

teCLD_Diagnostics_AttributeId

The following structure contains the enumerations used to identify the attributes of the Diagnostics cluster.

typedef enum 
{
 /* Hardware Information attribute IDs */
    E_CLD_DIAGNOSTICS_ATTR_ID_NUMBER_OF_RESETS = 0x0000,
    E_CLD_DIAGNOSTICS_ATTR_ID_PERSISTENT_MEMORY_WRITES,
 /* Stack/Network Information attribute IDs */
    E_CLD_DIAGNOSTICS_ATTR_ID_MAC_RX_BCAST = 0x0100,
    E_CLD_DIAGNOSTICS_ATTR_ID_MAC_TX_BCAST,
    E_CLD_DIAGNOSTICS_ATTR_ID_MAC_RX_UCAST,
    E_CLD_DIAGNOSTICS_ATTR_ID_MAC_TX_UCAST,
    E_CLD_DIAGNOSTICS_ATTR_ID_MAC_TX_UCAST_RETRY,
    E_CLD_DIAGNOSTICS_ATTR_ID_MAC_TX_UCAST_FAIL,
    E_CLD_DIAGNOSTICS_ATTR_ID_APS_RX_BCAST,
    E_CLD_DIAGNOSTICS_ATTR_ID_APS_TX_BCAST,
    E_CLD_DIAGNOSTICS_ATTR_ID_APS_RX_UCAST,
    E_CLD_DIAGNOSTICS_ATTR_ID_APS_TX_UCAST_SUCCESS,
    E_CLD_DIAGNOSTICS_ATTR_ID_APS_TX_UCAST_RETRY,
    E_CLD_DIAGNOSTICS_ATTR_ID_APS_TX_UCAST_FAIL,
    E_CLD_DIAGNOSTICS_ATTR_ID_ROUTE_DISC_INITIATED,
    E_CLD_DIAGNOSTICS_ATTR_ID_NEIGHBOR_ADDED,
    E_CLD_DIAGNOSTICS_ATTR_ID_NEIGHBOR_REMOVED,
    E_CLD_DIAGNOSTICS_ATTR_ID_NEIGHBOR_STALE,
    E_CLD_DIAGNOSTICS_ATTR_ID_JOIN_INDICATION,
    E_CLD_DIAGNOSTICS_ATTR_ID_CHILD_MOVED,
    E_CLD_DIAGNOSTICS_ATTR_ID_NWK_FC_FAILURE,
    E_CLD_DIAGNOSTICS_ATTR_ID_APS_FC_FAILURE,
    E_CLD_DIAGNOSTICS_ATTR_ID_APS_UNAUTHORIZED_KEY,
    E_CLD_DIAGNOSTICS_ATTR_ID_NWK_DECRYPT_FAILURE,
    E_CLD_DIAGNOSTICS_ATTR_ID_APS_DECRYPT_FAILURE,
    E_CLD_DIAGNOSTICS_ATTR_ID_PACKET_BUFFER_ALLOCATE_FAILURE,
    E_CLD_DIAGNOSTICS_ATTR_ID_RELAYED_UCAST,
    E_CLD_DIAGNOSTICS_ATTR_ID_PHY_TO_MAC_QUEUE_LIMIT_REACHED,
    E_CLD_DIAGNOSTICS_ATTR_ID_PACKET_VALIDATE_DROP_COUNT,
    E_CLD_DIAGNOSTICS_ATTR_ID_AVERAGE_MAC_RETRY_PER_APS_MESSAGE_SENT,
    E_CLD_DIAGNOSTICS_ATTR_ID_LAST_MESSAGE_LQI,
    E_CLD_DIAGNOSTICS_ATTR_ID_LAST_MESSAGE_RSSI
} teCLD_Diagnostics_AttributeId;

Parent topic:Enumerations

Parent topic:Diagnostics Cluster

Compile-time Options

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

#define CLD_DIAGNOSTICS

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 DIAGNOSTICS_CLIENT
#define DIAGNOSTICS_SERVER

Optional Attributes

Add this line to enable the optional Average MAC Retry Per APS Message Sent attribute:

#define CLD_DIAGNOSTICS_ATTR_ID_AVERAGE_MAC_RETRY_PER_APS_MESSAGE_SENT

Add this line to enable the optional Last Message LQI attribute:

#define CLD_DIAGNOSTICS_ATTR_ID_LAST_MESSAGE_LQI

Add this line to enable the optional Last Message RSSI attribute:

#define CLD_DIAGNOSTICS_ATTR_ID_LAST_MESSAGE_RSSI

Global Attributes

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

#define CLD_DIAGNOSTICS_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).

Parent topic:Diagnostics Cluster