Commissioning Cluster

This chapter details the Commissioning cluster which is defined in the ZCL and is a optional cluster for all ZigBee devices.

The Commissioning cluster has a Cluster ID of 0x0015.

Overview

The Commissioning cluster is used for commissioning the ZigBee stack on a device during network installation and defining the device behaviour with respect to the ZigBee network (it does not affect applications operating on the devices).

The Commissioning cluster server must be implemented on a device that is to be commissioned into a network.
The Commissioning cluster client must be implemented on a device that can initiate the commissioning of another device into a network - for example, on a commissioning tool.

This optional cluster is enabled by defining CLD_COMMISSIONING in the zcl_options.h file. The inclusion of the client or server software must also 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 Commissioning cluster are fully detailed in Section 43.10.

Only server attributes are supported and all are optional - the required attributes must be enabled in the compile-time options. The information that can potentially be stored in the Commissioning cluster is organised into the following attribute sets: Start-up Parameters, Join Parameters, End Device Parameters, Concentrator Parameters.

Note: The attribute values are set by the application but the application must ensure that these values are synchronized with the settings and NIB values for the ZigBee PRO stack.

The Commissioning cluster also provides optional commands, which can be enabled in the compile-time options.

Parent topic:Commissioning Cluster

Commissioning Cluster structure and attributes

The Commissioning cluster has only server attributes that are contained in the following tsCLD_Commissioning structure, organised as a set of structures containing the Commissioning cluster attribute sets:

typedef struct
{
#ifdef COMMISSIONING_SERVER    
/* Start- attribute setup Parameters attribute set */
    tsCLD_StartupParameters         sStartupParameters;
/* Join Parameters attribute set */
    tsCLD_JoinParameters            sJoinParameters;
/* End Device Parameters attribute set */
    tsCLD_EndDeviceParameters       sEndDeviceParameters;
/* Concentrator Parameters attribute set */
    tsCLD_ConcentratorParameters    sConcentratorParameters;
#endif
    zuint16       u16ClusterRevision;
} tsCLD_Commissioning;

where:

sStartupParameters is a structure containing the attributes of the Start-up Parameters attribute set - this structure and the associated attributes are detailed in [Section 43.2.1](start-up_parameters_tscld_startupparameters.md#id_d22b5600-7fda-403a-90c7-d433548a4983)
sJoinParameters is a structure containing the attributes of the Join Parameters attribute set - this structure and the associated attributes are detailed in [Section 43.2.2](join_parameters_tscld_joinparameters.md#id_02f93815-3ce8-498e-a271-cd3675dc7015) 
sEndDeviceParameters is a structure containing the attributes of the End Device Parameters attribute set - this structure and the associated attributes are detailed in [Section 43.2.3](end_device_parameters_tscld_enddeviceparameters.md#id_a29fedbf-ef44-458b-88af-f134a455d4c0)    
sConcentratorParameters is a structure containing the attributes of the Concentrator Parameters attribute set - this structure and the associated attributes are detailed in [Section 43.2.4](concentrator_parameters_tscld_concentratorparamete.md#id_3713b9e8-5da6-4db8-b678-617069de5091)
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](../../ZCL_fundamentals/topics/global_attributes.md#id_8f80e769-8ccd-4b4f-8609-579f4457d527).

Note: Memory is allocated at compile-time for all the Commissioning cluster attributes.

Start-up Parameters (tsCLD_StartupParameters)

The tsCLD_StartupParameters structure below contains the attributes of the Start-up Parameters attribute set:

typedef struct
{
#ifdef     CLD_COMMISSIONING_ATTR_SHORT_ADDRESS
    uint16              u16ShortAddress;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_EXTENED_PAN_ID
    zieeeaddress        u64ExtPanId;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_PAN_ID
    uint16              u16PANId;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_CHANNEL_MASK
    zbmap32             u32ChannelMask;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_PROTOCOL_VERSION
    uint8               u8ProtocolVersion;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_STACK_PROFILE
    uint8               u8StackProfile;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_START_UP_CONTROL
    zenum8               e8StartUpControl;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_TC_ADDR
    zieeeaddress         u64TcAddr;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_TC_MASTER_KEY
    tsZCL_Key            sTcMasterKey;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_NWK_KEY
    tsZCL_Key           sNwkKey;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_USE_INSECURE_JOIN
    bool_t              bUseInsecureJoin;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_PRE_CONFIG_LINK_KEY
    tsZCL_Key           sPreConfigLinkKey;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_NWK_KEY_SEQ_NO
    uint8               u8NwkKeySeqNo;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_NWK_KEY_TYPE
    zenum8              e8NwkKeyType;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_NWK_MANAGER_ADDR
    uint16              u16NwkManagerAddr;
#endif
} tsCLD_StartupParameters;

where:

u``16ShortAddress is the intended 16-bit network address of the device (which will be used provided that the address is not to be obtained from the parent - that is, on the Co-ordinator or on other ZigBee PRO devices for which e8StartUpControl is set to 0x00).
u64ExtPanId is the 64-bit Extended PAN ID of the network which the device should join (the special value of 0xFFFFFFFF can be used to specify no particular network).
u16PANId is the 16-bit PAN ID of the network which the device should join (which will be used provided that the PAN ID is not to be obtained from the parent - that is, on the Co-ordinator or on other ZigBee PRO devices for which e8StartUpControl is set to 0x00).
u32ChannelMask is a 32-bit bitmap representing an IEEE 802.15.4 channel mask which indicates the set of radio channels that the device should scan as part of the network join or formation process.
u8ProtocolVersion is used to indicate the ZigBee protocol version that the device is to support (only needed if the device potentially supports multiple versions).
u8StackProfile is used to indicate the stack profile to be implemented on the device - the possible values are 0x01 for ZigBee Stack profile and 0x02 for ZigBee PRO Stack profile.
e8StartUpControl is an enumeration which is used to indicate the start-up mode of the device (e.g. device should form a network with the specified Extended PAN ID) and therefore determines how certain other attributes will be used. For further information on how this attribute is used, refer to the ZCL Specification.
u64TcAddr is the 64-bit IEEE/MAC address of the Trust Centre node for the network with the specified Extended PAN ID (this is needed if security is to be implemented).
sTcMasterKey is the master key to be used during key establishment with the specified Trust Centre (this is needed if security is to be implemented). The default is a 128-bit zero value indicating that the key is unspecified.
sNwkKey is the network key to be used when communicating within the network with the specified Extended PAN ID (this is needed if security is to be implemented). The default is a 128-bit zero value indicating that the key is unspecified.
bUseInsecureJoin is a Boolean flag which, when set to TRUE, allows an unsecured join as a fall-back (even if security is enabled).
sPreConfigLinkKey is the pre-configured link key between the device and the Trust Centre (this is needed if security is to be implemented). The default is a 128-bit zero value indicating that the key is unspecified.
u8NwkKeySeqNo is the 8-bit sequence number for the network key. The default value is 0x00.
e8NwkKeyType is the type of the network key. The default value is 0x01 when u8StackProfile is 0x01 and 0x05 when u8StackProfile is 0x02.
u16NwkManagerAddr is the 16-bit network address of the Network Manager. The default value is 0x0000, indicating that the Network Manager is the ZigBee Co-ordinator.

Parent topic:Commissioning Cluster structure and attributes

Join Parameters (tsCLD_JoinParameters)

The tsCLD_JoinParameters structure below contains the attributes of the Join Parameters attribute set:

typedef struct
{
#ifdef     CLD_COMMISSIONING_ATTR_SCAN_ATTEMPTS
    uint8         u8ScanAttempts;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_TIME_BW_SCANS
    uint16         u16TimeBwScans;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_REJOIN_INTERVAL
    uint16         u16RejoinInterval;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_MAX_REJOIN_INTERVAL
    uint16         u16MaxRejoinInterval;
#endif
} tsCLD_JoinParameters;

where:

u8ScanAttempts is the number of scan attempts to make before selecting a parent to join. The default value is 0x05.
u16TimeBwScans is the time-interval, in milliseconds, between consecutive scan attempts. The default value is 0x64.
u16RejoinInterval is the time-interval, in seconds, between consecutive attempts to rejoin the network for an End Device which has lost its network connection. The default value is 0x3C.
u16MaxRejoinInterval is an upper limit, in seconds, on the value of the u16RejoinInterval attribute. The default value is 0x0E10.

Parent topic:Commissioning Cluster structure and attributes

End Device Parameters (tsCLD_EndDeviceParameters)

The tsCLD_EndDeviceParameters structure below contains the attributes of the End Device Parameters attribute set:

typedef struct
{
#ifdef     CLD_COMMISSIONING_ATTR_INDIRECT_POLL_RATE
    uint16         u16IndirectPollRate;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_PARENT_RETRY_THRSHLD
    uint8          u8ParentRetryThreshold;
#endif
} tsCLD_EndDeviceParameters;

where:

u16IndirectPollRate is the time-interval, in milliseconds, between consecutive polls from an End Device which polls its parent while awake (an End Device with a receiver that is inactive while sleeping).
u8ParentRetryThreshold is the number of times that an End Device should attempt to re-contact its parent before initiating the rejoin process.

Parent topic:Commissioning Cluster structure and attributes

Concentrator Parameters (tsCLD_ConcentratorParameters)

The sCLD_ConcentratorParameters structure below contains the attributes of the Concentrator Parameters attribute set:

typedef struct
{
#ifdef     CLD_COMMISSIONING_ATTR_CONCENTRATOR_FLAG
    bool_t         bConcentratorFlag;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_CONCENTRATOR_RADIUS
    uint8         u8ConcentratorRadius;
#endif
#ifdef     CLD_COMMISSIONING_ATTR_CONCENTRATOR_DISCVRY_TIME
    uint8         u8ConcentratorDiscoveryTime;
#endif
} tsCLD_ConcentratorParameters;

where:

bConcentratorFlag is a Boolean flag which, when set to TRUE, enables the device as a concentrator for many-to-one routing. The default value is FALSE.
u8ConcentratorRadius is the hop-count radius for concentrator route discoveries. The default value is 0x0F.
u8ConcentratorDiscoveryTime is the time-interval, in seconds, between consecutive discoveries of inbound routes initiated by the concentrator. The default value is 0x0000, indicating that this time-interval is unknown and the discoveries must be triggered by the application.

Parent topic:Commissioning Cluster structure and attributes

Parent topic:Commissioning Cluster

Attribute Settings

The Commissioning cluster structure contains only optional attributes. Each attribute is enabled/disabled through a corresponding macro defined in the zcl_options.h file (see Section 43.10) - for example, u16ShortAddress is enabled/disabled through the macro CLD_COMM_ATTR_SHORT_ADDRESS.

The function eCLD_CommissioningSetAttribute() can be used on the cluster server to write values to any one of the four attribute sets of the Commissioning cluster.

Parent topic:Commissioning Cluster

Initialisation

The function eCLD_CommissioningClusterCreateCommissioning() is used to create an instance of the Commissioning cluster. The function is generally called by the initialization function for the host device.

Parent topic:Commissioning Cluster

Commissioning Commands

A number of commissioning commands are provided to allow a Commissioning cluster client to remotely request actions relating to the Start-up Parameters attribute set (see Section 43.2.1) on a cluster server. This includes initiating a device restart from the current Start-up Parameter values, as well as the management of these attributes.

Device Start-up

The ‘current’ set of Start-up Parameter values on a cluster server are those used in the start-up procedure, which can be remotely initiated from a cluster client using the function eCLD_CommissioningCommandRestartDeviceSend(). This function sends a Restart Device command to the remote device hosting the cluster server. This command provides a number of options concerning the timing of the restart:

Without delay: The start-up procedure is invoked as soon as the command is received. This option requires both the delay and jitter to be specified as zero.
**With delay:**The start-up procedure is invoked after a specified delay (in seconds). If no delay is required, the delay period must be specified as zero.
With delay and jitter: The start-up procedure is invoked after a specified delay (in seconds) with a random jitter period added. It is necessary to indicate a maximum jitter period but the actual period will be randomly generated. If no jitter is required, the maximum jitter period must be specified as zero.

Note: If only jitter is required, the delay period must be specified as zero and the maximum jitter period must be non-zero.

In all of the above cases, it is possible to configure the start-up procedure to begin either without any further delay or at a ‘convenient’ moment (when there are no pending actions that should be completed before the restart).

The above options are configured in the command payload (see Section 43.9.2).

The cluster server will send a Restart Device Response to the requesting client before invoking the start-up procedure or starting the countdown (for the delay).

Parent topic:Commissioning Commands

Stored Start-up Parameters

In addition to the ‘current’ set of values for the Start-up Parameters attribute set, the cluster server can store other sets of values for these attributes in non-volatile memory. Each stored set of Start-up Parameter values is assigned a unique index number. At any time, a particular stored set of values can be retrieved and loaded to become the current set. Functions are provided for managing the saved sets of Start-up Parameter values.

Saving Start-up Parameters

In order to save a set of Start-up Parameter values, it is first necessary to set them as the current attribute values - this must be done locally by the application on the device hosting the server, possibly using the function eCLD_CommissioningSetAttribute().

The application on a device hosting a cluster client can send a Save Start-up Parameters command to the cluster server in order to request that the current set of Start-up Parameter values is saved to non-volatile memory. This can be done by calling eCLD_CommissioningCommandSaveStartupParamsSend () or, alternatively, eCLD_CommissioningCommandModifyStartupParamsSend (). The index number of the saved record must be specified in the request. If this number has already been used, the existing stored values will be over-written with the new values.

It is the responsibility of the user application on the device hosting the server to perform the save. When the command arrives, a ZCL custom event will be generated and the request should be handled by the user-defined callback function for the endpoint on which the application is located. The server will automatically send a Save Start-up Parameters Response to the requesting client.

Parent topic:Stored Start-up Parameters

Retrieving Stored Start-up Parameters

A set of Start-up Parameter values that have been stored by in non-volatile memory (as described in Section 43.5.2.1) can be retrieved and loaded as the current set of values. The required stored set of values is specified using its unique index number.

The application on a device hosting a cluster client can send a Restore Start-up Parameters command to the cluster server in order to request that the specified set of Start-up Parameter values is loaded from non-volatile memory. This can be done by calling eCLD_CommissioningCommandRestoreStartupParamsSend () or, alternatively, eCLD_CommissioningCommandModifyStartupParamsSend (). The index number of the relevant set must be specified in the request.

It is the responsibility of the user application on the device hosting the server to retrieve the relevant set of values and load them as the current values. When the command arrives, a ZCL custom event will be generated and the request should be handled by the user-defined callback function for the endpoint on which the application is located. The server will automatically send a Restore Start-up Parameters Response to the requesting client.

A device restart is required in order to implement the loaded values, as described in Section 43.5.1.

Parent topic:Stored Start-up Parameters

Parent topic:Commissioning Commands

Reset Start-up Parameters to Default Values

A set of Start-up Parameters on the cluster server can be reset to their default values.

The application on a device hosting a cluster client can send a Reset Start-up Parameters command to the cluster server in order to request that the Start-up Parameters are reset to their default values. This can be done by calling eCLD_CommissioningCommandResetStartupParamsSend () or, alternatively, eCLD_CommissioningCommandModifyStartupParamsSend (). Options are available concerning the set(s) of Start-up Parameters to reset - any combination of the following can be performed:

Reset the current set of Start-up Parameters
Reset all stored sets of Start-up Parameters or the stored set with given index
Erase the stored set of Start-up Parameters with given index

The required options must be specified in the request. The option to erase a stored set of Start-up Parameters allows storage space to be freed up.

It is the responsibility of the user application on the device hosting the server to reset the relevant set(s) of values. When the command arrives, a ZCL custom event will be generated and the request should be handled by the user-defined callback function for the endpoint on which the application is located. The server will automatically send a Reset Start-up Parameters Response to the requesting client.

A device restart is required in order to implement the reset (current) values, as described in Section 43.5.1.

Parent topic:Commissioning Commands

Parent topic:Commissioning Cluster

Commissioning Events

The Commissioning cluster has its own events that are handled through the callback mechanism outlined in Chapter 3. If a device uses this cluster then application-specific Commissioning event handling must be included in the user-defined callback function for the associated endpoint, where this callback function is registered through the relevant endpoint registration function. This callback function will then be invoked when a Commissioning event occurs and needs the attention of the application.

For a Commissioning 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_CommissioningCallBackMessage structure (fully detailed in Section43.9.6).

typedef struct
{
    uint8                      u8CommandId;
    union
    {
        tsCLD_Commissioning_RestartDevicePayload                    
                              *psRestartDevicePayload;
        tsCLD_Commissioning_ModifyStartupParametersPayload          
                              *psModifyStartupParamsPayload; 
    } uReqMessage;
    union
    {
        tsCLD_Commissioning_ResponsePayload                         
                              *psCommissioningResponsePayload; 
    } uRespMessage;
} tsCLD_CommissioningCallBackMessage;

When a Commissioning event occurs, one of a number of command types could have been received. The relevant command type is specified through the u8CommandId field of the tsCLD_CommissioningCallBackMessage structure. The possible command types are detailed below.

The table below details the command types that can be received by the cluster server.

u8CommandId Enumeration	Description
E_CLD_COMMISSIONING_CMD_RESTART_DEVICE	A Restart Device command has been received
E_CLD_COMMISSIONING_CMD_SAVE_STARTUP_PARAMS	A Save Start-up Parameters command has been received
E_CLD_COMMISSIONING_CMD_RESTORE_STARTUP_PARAMS	A Restore Start-up Parameters command has been received
E_CLD_COMMISSIONING_CMD_RESET_STARTUP_PARAMS	A Reset Start-up Parameters command has been received

The table below details the command types that can be received by the cluster client.

u8CommandId Enumeration	Description
E_CLD_COMMISSIONING_CMD_RESTART_DEVICE	A Restart Device response has been received
E_CLD_COMMISSIONING_CMD_SAVE_STARTUP_PARAMS	A Save Start-up Parameters response has been received
E_CLD_COMMISSIONING_CMD_RESTORE_STARTUP_PARAMS	A Restore Start-up Parameters response has been received
E_CLD_COMMISSIONING_CMD_RESET_STARTUP_PARAMS	A Reset Start-up Parameters response has been received

Parent topic:Commissioning Cluster

Functions

The following Commissioning cluster function is provided:

eCLD_CommissioningClusterCreateCommissioning

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

Description

This function creates an instance of the Commissioning 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 Commissioning 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 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

Note: (JNUG3131).

When used, this function 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 is automatically adjusted by the compiler using the following declaration:

uint8 au8CommissioningAttributeControlBits
[(sizeof(asCLD_CommissioningClusterAttributeDefinitions) / sizeof(tsZCL_AttributeDefinition))];

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 initialising 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 Commissioning cluster. This parameter can refer to a pre-filled structure called sCLD_Commissioning which is provided in the Commissioning.h file.
pvEndPointSharedStructPtr Pointer to the shared structure used for attribute storage. This parameter should be the address of the structure of type tsCLD_Commissioning which defines the attributes of Commissioning 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). For a cluster client, set this pointer to NULL.
psCustomDataStructure Pointer to a structure containing the storage for internal functions of the cluster (see Section 43.9.5)

Returns

E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eCLD_CommissioningCommandRestartDeviceSend

teZCL_Status eCLD_CommissioningCommandRestartDeviceSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber, tsCLD_Commissioning_RestartDevicePayload *psPayload);

Description

This function can be used on a Commissioning cluster client to send a Restart Device command to a cluster server on a remote device. This command is used to run the start-up procedure with a new set of values for the Start-up Parameters attributes (these values must already be installed). The new values may be implemented immediately or after a specified delay with an optional jitter.

When the command arrives, a ZCL custom event will be generated and the request should be handled by the user-defined callback function for the endpoint on which the application is located (see Section 43.6). Before running the start-up procedure or starting the countdown (for the delay), the server will send a Restart Device Response to the requesting client, where a ZCL custom event will be generated.

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 message 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 this message (see Section 43.9.2)

Returns

E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eCLD_CommissioningCommandSaveStartupParamsSend

teZCL_Status eCLD_CommissioningCommandSaveStartupParamsSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber
    tsCLD_Commissioning_ModifyStartupParametersPayload *psPayload);

Description

This function can be used on a Commissioning cluster client to send a Save Start-up Parameters command to a cluster server on a remote device. This command instructs the server to locally save a set of values for the attributes of the Start-up Parameters attribute set. A device can store different sets of start-up parameters (in non-volatile memory), with each set being referenced using an index number. This index number must be specified and if a set has already been stored with the same index number then the stored values will be over-written with the new values.

It is the responsibility of the user application on the device hosting the server to implement the command. When the command arrives, a ZCL custom event will be generated and the request should be handled by the user-defined callback function for the endpoint on which the application is located (see Section 43.6). The server will automatically send a Save Start-up Parameters Response to the client, where a ZCL custom event will be generated.

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 message 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 this message (see Section 43.9.3)

Returns

E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eCLD_CommissioningCommandRestoreStartupParamsSend

teZCL_Status eCLD_CommissioningCommandRestoreStartupParamsSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber, tsCLD_Commissioning_*psPayload)

Description

This function can be used on a Commissioning cluster client to send a Restore Start-up Parameters command to a cluster server on a remote device. This command instructs the server to load a saved set of values for the attributes of the Start-up Parameters attribute set. The index of the required set of Start-up Parameters must be specified in the command payload. Note that the command does not instruct the server to implement the loaded values using the start-up procedure - a Restart Device command is required to do this.

It is the responsibility of the user application on the device hosting the server to implement the command. When the command arrives, a ZCL custom event will be generated and the request should be handled by the user-defined callback function for the endpoint on which the application is located (see Section 43.6). The server will automatically send a Restore Start-up Parameters Response to the client, where a ZCL custom event will be generated.

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 message 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 this message (see Section 43.9.3)

Returns

E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eCLD_CommissioningCommandResetStartupParamsSend

teZCL_Status eCLD_CommissioningCommandResetStartupParamsSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber, tsCLD_*psPayload);

Description

This function can be used on a Commissioning cluster client to send a Reset Start-up Parameters command to a cluster server on a remote device. This command instructs the server to set the current Start-up Parameters to their default values. It is also possible to set one or all of any saved sets of Start-up Parameters to the defaults. The command can also be used to delete a specified set of saved Start-up Parameters.

It is the responsibility of the user application on the device hosting the server to implement the command. When the command arrives, a ZCL custom event will be generated and the request should be handled by the user-defined callback function for the endpoint on which the application is located (see Section 43.6). The server will automatically send a Reset Start-up Parameters Response to the client, where a ZCL custom event will be generated.

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 message 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 this message (see Section 43.9.3)

Returns

E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eCLD_CommissioningCommandModifyStartupParamsSend

teZCL_Status eCLD_CommissioningCommandModifyStartupParamsSend(
    uint8 u8SourceEndPointId,
    uint8 u8DestinationEndPointId,
    tsZCL_Address *psDestinationAddress,
    uint8 *pu8TransactionSequenceNumber,
    tsCLD_Commissioning_ModifyStartupParametersPayload *psPayload,
    teCLD_Commissioning_Command eCLD_Commissioning_Command);

Description

This function can be used on a Commissioning cluster client to send a command to modify a set of values for the Start-up Parameters attributes in the cluster server on a remote device. One of four commands can be specified and sent, as listed and described in the table below:

Command	Description
Restart Device	Used to run the start-up procedure with the current set of values for the Start-up Parameters attributes, as described for the function eCLD_Com-missioningCommandRestartDeviceSend(). These values may have been loaded using the Restore Start-up Parameters or Reset Start-up Parameters command.
Save Start-up Parameters	Used to save the current set of Start-up Parameter values with the speci-fied index, as described for the function eCLD_CommissioningCom-mandSaveStartupParamsSend().
Restore Start-up Parameters	Used to load the saved set of Start-up Parameter values with the specified index, such that these values become the current Start-up Parameter val-ues, as described for the function eCLD_CommissioningCommandRe-storeStartupParamsSend(). Note that these values are not implemented, which requires a Restart Device command.
Reset Start-up Parameters	Used to reset the current Start-up Parameters to their defaults. One or all of any stored sets of Start-up Parameter values can also be reset to the defaults, as described for the function eCLD_CommissioningComman-dResetStartupParamsSend(). The command can also be used to delete a particular set of stored Start-up Parameters.

It is the responsibility of the user application on the device hosting the server to implement the command. When the command arrives, a ZCL custom event will be generated and the request should be handled by the user-defined callback function for the endpoint on which the application is located (see Section 43.6). The server will automatically send a response for the relevant command to the client, where a ZCL custom event will be generated.

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 message 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 this message (see Section 43.9.3)
eCLD_Commissioning_Command Type of command to send, one of:
E_CLD_COMMISSIONING_CMD_RESTART_DEVICE
E_CLD_COMMISSIONING_CMD_SAVE_STARTUP_PARAMS
E_CLD_COMMISSIONING_CMD_RESTORE_STARTUP_PARAMS
E_CLD_COMMISSIONING_CMD_RESET_STARTUP_PARAMS

Returns

E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

eCLD_CommissioningSetAttribute

teZCL_Status eCLD_CommissioningSetAttribute(
    uint8 u8SourceEndPointId,
    teCLD_Commissioning_AttributeSet eAttributeSet,
    void *vptrAttributeSetStructure);

Description {

This function can be used on a Commissioning cluster server to write values to a particular attribute set of the Commissioning cluster.

Parameters

u8SourceEndPointId Number of the local endpoint through which to issue the request.
eAttributeSet Enumeration indicating attribute set to write to, one of:
E_CLD_COMMISSIONING_ATTR_SET_STARTUP_PARAMS
E_CLD_COMMISSIONING_ATTR_SET_JOIN_PARAMS
E_CLD_COMMISSIONING_ATTR_SET_ENDDEVICE_PARAMS
E_CLD_COMMISSIONING_ATTR_SET_CONCENTRATOR_PARAMS
vptrAttributeSetStructure Pointer to a structure containing the new values for the attribute set - the relevant structures are detailed in Section 43.2

Returns

E_ZCL_SUCCESS
E_ZCL_FAIL
E_ZCL_ERR_PARAMETER_NULL
E_ZCL_ERR_INVALID_VALUE

Parent topic:Functions

Parent topic:Commissioning Cluster

Enumerations

teCLD_Commissioning_AttributeID

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

typedef enum 
{
    E_CLD_COMMISSIONING_ATTR_ID_SHORT_ADDRESS             = 0x0000,
    E_CLD_COMMISSIONING_ATTR_ID_EXT_PANID,
    E_CLD_COMMISSIONING_ATTR_ID_PANID,
    E_CLD_COMMISSIONING_ATTR_ID_CHANNEL_MASK,
    E_CLD_COMMISSIONING_ATTR_ID_PROTOCOL_VERSION,
    E_CLD_COMMISSIONING_ATTR_ID_STACK_PROFILE,
    E_CLD_COMMISSIONING_ATTR_ID_STARTUP_CONTROl,
    E_CLD_COMMISSIONING_ATTR_ID_TC_ADDR                   = 0x0010,
    E_CLD_COMMISSIONING_ATTR_ID_TC_MASTER_KEY,
    E_CLD_COMMISSIONING_ATTR_ID_NETWORK_KEY,
    E_CLD_COMMISSIONING_ATTR_ID_USE_INSECURE_JOIN,
    E_CLD_COMMISSIONING_ATTR_ID_PRECONFIG_LINK_KEY,
    E_CLD_COMMISSIONING_ATTR_ID_NWK_KEY_SEQ_NO,
    E_CLD_COMMISSIONING_ATTR_ID_NWK_KEY_TYPE,
    E_CLD_COMMISSIONING_ATTR_ID_NWK_MANAGER_ADDR,
    E_CLD_COMMISSIONING_ATTR_ID_SCAN_ATTEMPTS            = 0x0020,
    E_CLD_COMMISSIONING_ATTR_ID_TIME_BW_SCANS,
    E_CLD_COMMISSIONING_ATTR_ID_REJOIN_INTERVAL,
    E_CLD_COMMISSIONING_ATTR_ID_MAX_REJOIN_INTERVAL,
    E_CLD_COMMISSIONING_ATTR_ID_INDIRECT_POLL_RATE       = 0x0030,
    E_CLD_COMMISSIONING_ATTR_ID_PARENT_RETRY_THRSHOLD,
    E_CLD_COMMISSIONING_ATTR_ID_CONCENTRATOR_FLAG        = 0x0040,
    E_CLD_COMMISSIONING_ATTR_ID_CONCENTRATOR_RADIUS,
    E_CLD_COMMISSIONING_ATTR_ID_CONCENTRATOR_DISCVRY_TIME,
} teCLD_Commissioning_AttributeID;;

Parent topic:Enumerations

teCLD_Commissioning_AttributeSet

The following structure contains the enumerations used to identify the attribute sets of the Commissioning cluster.

typedef enum 
{
    E_CLD_COMMISSIONING_ATTR_SET_STARTUP_PARAMS       = 0x00,    
    E_CLD_COMMISSIONING_ATTR_SET_JOIN_PARAMS,                      
    E_CLD_COMMISSIONING_ATTR_SET_ENDDEVICE_PARAMS,                   
    E_CLD_COMMISSIONING_ATTR_SET_CONCENTRATOR_PARAMS                     
} teCLD_Commissioning_AttributeSet;

Parent topic:Enumerations

teCLD_Commissioning_Command

The following structure contains the enumerations used to identify commands of the Commissioning cluster (the same enumerations are used for requests and their corresponding responses).

typedef enum 
{
    E_CLD_COMMISSIONING_CMD_RESTART_DEVICE             = 0x00,
    E_CLD_COMMISSIONING_CMD_SAVE_STARTUP_PARAMS,
    E_CLD_COMMISSIONING_CMD_RESTORE_STARTUP_PARAMS,
    E_CLD_COMMISSIONING_CMD_RESET_STARTUP_PARAMS 
} teCLD_Commissioning_Command;

The above enumerations are described in the table below:

Enumeration	Command
E_CLD_COMMISSIONING_CMD_RESTART_DEVICE	Restart Device request or response
E_CLD_COMMISSIONING_CMD_SAVE_STARTUP_PARAMS	Save Start-up Parameters request or response
E_CLD_COMMISSIONING_CMD_RESTORE_STARTUP_PARAMS	Restore Start-up Parameters request or response
E_CLD_COMMISSIONING_CMD_RESET_STARTUP_PARAMS	Reset Start-up Parameters request or response

Parent topic:Enumerations

Parent topic:Commissioning Cluster

Structures

Attribute Set Structures

The following structures contain the Commissioning cluster attribute sets and are detailed in the referenced sections:

tsCLD_StartupParameters - see Section 43.2.1
tsCLD_JoinParameters - see Section 43.2.2
tsCLD_EndDeviceParameters - see Section 43.2.3
tsCLD_ConcentratorParameters - see Section 43.2.4

Parent topic:Structures

tsCLD_Commissioning_RestartDevicePayload

The following structure contains the payload of a Restart Device command.

typedef struct
{
    zbmap8                  u8Options;
    uint8                   u8Delay;
    uint8                   u8Jitter;
} tsCLD_Commissioning_RestartDevicePayload;

where:

u8Options is a 8-bit bitmap specifying the required start-up options:

Bits	Option	Description
0-2	Start-up Mode	Determines the starting state of the device restart:

0b000: Restart with current Start-up Parameter values
0b001: Restart from existing stack state

All other values are reserved.

| |3|Immediate|Determines how quickly the start-up procedure will begin follow-ing receipt of the command or the specified delay/jitter:

1: Immediately
0: At a convenient moment (e.g. following any pending actions)

| |4-7|-|Reserved|

u8Delay specifies the time-delay, in seconds, before the start-up procedure should be executed. 
u8Jitter is a value which determines the possible range of values of the jitter that is added to the delay u8Delay - the jitter, in milliseconds, is a random value in the range 0 to u8Jitter x 80.

Parent topic:Structures

tsCLD_Commissioning_ModifyStartupParametersPayload

The following structure contains the payload of the following commands: Save Start-up Parameters, Restore Start-up Parameters and Reset Start-up Parameters.

typedef struct
{
    zbmap8                  u8Options;
    uint8                   u8Index;
} tsCLD_Commissioning_ModifyStartupParametersPayload;

where:

u8Options is an 8-bit bitmap specifying the required reset options for the Reset Start-up Parameters command (it is not used by the other commands):

Bits	Option	Description
0	Reset Current	Determines whether the current Start-up Parameters will be reset to their default values:

1: Reset to default values
0: Do not reset (remain unchanged)

| |1|Reset All|Determines whether all stored Start-up Parameter sets will be reset to their default values:

1: Reset all stored Start-up Parameter sets
0: Reset the stored Start-up Parameter set with specified index

| |2|Erase Index|Determines whether the stored Start-up Parameter set with speci-fied index will be erased:

1: Erase Start-up Parameter set with specified index
0: Do not erase Start-up Parameter set with specified index

| |3-7|-|Reserved|

u8Index is the index of the saved Start-up Parameter set to which actions specified in u8Options relate (this index is ignored if no actions are specified).

Parent topic:Structures

tsCLD_Commissioning_ResponsePayload

The following structure contains the payload of the responses to the following commands: Save Start-up Parameters, Restore Start-up Parameters and Reset Start-up Parameters.

typedef struct
{
    zenum8                  u8Status;
} tsCLD_Commissioning_ResponsePayload; 

where u8Status contains one of the ZCL command status codes listed and described in Section 7.1.4.

Parent topic:Structures

tsCLD_CommissioningCustomDataStructure

The Commissioning 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
{
    tsZCL_ReceiveEventAddress              sReceiveEventAddress;
    tsZCL_CallBackEvent                    sCustomCallBackEvent;
    tsCLD_CommissioningCallBackMessage     sCallBackMessage;
} tsCLD_CommissioningCustomDataStructure;

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

Parent topic:Structures

tsCLD_CommissioningCallBackMessage

For a Commissioning 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_CommissioningCallBackMessage structure:

typedef struct
{
    uint8                      u8CommandId;
    union
    {
        tsCLD_Commissioning_RestartDevicePayload                    
                              *psRestartDevicePayload;
        tsCLD_Commissioning_ModifyStartupParametersPayload          
                              *psModifyStartupParamsPayload; 
    } uReqMessage;
    union
    {
        tsCLD_Commissioning_ResponsePayload                         
                              *psCommissioningResponsePayload; 
    } uRespMessage;
} tsCLD_CommissioningCallBackMessage;

where:

u8CommandId indicates the type of Commissioning command that has been received by a cluster server or client (the same enumerations are used for requests on the server and responses on the client), one of:
- E_CLD_COMMISSIONING_CMD_RESTART_DEVICE
- E_CLD_COMMISSIONING_CMD_SAVE_STARTUP_PARAMS
- E_CLD_COMMISSIONING_CMD_RESTORE_STARTUP_PARAMS
- E_CLD_COMMISSIONING_CMD_RESET_STARTUP_PARAMS
uReqMessage is a union containing the payload of a request command in the following form:
- psRestartDevicePayload is a pointer to a structure containing the Restart Device command payload - see Section 43.9.2
- psModifyStartupParamsPayload is a pointer to a structure containing the (common) payload for the Save Start-up Parameters, Restore Start-up Parameters and Reset Start-up Parameters commands - see Section43.9.3
uRespMessage is a union containing the payload of a response command in the following form:
- psCommissioningResponsePayload is a pointer to a structure containing the (common) payload for the Save Start-up Parameters, Restore Start-up Parameters and Reset Start-up Parameters responses - see Section 43.9.4

For further information on Commissioning cluster events, refer to Section 43.6.

Parent topic:Structures

Parent topic:Commissioning Cluster

Compile-time options

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

#define CLD_COMMISSIONING

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

#define COMMISSIONING_CLIENT
#define COMMISSIONING_SERVER

Optional Attributes

The Commissioning cluster contains attributes that may be optionally enabled at compile-time by adding some or all of the following lines to the zcl_options.h file (see Section 43.2 and Section 43.3):

#define         CLD_COMM_ATTR_SHORT_ADDRESS
#define CLD_COMM_ATTR_EXTENED_PAN_ID
#define CLD_COMM_ATTR_PAN_ID
#define CLD_COMM_ATTR_CHANNEL_MASK
#define CLD_COMM_ATTR_PROTOCOL_VERSION
#define CLD_COMM_ATTR_STACK_PROFILE
#define CLD_COMM_ATTR_START_UP_CONTROL
        #define CLD_COMM_ATTR_TC_ADDR
#define CLD_COMM_ATTR_TC_MASTER_KEY
        #define CLD_COMM_ATTR_NWK_KEY
#define CLD_COMM_ATTR_USE_INSECURE_JOIN
        #define CLD_COMM_ATTR_PRE_CONFIG_LINK_KEY
#define CLD_COMM_ATTR_NWK_KEY_SEQ_NO
        #define CLD_COMM_ATTR_NWK_KEY_TYPE
#define CLD_COMM_ATTR_NWK_MANAGER_ADDR
#define CLD_COMM_ATTR_SCAN_ATTEMPTS
#define CLD_COMM_ATTR_TIME_BW_SCANS
#define CLD_COMM_ATTR_REJOIN_INTERVAL
#define CLD_COMM_ATTR_MAX_REJOIN_INTERVAL
        #define CLD_COMM_ATTR_INDIRECT_POLL_RATE
#define CLD_COMM_ATTR_PARENT_RETRY_THRSHLD
#define CLD_COMM_ATTR_CONCENTRATOR_FLAG
#define CLD_COMM_ATTR_CONCENTRATOR_RADIUS
#define CLD_COMM_ATTR_CONCENTRATOR_DISCVRY_TIME

Optional Commands

The Commissioning cluster contains commands that may be optionally enabled at compile-time by adding some or all of the following lines to the zcl_options.h file.

To enable the Save Start-up Parameters command, add the following line:

#define CLD_COMMISSIONING_CMD_SAVE_STARTUP_PARAMS

To enable the Restore Start-up Parameters command, add the following line:

#define CLD_COMMISSIONING_CMD_RESTORE_STARTUP_PARAMS

Parent topic:Commissioning Cluster