Thread CoAP Examples

The CoAP examples demonstrate interactions between nodes performing different Thread roles with the use of OpenThread and built-in CoAP protocol.

• Thread Simple CoAP Client and Thread Simple CoAP Server examples demonstrate Full Thread Device functionality (Thread Router role and REED role).
• Thread FreeRTOS CoAP Server example demonstrate Full Thread Device functionality (Thread Router role and REED role) with FreeRTOS.
• Thread MTD CoAP Client example demonstrates Minimal Thread Device functionality (Minimal End Device role and Sleepy End Device role).

The client node can control the state of BSP_LED_3 on Simple CoAP Server nodes or blinking of BSP_LED_2 and BSP_LED_3 on FreeRTOS CoAP Server nodes. It can change the state of LEDs either on every server node in the network with a multicast message, or on a single specific server node that is paired with the client node. Simple CoAP Client, Simple CoAP Server, and FreeRTOS CoAP Server examples implement the CLI interface, so more advanced users can communicate with the nodes through a serial port and configure them manually. MTD CoAP Client does not implement a CLI interface.

Description

Both the client and the server indicate their network state on BSP_LED_0. When the device is not connected to the network, the LED blinks at a 100 ms period. Once the device connects to a network, either as a Child or as a Leader, the LED stops blinking and remains turned on.

On startup, nodes automatically enter the network with default parameters. The first device that is turned on becomes a Leader of the network, while the rest of the nodes become Children and Routers. Note that an MTD CoAP client cannot become a Leader because MTD nodes do not support the Leader role.

Server

The application layer of the example is built on top of the CoAP protocol. The server nodes provide two resources:

• /light – Used to control BSP_LED_3.
• /provisioning – Disabled by default, used in pairing mechanism.

The only action that is triggered by a button on the server node is enabling the pairing mechanism. Once BSP_BUTTON_3 is pressed on the server node, it accepts requests on the /provisioning resource for five seconds. This is indicated by rapid blinking of BSP_LED_2. When pairing is disabled, either by receiving the request or by timeout, the LED is turned off.

The /light resource controls BSP_LED_3. It accepts three commands: LIGHT_TOGGLE, LIGTH_ON, and LIGHT_OFF. This resource accepts both multicast and unicast requests.

Server LED assignments:

• BSP_LED_0: Network state:
  • Blinking – Disconnected
  • Solid - Connected
• BSP_LED_2: Pairing enabled
• BSP_LED_3: LED controlled by the client node

Server button assignments:

• BSP_BUTTON_3: Enable pairing

Server with FreeRTOS

The application layer of the example is built on top of the CoAP protocol. The server nodes provide two resources:

• /light – Used to control blinking of BSP_LED_2 and BSP_LED_3.
• /provisioning – Disabled by default, used in pairing mechanism.

The only action that is triggered by a button on the server node is enabling the pairing mechanism. Once BSP_BUTTON_3 is pressed on the server node, it accepts requests on the /provisioning resource for five seconds. This is indicated by rapid blinking of BSP_LED_2. When pairing is disabled, either by receiving the request or by timeout, the LED goes back to indication of light resource state.

The /light resource controls blinking of BSP_LED_2 and BSP_LED_3. It accepts three commands: LIGHT_TOGGLE, LIGTH_ON, and LIGHT_OFF. This resource accepts both multicast and unicast requests. On state of /light resource is indicated by asynchronous blinking of BSP_LED_2 and BSP_LED_3. Each LED is controlled from separate FreeRTOS thread.

Server LED assignments:

• BSP_LED_0: Network state:
  • Blinking – Disconnected
  • Solid - Connected
• BSP_LED_2 and BSP_LED_3: Board state:
  • BSP_LED_2 blinking and BSP_LED_3 solid off - Pairing enabled
  • BSP_LED_2 and BSP_LED_3 blinking asynchronically - Light resource state is on
  • BSP_LED_2 and BSP_LED_3 solid off - Light resource state is off

Server button assignments:

• BSP_BUTTON_3: Enable pairing

Client

The client node is controlled by specific actions triggered by pressing of the buttons:

• Pressing BSP_BUTTON_0 results in sending a unicast LIGHT_TOGGLE message to the /light resource on a paired device. If no device is paired with the specific client node, pressing the button has no effect.
• Pressing BSP_BUTTON_1 results in sending a multicast LIGHT_ON or a LIGHT_OFF message (alternatively) to the /light resource. Sending a LIGHT_ON/LIGHT_OFF message instead of LIGHT_TOGGLE allows to synchronize the state of the LEDs on several server nodes.
• Pressing BSP_BUTTON_3 results in sending a multicast pairing request to the /provisioning resource.

By default, each client node can send multicast requests on the /light resource. Once a client node is paired with a server node, it can control the specific node using BSP_BUTTON_0. Note that sending unicast and multicast requests alternatively may result in no reaction to a multicast request on specific nodes because they may receive, for example, a LIGHT_ON command, while their LED is already on.

Client LED assignments:

• BSP_LED_0: Network state:
  • Blinking – Disconnected
  • Solid - Connected

Client button assignments:

• BSP_BUTTON_0: Send a unicast LIGHT_TOGGLE message to a paired server node.
• BSP_BUTTON_1: Send a multicast LIGHT_ON/LIGHT_OFF message.
• BSP_BUTTON_3: Send a multicast pairing request.

MTD Client

The MTD node starts in the lowest-power SED state. The SED state is characterized by a disabled receiver and a sleeping CPU. The node can then enter the MED state, which involves lower latency but higher power consumption. In the MED state, the CPU is also sleeping, but the radio is enabled.

If an MTD node is battery powered, it is recommended to set the SW6 switch to nRF_ONLY. This will result in powering off the LEDs and significant reduction of power consumption.

The MTD client node is controlled by specific actions triggered by pressing of the buttons:

Client LED assignments:

• BSP_LED_0: Network state:
  • Blinking - Disconnected
  • Solid - Connected
• BSP_LED_2: Power consumption mode:
  • Disabled - SED
  • Solid - MED

MTD client button assignments:

• BSP_BUTTON_0: Send a unicast LIGHT_TOGGLE message to the /light resource on a paired device. If no device is paired with a specific client node, pressing the button has no effect.
• BSP_BUTTON_1: Send a multicast LIGHT_ON or a LIGHT_OFF message (alternatively) to the /light resource. Sending a LIGHT_ON/LIGHT_OFF message instead of LIGHT_TOGGLE allows to synchronize the state of the LEDs on several server nodes.
• BSP_BUTTON_2: Switch power consumption modes: from MED to SED and from SED to MED.
• BSP_BUTTON_3: Send a multicast pairing request to the /provisioning resource.

Pairing

To enable pairing of a server node with a client node dynamically during runtime, a simple pairing mechanism has been implemented. This mechanism is not a part of Thread or CoAP specification, and was provided for the purpose of this example.

To pair a server node with a client node, you must first enable pairing on the server side. It can be done by pressing BSP_BUTTON_3 on the server node. Once the button is pressed, the node will wait for five seconds for the pairing message. This is indicated by rapid blinking of BSP_LED_2. When the pairing message is received, the server replies with pairing confirmation, and then disables the pairing and stops blinking on BSP_LED_2.

Once pairing on any server node is enabled, the client can send a pairing request message. It is a multicast CoAP message on the /provisioning resource and is triggered by pressing BSP_BUTTON_3. The client will store the data of the first server node that responds to the pairing message. Therefore, it is advised not to enable pairing on more than one server node at a time, as the result may be nondeterministic.

When the devices are paired, the client node can control BSP_LED_3 on the specific server node by sending a unicast message when BSP_BUTTON_0 is pressed. A single client node can be paired with only one server node, but multiple clients can control a single server node. The pairing procedure can be repeated to change the server that the client is paired with.

Setup

You can find the source code and the makefiles in the following folders:

• <InstallFolder>\examples\thread\simple-coap-client
• <InstallFolder>\examples\thread\mtd-coap-client
• <InstallFolder>\examples\thread\simple-coap-server

Testing

1. Build the example according to the instructions in Building examples.
2. Program one or more boards with the Thread Simple CoAP Client, the Thread Simple CoAP Server, and the Thread MTD CoAP Client examples.
3. Turn on the Simple CoAP Server or Simple CoAP Client node and wait until BSP_LED_0 stops blinking. The node will become the Leader of the network.
4. Turn on any of the other nodes. They will enter the network as Children, and Simple CoAP Client or Simple CoAP Server nodes will gradually become Routers.
5. You can control BSP_LED_3 on every server node by pressing BSP_BUTTON _1 on any client node.
6. Pair a client with a server. Press BSP_BUTTON_3 on a server node to enable pairing. Then, press BSP_BUTTON_3 on any client node to pair the two nodes. You can now control the BSP_LED_3 on this server node by pressing BSP_BUTTON _0 on the client node.
7. Optionally, you can connect to any of the Simple CoAP Server, Simple CoAP Client or FreeRTOS CoAP Server nodes through a serial port and run CLI commands. The application uses the following UART settings:
   • Baud rate: 115.200
   • 8 data bits
   • 1 stop bit
   • No parity
   • HW flow control: None
   For complete CLI documentation, refer to OpenThread CLI Reference.