Thread: CoAP Client

The Thread CoAP Client sample demonstrates controlling light resources of other nodes within an OpenThread network. To show this interaction, the sample requires a server sample that is compatible with the OpenThread network and has a light resource available. The recommended server sample referenced on this page is Thread: CoAP Server.

This sample supports optional Multiprotocol Bluetooth LE extension and Minimal Thread Device variant, which can be turned on or off. See Activating sample extensions for details.

Overview

This sample demonstrates how to access resources available on a Thread server node. After the Thread network is established, the client node can control the state of LED 4 on server nodes. It can turn on the LED 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.

The following CoAP resources are accessed on the server side:

• /light - Used to control LED 4.

• /provisioning - Used to perform provisioning.

This sample uses Zephyr CoAP API for communication, which is the preferred API to use for new CoAP applications. For example usage of the native Thread CoAP API, see the Thread: CoAP Server sample.

Multiprotocol Bluetooth LE extension

This optional extension can demonstrate the OpenThread stack and SoftDevice Controller working concurrently. It uses the Nordic UART Service (NUS) library to control the LED states over Bluetooth LE in a Thread network. For more information about the multiprotocol feature, see Multiprotocol support.

FEM support

Note

Software FEM support is not present on nRF53 Series devices yet. For now, it also cannot be combined with multiprotocol operation.

You can add support for the nRF21540 front-end module to the sample. See Radio front-end module (FEM) support for more information.

To add support for the nRF21540 FEM, add the provided dts-nrf21540-fem.overlay devicetree overlay file when building. The file is located in the samples/openthread/common folder. Make sure that the GPIOs in the file correspond to those in which your front-end module is connected.

Note

You must add the provided overlay file if you use the nRF21540 EK. If you use the nRF21540 DK, build your application for the nrf21540dk_nrf52840 board. The devicetree for the nRF21540 DK already contains the required FEM configuration, so you do not need to add the overlay file.

See Set devicetree overlays for different ways of adding the overlay file.

The easiest way to add the file when building is to set it in the DTC_OVERLAY_FILE variable. However, doing so will override the default settings. For some boards, this sample requires additional overlay files, which are automatically included when building with the default settings. When you set the DTC_OVERLAY_FILE variable, you must specify all overlay files that are needed for building. Check the boards folder to see the additional overlay files.

Follow the instructions in Providing CMake options to specify the DTC_OVERLAY_FILE variable. For example, to build the sample from the command line for an nRF52833 DK with an attached nRF21540 EK, invoke the following command within the sample directory:

west build -b nrf52833dk_nrf52833 -- -DDTC_OVERLAY_FILE="boards/nrf52833dk_nrf52833.overlay;../common/dts-nrf21540-fem.overlay"

Alternatively, you can copy the contents of dts-nrf21540-fem.overlay to the board’s overlay file.

To add support for other front-end modules, add the respective overlay files in the same way.

Device Firmware Upgrade extension

This optional extension can be used to perform an over-the-air Device Firmware Upgrade (DFU). In this process, the device that hosts the new firmware image sends it to the CoAP Client device using SMP over Bluetooth. The MCUboot bootloader solution is then used to replace the old firmware image with the new one.

Note

The Device Firmware Upgrade feature is currently supported only on the nRF52840 DK.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Build target
nRF5340 DK	PCA10095	nrf5340dk_nrf5340	nrf5340dk_nrf5340_cpuapp
nRF52840 DK	PCA10056	nrf52840dk_nrf52840	nrf52840dk_nrf52840
nRF52833 DK	PCA10100	nrf52833dk_nrf52833	nrf52833dk_nrf52833
nRF21540 DK	PCA10112	nrf21540dk_nrf52840	nrf21540dk_nrf52840

You can use one or more of the development kits listed above as the Thread CoAP Client. You also need one or more compatible development kits programmed with the Thread: CoAP Server sample.

Multiprotocol extension requirements

If you enable the Multiprotocol Bluetooth LE extension, make sure you have a phone or a tablet with the nRF Toolbox application installed.

Note

The testing instructions refer to nRF Toolbox, but similar applications can be used as well, for example nRF Connect for Mobile.

User interface

The following LED and buttons of the client development kit are used by this sample:

LED 1:

On when the OpenThread connection is established.

Button 1:

Send 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.

Button 2:

Send a multicast LIGHT_ON or LIGHT_OFF message (alternatively) to the /light resource. Sending this multicast message instead of LIGHT_TOGGLE allows to synchronize the state of the LEDs on several server nodes.

Button 4:

Send a multicast pairing request to the /provisioning resource.

Minimal Thread Device assignments

When the device is working as Minimal Thread Device (MTD), the following LED and Button assignments are also available:

LED 3:

The mode the device is working in:

• On when in the Minimal End Device (MED) mode.

• Off when in the Sleepy End Device (SED) mode.

Button 3:

Toggle the power consumption between SED and MED.

For more information, see Device type options in the Thread user guide.

Multiprotocol Bluetooth LE extension assignments

LED 2:

On when Bluetooth LE connection is established.

UART command assignments:

The following command assignments are configured and used in nRF Toolbox when Testing multiprotocol Bluetooth LE extension:

• u - Send a unicast CoAP message over Thread (the same operation as Button 1).

• m - Send a multicast CoAP message over Thread (the same operation as Button 2).

• p - Send a pairing request as CoAP message over Thread (the same operation as Button 4).

Building and running

Make sure to enable the OpenThread stack before building and testing this sample. See Thread for more information.

This sample can be found under samples/openthread/coap_client in the nRF Connect SDK folder structure.

See Building and programming a sample application for information about how to build and program the application.

Activating sample extensions

To activate the optional extensions supported by this sample, modify OVERLAY_CONFIG in the following manner:

• For the Minimal Thread Device variant, set overlay-mtd.conf.

• For the Multiprotocol Bluetooth LE extension, set overlay-multiprotocol_ble.conf.

• For the Device Firmware Upgrade extension, set overlay-dfu_support.conf. Because the Device Firmware Upgrade is performed over Bluetooth LE, you must also enable the Multiprotocol Bluetooth LE extension.

See Providing CMake options for instructions on how to add this option. For more information about using configuration overlay files, see Important Build System Variables in the Zephyr documentation.

Testing

After building the sample and programming it to your development kit, test it by performing the following steps:

1. Program at least one development kit with Thread: CoAP Server and reset it.

2. Turn on the CoAP Client and at least one CoAP Server. They will create the Thread network.

   Note

   It may take up to 15 seconds for nodes to establish the network. When the sample application is ready, the LED 1 starts blinking.

3. Press Button 2 on a client node to control LED 4 on all server nodes.

4. Pair a client with a server by completing the following steps:

   1. Press Button 4 on a server node to enable pairing.

   2. Press Button 4 on a client node to pair it with the server node in the pairing mode.

5. Press Button 1 on the client node to control the LED 4 on the paired server node.

Testing Minimal Thread Device

After building the MTD variant of this sample and programming it, the device starts in the SED mode with LED 3 off. This means that the radio is disabled when idle and the serial console is not working to decrease the power consumption. You can switch to the MED mode at any moment during the standard testing procedure.

To toggle MED, press Button 3 on the client node. LED 3 turns on to indicate the switch to the MED mode. At this point, the radio is enabled when it is idle and the serial console is operating.

Pressing Button 3 again will switch the mode back to SED. Switching between SED and MED modes does not affect the standard testing procedure, but terminal logs are not available in the SED mode.

Testing multiprotocol Bluetooth LE extension

To test the multiprotocol Bluetooth LE extension, complete the following steps after the standard Testing procedure:

1. Set up nRF Toolbox by completing the following steps:

   1. Tap UART to open the UART application in nRF Toolbox.

      

      UART application in nRF Toolbox

   2. Tap the EDIT button in the top right corner of the application to configure the UART commands. The button configuration window appears.

   3. Create the active application buttons by completing the following steps:

      1. Bind the top left button to the u command, with EOL set to LF and an icon of your choice. For this testing procedure, the > icon is used.

      2. Bind the top middle button to the m command, with EOL set to LF and an icon of your choice. For this testing procedure, the play button icon is used.

      3. Bind the top right button to the p command, with EOL set to LF and an icon of your choice. For this testing procedure, the settings gear icon is used.

      

      Configuring buttons in the UART application of nRF Toolbox

   4. Tap the DONE button in the top right corner of the application.

   5. Tap CONNECT and select the NUS_CoAP_client device from the list to connect to the device

      

      The UART application of nRF Toolbox after establishing the connection

      Note

      Observe that LED 2 on your CoAP Multiprotocol Client node lights up, which indicates that the Bluetooth connection is established.

2. In nRF Toolbox, press the middle button to control LED 4 on all CoAP server nodes.

3. Pair a client with a server by completing the following steps:

   1. Press Button 4 on a server node to enable pairing.

   2. In nRF Toolbox, press the right button to pair the two nodes.

4. In nRF Toolbox, press the left button to control LED 4 on the paired server node.

Testing Device Firmware Upgrade extension

There are two ways of performing the DFU:

• Using a smartphone with the nRF Connect for Mobile application installed.

• Using a Linux PC with the mcumgr command line tool.

To test the DFU extension, complete the steps for the chosen method.

Device Firmware Upgrade using nRF Connect for Mobile

1. Navigate to the build/zephyr directory and copy the app_update.bin file to your smartphone.

2. Install the nRF Connect for Mobile application on your smartphone and run it.

3. On the Scanner tab, find the device called NUS_CoAP_client and click the CONNECT button.

4. Click the DFU icon in the bar on the top.

5. Select the location of the app_update.bin file on your smartphone.

6. Select the desired DFU mode and click OK.

7. Observe the DFU progress on the mobile application chart or in the device logs.

After finishing the upgrade, the device will be rebooted. It should start operating with the new firmware version.

Device Firmware Upgrade using mcumgr

1. Install the Go language package (if it is not already installed).

2. Download mcumgr by invoking the following command:

   $ go get github.com/apache/mynewt-mcumgr-cli/mcumgr
   

3. Upload the firmware image to the device by running the following command in the sample directory:

   $ sudo mcumgr --conntype ble --connstring peer_name='NUS_CoAP_client' image upload build/zephyr/app_update.bin
   

   The operation might take a few minutes. Wait until the progress bar reaches 100%.

4. Obtain the list of images present in the device memory by running the following command:

   $ sudo mcumgr --conntype ble --connstring peer_name='NUS_CoAP_client' image list
   Images:
   image=0 slot=0
         version: 0.0.0
         bootable: true
         flags: active confirmed
         hash: 7bb0e909a846e833465cbb44c581cf045413a5446c6953a30a3dcc2c3ad51764
   image=0 slot=1
         version: 0.0.0
         bootable: true
         flags:
         hash: cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1
   Split status: N/A (0)
   

5. Select the new firmware image by calling the following method, replacing image-hash with the hash of the image present in slot 1 (for example, cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1):

   $ sudo mcumgr --conntype ble --connstring peer_name='NUS_CoAP_client' image test image-hash

   The selected image is marked with a pending flag.

6. Reset the device with the following command to let the bootloader swap the images:

   $ sudo mcumgr --conntype ble --connstring peer_name='NUS_CoAP_client' reset
   

   The device will be rebooted and the firmware images swapped. The swapping operation might take some time.

Sample output

The sample logging output can be observed through a serial port. For more details, see How to connect with PuTTY.

Dependencies

This sample uses the following nRF Connect SDK libraries:

• DK Button and LEDs

• CoAP utils

In addition, it uses the following Zephyr libraries:

• CoAP

  • include/net/coap.h

• Logging:

  • include/logging/log.h

• Kernel Services:

  • include/kernel.h

The following dependencies are added by the optional multiprotocol Bluetooth LE extension:

• SoftDevice Controller

• Nordic UART Service (NUS)

• Zephyr’s Bluetooth:

  • include/bluetooth/bluetooth.h

  • include/bluetooth/gatt.h

  • include/bluetooth/hci.h

  • include/bluetooth/uuid.h