Using Touchlink

Touchlink is used for the basic commissioning of a new network or adding a new node to an existing network. A dedicated Touchlink application (which is distinct from the main application on the node) must reside on its own endpoint. This requires:

• a Touchlink Commissioning cluster instance as a client to be created on the endpoint on the initiator node.

• a Touchlink Commissioning cluster instance as a server to be created on the endpoint on the target node.

The initiator node also requires a Touchlink Commissioning cluster instance as a server (on the same endpoint), since the node also needs the capability to join an existing network.

An endpoint is registered for Touchlink (on both nodes) using the function eZLL_RegisterCommissionEndPoint(). This function also creates a Touchlink Commissioning cluster instance of the type (server, client or both) determined by the compile-time options in the header file zcl_options.h (see Section 44.10).

The initiator must then send a sequence of request commands to the target node. The Touchlink request command set is summarized in Table 1. Touchlink functions for issuing these commands are provided and are detailed in Section 44.7.1.

Using Touchlink

Command	Identifier	Description
Scan Request *	0x00	Requests other devices (potential nodes) in the local neighbourhood to respond. A scan request is first performed on channel 11, up to five times until a response is received. If no response is received, a scan request is then performed once on each of channels 15, 20 and 25, and then the remaining channels (12, 13, 14, 16, etc) until a response is detected.
Device Information Request *	0x02	Requests information about the devices on a remote node
Identify Request	0x06	Requests a remote node to physically identify itself (for example, visually by flashing an LED)
Reset To Factory New Request	0x07	Requests a factory reset of a remote node
Network Start Request *	0x10	Requests a new network to be created comprising the initiator and a detected Router
Network Join Router Request *	0x12	Requests a Router to join the network
Network Join End Device Request *	0x14	Requests an End Device to join the network
Network Update Request *	0x16	Requests an update of the network settings on a remote node (if the supplied Network Update Identifier is more recent than the one on the node)

* These commands have corresponding responses.

All Touchlink commands are sent as inter-PAN messages.

Use of the above commands and associated functions is described in the sub-sections below.

Creating a network

A network is formed from an initiator node and a Router node (usually the initiator is an End Device and will have no routing capability in the network). The Touchlink network creation process is described below and is illustrated in the figure below. (also refer to the command list in the table in the Section Using Touchlink).

Note: Received Touchlink requests and responses are handled as ZigBee PRO events. The event handling is not detailed below but is outlined in Section 44.6.

1. Scan Request: The initiator sends a Scan Request to nodes in its vicinity. The required function is:
   eCLD\_ZllCommissionCommandScanReqCommandSend\(\)

2. Scan Response: A receiving node replies to the Scan Request by sending a Scan Response, which includes the device type of the responding node (e.g. Router). The required function is: eCLD\_ZllCommissionCommandScanRspCommandSend\(\)

3. Device Information Request: The initiator sends a Device Information Request to the detected Routers that are of interest. The required function is: eCLD\_ZllCommissionCommandDeviceInfoReqCommandSend\(\)

4. Device Information Response: A receiving Router replies to the Device Information Request by sending a Device Information Response. The required function is:
   eCLD\_ZllCommissionCommandDeviceInfoRspCommandSend\(\)

5. Identify Request (Optional): The initiator may send an Identify Request to the node which has been chosen as the first Router of the new network, in order to confirm that the correct physical node is being commissioned. The required function is:

   eCLD\_ZllCommissionCommandDeviceIdentifyReqCommandSend\(\)

6. Network Start Request: The intiator sends a Network Start Request to the chosen Router in order to create and start the network. The required function is:
   eCLD\_ZllCommissionCommandNetworkStartReqCommandSend\(\)

7. Network Start Response: The Router replies to the Network Start Request by sending a Network Start Response. The required function is: eCLD\_ZllCommissionCommandNetworkStartRspCommandSend\(\)

Once the Router has started the network, the initiator joins the network (Router). The initiator then collects endpoint and cluster information from the Lighting device(s) on the Router node, and stores this information in a local lighting database.

Once the network (consisting of the initiator and one Router) is up and running, further nodes may be added as described in Section 44.4.2.

Creating a Network ||

Parent topic:Using Touchlink

Adding to an existing network

A network (that has been set up as described in Section 44.4.1) can be extended by adding a node. The Touchlink extension process is described below and illustrated in the figure below (also refer to the command list in Table 1).

Note: Received Touchlink requests and responses are handled as ZigBee PRO events. The event handling is not detailed below but is outlined in Section 44.6.

1. Scan Request: The initiator sends a Scan Request to nodes in its vicinity. The required function is:

• eCLD_ZllCommissionCommandScanReqCommandSend()

2. Scan Response: A receiving node replies to the Scan Request by sending a Scan Response. The required function is:

• eCLD_ZllCommissionCommandScanRspCommandSend()

3. Device Information Request: The initiator sends a Device Information Request to those detected nodes that are of interest. The required function is:

• eCLD_ZllCommissionCommandDeviceInfoReqCommandSend()

4. Device Information Response: A receiving node replies to the Device Information Request by sending a Device Information Response. The required function is:

• eCLD_ZllCommissionCommandDeviceInfoRspCommandSend()

5. Identify Request (Optional): The initiator may send an Identify Request to the node which has been chosen to be added to the network, in order to confirm that the correct physical node is being commissioned. The required function is:

• eCLD_ZllCommissionCommandDeviceIdentifyReqCommandSend()

6. Network Join Request: Depending on the target node type, the initiator sends a Network Join Router Request or Network Join End Device Request, as appropriate, to the target node. The required function is one of:

• eCLD_ZllCommissionCommandNetworkJoinRouterReqCommandSend()

• eCLD_ZllCommissionCommandNetworkJoinEndDeviceReqCommandSend()

7. Network Join Response: Depending on the receiving node type, the node replies to the join request by sending a Network Join Router Response or Network Join End Device Response. The required function is one of:

• eCLD_ZllCommissionCommandNetworkJoinRouterRspCommandSend()

• eCLD_ZllCommissionCommandNetworkJoinEndDeviceRspCommandSend()

The node should now be a member of the network. The initiator then collects endpoint and cluster information from any Lighting device(s) on the new node, and stores this information in its local lighting database.

If the new node is to be used to control the light nodes of the network then it will need to learn certain information (such as controlled endpoints and configured groups) from the initiator - this is done using the Commissioning Utility commands, as described in Section 44.5.

Extending a Network (Adding a Node)

Parent topic:Using Touchlink

Updating network settings

If one or more of the network settings change (e.g. the radio channel used), all nodes of the network need to be updated with the new settings.

To allow nodes to keep track of the status of the network settings, the Network Update Identifier is used. This identifier takes a value in the range 0x00 to 0xFF and is incremented when a network update has occurred (the value wraps around at 0xFF).

A node can be instructed to update its network settings by sending a Network Update Request to it. The required function is:

eCLD_ZllCommissionCommandNetworkUpdateReqCommandSend()

The payload of the sent command contains the latest network settings and the current value of the Network Update Identifier (see Section 44.8.17). If the payload value is more recent than the value held by the target node, the node should update its network settings with those in the payload.

Parent topic:Using Touchlink

Stealing a node

A node that is already part of a network can be taken or ‘stolen’ by another network using Touchlink (in which case, the stolen node will cease to be a member of its previous network). This transfer can only be performed on a node which supports one or more Lighting devices (and not Controller devices).

The node is stolen using an initiator in the new network, e.g. from a remote control unit. The ‘stealing’ process is as follows:

1. The initiator sends a Scan Request to nodes in its vicinity. The required function is:

• eCLD_ZllCommissionCommandScanReqCommandSend()

2. A receiving node replies to the Scan Request by sending a Scan Response. The required function is:

• eCLD_ZllCommissionCommandScanRspCommandSend()

3. The initiator receives Scan Responses from one or more nodes and, based on these responses, selects a node (containing a Lighting device) that is already a member of another network.

4. The initiator then sends a Reset To Factory New Request to the desired node. The required function is:

• eCLD_ZllCommissionCommandFactoryResetReqCommandSend()

5. On receiving this request on the target node, the event E_CLD_COMMISSION_CMD_FACTORY_RESET_REQ is generated and the function ZPS_eAplZdoLeaveNetwork() should be called. In addition, all persistent data should be reset.

6. The node can then be commissioned into the new network by following the process in Section 44.4.2 from Step3.

Alternatively, instead of following the above process, a node can be stolen by either:

• Following the full process for creating a network in Section 44.4.1 and calling **ZPS_eAplZdoLeaveNetwork()**on the target node when a Network Start Request is received.

• Following the full process for adding a node in Section 44.4.2 and calling **ZPS_eAplZdoLeaveNetwork()**on the target node when a Network Join Router Request or Network Join End Device Request is received.

Note: If a node containing a Controller device (e.g. a remote control unit) is to be used in another network, it must first be reset using a Reset To Factory New Request. It can then be used to create a new network (see Section 44.4.1) or to learn the control information of an existing network (see Section 44.5).

Parent topic:Using Touchlink

Parent topic:Touchlink Commissioning Cluster