Thread: CLI

The Thread CLI sample demonstrates the usage of OpenThread Command Line Interface inside the Zephyr shell.

This sample supports optional Experimental Thread v1.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 v1.2 extension

This optional extension allows you to test available features from Thread Specification v1.2. You can enable these features either by activating the overlay extension as described below or by setting Thread Specification v1.2 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.

Requirements

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

Hardware platforms

PCA

Board name

Build target

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

nRF52833 DK

PCA10010

nrf52833dk_nrf52833

nrf52833dk_nrf52833

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 v1.2 extension requirements

If you enable the experimental Thread v1.2 extension, you will need nRF Sniffer for 802.15.4 based on nRF52840 with Wireshark to observe messages sent from the router to the leader board when testing v1.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 Working with Thread for more information.

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

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

To update OpenThread libraries provided by the nrfxlib, please 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.

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

    Thread samples have 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. Invoke some of the OpenThread commands:

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

      uart:~$ ot state
router
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 boards

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 boards

To test communication between boards, 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

    Thread samples have 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. Test communication between the boards with the ot ping <ip_address_of_the_first_board> command. 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

    Thread samples have 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 Specification v1.2 features

To test the Thread Specification v1.2 features, complete the following steps:

  1. Make sure both development kits are programmed with the CLI sample with the Thread v1.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. Test the state of the Thread network with the ot state command to see which board is the leader:

    uart:~$ ot state
leader
Done

  5. On the leader board, 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

  6. On the leader board, configure the Domain prefix:

    uart:~$ ot prefix add fd00:7d03:7d03:7d03::/64 prosD med
Done
uart:~$ ot netdataregister
Done
I: State changed! Flags: 0x00000200 Current role: 4
I: State changed! Flags: 0x00001001 Current role: 4

  7. On the router board, 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

  8. On the router board, 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 board will send an MLR.req message to the leader board (Backbone Router). This can be observed using the nRF Sniffer for 802.15.4 based on nRF52840 with Wireshark.

    Note

    The DUA registration with the Backbone Router is not yet supported.

Dependencies

This sample uses the following Zephyr libraries: