some elements have link to the corresponding websites

test connectivity

openthread API reference

Cheat sheet

IPv6 bit length : 128 bit = 8x 16 ibts => 00b1:00b2:00b3:00b4:00b5:00b6:00b7:00b8
Link-Local prefix : fe80::/16
Mesh-Local prefix : fd00::/8
Multicast Link-Local : ff02::1
Multicast Mesh-Local : ff03::1
RLOC16 : Routing locator in 16 bits 0x0401
RLOC16 Router mask : 0x0400
IID : Interface Identifier (includes RLOC16)
RLOC = Mesh-Local Prefix + IID

Tools

nRF Connect for desktop

nRF Command Line Tools

GNU Arm Embedded Toolchain v7-2018-q2

nRF SDK for Thread and Zigbee v4.1.0

download the SDK

nRF Connect SDK installing

install nRF Connect for deskop
From within nRF connect, install Toolchain Manager
From the Toolchain manager, install the last nRF Connect SDK

Thread Nodes

A Thread network setup contains the following Nodes

radio or network coprocessor : dongle connected to the raspberry pi
border router host : services running on a raspberry pi
cli tester : command line dongle through serial monitor for testing
mqtt-sn : end device with mqtt-sn such as sensors
Topology Monitor : GUI interface. Note the hex file to flash on the nRF52840 USB dongle are provided as part of the download pack in nRF_TTM-win32-x64_0.13.0.zip\nRF_TTM-win32-x64\hex. A different CLI or NCP fimware would not work.
Wireshark sniffer : dongle that captures all frames and shows them on wireshark

Border Router

To create a border router, a usb dongle needs to be flashed (Radio Co-Processor) and attached to a raspberry pi where the following services are installed.

Form a network

on the raspi command line

sudo ot-ctl dataset init new

sudo ot-ctl dataset channel 24
sudo ot-ctl dataset channel
sudo ot-ctl dataset panid 0x1234
sudo ot-ctl dataset panid
sudo ot-ctl dataset networkname ThreadMatter
sudo ot-ctl dataset networkname
sudo ot-ctl dataset extpanid 1111111122222222
sudo ot-ctl dataset networkkey 00112233445566778899aabbccddeeff
sudo ot-ctl dataset

sudo ot-ctl dataset commit active

sudo ot-ctl ifconfig up
sudo ot-ctl thread start

Copied!

check with

sudo ot-ctl state
sudo ot-ctl netdata show
sudo ot-ctl ipaddr

Copied!

on the web interface

connect on the raspberry pi url http://10.0.0.41/

on the left menu click on Join then select the required paramters (e.g. Channel,...) then click on FORM

wireshark sniffing

git clone https://github.com/NordicSemiconductor/nRF-Sniffer-for-802.15.4
Folow the user guide especially section Installing the nRF Sniffer capture plugin in Wireshark
- Flash the nrf802154_sniffer_dongle.hex
- configure the used masterkeys in wireshark menu Edit/Preferences then Protocols/IEEE 802.15.4 in Decryption Keys Edit...

When Forming a network, some Pakets can be sniffed including advertisment

MQTT Sensors Node

MQTT-SN is a protocol not requiring Thread necessarily, it is rather a protcol for a bridge that allows clients to interact with an MQTT Broquer with minimal payload and packets transfers, therefore, it is well adapted to ip over low power mesh networks such as Thread.
Example firmware mqttsn_sleepy_publisher and mqttsn_client_publisher are a port of the nRFSDK example from PCA10056 which was the only supported board to the PCA10059, the nRF52840 USB dongle, therefore the search gateway, connect, publish sequence have been merged in on button and run cyclically on each new press.

mqttsn_sleepy_publisher

mqttsn_client_publisher

MQTT-SN_spec_v1.2.pdf

useful commands

sudo systemctl status paho-mqttsn-gateway.service
sudo /usr/sbin/MQTT-SNGateway -f /etc/paho-mqtt-sn-gateway.conf
sudo nano /etc/paho-mqtt-sn-gateway.conf

Copied!

paho-mqtt-sn-gateway.conf

#**************************************************************************
# Copyright (c) 2016-2019, Tomoaki Yamaguchi
#
# All rights reserved. This program and the accompanying materials
# are made available under the terms of the Eclipse Public License v1.0
# and Eclipse Distribution License v1.0 which accompany this distribution.
#
# The Eclipse Public License is available at
#    http://www.eclipse.org/legal/epl-v10.html
# and the Eclipse Distribution License is available at
#   http://www.eclipse.org/org/documents/edl-v10.php.
#***************************************************************************
#
# config file of MQTT-SN Gateway
#

# IPv4 Address of iot.eclipse.org
BrokerName=10.0.0.42
BrokerPortNo=1883
BrokerSecurePortNo=8883

#
# When AggregatingGateway=YES or ClientAuthentication=YES,
# All clients must be specified by the ClientList File
#

ClientAuthentication=NO
AggregatingGateway=NO
QoS-1=NO
Forwarder=NO

#ClientsList=/path/to/your_clients.conf

PredefinedTopic=NO
#PredefinedTopicList=/path/to/your_predefinedTopic.conf

#RootCAfile=/etc/ssl/certs/ca-certificates.crt
#RootCApath=/etc/ssl/certs/
#CertsFile=/path/to/certKey.pem
#PrivateKey=/path/to/privateKey.pem

GatewayID=1
GatewayName=PahoGateway-01
KeepAlive=900
#LoginID=your_ID
#Password=your_Password


# UDP
GatewayPortNo=10000
MulticastIP=225.1.1.1
MulticastPortNo=1883

# GatewayUDP6Broadcast address is set to all Thread devices address
# in order to enable Thread Sleepy Devices to receive multicast messages
# sent from the gateway.
# UDP6
GatewayUDP6Port = 47193
GatewayUDP6Broadcast = ff03::1
GatewayUDP6If = wpan0

# XBee
Baudrate=38400
SerialDevice=/dev/ttyUSB0
ApiMode=2

# LOG
ShearedMemory=NO;

Copied!

Test vector for sending a SEARCHGW message to the MQTT-SQ gateway service

#send (Length 3)(MsgType SEARCHGW=1)(Radius 1)
echo -n -e "030101" | xxd -r -p | nc -u fd11:1111:1122:0:98bf:60c7:9431:ee90 47193

Copied!

Building on other frameworks

Platformio

although Zephyr is integrated in platformio, openthread is unfortunately not yet supported as of framework-zephyr 2.20400.201210 (2.4.0)
docs.platformio limitations

Arduino

in discussion in this openthread issue#1803, the issue is that Arduino lacks the netwroking layers required to provide a descent interface to the app.

Build with Matter Node

As the Matter Protocol can run over Thread, it is possible to connect Matter applications.

More about Project Matter

Command Line Interface

Openthread CLI Reference

cli dongle

building with openthread repo

new nRF52840 Build instructions

cd ~/ot-nrf528xx
./script/bootstrap
./bootstrap
sudo rm -rf build/
./script/build nrf52840 USB_trans -DOT_COMMISSIONER=ON -DOT_JOINER=ON -DOT_THREAD_VERSION=1.2
cd build/bin/
arm-none-eabi-objcopy -O ihex ot-cli-ftd ot-cli-ftd-com-join.hex

Copied!

ot-cli-ftd thread-reference-20191113

nrfjprog -f nrf52 --eraseall
nrfjprog -f nrf52 --program ot-cli-ftd.hex --sectorerase --verify

Copied!

building with nRFSDK

new nRF52840 Build instructions

cd nrf\v2.3.0\nrf\samples\openthread\cli
>west build -p always -b nrf52840dongle_nrf52840 -- -DOVERLAY_CONFIG="overlay-usb.conf" -DDTC_OVERLAY_FILE="usb.overlay"
>nrfutil pkg generate --hw-version 52 --sd-req=0x00 --application build/zephyr/zephyr.hex --application-version 1 build/zephyr/zephyr.zip
nrfutil dfu usb-serial -pkg build/zephyr/zephyr.zip -p COM8

Copied!

then on terminal laways preceed with ot for openthread commands

uart:~$ ot state
disabled
Done

Copied!

connecting a node with credentials

panid 0x1234
panid
channel 24
channel
networkname OpenThreadDemo
networkname
extpanid 1111111122222222
masterkey
ifconfig up
thread start
state

Copied!

Note masterkey command is for the Network Key

at this stage the state command should log child

wireshark should log the join as follows

it's possible to ping with the router ip

>ping fe80::c85c:d0c4:1103:31d5
Done
> 16 bytes from fe80:0:0:0:c85c:d0c4:1103:31d5: icmp_seq=2 hlim=64 time=12ms

Copied!

a good exercice is to commission a device through CLI

External commitioning

Commissioning

make sure you use cli dongles with Commissioner and joiner compile options, see cli dongle
openthread commissioning
commissioning commands
dataset commands
make sure the used masterky is configured in the wireshark sniffer to analyse the exchange

on the commissioner cli run

thread stop
ifconfig down

dataset init new
dataset
dataset channel 24
dataset channel
dataset masterkey 00112233445566778899aabbccddeeff
dataset commit active
ifconfig up
thread start
commissioner start
commissioner joiner add * ABCDE2

Copied!

on the joiner cli run

factoryreset
ifconfig up
joiner start ABCDE2

Copied!

commissioner and joiner logs

commissioner log

> commissioner start
Commissioner: petitioning
Done
> Commissioner: active

> commissioner joiner add * ABCDE2
Done
> ~ Discovery Request from 76380f6b58cf89f6: version=3,joiner=1
Commissioner: Joiner start a320c9053f0862ce
Commissioner: Joiner connect a320c9053f0862ce
Commissioner: Joiner finalize a320c9053f0862ce
Commissioner: Joiner end a320c9053f0862ce

Copied!

joiner log

> joiner start ABCDE2
Done
> Join success

Copied!

wireshark sniffing should display among others the following transactions
- MLE : Discovery Request
- MLE : Discovery Response
- DTLSv1.2 : Client Hello
- DTLSv1.2 : Hello Verify Request
- DTLSv1.2 : Server Hello, Server Key Exchange, Server Hello Done
- DTLSv1.2 : Client Key Exchange, Change Cipher Spec, Encrypted Handshake Message
- ...

Thread UDP packets

Thread UDP packets are encapsulated using 6LoWPAN which has a payload of 88 Bytes, that's why such a json UDP text message

thread_tags/7009D837C7BB557A{"alive":18673,"voltage":3.106,"light":184.948,"temperature":24.56,"humidity":46.49,"pressure":961.90}

Copied!

is split in two packets where each has an ACK. From one side that's a lot x4 times of what the RF power consumption could be for a simple broadcast, but at the same time it avoids taking care of manually adapting the program behaviour to accomodate the protocol. Also keeping a json text format instead of binary avoids a middle layer converting binary to text readable by apps, that would cost a bottleneck dependency between each device and the gateway.

![udp over 6LowPAN](./udp over 6LoWPAN.png)

FAQ - Discussion

If you need support, want to ask a question or suggest a different answer, you can join the discussion on the github forum
Home Smart Mesh - OpenThread category
see also
google groups openthread users

threadgroup FAQ

What is the difference between RCP/NCP Thread Stack ?

RCP stands for Radio Co-Processor and only includes the MAC Layer not the full Thread Core stack. More details : https://openthread.io/platforms#network-co-processor-ncp

What is the difference between FTD/ETD Thread Devices ?

FTD = Full Thread device can be a Thread router or more, an ETD End Thread Device can be M:minial or S:Sleepy and in both cases does not route packets. More details https://openthread.io/guides/thread-primer/node-roles-and-types

What is the difference between using an RCP/NCP and running Thread as a stand alone device ?

The difference only lays on the partitioning of the application, in the RCP/NCP the application runs on the Host be it a raspberry pi or another uC, in the stand alone the whole thread stack and app run on the same device. We can think of the NCP as example like the CLI=command line interface Thread utility, but the protocol is not text mode rather binary. If the host is an uC itself, the question would be, why using two uC and if it is possible rather to merge them in just one, a corner case might need that like for example a double uC with WiFi and thread capabiltiy.

Does the Thread Topolog Monitor use the same CLI firmware as the openthread CLI ?

No, the Thread Topology monitor TTM comes with it own firmware that needs to be flashed

How does the Thread Topolog Monitor work ? What can it see ?

The Thread Topolog Monitor TTM is an active node on the network, it needs the credentials to be able to join it and only then it can retrieve info from the network it will also display itself in the network.

What is the difference between the Thread Topology Monitor and the 802.15.4 sniffer ?

The 802.15.4 sniffer does not join the network and is totally passive. It can listen to all the traffic of the channel it is in, including all pan ids. If it has the master key, it can then decript data from the corresponding network.

can I run openthread with Arduino ?

No, at least not at the moment and not within a native integration similar to the wifi and network in arduino, see the list of libraries and the connectivity section https://www.arduino.cc/reference/en/libraries/. Despite being known to be an IDE, under the hoods, Arduino is also a framework. The current preferred and supported framework for openthread is Zephyr-OS.

can I run openthread with platformio ?

This is under investigation and should be available soon. The current platformio integration of Zephyr-OS does not include openthread, but this is likely to change any time soon.

Which other families than nRF from Nordic support Thread ?

Many platforms are supported including but not limited to Cascoda, NXP, Qorvo which extends to uwb variant, Samsung, Silicon Labs, STMicroelectronics, Synopsys, Telink Semiconductors, TI more details on openthread platforms. Note that Espressif although listed in the platforms, does not support 802.15.4 therefore can only run the openthread stack as a host that requires an external RCP from the previous list.

Overview

Cheat sheet

Specification

Tools

Thread Nodes

Border Router

raspberry pi

Radio Co-Processor (RCP)

udp test

Form a network

wireshark sniffing

MQTT Sensors Node

Firmware flow diagram

Firmware search gateway

Building on other frameworks

Platformio

Arduino

Build with Matter Node

Command Line Interface

cli on border router

cli dongle

cli reference

Commissioning

Thread UDP packets

FAQ - Discussion