Thread: CLI

The Thread CLI sample demonstrates how to send commands to a Thread device using the OpenThread Command Line Interface (CLI). The CLI is integrated into the Zephyr shell.

This sample supports optional Experimental Thread 1.2 extension, which can be turned on or off. See Activating sample extensions for details.

Overview

The sample demonstrates the usage of commands listed in OpenThread CLI Reference. OpenThread CLI is integrated into the system shell accessible over serial connection. To indicate a Thread command, the ot keyword needs to precede the command.

The amount of commands you can test depends on the application configuration. The CLI sample comes with the full set of OpenThread functionalities enabled (CONFIG_OPENTHREAD_NORDIC_LIBRARY_MASTER).

If used alone, the sample allows you to test the network status. It is recommended to use at least two development kits running the same sample to be able to test communication.

Diagnostic module

By default, the CLI sample comes with the CONFIG_OPENTHREAD_NORDIC_LIBRARY_MASTER feature set enabled, which allows you to use Zephyr’s diagnostic module with its diag commands. Use these commands for manually checking hardware-related functionalities without running a Thread network. For example, when adding a new functionality or during the manufacturing process to ensure radio communication is working. See Testing diagnostic module section for an example.

Note

If you disable the CONFIG_OPENTHREAD_NORDIC_LIBRARY_MASTER feature set, you can enable the diagnostic module with the CONFIG_OPENTHREAD_DIAG Kconfig option.

Experimental Thread 1.2 extension

This optional extension allows you to test available features from the Thread 1.2 Specification. You can enable these features either by activating the overlay extension as described below or by setting Thread 1.2 Specification options.

Certification tests with CLI sample

The Thread CLI sample can be used for running certification tests. See Thread certification for information on how to use this sample on Thread Certification Test Harness.

Minimal configuration

This optional extension demonstrates an optimized configuration for the Thread CLI sample. The provided configurations optimize the memory footprint of the sample for single protocol and multiprotocol use.

For more information, see Memory footprint optimization.

Serial transport

The Thread CLI sample supports UART and USB CDC ACM as serial transports. By default, it uses UART transport. You can switch to USB transport by activating the USB overlay extension, as described below.

FEM support

You can add support for the nRF21540 front-end module to this sample by using one of the following options, depending on your hardware:

  • Build the sample for one board that contains the nRF21540 FEM, such as nrf21540dk_nrf52840.

  • Manually create a devicetree overlay file that describes how FEM is connected to the nRF5 SoC in your device. See Set devicetree overlays for different ways of adding the overlay file.

  • Provide nRF21540 FEM capabilities by using a shield, for example the nRF21540 EK shield that is available in the nRF Connect SDK. In this case, build the project for a board connected to the shield you are using with an appropriate variable included in the build command. This variable instructs the build system to append the appropriate devicetree overlay file. For example, to build the sample from the command line for an nRF52833 DK with the nRF21540 EK attached, use the following command within the sample directory:

    west build -b nrf52833dk_nrf52833 -- -DSHIELD=nrf21540_ek
    

    This command builds the application firmware. See Programming nRF21540 EK for information about how to program when you are using a board with a network core, for example nRF5340 DK.

Each of these options adds the description of the nRF21540 FEM to the devicetree. See Radio front-end module (FEM) support for more information about FEM in the nRF Connect SDK.

To add support for other front-end modules, add the respective devicetree file entries to the board devicetree file or the devicetree overlay file.

Requirements

The sample supports the following development kits for testing the network status:

Hardware platforms

PCA

Board name

Build target

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp_ns

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

nRF52840 Dongle

PCA10059

nrf52840dongle_nrf52840

nrf52840dongle_nrf52840

nRF52833 DK

PCA10100

nrf52833dk_nrf52833

nrf52833dk_nrf52833

nRF21540 DK

PCA10112

nrf21540dk_nrf52840

nrf21540dk_nrf52840

Optionally, you can use one or more compatible development kits programmed with this sample or another Thread sample for testing communication or diagnostics and Configuring on-mesh Thread commissioning.

Thread 1.2 extension requirements

If you enable the Experimental Thread 1.2 extension, you will need nRF Sniffer for 802.15.4 to observe messages sent from the router to the leader kit when Testing Thread 1.2 features.

User interface

All the interactions with the application are handled using serial communication. See OpenThread CLI Reference for the list of available serial commands.

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/cli in the nRF Connect SDK folder structure.

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

To update the OpenThread libraries provided by nrfxlib, invoke west build -b nrf52840dk_nrf52840 -t install_openthread_libraries.

Activating sample extensions

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

  • For the experimental Thread 1.2 variant, set overlay-thread_1_2.conf.

  • For the minimal single protocol variant, set overlay-minimal_singleprotocol.conf.

  • For the minimal multiprotocol variant, set overlay-minimal_multiprotocol.conf.

  • For USB transport support, set overlay-usb.conf. Additionally, you need to set DTC_OVERLAY_FILE to usb.overlay.

  • For turning on logging, set overlay-logging.conf.

  • For redirecting logs to RTT, set overlay-rtt.conf. For more information about RTT please refer to RTT logging.

  • For debbuging a Thread sample with GDB thread awareness, set overlay-debug.conf.

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. Turn on the development kit.

  2. Set up the serial connection with the development kit. For more details, see How to connect with PuTTY.

    Note

    This sample has Hardware Flow Control mechanism enabled by default in serial communication. When enabled, it allows devices to manage transmission by informing each other about their current state, and ensures more reliable connection in high-speed communication scenarios.

  3. Configure the required Thread network parameters with the ot channel, ot panid, and ot networkkey commands. Make sure to use the same parameters for all nodes that you add to the network. The following example uses the default OpenThread parameters:

    uart:~$ ot channel 11
    Done
    uart:~$ ot panid 0xabcd
    Done
    uart:~$ ot networkkey 00112233445566778899aabbccddeeff
    Done
    
  4. Enable the Thread network with the ot ifconfig up and ot thread start commands:

    uart:~$ ot ifconfig up
    Done
    uart:~$ ot thread start
    Done
    
  5. Invoke some of the OpenThread commands:

    1. Test the state of the Thread network with the ot state command. For example:

      uart:~$ ot state
      leader
      Done
      
    2. Get the Thread network name with the ot networkname command. For example:

      uart:~$ ot networkname
      ot_zephyr
      Done
      
    3. Get the IP addresses of the current thread network with the ot ipaddr command. For example:

      uart:~$ ot ipaddr
      fdde:ad00:beef:0:0:ff:fe00:800
      fdde:ad00:beef:0:3102:d00b:5cbe:a61
      fe80:0:0:0:8467:5746:a29f:1196
      Done
      

Testing with more kits

If you are using more than one development kit for testing the CLI sample, you can also complete additional testing procedures.

Note

The following testing procedures assume you are using two development kits.

Testing communication between kits

To test communication between kits, complete the following steps:

  1. Make sure both development kits are programmed with the CLI sample.

  2. Turn on the developments kits.

  3. Set up the serial connection with both development kits. For more details, see How to connect with PuTTY.

    Note

    This sample has Hardware Flow Control mechanism enabled by default in serial communication. When enabled, it allows devices to manage transmission by informing each other about their current state, and ensures more reliable connection in high-speed communication scenarios.

  4. Configure the required Thread network parameters with the ot channel, ot panid, and ot networkkey commands. Make sure to use the same parameters for all nodes that you add to the network. The following example uses the default OpenThread parameters:

    uart:~$ ot channel 11
    Done
    uart:~$ ot panid 0xabcd
    Done
    uart:~$ ot networkkey 00112233445566778899aabbccddeeff
    Done
    
  5. Enable the Thread network with the ot ifconfig up and ot thread start commands:

    uart:~$ ot ifconfig up
    Done
    uart:~$ ot thread start
    Done
    
  6. Test communication between the kits with the following command:

    ot ping ip_address_of_the_first_kit

    For example:

    uart:~$ ot ping fdde:ad00:beef:0:3102:d00b:5cbe:a61
    16 bytes from fdde:ad00:beef:0:3102:d00b:5cbe:a61: icmp_seq=1 hlim=64 time=22ms
    
Testing diagnostic module

To test diagnostic commands, complete the following steps:

  1. Make sure both development kits are programmed with the CLI sample.

  2. Turn on the developments kits.

  3. Set up the serial connection with both development kits. For more details, see How to connect with PuTTY.

    Note

    This sample has Hardware Flow Control mechanism enabled by default in serial communication. When enabled, it allows devices to manage transmission by informing each other about their current state, and ensures more reliable connection in high-speed communication scenarios..

  4. Make sure that the diagnostic module is enabled and configured with proper radio channel and transmission power by running the following commands on both devices:

    uart:~$ ot diag start
    start diagnostics mode
    status 0x00
    Done
    uart:~$ ot diag channel 11
    set channel to 11
    status 0x00
    Done
    uart:~$ ot diag power 0
    set tx power to 0 dBm
    status 0x00
    Done
    
  5. Transmit a fixed number of packets with the given length from one of the devices. For example, to transmit 20 packets that contain 100 B of random data, run the following command:

    uart:~$ ot diag send 20 100
    sending 0x14 packet(s), length 0x64
    status 0x00
    Done
    
  6. Read the radio statistics on the other device by running the following command:

    uart:~$ ot diag stats
    received packets: 20
    sent packets: 0
    first received packet: rssi=-29, lqi=255
    last received packet: rssi=-30, lqi=255
    Done
    
Testing Thread 1.2 features

To test the Thread 1.2 features, complete the following steps:

  1. Make sure both development kits are programmed with the CLI sample with the Experimental Thread 1.2 extension enabled.

  2. Turn on the developments kits.

  3. Set up the serial connection with both development kits. For more details, see How to connect with PuTTY.

  4. Configure the required Thread network parameters with the ot channel, ot panid, and ot networkkey commands. Make sure to use the same parameters for all nodes that you add to the network. The following example uses the default OpenThread parameters:

    uart:~$ ot channel 11
    Done
    uart:~$ ot panid 0xabcd
    Done
    uart:~$ ot networkkey 00112233445566778899aabbccddeeff
    Done
    
  5. Enable the Thread network with the ot ifconfig up and ot thread start commands:

    uart:~$ ot ifconfig up
    Done
    uart:~$ ot thread start
    Done
    
  6. Test the state of the Thread network with the ot state command to see which kit is the leader:

    uart:~$ ot state
    leader
    Done
    
  7. On the leader kit, enable the Backbone Router function:

    uart:~$ ot bbr enable
    DIo:
     State changed! Flags: 0x02001000 Current role: 4
    I: State changed! Flags: 0x00000200 Current role: 4
    I: State changed! Flags: 0x02000001 Current role: 4
    
  8. On the leader kit, configure the Domain prefix:

    uart:~$ ot prefix add fd00:7d03:7d03:7d03::/64 prosD med
    Done
    uart:~$ ot netdata register
    Done
    I: State changed! Flags: 0x00000200 Current role: 4
    I: State changed! Flags: 0x00001001 Current role: 4
    
  9. On the router kit, display the autoconfigured Domain Unicast Address and set another one manually:

    uart:~$ ot ipaddr
    fd00:7d03:7d03:7d03:ee2d:eed:4b59:2736
    fdde:ad00:beef:0:0:ff:fe00:c400
    fdde:ad00:beef:0:e0fc:dc28:1d12:8c2
    fe80:0:0:0:acbd:53bf:1461:a861
    uart:~$ ot dua iid 0004000300020001
    Io:
    State changed! Flags: 0x00000003 Current role: 3
    uart:~$ ot ipaddr
    fd00:7d03:7d03:7d03:4:3:2:1
    fdde:ad00:beef:0:0:ff:fe00:c400
    fdde:ad00:beef:0:e0fc:dc28:1d12:8c2
    fe80:0:0:0:acbd:53bf:1461:a861
    Done
    
  10. On the router kit, configure a multicast address with a scope greater than realm-local:

    uart:~$ ot ipmaddr add ff04::1
    Done
    : State changed! Flags: 0x00001000 Current role: 3
    uart:~$ ot ipmaddr
    ff04:0:0:0:0:0:0:1
    ff33:40:fdde:ad00:beef:0:0:1
    ff32:40:fdde:ad00:beef:0:0:1
    ff02:0:0:0:0:0:0:2
    ff03:0:0:0:0:0:0:2
    ff02:0:0:0:0:0:0:1
    ff03:0:0:0:0:0:0:1
    ff03:0:0:0:0:0:0:fc
    Done
    

    The router kit will send an MLR.req message and a DUA.req message to the leader kit (Backbone Router). This can be observed using the nRF Sniffer for 802.15.4.

  11. On the leader kit, list the IPv6 addresses:

    uart:~$ ot ipaddr
    fd00:7d03:7d03:7d03:84c9:572d:be24:cbe
    fdde:ad00:beef:0:0:ff:fe00:fc10
    fdde:ad00:beef:0:0:ff:fe00:fc38
    fdde:ad00:beef:0:0:ff:fe00:fc00
    fdde:ad00:beef:0:0:ff:fe00:7000
    fdde:ad00:beef:0:a318:bf4f:b9c6:5f7d
    fe80:0:0:0:10b1:93ea:c0ee:eeb7
    

    Note down the link-local address. You must use this address when sending Link Metrics commands from the router kit to the leader kit.

    The following steps use the address fe80:0:0:0:10b1:93ea:c0ee:eeb7. Replace it with the link-local address of your leader kit in all commands.

  12. Run the following commands on the router kit:

    1. Reattach the router kit as SED with a polling period of 3 seconds:

      uart:~$ ot pollperiod 3000
      Done
      uart:~$ ot mode -
      Done
      
    2. Perform a Link Metrics query (Single Probe):

      uart:~$ ot linkmetrics query fe80:0:0:0:10b1:93ea:c0ee:eeb7 single qmr
      Done
      Received Link Metrics Report from: fe80:0:0:0:10b1:93ea:c0ee:eeb7
      - LQI: 220 (Exponential Moving Average)
      - Margin: 60 (dB) (Exponential Moving Average)
      - RSSI: -40 (dBm) (Exponential Moving Average)
      
    3. Send a Link Metrics Management Request to configure a Forward Tracking Series:

      uart:~$ ot linkmetrics mgmt fe80:0:0:0:10b1:93ea:c0ee:eeb7 forward 1 dra pqmr
      Done
      Received Link Metrics Management Response from: fe80:0:0:0:10b1:93ea:c0ee:eeb7
      Status: Success
      
    4. Send an MLE Link Probe message to the peer:

      uart:~$ ot linkmetrics probe fe80:0:0:0:10b1:93ea:c0ee:eeb7 1 10
      Done
      
    5. Perform a Link Metrics query (Forward Tracking Series):

      uart:~$ ot linkmetrics query fe80:0:0:0:10b1:93ea:c0ee:eeb7 forward 1
      Done
      Received Link Metrics Report from: fe80:0:0:0:10b1:93ea:c0ee:eeb7
      - PDU Counter: 13 (Count/Summation)
      - LQI: 212 (Exponential Moving Average)
      - Margin: 60 (dB) (Exponential Moving Average)
      - RSSI: -40 (dBm) (Exponential Moving Average)
      
    6. Send a Link Metrics Management Request to register an Enhanced ACK-based Probing:

      uart:~$ ot linkmetrics mgmt fe80:0:0:0:10b1:93ea:c0ee:eeb7 enhanced-ack register qm
      Done
      Received Link Metrics Management Response from: fe80:0:0:0:10b1:93ea:c0ee:eeb7
      Status: Success
      
    7. Send a Link Metrics Management Request to clear an Enhanced ACK-based Probing:

      uart:~$ ot linkmetrics mgmt fe80:0:0:0:10b1:93ea:c0ee:eeb7 enhanced-ack clear
      Done
      Received Link Metrics Management Response from: fe80:0:0:0:10b1:93ea:c0ee:eeb7
      Status: Success
      
  13. Verify the Coordinated Sampled Listening (CSL) functionality.

    The following steps use the address fe80:0:0:0:acbd:53bf:1461:a861. Replace it with the link-local address of your router kit in all commands.

    1. Send an ICMPv6 Echo Request from the leader kit to link-local address of the router kit:

      uart:~$ ot ping fe80:0:0:0:acbd:53bf:1461:a861
      16 bytes from fe80:0:0:0:acbd:53bf:1461:a861: icmp_seq=2 hlim=64 time=2494ms
      1 packets transmitted, 1 packets received. Packet loss = 0.0%. Round-trip min/a
      Done
      

      Observe that there is a long latency on the reply of up to 3000 ms. This is due to the indirect transmission mechanism based on data polling.

    2. Enable a CSL Receiver on the router kit (now SED) by configuring a CSL period of 0.5 seconds:

      uart:~$ ot csl period 3125
      Done
      
    3. Send an ICMPv6 Echo Request from the leader kit to the link-local address of the router kit:

      uart:~$ ot ping fe80:0:0:0:acbd:53bf:1461:a861
      uart:~$ W: TX_STARTED event will be triggered without delay
      16 bytes from fe80:0:0:0:acbd:53bf:1461:a861: icmp_seq=3 hlim=64 time=421ms
      1 packets transmitted, 1 packets received. Packet loss = 0.0%. Round-trip min/a
      Done
      

      Observe that the reply latency is reduced to a value below 500 ms. The reduction occurs because the transmission from the leader is performed using CSL, based on the CSL Information Elements sent by the CSL Receiver.

Dependencies

This sample uses the following Zephyr libraries:

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