Thread: CLI

• Requirements
• Overview
  • Certification tests with CLI sample
• User interface
  • Diagnostic module
• Configuration
  • Configuration files
  • FEM support
  • Memory optimization
  • Serial transport
• Building and running
  • Testing
  • Power consumption measurements
• Dependencies

The :ref:`Thread <ug_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.

Requirements

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

.. table-from-sample-yaml::

Optionally, you can use one or more compatible development kits programmed with this sample or another :ref:`Thread sample <openthread_samples>` for :ref:`testing communication or diagnostics <ot_cli_sample_testing_multiple>` and :ref:`thread_ot_commissioning_configuring_on-mesh`.

You need `nRF Sniffer for 802.15.4`_ to observe messages sent from the router to the leader kit when :ref:`ot_cli_sample_testing_multiple_v12`.

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 number of commands you can test depends on the application configuration. The CLI sample comes with the :ref:`full set of OpenThread functionalities <thread_ug_feature_sets>` enabled (:kconfig:option:`CONFIG_OPENTHREAD_NORDIC_LIBRARY_MASTER`). Thread 1.2 version is selected as default.

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 for testing the communication.

Certification tests with CLI sample

You can use the Thread CLI sample to run certification tests. See :ref:`ug_thread_cert` for information on how to use this sample on Thread Certification Test Harness.

User interface

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

Diagnostic module

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

Note

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

Configuration

|config|

Configuration files

The sample provides predefined configuration files for typical use cases, and to activate sample extensions. You can find the configuration files in the root directory of the sample.

Specify the corresponding file names in the :makevar:`OVERLAY_CONFIG` option when building. See :ref:`cmake_options` for instructions on how to add this option. For more information about using configuration overlay files, see :ref:`zephyr:important-build-vars` in the Zephyr documentation.

The following configuration files are available:

• :file:`overlay-usb.conf` - Enables USB transport support. Additionally, you need to set :makevar:`DTC_OVERLAY_FILE` to :file:`usb.overlay`.
• :file:`overlay-logging.conf` - Enables logging using RTT. For additional options, refer to :ref:`RTT logging <ug_logging_backends_rtt>`.
• :file:`overlay-debug.conf` - Enables debugging the Thread sample with GDB thread awareness.
• :file:`overlay-ci.conf` - Disables boot banner and shell prompt.
• :file:`overlay-multiprotocol.conf` - Enables Bluetooth LE support in this sample.
• :file:`overlay-tcp.conf` - Enables experimental TCP support in this sample.
• :file:`overlay-low_power.conf` - Enables low power consumption mode in this sample. Additionally, you need to set :makevar:`DTC_OVERLAY_FILE` to :file:`low_power.overlay`.

FEM support

Memory optimization

See :ref:`app_memory` for actions and configuration options you can use to optimize the memory footprint of the sample.

Serial transport

The Thread CLI sample supports UART and USB CDC ACM as serial transports. By default, it uses UART transport. To switch to USB transport, :ref:`activate the USB overlay extension <ot_cli_sample_activating_variants>`.

Building and running

|enable_thread_before_testing|

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

Testing

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

1. Turn on the development kit.

2. |connect_terminal_ANSI|

   Note

   |thread_hwfc_enabled|

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
      OpenThread
      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 multiple 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. |connect_terminal_both_ANSI|

   Note

   |thread_hwfc_enabled|

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=3 hlim=64 time=23ms
   1 packets transmitted, 1 packets received. Packet loss = 0.0%. Round-trip min/av
   Done

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

   Note

   |thread_hwfc_enabled|.

4. Make sure that the diagnostic module is enabled and configured with proper radio channel and transmission power. Run 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. To read the radio statistics on the other device, run 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 and Thread 1.3 features

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

1. Enable the extra options :kconfig:option:`CONFIG_OPENTHREAD_BORDER_ROUTER`, :kconfig:option:`CONFIG_OPENTHREAD_BACKBONE_ROUTER` and :kconfig:option:`CONFIG_OPENTHREAD_SRP_SERVER` when building the CLI sample.

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

3. Turn on the developments kits.

4. |connect_terminal_both_ANSI|

7. Test the state of the Thread network with the ot state command to see which kit is the leader:

   uart:~$ ot state
   leader
   Done

8. On the leader kit, enable the Backbone Router function:

   uart:~$ ot bbr enable
   Done

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

10. 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
    Done
    uart:~$ ot dua iid 0004000300020001
    Done
    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

11. On the router kit, configure a multicast address with a scope greater than realm-local:

    uart:~$ ot ipmaddr add ff04::1
    Done
    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 sends an MLR.req message and a DUA.req message to the leader kit (Backbone Router). Use the `nRF Sniffer for 802.15.4`_ to observe this.

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

13. Run the following commands on the router kit:

    1. Reattach the router kit as Sleepy End Device (SED) with a polling period of three 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 data in Enh Ack from neighbor, short address:0xa400 , extended address:12b193eac0eeeeb7
       - LQI: 255 (Exponential Moving Average)
       - Margin: 68 (dB) (Exponential Moving Average)

    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

14. 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, up to 3000 ms, on the reply. This is due to the indirect transmission mechanism based on data polling.

    2. Stop frequent polling on the router kit (now SED) by configuring a polling period of 240 seconds:

       uart:~$ ot pollperiod 240000
       Done

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

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

15. Verify the Service Registration Protocol (SRP) functionality.

    1. On the leader kit, enable the SRP Server function:

       uart:~$ ot srp server enable
       Done

    2. Register a _ipps._tcp` service on the router kit (now SED):

       uart:~$ ot srp client host name my-host
       Done
       uart:~$ ot srp client host address fdde:ad00:beef:0:e0fc:dc28:1d12:8c2
       Done
       uart:~$ ot srp client service add my-service _ipps._tcp 12345
       Done
       uart:~$ ot srp client autostart enable
       Done

    3. On the router kit (now SED), check that the host and service have been successfully registered:

       uart:~$ ot srp client host
       name:"my-host", state:Registered, addrs:[fdde:ad00:beef:0:e0fc:dc28:1d12:8c2]
       Done

    4. Check the host and service on the leader kit:

       uart:~$ ot srp server host
       my-host.default.service.arpa.
          deleted: false
          addresses: [fdde:ad00:beef:0:e0fc:dc28:1d12:8c2]
       Done
       uart:~$ ot srp server service
       my-service._ipps._tcp.default.service.arpa.
          deleted: false
          subtypes: (null)
          port: 12345
          priority: 0
          weight: 0
          ttl: 7200
          TXT: []
          host: my-host.default.service.arpa.
          addresses: [fdde:ad00:beef:0:e0fc:dc28:1d12:8c2]
       Done

Power consumption measurements

You can use the Thread CLI sample to perform power consumption measurements for Sleepy End Devices.

After building and flashing with :file:`overlay-low_power.conf` and :file:`low_power.overlay`, the device will start regular operation with the UART console enabled. This allows for easy configuration of the device, specifically the Sleepy End Device polling period or the Synchronized Sleepy End Device (SSED) CSL period and other relevant parameters.

When the device becomes attached to a Thread Router it will automatically suspend UART operation and power down unused RAM. In this mode, you cannot use the CLI to control the device. Instead, the device will periodically wake up from deep sleep mode and turn on the radio to receive any messages from its parent.

If the device is connected to a `Power Profiler Kit II (PPK2)`_, you can perform detailed power consumption measurements.

See :ref:`thread_power_consumption` for more information.

Dependencies

This sample uses the following Zephyr libraries:

• :ref:`zephyr:kernel_api`:
  • include/kernel.h
• :ref:`zephyr:thread_protocol_interface`

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

• :ref:`nrfxlib:softdevice_controller`
• :ref:`nus_service_readme`
• Zephyr's :ref:`zephyr:bluetooth_api`:
  • include/bluetooth/bluetooth.h
  • include/bluetooth/gatt.h
  • include/bluetooth/hci.h
  • include/bluetooth/uuid.h

In addition, it uses the following secure firmware component:

• :ref:`Trusted Firmware-M <ug_tfm>`