OpenThread Border Router Getting Started Guide
Prerequisites
MMB Enterprise Gateway loaded with OTBR image.
An OpenThread Full Thread Device
For the purpose of this Demo, MMB recommends and assumes the Nordic Semiconductor nRf52840 Dongle loaded with OpenThread FTD CLI firmware as an end device.
Linux operating system (or virtual machine). Ubuntu 18.04 recommended.
LAN Ethernet Access
SSH client
Setting up the Thread Network
Forming a Network
To form a network, you must start by determining the border router’s IP address, this could be done by running an arp-scan command and grepping for MMB’s identifier.
hanin@hanin-pc:~$ sudo arp-scan --localnet -I enp0s25 | grep 24:46
192.168.1.101 00:24:46:00:00:e4 MMB Research Inc.
Direct your browser to that address to access the OpenThread Border Router landing page. Select ‘Form’ on the left side of the page to get to the Form Network menu where you can configure most of the network parameters.
Adjust the parameters to your choosing, set up and make note of your passphrase as this will be your Border Agent passphrase. (Note: 8 digits passphrase preferred)
Click the “FORM” button at the bottom of the window when done configuring your network parameters, you will then be prompted to confirm your choice, an operation success message will pop up upon network formation.
Connecting a Thread End Device to the network
Establish an SSH Connection
To join a new device, in a new terminal ssh into the gateway by running the following command where address is the gateway’s IP address fetched previously (i.e mmb@192.168.1.101)
hanin@hanin-pc:~$ ssh mmb@address
Detailed instructions about establishing a ssh connection with your gateway are provided on our Establishing an SSH connection to the Gateway page.
Start the Commissioner
Once logged in, launch the OTBR command utility by running the following command
[mmb@Tripoli-0000e4:~]$ sudo ot-ctl
>
From here on you can type “help” for a full list of supported commands, you can also verify the value of the parameters previously set in the web GUI such as the network’s name, panID, masterkey and others.
[mmb@Tripoli-0000e4:~]$ sudo ot-ctl
>
> networkname
OpenThreadDemo
Done
> panid
0x1234
Done
Start the commissioner by running ot command commissioner start
, wait a few seconds until an activation message is received
> commissioner start
Commissioner: petitioning
Done
Commissioner: active
Allow devices to join by running ot command commissioner joiner add <EUI64> <passphrase>
, use the “ * “ wildcard to allow any device with the correct passphrase to join, alternatively you can restrict joining to a specific device by providing the desired device’s EUI64 instead.
> commissioner joiner add * J01NME
Done
NOTE: When selecting a joiner password, the password must contain only a combination of uppercase letters and numbers, but may not include the letters “I”, “O”, “Q”, “Z”. The password must be between 6 and 32 characters in length.
Setup and Join an OpenThread CLI Device
Note: This step assumes the user has a device running OpenThread’s Full Thread Device (ftd) CLI with the JOINER compile time flag enabled.
Establish a serial connection with the FTD device by running, in a separate terminal, the following command where XXXX is the port number assigned to the device upon connection (i.e ttyACM0)
hanin@hanin-pc:~$ picocom -b 115200 /dev/ttyXXXX
Run the following commands to make sure all configurations are cleared.
> factoryreset
> reset
> thread stop
Done
> ifconfig down
Done
Bring up up the device by running
> ifconfig up
Done
Enable the joiner role and provide the same passphrase set up in the commissioner
Note: This command has to be run while the commissioner joiner command has not yet expired (you will get a “joiner remove” message on the commissioner side if that was the case).
> joiner start J01NME
Done
The join process can take up to a minute, once done you should expect a message on your gateway (commissioner) to alert you that a new device has joined the network successfully.
> Commissioner: Joiner start af5570f5a1810b7a
Commissioner: Joiner connect af5570f5a1810b7a
Commissioner: Joiner finalize af5570f5a1810b7a
Commissioner: Joiner end af5570f5a1810b7a
Once the commissioner reports a successful device join, on your joiner device start thread by running
> thread start
This process can take a few second, after which you can run “state”, the joiner will then report back its role in the network, the role is assigned to the device by the network based on the current topology and will be either a router or a child
> state
router
Done
You can also fetch the device on your commissioner device by running router table
or child table
to get a list of all current network devices.
Testing Thread Network Connectivity
On-Mesh Pinging
Run the following command on the Enterprise OTBR ssh session to obtain its on-mesh IPV6 address, note that if you are still running in the ot command utility you need to press Ctrl+C to exit that environment first.
[mmb@Tripoli-0000e4:~]$ ifconfig wpan0
we are looking for an inet6 address that starts with the prefix assigned to the commissioner when forming the network, in our case that is fd11:22:
inet6 addr: fd11:22::23ae:dabb:89f2:eef0/64 Scope:Global
From your joiner device, ping the commissioner on that address, the output should return immediately and look as follows
> ping fd11:22::23ae:dabb:89f2:eef0
> 16 bytes from fd11:22:0:0:23ae:dabb:89f2:eef0: icmp_seq=1 hlim=64 time=40ms
Off-Mesh Pinging
Run the following command on the gateway to bring up radvd and allow on-mesh devices to ping off resources (i.e IPv6 LAN resources), this command will start router advertisements as necessary, and add the Off-Mesh Routes to the thread network.
[mmb@Tripoli-0000e4:~]$ sudo ipv6-radvd-dispatcher
If you don’t have LAN IPv6 support, it should output something similar to the following:
Adding route prefix "fd11:2446:a836:9b82::" with len 64, priority "medium", stable:yes, domain-id 0.
Route prefix added.
Adding route prefix "fd11:2446:a285:cdb2::" with len 64, priority "medium", stable:yes, domain-id 0.
Route prefix added.
After this command is run, router advertisements will be broadcast by the Enterprise OTBR, giving your LAN devices IPv6 connectivity.
You can confirm this by checking the IPv6 addresses associated with another device on your LAN, running an ifconfig
command on your developer machine, provided that the machine is on the same LAN as the Enterprise OTBR, should return, amongst others, two usable inet6 addresses (private/public) that matches the prefix set by the commissioner (in our case starts with fd11:2446:
)
inet6 fd11:2446:f1ca:3a6b:4458:f97d:fe6b:938 prefixlen 64 scopeid 0x0<global>
inet6 fd11:2446:f1ca:3a6b:b80d:a4bc:6df1:9efe prefixlen 64 scopeid 0x0<global>
The thread end device and the developer machine on the LAN can now contact each other via the border router. Run the ping command on the thread end device to see it in action:
> ping fd11:2446:a285:cdb2:ec89:a088:3f76:bdf6
> 16 bytes from fd11:2446:a285:cdb2:ec89:a088:3f76:bdf6: icmp_seq=1 hlim=63 time=36ms
Congratulations, you are now running a Thread Border Router on the Enterprise OTBR.
Pinging an IPv4 Resource Using NAT64
The Enterprise OTBR is loaded with Tayga for NAT64 translations to allow communication between IPV6 and IPV4 resources. Tayga can be configured to meet network requirements by editing /etc/tayga.conf and /etc/default/tayga files.
The Enterprise OTBR is configured to use the well known 6-to-4 prefix of “64:ff9b::/96”, this means that in order to ping an IPv4 resource from your thread end device, this prefix has to prepend that resource’s address.
To ping the Google public DNS server of 8.8.8.8, issue the following command to the thread end device
> ping 64:ff9b::808:808
16 bytes from 64:ff9b::808:808: icmp_seq=1 hlim=63 time=41ms
Limitations
The 6-to-4 prefix does not allow NAT64 to operate inside the LAN on which it sits, thus to ping a LAN device, the “prefix” directive inside /etc/tayga.conf would have to be changed to something in the Unique Local Unicast range of fc00::/7.
Confirm that you cannot ping a LAN device
Converting your LAN device’s IPv4 address to the 4-in-6 format inside the well-known prefix and attempt to ping it, this should not return a response.
Example: 192.168.0.2 becomes 64:ff9b::c0a8:0002 (192 = 0xc0, 168 = 0xa8, … )
> ping 64:ff9b::c0a8:0002
To remedy this, open /etc/tayga.conf and change the “prefix” directive to a prefix in fc00::/7.
An example of a prefix in this range is fd11:2446:64::/96 which is included in the file at the time of this writing, so all that is required is to comment out the existing prefix and uncomment the provided one.
Restart Tayga with the following command, run the ping command with the new prefix and it should return successfully
[mmb@Tripoli-0000e4:~]$ sudo /etc/init.d/tayga restart
After Tayga restarts, you will be able to successfully ping the address from your end device.
> ping fd11:2446:64::c0a8:0002
> 16 bytes from fd11:2446:64:0:0:0:c0a8:0002: icmp_seq=6 hlim=61 time=34ms
Legal Notices
Copyright © 2020 MMB Networks, Inc. All rights reserved.
Confidential materials prepared and delivered by MMB Networks for receipt and review only by any partner subject to a valid and enforceable MMB Networks confidentiality agreement. Any receipt, review, or misuse of any of the content exchanged hereunder by any party not a party to this confidential exchange shall be subject to any and all rights available under the law. All rights, title and interest to the materials shall remain with MMB Networks.
Any suggestions provided to MMB Networks with respect to MMB Networks' products or services shall be collectively deemed “Feedback.” You, on behalf of yourself, or if you are providing Feedback on behalf of your employer or another entity, represent and warrant that you have full legal authority to bind such entity to these terms, agree to grant and hereby grant to MMB Networks a nonexclusive, perpetual, irrevocable, royalty free, worldwide license to use and otherwise exploit such Feedback within any MMB Networks products and services.