Thread was designed with one goal in mind; to create the best way to connect and control products in a home environment. The key features of Thread are:
- Designed for home.
- Built-in security.
- Optimized for battery-operated devices.
- Utilizes IPv6 protocols.
- Robust mesh network.
- Simple to set up and use.
The Thread stack is built on IPv6 over Low power Wireless Personal Area Networks (6LoWPAN), which itself builds on IEEE 802.15.4 to offer IP-based networking. Internet Protocol (IP) provides the core mechanism for relaying datagrams across IP networks, and its routing capabilities enable internetworking.
Read more at the Thread Group site.
Why Mbed OS with Thread stack
Mbed OS is an open source embedded operating system designed specifically to facilitate the creation and deployment of commercial, standards-based IoT solutions at scale. Mbed OS features full support for Thread to simplify development of secure IoT applications in home and to ease the Thread product certification. The Mbed OS Thread stack is a Thread Group certified component.
Thread stack is based on the Mbed OS key elements
The key elements of Mbed OS are:
- Hardware platform agnostic layer that allows easy adaptation of new hardware components.
- Modular approach, which allows including the necessary libraries based on the application needs.
- Multilayer build (SW/HW) in security that helps you to protect your IoT solutions.
- Mbed RTOS (Arm CMSIS-RTOS) providing the real time software execution.
- Toolchain and IDE support.
Thread stack is implemented in the Nanostack library, which also supports other 6LoWPAN-based protocols. In Mbed OS, the Thread stack runs in its own RTOS thread using an internal event scheduler. Mbed OS provides the Mesh C++ API for building Thread applications.
- To connect to the Thread network, use the Thread interface API.
- For the socket communication over the Thread network, use the Mbed sockets API.
Nanostack provides a set of C API headers with more functionalities. The nanostack repository has the following header files():
thread_management_if.hfor initializing the stack and managing the network data.
thread_commissioning_api.hfor implementing an on-mesh or a native Thread commissioner.
thread_border_router_api.hfor implementing a Thread border router.
thread_diagcop_lib.hfor building and parsing the Thread diagnostics protocol TLV messages.
thread_meshcop_lib.hfor building and parsing the Thread mesh commissioning protocol TLV messages.
thread_net_config_api.hfor making neighbour discovery (ND) data requests.
Thread devices you can build on Mbed OS
The Mbed OS Mesh API allows you to define 3 types of devices:
- Router enabled device (REED), which can become an active router.
- Sleepy end device (SED).
- Minimal end device (MED).
In addition the Nanostack API allows you to define the Full end device (FED) device type.
In most cases, the REED, MED and SED configurations are enough to build a network. In a SED device, the radio is switched off during the sleep times. To take the full advantage of the SED configuration, the application developer must implement the sleep procedures in the device.
For an end device or a router example, see mesh minimal example.
Mbed OS offers separate configurations for different Thread end device types. Usually, the end devices are the most constrained devices in the Thread network. They serve as last hop in the mesh topology. Devices such as plain sensors, controls and switches can be implemented as end devices only. For the most constrained hardware, the minimal end device (MED) or the sleepy end device (SED) is an optimal selection as the implementation requires the smallest amount of flash and RAM memory due to the limited functionality. Note that a sleepy end device also requires more resources on the parent device. End devices communicate through a parent and can switch to another parent if the current connection is broken.
A Thread network does not work with end devices only. There must be router devices, that can route the traffic between nodes and to the back-end network through the border router.
Minimal end device (MED):
- Registers its address to a single parent.
- Relies all routing and address queries on the parent.
- Must start a new scan if the parent is lost; longer disconnect from network.
Sleepy end device (SED) is like MED, but:
- Does not keep the radio on all the time.
- Uses a polling mechanism to receive packets from the parent (polling time configurable).
- Requires the parent to store packets when in sleep.
- Can be temporarily switched to MED to transfer large amounts of data.
Full End Device (FED):
- Does not register addresses to the parent.
- Makes address queries.
- Listens to multicast messages from other devices (others than parent).
- Reduces the parent device's load and memory requirements compared to MED and SED.
In Thread networks, devices operate in several specific roles separated by the services they provide. All router devices provide mesh routing and they can switch the state between an active router and a REED device without any user interaction. The first router on a network becomes a leader, that manages:
- Router ID assignment.
- Thread network data registration.
- Network data distribution.
- Commissioner petition.
Additionally, a router can act as a border router (must be configured in build time), that provides services for devices within the Thread mesh network and the backbone network.
Mbed OS offers a separate build for a Thread border router. The border router routes IPv6 traffic to the external IPv6 networks. Currently, our border router uses an Ethernet connection to the backbone IP network, but also other means of connectivity are available (cellular or WiFi).
See an example of a Thread border router.
Commissioning takes place when new devices need to be added to the Thread network. All Mbed OS Thread devices (end nodes and routers) can join to any certified Thread network. In Thread, there can be one commissioner, that allows new devices to join the network. There are three types of commissioners:
- A native commissioner uses the 802.15.4 radio interface, but does not belong to the Thread network.
- An on-mesh commissioner is a Thread device already joined in the Thread network.
- An external commissioner connects to the Thread network through the border router, that is connected to the backbone.
Example use case for external commissioning
An external commissioner uses mDNS-SD service discovery to find a list of available Thread networks. When you select the network to connect to, the application asks for the network passphrase. The passphrase is usually placed on a label on the border router box (like in WiFi).
The commissioner application generates PSKc from:
- The network passphrase.
- The Thread network name.
- The extended PAN ID.
The Thread network name and the extended PAN ID are received in the scanning phase. The commissioner application can now start a DTLS session using the generated PSKc.
After the authentication phase, the commissioner requests the Thread network leader to petition the commissioner to become an authorized commissioner. Here, the border router works as an arbitrator in the middle.
Now, the Thread network is ready to accept new joiner devices.
- The commissioner application scans the QR code, which is PSKd (Pre-Shared Key for device) + EUI64, from the device's label and informs the Thread network that this device is accepted to the network.
- The joiner device detects in the scanning response that it can now join the network and starts a DTLS session using PSKd.
- The session is created through the Thread network (via the joiner router and the border router) to the commissioner application.
- The commissioner authenticates the device and accepts it to the network.
- The device receives the Thread configuration, which allows it to join.
Note: Thread uses hashing and elliptic curve algorithms for the secure communication. PSKd(s) and EUI64(s) are never transmitted in plain text over the peer to peer connection.
Storing configuration settings in the file system
The Thread network stack can write network configuration settings to the file system and read them in the following startup. The size of the Thread configuration settings is a few thousand bytes. You can store network configuration settings to the file system when:
- You enable the file system as instructed in the Mbed OS storage documentation.
- You set the file system root path to the Thread network stack by calling the function
ns_file_system_set_root_path(root-path). Do this before starting the Thread stack to read possible configuration settings in the first power up.
Depending on the selected file system, the application may need to format the file system before you can use it.
How to start on Mbed OS
The Mbed OS Thread stack supports all three types of commissioners. You can create an external commissioner application by using the Thread MeshCoP protocol or use the Mbed OS APIs (
thread_commissioning_api.h) to implement a native or an on-mesh commissioner. Currently, there is no reference implementation for native or on-mesh commissioners. External commissioning is supported through the Nanostack border router. An external Commissioning application (Android) is already available. Also an IOS version will be available soon.
See Thread commissioning guide how to commission a Thread device to the network in practice.
The maturity of the Mbed OS Thread implementation
Mbed OS provides a certified Thread 1.1 stack implementation.
In addition to the Thread Group certification, where the focus is to ensure interoperability with different implementations, the Arm Mbed team is focused on delivering a high quality implementation of the software components required in the Thread implementation. We have invested in the automated test environment, where we can verify all the change requests as well as the regular releases.
To ensure high quality the Mbed OS Thread stack is tested daily including:
- The non-functional test sets (stability, reliability, performance, stress, recovery).
- The functional test cases using Valgrind memory analysis tool.
- The code coverage measurement using LCov.
- Automated certification test cases to ensure the certification validation all the time.
- The RAM/ROM and performance measurements with trend charts.
To ensure the production ready delivery we also check:
- Security vulnerabilities using Defensics automated testing tool.
- Static code analysis using the Coverity tool.
- Interoperability against other vendors using the official Thread certification harness.
How to commission a Thread device in practice
Commissioning a Thread device requires:
- An Android device to run the commissioning app.
- A working IPv6 backhaul network with a Wi-Fi access point capable of handing out IPv6 addresses over its LAN.
- A border router running the nanostack-border-router application.
- A working IPv6 network with:
- An Android device that can ping the border router.
- A development machine (a PC) that can ping the border router.
- A PC and border router with IPv6 addresses assigned to them from the Wi-Fi access point.
- A Thread-capable end device.
A model network setup could look like this: Sample network setup
Building the end node application
By default, the Mbed Thread applications/examples use the static network link configuration defined in the mesh-api configuration file. If you want to use the Thread commissioning, add the following lines to your
.json file. You can use the mesh minimal application as an example.
"macros": ["MBEDTLS_USER_CONFIG_FILE=\"mbedtls_config.h\""]in to the same level as
false prevents the usage of the predefined link configuration values and allows the device to start network scanning.
Now build the application for your chosen target from Mbed CLI with:
mbed compile -t <toolchain> -m <target> -c
Once the binary is generated, flash the binary to the end device, and run the application. Do not power on the end device until the border router has obtained an IPv6 address from the Wi-Fi access point.
QR code generation
You can use a free online tool to generate a QR code.
In the online tool, fill in the URL field. The following is an example:
v=1&eui=000b57fffe07a8be&cc=ABCDEFGH. Fill in the correct values for your device, and ensure
v=1 is always present. The other required parameters are:
ccis the PSKd, which is configured in the
.jsonfile (see the mesh-api configuration). PSKd must be uppercase characters (0-9, A-Y excluding I,O,Q and Z)
euiis equal to the EUI64 address.
You can get the EUI64 address for your end device by using the
device_eui64_get method in your application. Please see the mesh minimal example for details.
There are four additional (optional) query parameters you can put into this field:
vsProduct/Vendor serial number.
Once you have completed the details, proceed to generate the QR code for your end device.
Using the Thread commissioning application
You can use the Thread Android application for commissioning. Download and install this on your Android device, turn on Wi-Fi and start the app. Then follow these steps after ensuring all the requirements listed above are satisfied:
- Set up a connection to the Wi-Fi access point to which the Thread border router is connected. When connected, the application lists your Thread border router(s).
- Select a border router from the list.
- Enter the passphrase requested by the application. It is
Thread Network(when using the default Mesh API Thread configuration). After successful connection to the border router, the application is ready to scan the QR code. NOTE: You may need to grant Android permissions in the app.
- Power on your Thread device if it is not already on.
- Scan the QR code. The Thread device joins the network. If you are using the mesh-minimal application, the IP address prints on the serial console:
connected. IP = ....
Thread mesh questions and answers
How are devices joined to the networks and what are the options for commissioning modes?
There are no different commissioning modes for devices joining to the network, there are only different kinds of commissioners (on-mesh, native, external). Thread devices either have the configuration or not. If they don’t have the configuration, they try to find a Thread network that accepts them. Then they do the commissioning using DTLS to authenticate themselves and if successful, they will receive the network credentials and become a part of the network.
Where are the default configurations of the Nanostack set?
- Thread devices do not have a default configuration. They should always be commissioned to the network and receive the configuration on site. A commissioner can modify the configurations to the entire network and all Thread devices in the network will automatically pick the new configuration and save it to NVM.
- The border router may have a default configuration set, that provides a starting point for setting up the network.
Are the Thread configurations easily exposed to the application and are they runtime configurable?
- The Thread management API can be used to read/store/delete the Thread link configuration and to define the device configuration (
- The Thread commissioner can change the network configuration of the entire Thread network. By using the
thread_management_if.h, you can build an on-mesh or native commissioner that can update the network configuration.
- For example, the border router can be set up with the default configuration. The commissioner can then update the whole Thread network configuration (including border router).
Who selects the channel and PAN ID? Will different manufacturers pick different channels and PAN IDs?
Channel and PAN ID are part of the Thread configuration that is received when a device is commissioned to the Thread network. The commissioner can modify the configuration at any time. The manufacturer does not decide the Thread link configuration.
How can ad-hoc mesh networks be easily formed with different manufacturers?
Ad-hoc networks with devices from different manufacturers can be easily created by commissioning.
Does the border router listen on all channels or just one?
- The border router is a Thread router device and uses the same configuration as other devices in the Thread network. So it uses a single channel.
- Devices that have not yet joined the Thread network scan all channels and PAN IDs to find a Thread network that they want to be part of.
How to commission with a mobile device? Is there an example app?
An example application is downloadable from the Android store.
Are there any application examples?
How to debug and visualize the network?
- You can download a Wireshark version that supports the Thread protocol from the Wireshark web page.
- A commissioner can do network diagnostics and topology images using Thread-specific diagnostics commands. Our software supports this but there is no C/C++ API support.
How to check for errors or check the link quality?
Link quality and errors are easiest to debug using Wireshark.
How to send/receive with UDP and TCP sockets. How to use multicast groups?
The mesh minimal uses socket communication and multicasting. See more details in the mesh minimal example.
What if my ISP does not provide IPv6 service? Why do I need IPv6 internet service? Can I use a tunneling service?
Thread is based on the IPv6 protocol. If the communication must go over IPV4 network, there are two solutions available:
- IPv6 tunneling.
What happens if a packet cannot reach its destination (for example, no internet connection to border router)? What is the response back to the device?
There are no special Thread codes available, you will have the normal internet error codes. An application must handle the temporary network connection problems with proper retry logic.
How are network errors sent back to the device? Is there a description of what went wrong or simply no response?
There are no special error codes in Thread. The application can receive ICMPv6 error codes.
How to message all nodes in the mesh? Can I use a multicast address?
IPv6 multicast messages are supported. link-local and realm-local (mesh-local) multicast scopes work within the Thread network, as well the site-local multicast messages.
How can I use link-local addresses versus global addresses?
- Usually, global addresses are used to communicate with the remote services. When a device has the destination address, the network stack selects the proper source address and route to that destination.
- An application developer may implement a protocol (using multicast) for querying the link-local or mesh-local addresses from other devices in the Thread network. Link-local addresses work only over one radio hop. Mesh-local addresses work over multiple hops in the Thread network.
- The Mbed OS mesh API provides functions to query the device's own addresses (link-local or global).
What are the configurable parameters in the Thread devices? What do they mean and where are they documented?
- The Thread configurable parameters are the Active Operational Dataset parameters. The parameter explanations can be found in the Mbed Mesh API. More information can be found in the Thread specification.
- The Thread device configuration includes PSKd and EUI64 (usually the MAC address of the radio chip), that are used to commission the device.
What are PSKc and PSKd? Where can find these?
- PSKc is the authentication key for the native or external commissioner. This value is generated from the passphrase of the network combined with the network name and XPANID that are received when scanning the networks. The commissioner application asks for this passphrase after scanning and selecting an available Thread network, exactly the same way as in Wi-Fi.
- PSKd is the authentication key used to authenticate a device to the Thread network in combination with EUI64.
- These values are printed to a sticker on the device or the device packaging in the form of a QR code that is then scanned by the commissioner application. This allows the device to be commissioned to the Thread network. After the authentication, the Thread configuration is given to the new device.