Silicon Labs UG116 User guide

Brand: Silicon Labs

Model: UG116

Type: User guide

UG116: Developing Custom Border Router

Applications

A Thread border router is a device in a Thread network that pro-

vides connectivity to adjacent networks on other physical layers.

The border router provides services for devices within the Thread

network, including routing services for off-network operations. Sil-

icon Labs provides a Border Router Add-On Kit containing a

Raspberry Pi device, example applications, and the underlying

APIs required to build border router software. This user guide

provides information for developing custom border router applica-

tions.

KEY POINTS

• Architecture

• Operation

• Build and installation instructions

• Border Router configuration

• Test router configuration

• Utilities, files and services

• Resources

silabs.com | Building a more connected world. Rev. 0.3

1. Introduction

This user guide is intended for software engineers who wish to develop a Thread Border Router System, and who are familiar with the

Thread specification, Silicon Labs Thread stack and Silicon Labs development kits. The hardware referenced in this document is availa-

ble with the Thread Border Router Add-On Kit, part number RD-0004-0201.

This user guide assumes familiarity with these documents:

• QSG102: Thread Border Router Add-On Kit Quick Start Guide

• QSG113: Getting Started with Silicon Labs Thread

• UG103.11: Application Development Fundamentals: Thread

• AN1010: Building a Customized NCP Application

This user guide addresses the following topics:

• Architecture: Shows the components, data paths, and management paths between the Thread commissioner, Thread Border Rout-

er host and NCP, and Thread end nodes.

• Operation: Describes the operation of the Thread Border Router System, including commissioning, discovery and end-to-end IPv6

communication.

• Build and Installation Instructions: Describes the build and installation procedure for the IP modem, IP driver, commissioning,

border router and web server applications.

• Border Router configuration: Provides a reference to explain the modifications the silabs-border-router package installation makes

to the Raspbian Jessie Lite operating system installation.

• Test router configuration: Provides a procedure to install the silabs-test-router package on the Border Router.

• Utilities, Files and Services: Contains a listing that may be useful for Border Router configuration and development.

• Resources: Includes additional information available for software engineers.

UG116: Developing Custom Border Router Applications

Introduction

silabs.com | Building a more connected world. Rev. 0.3 | 2

2. Architecture

This section describes the components and features of the Thread Border Router System, including the Thread commissioner, Thread

Border Router host and NCP, and Thread end nodes.

Figure 2.1. Border Router System Architecture

2.1 Thread Commissioning App for iOS/Android

The Thread commissioning app for iOS/Android is a utility and reference design for commissioning Thread devices. It exchanges com-

missioner data via Wi-Fi with the commission-proxy-app on the Thread Border Router host and features a tool to securely commis-

sion Thread end nodes on the 802.15.4 Thread network. More information about commissioning can be found in the Thread Commis-

sioning white paper, which is publically available from the Thread Group.

The external Thread commissioner app and source for iOS/Android is provided by the Thread Group and can be acquired as described

in QSG102: Thread Border Router Add-On Kit Quick Start Guide. The steps for building the application are outside the scope of this

document.

2.2 Border Router Commissioning Proxy (commission-proxy-app)

The Border Router commissioner proxy (commission-proxy-app) on the Border Router host manages the communication between the

Thread stack and the external commissioner. Its features include:

• Initiating mDNS advertisement with the Avahi service to the external Thread commissioning app for iOS/Android.

• Running the DTLS/JPAKE handshake required to create a secure connection between the Thread network and an external commis-

sioner.

2.3 Border Router IP driver Application (ip-driver-app)

The IP driver application (ip-driver-app) on the Border Router acts as the main dispatch for the IP modem. Its features include the

ability to act as an intermediary, similar to a multiplexer / de-multiplexer, that can read from and write to different streams over a single

serial connection between the host and NCP.

2.4 Border Router IP Modem Application (ncp-uart)

The IP modem application (ncp-uart) on the Border Router runs the Thread stack software. Its features include a serial host interface

that can run on Silicon Labs devices such as EM35x or EFR32MG. In the case of the Thread Border Router Add-On kit, the default

NCP is the CEL EM3588 USB Thread Adapter, but can be an EFR32 Mighty Gecko 2.4 GHz Mesh Networking Starter Kit (WSTK)

paired with an EFR32MG1 or EFR32MG12 radio board.

UG116: Developing Custom Border Router Applications

Architecture

silabs.com | Building a more connected world. Rev. 0.3 | 3

2.5 Thread End Node Sensor/Actuator Application (sensor-actuator-node)

The sensor/actuator application (sensor-actuator-node) on the Thread end nodes provides I/O for sensors, buttons and indicators. It

exchanges data and management packets via the Thread network with the ncp-uart application on the Border Router NCP. Its fea-

tures include:

• Secure commissioning by the Thread commissioning app for iOS/Android.

• LED actuator control.

• Push button and temperature telemetry reporting.

2.6 Border Router Management Application (border-router-mgmt-app)

The Border Router management application (border-router-mgmt-app) is a system management application that manages the state

of the border router during network bring-up and configuration, and tracks the state during normal operation. It features include:

• Thread network configuration.

• Device discovery.

• Reacting to changes in network state.

• Removal of Thread end nodes from the Thread network.

• Removal of the Thread Border Router from the Thread network.

2.7 Web Server

The web server application on the Border Router host serves a user interface for the border-router application and is included to help

with demonstration and diagnostics. It is similar in concept to a router administration server. Its features include:

• Exposing border-router application features.

• Controlling and monitoring Thread end nodes.

• Removing devices from view.

• Displaying system IP addresses.

• Acting as the Node.js back-end server.

• Providing React UI front-end implementation for rendering on computer or mobile device.

2.8 Web Browser

The web browser renders the web server user interface. Demonstration with the web browser is described in QSG102: Thread Border

Router Add-On Kit Quick Start Guide.

2.9 Application

The application refers to an iOS/Android mobile device app, web browser plug-in such as Copper for the Mozilla browser, or any other

application capable of communicating with the ip-driver-app via CoAP. Demonstration with Copper plugin is described in QSG102:

Thread Border Router Add-On Kit Quick Start Guide.

UG116: Developing Custom Border Router Applications

Architecture

silabs.com | Building a more connected world. Rev. 0.3 | 4

3. Operation

This section describes the operation of the Thread Border Router System, including commissioning, discovery and end-to-end IPv6

communication.

3.1 Understanding the Border Router Management Application

The Thread Border Router Management Application (border-router-mgmt-app) orchestrates much of what happens during network

formation and in setting the parameters for use in a new Thread network. The state machine for the management application is shown

in the following figure.

UG116: Developing Custom Border Router Applications

Operation

silabs.com | Building a more connected world. Rev. 0.3 | 5

The left half of the state machine drawing corresponds to the status of the network layer. The Silicon Labs Thread Stack drives this

state machine, and the border-router management application has no direct control over it. Instead, the border router application can

indirectly influence the network state by calling various stack functions. These stack functions that influence the network state are

shown above the arrows drawn from the border-router state machine to the network state diagram.

Note that the network state diagram is incomplete and only shows states of interest to the border-router application.

The right half of the figure describes the state of the border-router management application. Each state is briefly described here:

RESET_NETWORK_STATE: Calls stack function emberResetNetworkState. This clears network information from the NCP and im-

mediately drops the border router from whatever network it was previously attached to.

User CLI command network-management reset is a method provided to users to achieve the same effect as going to the RE-

SET_NETWORK_STATE. It is essentially equivalent to calling stack function emberResetNetworkState.

RESUME_NETWORK: The border router always transitions to this state if the stack transitions to the EMBER_SAVED_NETWORK

state. It calls the stack function emberResumeNetworkState, which causes the stack to attempt to re-join a previously-known network.

This is usually what will happen if the border-router is rebooted during the UP_STATE.

FORM_NETWORK: The border router always transitions to this state if the stack transitions to the EMBER_NO_NETWORK state. De-

pending on the value of AUTO_FORM_NETWORK, the border router either attempts to form a network using default settings or to form

a network using manual settings. AUTO_FORM_NETWORK may be set in two ways:

1. In the /etc/siliconlabs/border-router.conf file.

2. Via the CLI commands set-auto-form-off and set-auto-form-on.

If AUTO_FORM_NETWORK = 1, then default settings are used. emberFormNetwork is called, which generates a random Network

Master Key

If AUTO_FORM_NETWORK = 0, then manual settings are used. The border-router will wait in the FORM_NETWORK state until

the user provides the network settings on the CLI by using the network-management commission command.

JOIN_NETWORK_COMPLETION: This state only applies to manual network formation. It is reached once the user enters appropriate

data using the network-management commission command, and tells the stack to use that data to join the network.

GET_COMMISSIONER: This state is always reached when the stack transitions to EMBER_JOINED_NETWORK_ATTACHED. The

transition to that network state means that the border router can communicate as a member of a Thread network, but has not yet con-

figured other settings appropriate for a border router. This state sets the commissioner pre-shared key.

CONFIGURE_BORDER_ROUTER: This state is reached upon successful completion of emberGetCommissioner. It informs the stack

of some of the services available, such as routing, DNS (domain name system) and SLAAC (stateless autoconfiguration) using a call to

emberConfigureGateway.

INITIALIZE_BORDER_ROTUER: Reached upon a successful call to emberConfigureGateway. It does some final configuration and

sets up DNS.

UP_STATE: The border-router should remain in this state as long as it is on a stable network and the user takes no action otherwise. A

heartbeat is issued periodically as long as we remain in this state.

3.2 Network Formation

To form a new network means to erase the network settings, such as the Network Master Key and Extended PAN ID, and generate

new ones. A border router will no longer be able to communicate with its old network after it forms a new one. The Silicon Labs Border

Router Add-On Kit provides two methods for network formation: Network formation with default settings, and network formation with

manual settings. Using default settings is the most secure because a random Network Master Key will be generated. Once generated,

the Silicon Labs Thread Stack does not provide any mechanism for retrieving the key. Even when new devices join, the Network Master

Key is shared with them over a secure DTLS connection and cannot be intercepted by a third party.

The state of AUTO_FORM_NETWORK determines whether default or manual settings are used to derive a new network:

set-auto-form-on means to use default network settings, including a randomly-generated Network Master Key

set-auto-form-off means to use manual network settings, including a manually-entered Network Master Key

The sections below describe how to set this variable from the CLI.

UG116: Developing Custom Border Router Applications

Operation

silabs.com | Building a more connected world. Rev. 0.3 | 6

3.2.1 Network Formation with Default Settings

In order to form a new network, issue a network-management reset command. There are two methods for doing this: One is to use

the CLI (described below) and the other is to issue the reset using the webserver GUI (as described in QSG102: Thread Border Router

Add-On Kit Quick Start Guide). The GUI method is not recommended because no mechanism exists for ensuring the state of AU-

TO_FORM_NETWORK.

In order to obtain CLI access to the border router, the user must kill the border-router-mgmt-app process and restart it in the fore-

ground. The first step is to get the process ID of the application.

> ps aux | grep border-router-mgmt-app

To kill the application, type:

> sudo kill <PID>

Where <PID> is replaced with the actual PID number found above. Next restart the application in the foreground:

> sudo /opt/siliconlabs/threadborderrouter/bin/border-router-mgmt-app –m 4901

An example of the output of this command may be something like:

pi@br-0093:~ $ sudo /opt/siliconlabs/threadborderrouter/bin/border-router-mgmt-app -m 4901

Reset info: 0x0B (SOFTWARE)

Removing any IPv6 addresses configured on the host...

Unbound from fe80::ba27:ebff:fe63:4ac4

Unbound from 2001:db8:8569:b2b1::1

Unbound from fe80::76da:38ff:fe66:135b

Bound to fd09:3a1f:d733:0:e524:c328:9cd5:5848

Listening for CoAP on fd09:3a1f:d733:0:e524:c328:9cd5:5848

Bound to fe80::a6a2:4804:5e6d:a097

Listening for CoAP on fe80::a6a2:4804:5e6d:a097

Rejoined network "br-0093"

Bound to fd09:3a1f:d733:0:e524:c328:9cd5:5848

Listening for CoAP on fd09:3a1f:d733:0:e524:c328:9cd5:5848

Bound to fe80::a6a2:4804:5e6d:a097

Listening for CoAP on fe80::a6a2:4804:5e6d:a097

Init: 0x00

Host: Thread 2.3.0.0 GA build 0 management 3584 (May 30 2017 11:06:43)

NCP: Thread 2.3.0.0 GA build 0 management 3584 (May 30 2017 11:04:23)

Stack initialized

OTA Bootload Server Policy: GetImageNotifyInfo a=400:0:ec65:8b7e:74c3:400:f465:8b7e m=0x364C t=0x0005 v=0x00000

000

Setting fixed commissioner key: "COMMPW1234"

Configuring default gateway for: 2001:db8:385:9318::/64

Initializing border router

Making 'all thread nodes' address: ff33:40:fd09:3a1f:d733::1

Listening on all mesh nodes multicast

Listening for CoAP on ff03::1

Listening on all mesh routers multicast

Listening for CoAP on ff03::2

Listening on all thread nodes multicast

Listening for CoAP on ff33:40:fd09:3a1f:d733::1

Configured DNS64

Border router is up

At this point, we make sure that AUTO_FORM_NETWORK is turned on and issue the net reset:

border-router-mgmt-app> set-auto-form-on

border-router-mgmt-app> net reset

Removing any IPv6 addresses configured on the host...

Unbound from fe80::ba27:ebff:fe63:4ac4

Unbound from 2001:db8:8569:b2b1::1

Unbound from fe80::76da:38ff:fe66:135b

border-router-mgmt-app> Forming network "br-0093"

Reset network state complete

Bound to fdce:ecee:d514:0:6472:3b8e:ea39:a3a5

Listening for CoAP on fdce:ecee:d514:0:6472:3b8e:ea39:a3a5

UG116: Developing Custom Border Router Applications

Operation

silabs.com | Building a more connected world. Rev. 0.3 | 7

Bound to fe80::24bf:7bfe:2e72:4e86

Listening for CoAP on fe80::24bf:7bfe:2e72:4e86

Formed network "br-0093"

OTA Bootload Server Policy: GetImageNotifyInfo a=400:0:ec65:8b7e:74c3:400:f465:8b7e m=0x364C t=0x0005 v=0x00000

000

Setting fixed commissioner key: "COMMPW1234"

Bound to 2001:db8:385:9318:1b76:cb45:b2ab:3063

Listening for CoAP on 2001:db8:385:9318:1b76:cb45:b2ab:3063

Configuring default gateway for: 2001:db8:385:9318::/64

Initializing border router

Making 'all thread nodes' address: ff33:40:fdce:ecee:d514::1

Listening on all mesh nodes multicast

Listening for CoAP on ff03::1

Listening on all mesh routers multicast

Listening for CoAP on ff03::2

Listening on all thread nodes multicast

Listening for CoAP on ff33:40:fdce:ecee:d514::1

Configured DNS64

Border router is up

The states traversed by the border router during this process are highlighted in the following figure.

In order to commission a device onto this network, proceed to section 3.3 Commissioning Using the External Commissioning Applica-

tion.

UG116: Developing Custom Border Router Applications

Operation

silabs.com | Building a more connected world. Rev. 0.3 | 8

UG116: Developing Custom Border Router Applications

Operation

silabs.com | Building a more connected world. Rev. 0.3 | 9

3.2.2 Network Formation with Manual Settings

Using manual settings is less secure because it lets the Network Master Key escape the Thread network in plain text. It is still possible

for a customer to contain this breach within their system, but there is some risk in doing so.

The advantage of using manual settings is that knowing the Network Master Key allows for some specific use cases:

1. Debugging of the Thread network using packet capture: Packet capture tools, such as the Silicon Labs Network Analyzer, can-

not decrypt network traffic unless the Network Master Key is known. However, by design, it is impossible to read the key from the

stack. Manually creating your own master key allows you to keep track of it and use it for debugging decryption.

2. Out-of-band commissioning of devices: A known master key can be preshared with devices so that they can join a Thread net-

work without going through the in-band commissioning process.

As described above in section 3.2.1 Network Formation with Default Settings, the user must first to obtain CLI access to the border

router by killing the border-router-mgmt-app process and restarting it in the foreground. The first step is to get the process ID of the

application:

> ps aux | grep border-router-mgmt-app

To kill the application, type:

> sudo kill <PID>

where <PID> is replaced with the actual PID number found above.

Restart the application in the foreground:

> sudo /opt/siliconlabs/threadborderrouter/bin/border-router-mgmt-app –m 4901

Turn AUTO_FORM_NETWORK off:

border-router-mgmt-app> set-auto-form-off

This time, when net reset is issued, the border router waits for user input in order to proceed out of the FORM_NETWORK state:

border-router-mgmt-app> net reset

Removing any IPv6 addresses configured on the host...

Unbound from fe80::ba27:ebff:fe63:4ac4

Unbound from 2001:db8:8569:b2b1::1

Unbound from fe80::76da:38ff:fe66:135b

border-router-mgmt-app> Border Router is waiting on `network-management commission ...` command to form and joi

n network

Reset network state complete

As seen in the net reset response, the Border Router is waiting on a network-management commission command. The syntax for this

command is as follows:

network-management commission <preferred channel:1> <fallback channel mask:4> <network id:0--16> <ula prefix> <

extended pan id:8> <key:16> [<pan id:2> [<key sequence:4>]]

For more information on these parameters, search for the emberJoinNetwork function in the Silicon Labs Thread API Reference Guide.

The emberJoinNetwork function is the underlying API call for the network-management commission CLI command.

Here is an example of how to use this command as well as the border-router-mgmt-app output response:

border-router-mgmt-app> network-management commission 13 0 "example-id" "fd01::/64" {0102030405060708} {656D626

57220454D3235302063686970} 1234 0

border-router-mgmt-app> Pre-Commission stack call successful.

Completing precommisioned join

emberJoinNetworkReturn pre-commissioned success.

Bound to fd01::f815:7da5:a0e4:2c49

Listening for CoAP on fd01::f815:7da5:a0e4:2c49

Bound to fe80::1837:4661:128b:b86e

Listening for CoAP on fe80::1837:4661:128b:b86e

Rejoined network "example-id"

OTA Bootload Server Policy: GetImageNotifyInfo a=400:0:ec65:8b7e:74c3:400:f465:8b7e m=0x364C t=0x0005 v=0x00000

000

Setting fixed commissioner key: "COMMPW1234"

UG116: Developing Custom Border Router Applications

Operation

silabs.com | Building a more connected world. Rev. 0.3 | 10

Bound to 2001:db8:385:9318:5075:ebe1:7d18:db74

Listening for CoAP on 2001:db8:385:9318:5075:ebe1:7d18:db74

Configuring default gateway for: 2001:db8:385:9318::/64

Initializing border router

Making 'all thread nodes' address: ff33:40:fd01::1

Listening on all mesh nodes multicast

Listening for CoAP on ff03::1

Listening on all mesh routers multicast

Listening for CoAP on ff03::2

Listening on all thread nodes multicast

Listening for CoAP on ff33:40:fd01::1

Configured DNS64

Border router is up

UG116: Developing Custom Border Router Applications

Operation

silabs.com | Building a more connected world. Rev. 0.3 | 11

The state diagram for this operation is shown in the following figure.

In order to commission a device onto this network, either of two different methods can be used:

1. To use an external commisioner, go to section 3.3 Commissioning Using the External Commissioning Application. Note that even

though the network parameters are specified manually, the origin of the parameters is unknown both to the Thread network and to

the external commissioner. Therefore, they behave the same in either case.

2. To provide network parameters to a Joiner device using the device CLI, go to section 3.4 Commissioning Using Out-of-Band Injec-

tion of Network Data. This method can only be used if the Network Master Key is known.

UG116: Developing Custom Border Router Applications

Operation

silabs.com | Building a more connected world. Rev. 0.3 | 12

3.3 Commissioning Using the External Commissioning Application

Commissioning via an external commissioner is the standard way of adding a device to a Thread network. The steps a user should

follow are outlined in QSG102: Thread Border Router Add-On Kit Quick Start Guide. Here we provide more detail about how the vari-

ous Border Router applications participate in the process.

1. The border-router-mgmt-app forms a Thread network and establishes the commissioner key as described in section 3.1 Under-

standing the Border Router Management Application.

2. The external commissioner uses the pre-shared commissioner key to perform a DTLS/JPAKE handshake with the commission-pr

oxy-app and establish a secure connection to the Thread network.

3. The external commissioner uses a second pre-shared join key to perform a DTLS/JPAKE handshake with the Joiner and establish

a secure connection to the Joiner via the Thread Network. If the commissioner is satisfied with the credentials of the Joiner, it al-

lows the Network Master Key to be shared with the Joiner in a secure fashion from the Thread Network. The Network Master Key

is never known by the commissioner.

Figure 3.1. Commissioning

3.4 Commissioning Using Out-of-Band Injection of Network Data

If a network was formed using manual settings, then those settings can be injected into another device to allow it onto the Thread net-

work directly without having to go through the in-band commissioning process. This section specifically refers to the sensor-actuator-

node device that comes as part of the Border Router Add-On Kit.

This can be done by going to the CLI of the device in Simplicity Studio and running the following commands:

sensor-actuator-node> network-management reset

sensor-actuator-node> network-management commission 13 0 "example-id" "fd01::/64"

{0102030405060708} {656D62657220454D3235302063686970} 1234 0

Note that the parameters must be identical to the parameters of the commission command used in the border-router-mgmt-app CLI

in order to put the border-router and the sensor-actuator on the same network.

UG116: Developing Custom Border Router Applications

Operation

silabs.com | Building a more connected world. Rev. 0.3 | 13

3.5 Discovery

1. An application sends a discovery request via CoAP to the border-router-mgmt-app.

2. The border-router-mgmt-app sends a discovery multicast request to the ncp-uart application.

3. Each Thread end node responds to the multicast with its global IPv6 address and device type.

Figure 3.2. Discovery

3.6 End-to-End IPv6 Communication

1. The web server, or an application such as the Copper plugin for Mozilla, sends and receives messages via CoAP to and from the

IPv6 address of the desired Thread end node. This assumes commissioning and discovery have completed.

Figure 3.3. End-to-End IPv6 Communication

UG116: Developing Custom Border Router Applications

Operation

silabs.com | Building a more connected world. Rev. 0.3 | 14

4. Build and Installation Instructions

This section describes the build and installation procedure for the IP modem, IP driver, commissioning, border router, and web server

applications. The following steps assume that you have installed Simplicity Studio, the Silicon Labs Thread stack, and the IAR-EWARM

compiler. Refer to QSG113: Getting Started with Silicon Labs Thread, for a detailed tutorial.

4.1 Build the Border Router IP Modem Application

The Silicon Labs Thread stack supports building NCP applications in Simplicity Studio AppBuilder, with customizations for target hard-

ware, initialization, main loop processing, event definition and handling, and host/NCP command extensions. Refer to AN1010: Building

a Customized NCP, for a detailed set of build instructions. Refer to CEL 0011-09-07-00-000 (Issue G) for a detailed set of programming

instructions for using an ISA3 debug adapter to install the application and bootloader. The bootloader for the CEL EM3588 USB Thread

Adapter is located at tool/bootloader-em3588/serial-uart-bootloader, relative to root of the Silicon Labs Thread stack installation.

4.2 Build the Border Router IP Driver Application

1. Copy the Thread stack (C:/SiliconLabs/SimplicityStudio/v4/developer/sdks/gecko_sdk_suite) to the Border Router (/home/pi), using

winscp as described in section 8.5 Transfer Files To and From the Border Router.

2. It is not necessary to generate a project with AppBuilder because no configuration options are required.

3. Change to the Thread directory:

$ cd /home/pi/gecko_sdk_suite/v1.0/protocol/thread_x.x/

4. Make the application from the root of the Thread stack directory:

$ make -f app/ip-ncp/ip-driver-app.mak

5. Copy the application to the executable directory from the root of the Thread stack directory:

$ sudo service border-router-apps stop

$ sudo cp /home/pi/gecko_sdk_suite/v1.0/protocol/thread_2.2/build/ip-driver-app/ip-driver-app

/opt/siliconlabs/threadborderrouter/bin

UG116: Developing Custom Border Router Applications

Build and Installation Instructions

silabs.com | Building a more connected world. Rev. 0.3 | 15

4.3 Build the Border Router Commissioner Proxy

1. Obtain the source code for the Rijndael cipher.

2. The commission-proxy-app requires the AES-128 cipher. Silicon Labs cannot provide this software implementation of AES-128

because it is classified as strong cryptography and subject to export restrictions. An implementation of Rijndael known to be com-

patible with the Thread commissioning application is:

• http://www.efgh.com/software/rijndael.zip (md5: cd49617fa6593d2ab67a68f64ede2d78)

3. The cipher consists of the following files:

• rijndael-alg-fst.c

• rijndael-alg-fst.h

• rijndael-api-fst.c

• rijndael-api-fst.h

4. The header files are included in the Silicon Labs Thread installation to assist you in locating the corresponding source files. Once

Rijndael has been acquired, copy the source files to the following locations relative to the root of the Thread stack installation to

complete the configuration:

• hal/micro/generic/aes/rijndael-alg-fst.c

• hal/micro/generic/aes/rijndael-api-fst.c

5. Copy the Thread stack to the Border Router.

6. It is not necessary to generate a project with AppBuilder because no configuration options are required.

7. Make the application from the root of the Thread stack directory:

$ make -f app/thread-commissioning/commission-proxy-app.mak

8. Copy the application to the executable directory from the root of the Thread stack directory:

$ cp app/thread-commissioning/commission-proxy-app /opt/siliconlabs/threadborderrouter/bin

4.4 Build the Border Router Application

1. Create and generate the border-router example.

2. Select generation directory “app/thread/sample-app/border-router/border-router” relative to the stack and select “Unix host” as the

target architecture. This generates the project in place within the Thread stack.

3. Copy the Thread stack to the Border Router.

4. Make the application from the root of the Thread stack: directory:

$ make -C app/thread/sample-app/border-router/border-router

5. Copy the application to the executable directory from the root of the Thread stack directory: :

$ cp app/thread/sample-app/border-router/border-router/build/exe/border-router

/opt/siliconlabs/threadborderrouter/bin

UG116: Developing Custom Border Router Applications

Build and Installation Instructions

silabs.com | Building a more connected world. Rev. 0.3 | 16

4.5 Build the Web Server Application

The website React user interface source code is located at /opt/siliconlabs/threadborderrouter/src/reactui and the node.js server source

is located at /opt/siliconlabs/threadborderrouter/webserver. Follow the instruction below to build these components.

1. Install dependencies:

$ cd /opt/siliconlabs/threadborderrouter/src/reactui

$ sudo npm install -g gulp

$ sudo npm install

2. Generate the React user interface, copy to the server directory, and restart the Apache server:

$ sudo gulp build-dev

$ sudo service apache2 stop

$ sudo rm –r /var/www/html/*

$ sudo cp -r /opt/siliconlabs/threadborderrouter/src/reactui/dist/* /var/www/html

$ sudo service apache2 start

3. Restart the node.js server:

$ sudo service border-router-apps {start | stop | restart}

UG116: Developing Custom Border Router Applications

Build and Installation Instructions

silabs.com | Building a more connected world. Rev. 0.3 | 17

5. Using the EFR32 Mighty Gecko Wireless Starter Kit as the NCP

Although the Border Router Add-On Kit ships with a CEL USB dongle intended to run the NCP application, it is possible to use a WSTK

for this purpose, by following three steps: flashing the NCP firmware, setting up the hardware, and modifying the border router.

5.1 Flashing the NCP Firmware

The NCP firmware can be flashed onto an EFR32MG12 device using the same steps as flashing the sensor actuator node firmware.

The binaries are located in the following location of the border router file system.

Device Programming File

EFR32MG12 /opt/siliconlabs/threadborderrouter/firmware/ncp-uart/efr32mg12p432f1024gl125/ncp-uart-

efr32mg12p432f1024gl125.s37

A bootloader is required, and is also available in the border router file system.

Device Bootloader

EFR32MG12 /opt/siliconlabs/threadborderrouter/firmware/sensor-actuator-node/efr32mg12p432f1024gl125/serial-uart-boot-

loader.s37

IMPORTANT: Erase the device before programming.

5.2 Setting up the Hardware

To set up the hardware, connect a USB cable between the border router host Raspberry Pi and the WSTK. The WSTK provides the

UART-to-USB translation between the EFR32MG12 radio chip and the host. The WSTK requires that the EFR32MG12 chip be config-

ured for hardware flow control, which is already the case for the precompiled binaries available above. This hardware setup disables

debugging capabilities of the WSTK over USB, since that would require connecting to a development computer running Simplicity Stu-

dio rather than to the border-router host. However, full debugging capabilities are still available through the Ethernet port.

5.3 Modifying the border-router

Using a text editor, open the following file: /opt/siliconlabs/threadborderrouter/bin/silabsenv

Locate the NCP_DEVICE flag. Comment it out and make a new line that says NCP_DEVICE="/dev/ttyACM0"

You should end with the following lines in the silabs-scripts file:

#the ncp device is the /dev endpoint of the ncp

#NCP_DEVICE="/dev/ttyUSB0"

NCP_DEVICE="/dev/ttyACM0"

Reboot the border-router.

UG116: Developing Custom Border Router Applications

Using the EFR32 Mighty Gecko Wireless Starter Kit as the NCP

silabs.com | Building a more connected world. Rev. 0.3 | 18

6. Silicon Labs Thread Border Router Configuration

The silabs-border-router package is a collection of files describing Silicon Labs host application binaries, support scripts that enable

host applications and Linux utilities to interact, and modifications to common Linux utilities. Its installation configures the Raspbian Jes-

sie Lite operating system to behave as a Border Router between the Thread mesh and IPv6 networks. This section provides a refer-

ence to the modifications the silabs-border-router package makes to the Raspbian Jessie Lite operating system. The steps for installing

the silabs-border-router package are described in QSG102, Thread Border Router Add-On Kit Quick Start Guide.

6.1 The Border Router Configuration File

System variables that either modify multiple daemons on the Border Router or apply directly to configuration of the Silabs Host Applica-

tions are installed into the Border Router Configuration file (/etc/siliconlabs/border-router.conf). This file includes network settings, host

application settings, and the ability to enable and disable advanced router features such as DNS64 or NAT64. The file is formatted as a

list of key-value pairs and includes comments detailing the behavior of each key-value pair. The following table describes the default

key-value pairs that the border-router.conf file provides.

Table 6.1. Default Border Router Configuration Settings

Key Value Description

FILE_VERSION 1 The current version of the Border Router Configuration File.

AUTO_FORM_NETWORK 1 A Boolean describing if the Border Router should automatically form a

Thread network on startup using default settings, or if it should wait for the

user to enter manual settings.

NETWORK_ID br-XXXX A string providing a pseudorandom Thread network ID.

MESH_SUBNET 2001:db8:385:9318::/64 An IPv6 prefix and subnet width assigned to the Thread network (tun0).

HOST_SUBNET 2001:db8:8569:b2b1::/64 An IPv6 prefix and subnet width assigned to the Wi-Fi network (wlan0).

USE_PREFIX_DELEGATION 0 A Boolean describing if the Border Router should enable IPv6 Prefix Dele-

gation on the Ethernet interface (eth0). Prefix delegation causes the MESH

and HOST obtain dynamic prefixes from any prefix delegation server run-

ning on eth0.

NAT64_PREFIX fc01:6464::/96 An IPv6 prefix whose subnet width must be exactly /96 used by the NAT64

service to map IPv4-only destinations to an IPv6 address.

6.2 Silicon Labs Host Applications

The Silicon Labs Host Applications use the underlying Silicon Labs Thread Stack to form and operate the Thread network. Three host

applications are part of the border-router package: ip-driver-app, commission-proxy-app, and border-router-mgmt-app. The ip-driver-

app configures the 802.15.4 interface (tun0) and performs translation between the external IPv6 and internal 6LoWPAN networks, as

well as providing the host-side of a binary command pipe to the NCP. The commission-proxy-app advertises both the availability of the

Thread Commissioner service via mDNS to external commissioner candidates and also proxies communication between a connected

commissioner and the thread network. The border-router-mgmt-app reads the Linux configuration and uses the Thread stack API to

send commands through the ip-driver-app to form and operate the Thread Network. The Silicon Labs Host Applications are installed in

the ‘bin’ folder within the SILABS_BORDER_ROUTER_ROOT directory: /opt/siliconlabs/threadborderrouter/bin.

6.3 Linux Configuration File Modifications

The silabs-border-router package has dependencies on a number of common Linux utilities. The utilities in the silabs-border-router

package have been adapted to provide the functionality of a standard router through modifications to their configuration files. The si-

labs-border-router package modifies standard Linux configuration in one of four different ways: installation of new configuration files,

automated injection of minor additional code into existing static configuration files, install-time complete replacement of existing static

configuration files, and by using a template to dynamically rewriting existing configurations as the network state changes. In all files

where configuration settings are required by the silabs-border-router package, comment sections between #SILABS_BORDER_ROUTER

markers provide detailed information about each modification’s function and purpose, and provide hints for safely customizing the op-

tion in question.

UG116: Developing Custom Border Router Applications

Silicon Labs Thread Border Router Configuration

silabs.com | Building a more connected world. Rev. 0.3 | 19

6.4 New Configuration Files

In instances where a Linux utility does not provide its own default configuration, the silabs-border-router package installs a new configu-

ration file to the appropriate directory within the Linux file system. All entries in these files should be considered ‘critical’ to the Border

Router Add On Kit’s default functionality, and modifying them may result in the failure of an intended feature or service. The following

table describes the ‘Installed Configuration Files’ silabs-border-router provides.

Table 6.2. New Configuration Files

Path Description

/etc/default/isc-dhcp-server Contains settings used by the initialization script for the DHCP service.

/etc/init.d/border-router-apps The initialization script that daemonizes the Silabs host applications on-startup.

/etc/logrotate.d/siliconlabs Adds the Silicon Labs logfiles to the logrotate daemon’s scheduler.

/etc/modules-load.d/silabs.conf Instructs the Linux Kernel to load drivers required by the Border Router Add On Kit.

/etc/siliconlabs/border-router.conf Defines common variables used to coordinate between the host applications and

operating system.

/etc/sysctl.d/30-silabs.conf System control settings with priority (30) that are executed to enable IP routing.

/etc/udev/rules.d/99-silabs.rules Startup rules at lowest priority (99) for the NCP.

/etc/iptables.ipv4.nat Adds NAT44 rules to enable Ipv4 routing.

/etc/dhcpcd.exit-hook A script run when Prefix Delegation occurs. This script reconfigures tun0 and wlan0

to use a delegated prefix for their subnet.

6.5 Minor Configuration Files

In instances where only minor changes to a configuration file are required in order to enable a feature of the Border Router, the silabs-

border-router package injects additional configuration settings between the text tags #SILABS_AUTOGEN_START and #SILABS_AUTOGEN_

END. These tags denote that text between them is volatile and will be removed or overwritten if the silabs-border-router package is re-

moved or upgraded, and that certain dynamic processes may also overwrite these sections during normal Border Router operation. The

configuration outside of these markers can usually be easily modified without disabling the Border Router’s intended functionality. Addi-

tional configuration settings are recorded in files prepended with the keyword ‘additional’ followed by the filename they modify. For ex-

ample: additional-dhcpd.conf contains additional settings that will be injected into the dhcpd.conf file, between #SILABS_AUTOGEN mark-

ers. These additional configuration settings appear in files installed into the SILABS_BORDER_ROUTER_ROOT directory, which is lo-

cated at /etc/siliconlabs/threadborderrouter. The following table describes the ‘Minor Configuration Files’ to which the silabs-border-rout-

er package adds additional lines

Table 6.3. Minor Configuration Files

Destination File Source file Description

/etc/bash.bashrc additional-bash.bashrc Adds the Silicon Labs binary directory to PATH.

/etc/resolvconf.conf additional-resolvconf.conf Installs the optional DNS and DNS64 services to the host-resolve path.

/etc/dhcpcd.conf additional-dhcpcd.conf Disables the dhcpv4 client on wireless interfaces, enables Prefix Delega-

tion on eth0.

/etc/dhcp/dhcpd.conf additional-dhcpd.conf Configures the DHCP server daemon, which assigns addresses on wlan0.

In instances where most of a configuration file must be modified in order to enable a feature of the Border Router, the silabs-border-

router package backs up and replaces the previously installed configuration file. The silabs-border-router package first appends the ex-

tension ‘.old’ to any existing configuration files to be overwritten. Next, a corresponding file with the extension ‘.new’ is copied from the

SILABS_BORDER_ROUTER_ROOT directory to its destination, with the ‘.new’ extension removed. This behavior is equivalent to the

following commands:

mv /etc/network/interfaces /etc/network/interfaces.old

cp /opt/siliconlabs/threadborderroter/interfaces.new /etc/network/interfaces

UG116: Developing Custom Border Router Applications

Silicon Labs Thread Border Router Configuration

silabs.com | Building a more connected world. Rev. 0.3 | 20

Page is loading ...

Silicon Labs UG116 User guide

Silicon Labs UG116 User guide

Silicon Labs UG116 User guide

Related papers

Other documents