Gateway / Border gateway¶

A gateway or border gateway is a device that act as the interface between the Mira network and the rest of the world.

Gateway vs. Border gateway¶

The device might be called either gateway or border gateway, the term are often used interchangeably although they technically are slightly different.

In regards to Mira the terms may (except for in this section) be used interchangeably since the difference are mainly in regards to configuration and applications.

Gateway¶

A gateway typically run a piece of software locally on the device that receives packets from the Mira network and forward them to some cloud platform via MQTT, a REST API or any other method.

In this scenario one typically does not permit raw IPv6 packets to be routed between the Mira network and the outside world. One could say that a gateway typically works on the application layer.

Border gateway¶

A border gateway acts on the network layer and will allow for IPv6 packets to be routed between different networks. It may for instance be set up to route packets between the Mira network and an Ethernet connection.

With a border gateway it is possible to use standard Internet end-to-end security mechanisms like DTLS, etc.

Gateway support in Mira¶

Gateway support in Mira consists of two parts:

A radio running a special software - this is called "Radio on a stick" (aka. RoaS).
A piece of software that runs on a POSIX host to create the networking interfaces needed and that interfaces with the RoaS.

Gateway software is available for the following platforms (can be downloaded from the download portal):

Linux
- x86_64
- ARMv7-A (Cortex A7, etc)
- ARMv8-A (Cortex A53, etc)
Mac OS
- x86_64

For platform questions and platform requests, please contact LumenRadio.

When running the host software a tun interface is created with a /64 IPv6 prefix. Once this is created packets can be send to and from the Mira network assuming you know the nodes' IPv6 addresses.

If, in a node in the network, getting the root address and sending to (as in the network sender example) these packets will be sent to the corresponding UDP port on the host in the gateway. This allows for writing your gateway code in any programming language that can be used on the host system.

Running the gateway¶

Connecting the RoaS¶

First the RoaS needs to be programmed. On a nRF52840 RoaS this will be done by running the following command when in the corresponding directory:

nrfjprog --family nrf52 --sectorerase \
    --program mira_roas-nrf52840.hex --reset --verify

Running the host software¶

Start the gateway software as follows (parameters may differ slightly depending on the system):

sudo ./mira_gateway --rate=0 --mode=root --dev=/dev/ttyUSB0 --tundev=tun0 \
    --key=11121314212223243132333441424344 --panid=13243546 --forward-udp

Parameter	Description
`rate`	The Mira performance rate to use at the gateway (this would typically be `0` for highest performance).
`mode`	The mode of operation of the gateway (should be `root` in most cases).
`dev`	The serial device where the RoaS is connected.
`tundev`	The tun device that shall be created.
`key`	The link-layer encryption key to use (in hexadecimal).
`panid`	The PAN ID to use (in hexadecimal).
`forward-udp`	Forward incoming UDP packets to host computer network stack.

For starting this automatically at boot time it is recommended to start this from a script.

#!/usr/bin/env bash

if [ "$EUID" -ne 0 ]
  then echo "Please run as root"
  exit
fi

this_dir="$(cd $(dirname "${BASH_SOURCE[0]}") && pwd)"

$this_dir/mira_gateway \
  --rate=0 \
  --mode=root \
  --dev=/dev/ttyUSB0 \
  --tundev=tun0 \
  --key=11121314212223243132333441424344 \
  --panid=13243546 \
  --forward-udp

Testing the gateway¶

To verify functionality of the gateway, first flash a node to be running the network_sender example.

Start the gateway with the same network credentials as the network_sender node. Also make sure to use the --forward-udp option.

Run the command nc -l -6 -u 456 to start listen for UDP packets on port 456. (Note: you might need to have root privileges to do this.) Once the network has formed, you will start to receive packets from the network_sender node.

Wait for some additional time to let downward routes be established. Then run the following command:

ping6 -i 5 -c 50 fd01::1234

Replace fd01::1234 with the IPv6 address of the network_sender device. And make sure that the wait time (the -i option) is long enough in relation to the configured performance rates of the devices.

If the host system could successfully ping the network_sender, the gateway interfaces are functional.

If IPv6 routing in/out of the network is required, continue to the next section. Otherwise the gateway application can be written.

Setting up routing¶

If routing is to be performed, IPv6 forwarding is required in the host operating system. Please refer to documentation on this topic for your specific operating system.

The border gateway will liekly need to be set up to advertise that it is a router for the network prefix of the Mira network. This can be done in many different ways, radvd for Linux is one option. It will send ICMPv6 Router Advertisements on your Ethernet or WiFi network.

License handling of RoaS¶

The RoaS need a license to run. See License for details.

PA/LNA support on RoaS¶

Custom PA/LNA hardware control is supported on a RoaS. Configuration is done using the license area. See License for details.

FOTA support¶

The gateway supports distributing firmwares to Mira devices via the Mira FOTA service.

Firmwares are stored in the firmwares directory as N.bin, where N is the slot number (0 to 19). The border gateway reloads changed files regulary.

To prevent distributing partly written firmwares, first copy the new firmware to a temporary name and then move it over the old firmware file. Ie: cp new-firmware firmwares/0.tmp && mv firmwares/0.tmp firmwares/0.bin

Reference gateway¶

LumenRadio has a reference gateway for development purposes that consists of a Raspberry Pi with a built-in Mira radio module as a RoaS. It can be used for reference purposes when building your own gateway, or while developing.

Reference gateway
Figure 1: A Mira gateway