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:

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

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.

Quick start guide for MiraUSB module¶

The quickest way to getting a Mira Gateway running is to use a Raspberry Pi and a MiraUSB module.

Prepare the Pi with Raspberry Pi OS, see here for instructions.
Copy gateway/mira-gateway-armhf.deb to the Pi's memory card.
Boot it up and login.
Run: sudo dpkg -i mira-gateway-armhf.deb
Edit /etc/default/mira-gateway, set MIRA_GW_ANTENNA to 1.
Edit /etc/mira-gateway/mira-gateway.env, set values for MIRA_GW_PAN_ID and MIRA_GW_KEY/
Connect the Radio Module in a free USB port.
Start the service with: sudo systemctl start mira-gateway

Run journalctl -u mira-gateway.service -f to see the latest messages from the service. After a couple of minutes it will show Joining network and Joined network. After that mesh nodes will start to join the network.

Known problem with Raspberry Pi¶

Sometimes when restarting the gateway software the MiraUSB device will disapear from the USB bus. To get it back, one can reset the USB bus with sudo usbreset 2/1.

There is a comment showing a possible workaround for this in the debian packet's startup script, /opt/lumenradio/mira-gateway/bin/mira-gateway-startup. The drawback of that solution is that all USB devices connected to the pi will reinitialize.

Installing a RoaS¶

To build a RoaS on hardware that is not preinstalled one needs to flash the necessary files. The host and the RoaS can communicate either through a serial port or through USB. The two different ways use two different bootloaders.

RoaS, connected through a serial port¶

The RoaS needs to be programmed with the mira_gatewayboot-nrf52840-bare.hex serial bootloader for nRF52840. Other versions of the bootloader are available for other platforms.

RoaS, connected through USB¶

MiraUSB modules from LumenRadio are delivered ready to run, with the bootloader and license already installed.

For custom hardware, the RoaS needs to be programmed with the usb_bootloader_nrf52840.hex USB bootloader and the mbr_nrf52_*_mbr.hex MBR.

Installing the host software¶

The host software for linux on ARM are delivered in three different ways:

A debian package for raspbian mira-gateway-armhf.deb that is installed with sudo dpkg -i mira-gateway-armhf.deb.
An archive mira-gateway-armhf.tar.gz that can be unpacked in root with cd /; sudo tar -xvf /path/to/mira-gateway-armhf.tar.gz.
The executable binary mira_gateway-armhf-linux and scripts under gateway/scripts

The debian package and the archive both contain a systemd configuration file to automatically start the service. After installing/unpacking the software, edit /etc/default/mira-gateway and /etc/mira-gateway/mira-gateway.env to change the default settings. Without change, the server uses the same pan ID and network key as the example applications and network traffic are NOT forwarded to/from the mesh network and the host.

If you copy the binary, the scripts directory and contents need to be copied to the same directory as the binary.

Running the host software directly from a script¶

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

sudo ./mira_gateway --rate=0 --mode=root --dev=AUTO --dfu-dev=AUTO --tundev=tun0 \
    --key=11121314212223243132333441424344 --panid=13243546

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 tty device where the RoaS is connected (after DFU when running over USB). For USB "AUTO" works for automatic detection or don't add this argument.
`dfu-dev`	The tty device where the RoaS is connected, before DFU has run. For USB "AUTO" works for automatic detection.
`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).
`antenna`	Set what antenna to use. For LumenRadio's radio modules, 0 (the default) is the internal antenna, 1 is the external antenna.
`host-ip`	Set the root's address. The /64 prefix is used as the network's prefix.
`bind-ip1`	Extra IP address to bind on the interface, most often used for multicast addresses.
`bind-ip2`	Dito
`bind-ip3`	Dito
`no-reconnect`	During startup, root immediatly creates a new network, causing all nodes to timeout and reconnect after a long time. Mostly useful for testing.
`max-fota-clients`	Max number of simultaneous FOTA clients the gateway can serve. Default and minimum is 2 and max is 58.

License handling of RoaS¶

MiraUSB module is delivered with a built in license.

For other hardwares a license file needs to be added to a licenses directory in the same directory as the mira_gateway binary. If the host software is installed through the debian package, the license directory is found under /opt/lumenradio/mira-gateway/bin/licenses. The license file name should be .lic.

See License for details about generating such a file. The DeviceID of the device will be written in the gateway's output if the license isn't available. For USB connected devices, the USB device's serial number is also its DeviceID and it can be found with sudo lsusb -v on linux (the last text after iSerial for the device with "Nordic Semiconductor" as Vendor) or using System Information on macOS (find the device in the USB->USB Device Tree and the DeviceID is shown after "Serial Number:").

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.

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 likely 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.

PA/LNA support on RoaS¶

Custom PA/LNA hardware control is supported on a RoaS. Configure it in the license file. See License for details. This is already done for the MiraUSB module.

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 and a radio module.

It can be used for reference purposes when building your own gateway, or while developing.

Reference gateway
Figure 1: A Mira gateway