openthread / ot-docs

OpenThread documentation

---

What is OpenThread?

OpenThread released by Google is...

...an open-source implementation of the Thread networking protocol. Google Nest has released OpenThread to make the technology used in Nest products more broadly available to developers to accelerate the development of products for the connected home.

...OS and platform agnostic, with a narrow platform abstraction layer and a small memory footprint, making it highly portable. It supports both system-on-chip (SoC) and network co-processor (NCP) designs.

...a Thread Certified Component, implementing all features defined in the Thread 1.3.0 specification, including all Thread networking layers (IPv6, 6LoWPAN, IEEE 802.15.4 with MAC security, Mesh Link Establishment, Mesh Routing) and device roles, as well as Border Router support.

More information about Thread can be found at threadgroup.org. Thread is a registered trademark of the Thread Group, Inc.

Who supports OpenThread?

Getting started

All end-user documentation and guides are located at openthread.io. If you're looking to do things like...

• Learn more about OpenThread features and enhancements
• Use OpenThread in your products
• Learn how to build and configure a Thread network
• Port OpenThread to a new platform
• Build an application on top of OpenThread
• Certify a product using OpenThread

...then openthread.io is the place for you.

Note: For users in China, end-user documentation is available at openthread.google.cn.

If you're interested in contributing to OpenThread, read on.

Contributing

We would love for you to contribute to OpenThread and help make it even better than it is today! See our Contributing Guidelines for more information.

Contributors are required to abide by our Code of Conduct and Coding Conventions and Style Guide.

License

OpenThread is released under the BSD 3-Clause license. See the LICENSE file for more information.

Please only use the OpenThread name and marks when accurately referencing this software distribution. Do not use the marks in a way that suggests you are endorsed by or otherwise affiliated with Nest, Google, or The Thread Group.

Need help?

OpenThread support is available on GitHub:

• Bugs and feature requests — submit to the Issue Tracker
• Community Discussion - ask questions, share ideas, and engage with other community members

ot-docs's Issues

Path error in step 4 of codelab "Build a Thread network with nrf52840 boards and OpenThread"

The path to run ot-ctl should be "./build/posix/src/poxis/ot-ctl". The current path does not exist.

otUdpBind example usage need to be updated

OpenThread PR#6761 added a new arg for otUdpBind(..., otNetifIdentifier aNetif).
The example in the codelab is still using the old API.

When the example is build, the compile error out like this:

../openthread/examples/apps/cli/main.c:319:5: error: too few arguments to function 'otUdpBind'
  319 |     otUdpBind(aInstance, &sUdpSocket, &listenSockAddr);
      |     ^~~~~~~~~
In file included from ../openthread/examples/apps/cli/main.c:46:
../openthread/include/openthread/udp.h:209:9: note: declared here
  209 | otError otUdpBind(otInstance *aInstance, otUdpSocket *aSocket, const otSockAddr *aSockName, otNetifIdentifier aNetif);
      |         ^~~~~~~~~

Not sure if OT_NETIF_UNSPECIFIED or OT_NETIF_THREAD is the correct answer for this example code.

Quitting ot-ctl will not lead to termination of ot-daemon

In the chapter Manage the network with OpenThread Daemon of the codelab Simulating a Thread network with OpenThread (site/en/codelabs/openthread-simulation-posix/index.lab.md), the document states that quit ot-ctl by using Ctrl+D, which did not work on my macOS 12.4, with the current latest Thread version 4. In addition, ot-daemon will not terminate as instructed when trying to use exit command to quit ot-ctl. I guess that the mechanism may change after the version upgrades.

Build Thread network with nRF52840 references old scan with Thread Beacons payload

In the OpenThread "Build a Thread network with nRF52840 boards and OpenThread" codelab, in the "Create the Thread network" step, the scan data referenced was removed 5 months ago in pull 7472.

ping missing from openthread/codelab_otsim Docker image

Minor problem, but ping is missing from the openthread/codelab_otsim Docker image.

> root@ebc7d981f006:~/src/openthread# ping6 -c 4 fdca:f078:8ce4:39be:b258:c4b4:24b6:d7d
bash: ping6: command not found

We can either update the Codelab to instruct the reader to run apt install inetutls-ping,
or the image can be updated to include the tool.

Information missing in codelab

An information is missing in this codelab: https://openthread.io/codelabs/openthread-hardware#4

It is not indicated that you should use the "nRF USB port". If you don't, you don't get the prompt when you call the screen command.

mknod fails in rootless docker setups

Even when running the docker container with the net_admin capability, if you are running docker in rootless mode, you won't be able to create device nodes. Running mknod in these cases will return Operation not permitted.

Came across this issue while following the openthread-simulation codelab: https://openthread.io/codelabs/openthread-simulation#4

Perhaps a note can be added about rootless docker at the start or in the docker troubleshooting chapter?

Broken links in the page Simulate Thread Networks using OTNS / 12. Congratulations

Hello,

I would like to report broken links. Following links in the page Simulate Thread Networks using OTNS 12. Congratulations
are broken:

• Simulating a Thread network with OpenThread
• Simulating a Thread network using OpenThread in Docker
• Build a Thread network with nRF52840 boards and OpenThread

Regards
Ludovic

Codelab 'Simulating a Thread network using OpenThread in Docker': unable to run ot-daemon

The Docker Thread sim Codelab has a possible issue with running the ot-daemon in container #2 (https://openthread.io/codelabs/openthread-simulation#4).

Initially, the daemon is unable to find the ipset command (apparently this is missing from the Docker image).

Once ipset is installed, however, it displays a message that the ip set does not exist:

root@162dbab6802a:~/src/openthread# ./output/posix/bin/ot-daemon -v 'spinel+hdlc+forkpty://output/simulation/bin/ot-rcp?forkpty-arg=2'
./output/posix/bin/ot-daemon[170]: Running OPENTHREAD/g442b7e82f; POSIX; Jan  7 2022 05:52:28
./output/posix/bin/ot-daemon[170]: Thread version: 3
./output/posix/bin/ot-daemon[170]: Thread interface: wpan0
./output/posix/bin/ot-daemon[170]: RCP version: OPENTHREAD/g442b7e82f; SIMULATION; Jan  7 2022 05:50:28
ipset v6.34: Kernel support protocol versions 6-7 while userspace supports protocol versions 6-6
The set with the given name does not exist

When one runs ipset list, no ip sets are listed.

This behavior was observed on two different Debian machines, one running the latest vanilla Debian Stretch.

simulation codelab "commissioner joiner add * JO1NME" didn't work

When following the tutorial here:
https://openthread.io/codelabs/openthread-simulation#3

I got stuck trying to execute the command:
> commissioner joiner add * JO1NME
Error 7: InvalidArgs

Changing to this worked:
> commissioner joiner add * AAAABBBB
Done

But I don't know why

OTBR Web service is not started?

I'm following the steps here: https://openthread.io/guides/border-router/build to install OTBR on a Raspberry Pi 4.

At step 5 where one issue the command "sudo systemctl status" the documentation mentions that the otbr-web.service should be started. This not the case for my 2 attempts do perform this.

Broken link for Microchip on Vendor Support page

On the Vendor Support page, the link for Microchip gives a 404.

"Get the specification" link on openthread.io is dead (404)

To update link to: https://www.threadgroup.org/support#specifications

@jrhodie FYI - I saw you did some work on documentation recently. Maybe you know who could fix this?

Need to specify Thread interface when executing ot-ctl on macOS

In the chapter Manage the network with OpenThread Daemon of the codelab Simulating a Thread network with OpenThread (site/en/codelabs/openthread-simulation-posix/index.lab.md), I start ot-daemon with the command ./output/posix/bin/ot-daemon -v 'spinel+hdlc+forkpty://output/simulation/bin/ot-rcp?forkpty-arg=2' as it instructs. On my macOS 12.4, it outputs

Jun 22 11:57:45  ./output/posix/bin/ot-daemon[24378] <Info>: Running OPENTHREAD/20200818-01767-g481a064f0; POSIX; Jun 21 2022 15:35:36
Jun 22 11:57:45  ./output/posix/bin/ot-daemon[24378] <Info>: Thread version: 4
Jun 22 11:57:46  ./output/posix/bin/ot-daemon[24378] <Info>: Thread interface: utun4
Jun 22 11:57:46  ./output/posix/bin/ot-daemon[24378] <Info>: RCP version: OPENTHREAD/20200818-01767-g481a064f0; SIMULATION; Jun 21 2022 15:33:51

Notice that Thread interface used by ot-daemon is utun4 while the default interface used by ot-ctl is wpan0. So we have to manually specify the interface with arguments -I utun4 in this case when starting ot-ctl later, i.e., execute ./output/posix/bin/ot-ctl -I utun4 instead of ./output/posix/bin/ot-ctl.

Cannot check state of a node

I cannot check the node 2 state in this codelab: https://openthread.io/codelabs/openthread-simulation#4

prompt dont shows ">"

No ping6 in codelab_otsim

When following https://openthread.io/codelabs/openthread-simulation#4 step 5, I get the following:

root@a761053b08c5:~/src/openthread# ping6 -c 4 fdd5:a079:4a43:2154:7d6a:709b:42d:a16d
bash: ping6: command not found

If I manually install the iputils-ping package, it works OK, so it looks like ping6 is missing from the Docker image.

It also says:

on your host machine's command line, ping Node 1

whereas it makes more sense to me to say something like:

on the container's command line, ping Node 1

Missing old Raspberry Pi SoftAP configuration

Hi there,

Back ago, I've followed on opentherad.io a guide to setup a SoftAP on the Raspberry Pi and configuration of all the services (dnsmasq, hostapd, tayga, NAT, ip fwd, etc...) to have a running setup to use along with Thread 1.1 external commissioning App.
Today I'd like to rebuild the same setup with a up to date OTBR and RCP code but this part is missing in the docs.
Commit 6a8ae56 suggests it has been done on purpose.

What is the reason behind that ?
BTW, today's doc suggests RPi is still providing an AP.

Thx and Regards

BeagleBone Black not booting after following OTBR guide

Hello!
I'm building an OTBR with my BeagleBone Black and an ESP32-H2.

[Problem]
After executing the command INFRA_IF_NAME=wlan0 ./script/setup in the OTBR guide (URL: https://openthread.io/guides/border-router/build) and rebooting the board I cannot connect to it. Even if I ping beaglebone.local it does not resolve the name. Notably, the 4 LEDs of the BBB are blinking in the following sequence: D2(0), D2(0), D4(2) D(2). The D4 LED blinks softly, though, and the sequence is a little bit unclear (quite fast and weird).

[Important Information]

• I'm using an 8GB uSD card I flashed with the image bone-debian-10.3-iot-armhf-2020-04-06-4gb.img.xz as per the guide with URL https://openthread.io/guides/border-router/beaglebone-black
• The BBB is connected with ETHERNET to the router.
• The BBB is connected to the PC as well.
• The PC I'm using has an UBUNTU 22.04 LTS installed.

[What I would like]
To fix this issue, because the alternative is to start all over again by flashing the uSD card and installing everything.

All help is appreciated!

Update porting guide to reflect new repo structure

The porting guide needs to be updated to support:

• separate repo for platform
• cmake/ninja build system

Error in codelab

In this codelab (https://openthread.io/codelabs/openthread-border-router#3), there is:

Thread start

It returns
Error 35: InvalidCommand

thread start
is working

Add a linter for Markdown formatting

See if we can use prettify for Markdown content. This content has some special Markdown formatting specific to the openthread.io import that must be accounted for.

Questions about codelab

I have completed this codelab: https://openthread.io/codelabs/openthread-border-router#0

Can you please point me:

• How to see the list of end devices in the Thread network? Shall I use "sudo service otbr-agent status" on the border router?
• How to disconnect the end device (I want to redo the operation but now with the open thread commissioning app).

Thank you!
Regards

Update Netdata concepts page

openthread/openthread#8826 added a few netdata commands and some info to the Netdata CLI README. Please update https://github.com/openthread/ot-docs/blob/main/site/en/reference/cli/concepts/netdata.md as needed to align with it.

Silicon Labs EFR32 Codelab Updates

Hi @silabs-mithil,
I was just going through our documentation and noticed that the EFR32 Codelab is referencing an older Docker tag: siliconlabsinc/openthread-border-router:gsdk-3.2.0

I see that there are some newer images: https://hub.docker.com/r/siliconlabsinc/openthread-border-router/tags

Would it be possible to update this Codelab to a more recent Thread 1.2 version? Is it just a matter of updating the tag, or does the Codelab need additional updates too?

Thanks so much, and please let me know if there's anything I can do to help. I'm happy to make any updates required.
Sarah
@Vyrastas

Missing command in step 8 of codeleb "Building a Thread network with nrf52840 bords and openThread"

In the RCP node, before executing command "thread start" it is necessary to execute "ifconfig up" to bring up the IPv6 interface. After this the comand "thread start" can be executed. Otherwise and error will appear.

Update Dataset concepts with warning about production use

There was info added to the DATASET readme in the main repo https://github.com/openthread/openthread/pull/10026/files#diff-38fb58c06769c0283e1dd05c06244d63d29561169ca8a2b56166130255467a04

Specifically about restrictions for dataset CLI commands in production. We should add a similar warning to our Dataset concepts guide: https://github.com/openthread/ot-docs/blob/main/site/en/reference/cli/concepts/dataset.md

Missing Border Agent docs for OTBR Docker

The OTBR Docker guide lacks information about how to expose the IPv6 UDP port of the Border Agent to the host to be able to connect with the OT Commissioner: https://github.com/openthread/ot-docs/blob/main/site/en/guides/border-router/docker/run.md

Requirement for Raspberry Pi OS with Desktop?

Related to this page: https://openthread.io/guides/border-router/docker

I think the requirement for using Raspberry Pi OS with Desktop is a bit confusing.

"You cannot use the Lite version, as you need to access the OTBR Web GUI in a web browser."

In my experience it's possible to open the OTBR Web GUI in a web browser running on another computer.

Maybe it should be clarified?