Thread CoAP Examples

Table of Contents

• Setup
  • LED and button assignments
• Startup and commissioning roles
• Simple CoAP Server
• FreeRTOS CoAP Server
• Simple CoAP Client
• MTD CoAP Client
• Pairing
  • Enabling pairing (server)
  • Sending pairing request (client)
  • Controlling LED on server (client)
• Testing
  • CLI support

This information applies to the following SoCs: nRF52833 and nRF52840.

Thread CoAP Examples are server and client examples that demonstrate interactions between nodes performing different Thread roles with the use of OpenThread and the built-in CoAP protocol.

The interactions are based on the usage of LEDs. A press of a button on the client node triggers unicast or multicast commands, which can change the state of LEDs on the server nodes.

The following examples are discussed on this page:

• Simple CoAP Server
• FreeRTOS CoAP Server
• Simple CoAP Client
• MTD CoAP Client

Most of these examples offer CLI support.

---

Setup

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

• <InstallFolder>\examples\thread\simple_coap_server
• <InstallFolder>\examples\thread\freertos_coap_server
• <InstallFolder>\examples\thread\simple_coap_client
• <InstallFolder>\examples\thread\mtd_coap_client

LED and button assignments

All examples use LED assignments as described in Thread BSP LED and button reference for the following LEDs:

• LED1 – Used to indicate the network connection state.

For example-specific LED assignments and button assignments, see the following sections.

---

Startup and commissioning roles

On startup, the nodes automatically enter the network with the default parameters.

Concerning the device roles:

• The first device that is turned on becomes the Leader of the network.
• The rest of the nodes become Children and Routers.
• The MTD CoAP client cannot become a Leader because MTD nodes do not support the Router role, which is required to become a Leader.

---

Simple CoAP Server

Together with the Simple CoAP Client example, the Thread Simple CoAP Server example demonstrates the Full Thread Device functionality (Thread Router role and REED role).

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

• /light – Used to control LED4.
  • Accepts the following commands:
    • THREAD_COAP_UTILS_LIGHT_CMD_TOGGLE,
    • THREAD_COAP_UTILS_LIGHT_CMD_ON,
    • THREAD_COAP_UTILS_LIGHT_CMD_OFF.
  • Accepts both multicast and unicast requests.
• /provisioning – Disabled by default, used in pairing mechanism.

The only action that is triggered by Button 4 on the server node is Pairing.

Simple CoAP Server LED assignments

• LED3: Pairing enabled.
• LED4: LED controlled by the client node.

Simple CoAP Server button assignments

• Button 4: Enable pairing.

---

FreeRTOS CoAP Server

The Thread FreeRTOS CoAP Server example demonstrates Full Thread Device functionality (Thread Router role and REED role) with FreeRTOS.

This example is not supported on Keil.

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 LED3 and LED4.
  • Accepts the following commands:
    • THREAD_COAP_UTILS_LIGHT_CMD_TOGGLE,
    • THREAD_COAP_UTILS_LIGHT_CMD_ON,
    • THREAD_COAP_UTILS_LIGHT_CMD_OFF.
  • Accepts both multicast and unicast requests.
  • Its state is indicated by asynchronous blinking of LED3 and LED4.
  • Each LED is controlled from a separate FreeRTOS thread.
• /provisioning – Disabled by default, used in Pairing.

The only action that is triggered by a button on the server node is Pairing.

Note

When pairing is disabled, either by receiving the request or by timeout, the LED3 goes back to indicating the light resource state.

FreeRTOS CoAP Server LED assignments

• LED3 and LED4: Board state:
  • LED3 blinking and LED4 solid off – Pairing enabled.
  • LED3 and LED4 blinking asynchronically – Light resource state is on.
  • LED3 and LED4 solid off – Light resource state is off.

FreeRTOS CoAP Server button assignments

• Button 4: Enable pairing.

---

Simple CoAP Client

Together with the Simple CoAP Server example, the Thread Simple CoAP Client example demonstrates the Full Thread Device functionality (Thread Router role and REED role).

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

Simple CoAP Client button assignments

• Button 1: Send a unicast THREAD_COAP_UTILS_LIGHT_CMD_TOGGLE message to the /light resource on a paired server device. If no device is paired with the specific client node, pressing the button has no effect.
• Button 2: Send a multicast THREAD_COAP_UTILS_LIGHT_CMD_ON or a THREAD_COAP_UTILS_LIGHT_CMD_OFF message (alternatively) to the /light resource on a multicast address, to be received and processed by all servers. Sending a THREAD_COAP_UTILS_LIGHT_CMD_ON/THREAD_COAP_UTILS_LIGHT_CMD_OFF message instead of THREAD_COAP_UTILS_LIGHT_CMD_TOGGLE allows to synchronize the state of the LEDs on several server nodes.
• Button 3: Send a multicast pairing request to the /provisioning resource.

---

MTD CoAP Client

Thread MTD CoAP Client example demonstrates Minimal Thread Device functionality, with its two states:

• Sleepy End Device (SED), characterized by a disabled receiver and a sleeping CPU.
• Minimal End Device role (MED), characterized by radio being enabled and CPU still sleeping. This state involves lower latency, but higher power consumption.

The MTD node starts in the lowest-power SED state. It can then enter the MED state.

If an MTD node is battery-powered, set the SW6 switch to nRF_ONLY. This will result in powering off the LEDs and reducing the power consumption significantly.

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

MTD client LED assignments

• LED3: Power consumption mode:
  • Disabled – SED.
  • Solid – MED.

MTD client button assignments

• Button 1: Send a unicast THREAD_COAP_UTILS_LIGHT_CMD_TOGGLE message to the /light resource on a paired server device. If no device is paired with a specific client node, pressing the button has no effect.
• Button 2: Send a multicast THREAD_COAP_UTILS_LIGHT_CMD_ON or a THREAD_COAP_UTILS_LIGHT_CMD_OFF message (alternatively) to the /light resource on a multicast address, to be received and processed by all servers. Sending a THREAD_COAP_UTILS_LIGHT_CMD_ON/THREAD_COAP_UTILS_LIGHT_CMD_OFF message instead of THREAD_COAP_UTILS_LIGHT_CMD_TOGGLE allows to synchronize the state of the LEDs on several server nodes.
• Button 3: Switch power consumption modes: from MED to SED and from SED to MED.
• Button 4: 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 specifically for this set of examples.

In this mechanism, 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.

Enabling pairing (server)

To pair a server node with a client node, you must first enable pairing on the server side. This can be done by pressing Button 4 on the server node.

Once the button is pressed, the server node will wait for five seconds for the pairing request message from the client (see below). This is indicated by rapid blinking of LED3.

• When a pairing message is received, the server replies with the pairing confirmation, and then disables the pairing and stops the blinking on LED3.
• When no pairing message is received within 5 seconds, the pairing is disabled by timeout, and the LED3 stops blinking.

Sending pairing request (client)

Once pairing on any server node is enabled, the client can send a pairing request message. It is a multicast CoAP message on the server /provisioning resource and is triggered by pressing Button 4 on the server node.

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.

Controlling LED on server (client)

When the devices are paired, the client node can control the state of LED4 on Simple CoAP Server nodes or blinking of LED3 and LED4 on FreeRTOS CoAP Server nodes by pressing the following buttons:

• Button 1 to send a unicast message to a single specific server node that is paired with the client node.
• Button 2 to send a multicast message to change the state of LEDs on every server node in the network. By default, each client node can send multicast requests on the /light resource.

Note

Sending unicast and multicast requests alternatively can result in no reaction to a multicast request on specific nodes because they may receive, for example, a THREAD_COAP_UTILS_LIGHT_CMD_TOGGLE command, while their LED is already on.

---

Testing

1. Build the example according to the instructions in Building examples.
2. Program at least one board with a CoAP server example and at least one board with a CoAP client example. You can also program more boards with other examples from the CoAP example set.
3. Turn on the CoAP server or the CoAP client node and wait until LED1 stops blinking. The node becomes the Leader of the network.

   Note

   In case of the MTD client, you have to power it on after powering on the server or a client other than MTD, otherwise the MTD client LED does not stop blinking and the MTD client does not join the network.

4. Turn on any of the other nodes. They enter the network as Children, and Simple CoAP Client or Simple CoAP Server nodes gradually become Routers.
5. Press Button 2 on any client node to control LED4 on every server node.
6. Pair a client with a server:
   1. Press Button 4 on a server node to enable pairing.
   2. Press Button 4 on any client node to pair the two nodes. You can now control the LED4 on this server node by pressing Button 1 on the client node.

CLI support

Optionally, you can connect to CoAP nodes through a serial port and run CLI commands to configure them manually using OpenThread CLI Reference:

Not all nodes support CLI commands:

• CLI supported
  • Simple CoAP Client
  • Simple CoAP Server
  • FreeRTOS CoAP Server
• CLI not supported
  • MTD CoAP Client

The application uses the following UART settings:

• Baud rate: 115200
• 8 data bits
• 1 stop bit
• No parity
• HW flow control: None