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.
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.
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:
- 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.
sudo dpkg -i mira-gateway-armhf.deb
MIRA_GW_ANTENNAto 1 and set
- Connect the Radio Module in a free USB port.
- Start the service with:
sudo systemctl start mira-gateway
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,
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
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.debthat is installed with
sudo dpkg -i mira-gateway-armhf.deb.
- An archive
mira-gateway-armhf.tar.gzthat can be unpacked in root with
cd /; sudo tar -xvf /path/to/mira-gateway-armhf.tar.gz.
- The executable binary
mira_gateway-armhf-linuxand scripts under
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 file 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):
||The Mira performance rate to use at the gateway (this would typically be
||The mode of operation of the gateway (should be
||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.|
||The tty device where the RoaS is connected, before DFU has run. For USB "AUTO" works for automatic detection.|
||The tun device that shall be created.|
||The link-layer encryption key to use (in hexadecimal).|
||The PAN ID to use (in hexadecimal).|
||Set what antenna to use. For LumenRadio's radio modules, 0 (the default) is the internal antenna, 1 is the external antenna.|
||Forward incoming UDP packets to host computer network stack.|
||Set the root's address. The /64 prefix is used as the network's prefix.|
||Extra IP address to bind on the interface, most often used for multicast addresses.|
||During startup, root immediatly creates a new network, causing all nodes to timeout and reconnect after a long time. Mostly useful for testing.|
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
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
Start the gateway with the same network credentials as the network_sender node.
Also make sure to use the
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
Wait for some additional time to let downward routes be established. Then run the following command:
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.
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
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.
Figure 1: A Mira gateway