openwrt-packages/net/openthread-br

OpenThread Border Router

This package contains the OpenThread Border Router.

Requirements

To use this package, you need a Thread Radio Co-Processor (RCP). Testing of this package was done with Nordic Semiconductor nRF52840 USB dongles.

Building and flashing the dongle with the Thread RCP firmware is out of scope of this document.

One caveat for this dongle is worth mentioning here. The nRF52840 USB dongle seems to come with the U2F bootloader. To get it in mass storage mode to copy a firmware file, you need to plug it in while pressing the reset button. However, after the initial flash with the ot-rcp firmware, this method stops working. Instead, you need to double press the reset button after plugging in the dongle.

Packaging decisions

Configurable package build

OpenThread is complex software. Adding config options to change the build of the package will likely result in more bug reports. As the package and its dependencies are unlikely to fit in any router with small flash (16MB or less), I don't see much point in making things configurable for reducing size either.

Firewall support

OpenWrt uses firewall4 with nftables by default, but the OpenThread firewall implementation uses IPTables and IPset. While we still support firewall3 with IPTables, it's not a good idea to add new dependencies to old things. Therefore, firewall support is disabled completely.

This can be revised once the following feature request is implemented: https://github.com/openthread/ot-br-posix/issues/1675

mDNSResponder

The package depends on mDNSResponder. The alternative, Avahi, depends on D-Bus, which is not something I feel comfortable with running on any router. While there are Avahi packages without D-Bus support, using OpenThread Border Router with Avahi requires libavahi-client, and this requires Avahi to be built with D-Bus support.

REST Server

The REST server is enabled to make this package compatible with Home Assistant.

TREL support

Thread Radio Encapsulation Link support is enabled, as it allows Border Routers to communicate over other links (e.g. Ethernet), reducing traffic over the 802.15.4 radios.

The following Github discussion contains a good explanation of TREL: https://github.com/openthread/openthread/discussions/8478

UCI/netifd support

The package contains a minimal netifd protocol handler. This allows configuring the Thread network in /etc/config/network. The agent will be started by netifd, rather than using an init script.

OpenThread does not store prefix information in non-volatile storage. As a result, every time the agent is restarted, a different prefix would be used. This is not very nice, and makes it very difficult to run the OpenThread Border Router on a device that is not your main router. Therefore, prefixes can be configured in /etc/config/network. This way, you can add a static route to the Thread prefix(es) in your main router, making it possible to access devices on the Thread network from your entire network.

Create network

When starting the OpenThread Border Router for the first time, a Thread network must be created.

As the agent is started by netifd, we first need to create an interface in /etc/config/network:

config interface 'thread'
        option device 'wpan0'
        option proto 'openthread'
        option backbone_network 'lan'
        option radio_url 'spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=460800'
        list prefix 'fd6f:5772:5468:7200::/64 paros'
        option verbose '0'

Prefix and verbose are optional. Everything else is required. The protocol handler will fail if a required setting is missing. If something isn't working, check ifstatus for the OpenThread interface:

# ifup thread
# ifstatus thread
{
        "up": false,
        "pending": false,
        "available": true,
        "autostart": false,
        "dynamic": false,
        "proto": "openthread",
        "data": {

        },
        "errors": [
                {
                        "subsystem": "openthread",
                        "code": "MISSING_BACKBONE_NETWORK"
                }
        ]
}

In the above example, the backbone_network option is missing.

The protocol handler will automatically start the the Thread network, so we need to bring it down for the initial setup. This only needs to be done once.

ubus call otbr threadstop

LuCI

Creating a network in LuCI appears to be broken for the moment.

CLI

ot-ctl dataset init new
ot-ctl dataset panid 0x12ab
ot-ctl dataset extpanid 12ab12ab12ab12ab
ot-ctl dataset networkname OpenWrThread
ot-ctl dataset networkkey ddf429af1c52d1735ffaf36fae343ee8
ot-ctl dataset commit active
ot-ctl ifconfig up
ot-ctl thread start
ot-ctl netdata register

Configure route

Before you can join a device to your new Thread network, you must add a route to the Thread prefix on the commissioner device via the OpenWrt router running the OpenThread Border Router.

Get the prefix:

ot-ctl prefix

Example output:

fd6b:a92f:c531:1::/64 paros low f000
Done

Configuring the route is out of scope of this document, but it must be done, or joining Thread devices will fail.

Get hex-encoded operational dataset TLV

This is needed to join devices to the Thread Network.

ot-ctl dataset active -x

Example output:

0e080000000000010000000300001035060004001fffe00708fd488c6a892ec30c04106e220c964a14a7e10e9004691920ec390c0402a0f7f80102ffff030b5468726541646c6576696f0208ffffffffffffffff0510ddf429af1c52d1735ffaf36fae343ee8

Join another OpenThread Border Router

Simply configure the active dataset in /etc/config/network:

config interface 'thread'
        option device 'wpan0'
        option proto 'openthread'
        option backbone_network 'lan'
        option dataset '0e080000000000010000000300000f35060004001fffe0020836b86cd9746ab3080708fd9850cbe719b1d205101f11a11320828c7a6ebc2f2e675c0dca030e686f6d652d617373697374616e740102716f041025804ed78614258ebedf4e2db37b3b6e0c0402a0f7f8'
        list prefix 'fd6f:5772:5468:7200::/64 paros'
        option radio_url 'spinel+hdlc+uart:///dev/ttyACM0?uart-baudrate=460800'
        option verbose '0'

Afterwards, bring up the interface:

ifup thread

Join a Thread device via Matter

ESP32

The following procedure has been tested with an ESP32-C6 using the Matter lighting-app example. Building and flashing that app is out of scope of this document.

During startup, the lighting app will print the SetupQRCode to the serial console:

I (1614) chip[SVR]: SetupQRCode: [MT:Y.K9042C00KA0648G00]
I (1624) chip[SVR]: Copy/paste the below URL in a browser to see the QR Code:
I (1634) chip[SVR]: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AY.K9042C00KA0648G00
I (1644) chip[SVR]: Manual pairing code: [34970112332]

Decide on a node ID for the device.

./chip-tool pairing code-thread 0x65737933320000 hex:0e080000000000010000000300001035060004001fffe00708fd488c6a892ec30c04106e220c964a14a7e10e9004691920ec390c0402a0f7f80102ffff030b5468726541646c6576696f0208ffffffffffffffff0510ddf429af1c52d1735ffaf36fae343ee8 MT:Y.K9042C00KA0648G00 --paa-trust-store-path /path/to/connectedhomeip/credentials/test/attestation/