A Docker Practice for LoRa Gateway Using RAK833 mPCIe Module

What’s Docker?

Docker unlocks the potential of your organization by giving developers and IT the freedom to build, manage and secure business-critical applications without the fear of technology or infrastructure lock-in.

By combining its industry-leading container engine technology, an enterprise-grade container platform and world-class services, Docker enables you to bring traditional and cloud native applications built on Windows Server,Linux and mainframe into an automated and secure supply chain, advancing dev to ops collaboration and reducing time to value.

Because Docker increases productivity and reduces the time it takes to bring applications to market, you now have the resources needed to invest in key digitization projects that cut across the entire value chain, such as application modernization,cloud migration and server consolidation. With Docker, you have the solution that helps you manage the diverse applications, clouds and infrastructure you have today while providing your business a path forward to future applications.

What’s LoRaWAN?

LoRaWAN is a Low Power, Wide Area (LPWA) networking protocol designed to wireless connect battery operated ‘things’ to the internet in regional, national or global networks, and targets key Internet of Things (IoT) requirements such as bi-directional communication, end-to-end security, mobility and localization services.

LoRaWAN network architecture is deployed in a star-of-stars topology in which gateways relay messages between end-devices and a central network server. The gateways are connected to the network server via standard IP connections and act as a transparent bridge, simply converting RF packets to IP packets and vice versa.The wireless communication takes advantage of the Long Range characteristics of the LoRa physical layer, allowing a single-hop link between the end-device and one or many gateways. All modes are capable ofbi-directional communication, and there is support for multicast addressing groups to make efficient use of spectrum during tasks such as Firmware Over-The-Air (FOTA) upgrades or other mass distribution messages.

What’s RAK833?

The RAK833 is a LoRa gateway mini PCIe module with SPI and USB interface.

It is a LoRa Radio frontend, and acts as a receiver of incoming LoRa data packets and forwards them to an aggregator management software/hardware host. It can also transmit LoRa data packets based on the host boards request. In our case a raspberry Pi3 module B+ is the host board controlling the RAK833 frontend.

You can learn morea bout RAK833 in its datasheet from the following link:

http://docs.rakwireless.com/en/LoRa/RAK833-Pcie-Gateway/Hardware_Specification/RAK833%20LoRa%20Gateway%20DataSheet%20V1.3.pdf

Where is the source code?

You can find the source code here: https://github.com/Ellerbach/lora_gateway.

It is made by Laurent Ellerbach who comes from Microsoft.

If you want other solution of RAK833, for example, RAK833 + Raspberry Pi and RAK833 + OpenWRT, you can see the RAKWireless Github repositories and find the following projects:

https://github.com/RAKWireless/RAK833-LoRaGateway-RPi

https://github.com/RAKWireless/RAK833-LoRaGateway-OpenWRT-MT7628

After a few days, there may be another solution for RAK833 + SolidRun.

Hardware Preparations

The needed hardware is a RAK833 LoRa gateway module, which is made by RAKWireless and support SPI + USB via a mPCIe physical interface. You can find this specific RAK833 mPCIe module in the following link:

https://www.aliexpress.com/item/RAK833-SPI-USB-Industrial-Grade-Mini-PCIe-LoRa-Gateway-Concentrator-Module-SX1301-FT2232H-Chip-868-915MHz/32867370031.html.

Note: it is critical to plug the antena before using the board. It may destroy the board if you're not doing it.

It does then require a specific USB-mPCIe adapt or which is basically a pass through connecting the USB pins from the mPCIe board to the regular USB. This part is actually quite complicated to find. You can find it in the following link: https://www.aliexpress.com/item/Mini-PCI-Express-pcie-pci-express-PCI-E-Wireless-WWAN-to-USB-Adapter-Card-with-SIM/32657444139.html.

Be aware that hard drive ones and other implementing a USB component on the board won't work. Only those ones are actually working. Cost is about 8€.

The solution is designed to work on a Raspberry Pi 3 (works as well on v2, 3B and 3B+). so you'll need a Raspberry Pi. This one is easy to find.

The all solution looks like this:

How to use the Docker Container

This container has been built to be more specifically used as a LoRa Network Packet Forwarder. And be used with Azure IoT Edge.

You will find the perfect use case in the Azure LoRaWan Starter Kit.

Rapsberry Pi and other arm32v7 processors

You can directly use this module as a Docker container:

docker pull ellerbach/lorawanpktfwdmodulerak833usb:0.0.1-arm32v7

When you'll run it, make sure you run it with privileges:

docker run --privileged ellerbach/lorawanpktfwdmodulerak833usb:0.0.1-arm32v7

Note: If you want to run on other OS, Please see the below:

Running on a Mac OSX

This is a bit more complicated, please check the specific steps for Mac OSX. Once you've installed Virtual Box and setup the USB port, you can either continue the process and rebuild the dockerfile, either just use it.

docker pull ellerbach/lorawanpktfwdmodulerak833usb:0.0.1-amd64

When you'll run it, make sure you run it with privileges:

docker run --privileged ellerbach/lorawanpktfwdmodulerak833usb:0.0.1-amd64

Running on Linux 64bits OS

You can directly enjoy the container on any Linux 64 bit OS.

docker pull ellerbach/lorawanpktfwdmodulerak833usb:0.0.1-amd64

When you'll run it, make sure you run it with privileges:

docker run --privileged ellerbach/lorawanpktfwdmodulerak833usb:0.0.1-amd64

Debian arm32v7 Docker Image

The docker filecontains all what is needed to build a container with all the individual needed components. In short, you'll need the libmpsse library and few dependencies. You'll need as well, this repository and the LoRaPacket Forwarder.

The Dockerfile contains 2 large sections. The first one use a standard arm32v7 Debian image and build the full solution. The second one is the same image used to run the solution. It is a good practice to use one container to build the solution and using a light one, with only the necessary elements to run it.

This principle allow when possible (not in our case because of the hardware dependencies) a cross platform build in the first container and just what is needed in the second one. This reduce the size of the final containers and reduces as well the security risk by having the minimum number of software in it.

I do recommend to use the Moby version of Docker. This will do the trick:

# Download and install the moby-engine

curl -L https://aka.ms/moby-engine-armhf-latest -o moby_engine.deb && sudo dpkg -i./moby_engine.deb

# Download and install the moby-cli

curl -L https://aka.ms/moby-cli-armhf-latest -o moby_cli.deb && sudo dpkg -i./moby_cli.deb

# Run apt-get fix

sudo apt-get install -f

# Add the pi user to the group which can run Docker without priviledges. Need to logoff and log on

sudo usermod -aG docker pi

In order to understand all what is needed in the container, please refer to the next section.

Note: this container can be fully build on Windows with Docker setup to run Linux containers. This will be much easier and much faster than building it on a Raspberry Pi.

Make a Dockerfile for this solution

You can make a Dockerfilefor this solution as follow:

# This docker builds a container for the SPI/USB RAK833 (and equivalent) LoRaWaN gateway using a USB-SPI adaptor

# The first image is used to build the full solution

FROM arm32v7/debian:stretch-slim as builder

RUN apt-get update && apt-get upgrade -y

RUN apt-get install -y git build-essential

RUN apt-get install -y swig libftdi-dev curl

# libmpsse install

WORKDIR /build

RUN git clone https://github.com/devttys0/libmpsse.git

WORKDIR /build/libmpsse/src

RUN./configure --disable-python

RUN make

RUN make install

RUN ldconfig

# Lora Gateway for RAK833 based modules

WORKDIR /build

RUN git clone https://github.com/ellerbach/lora_gateway

RUN cp./lora_gateway/libloragw/99-libftdi.rules /build/99-libftdi.rules

WORKDIR /build/lora_gateway

RUN make

# Lora packet forwarder

WORKDIR /build

RUN git clone https://github.com/ellerbach/packet_forwarder.git

WORKDIR /build/packet_forwarder

RUN make

# Download in the first image the needed FTDI dependencies package

WORKDIR /build

RUN curl -L http://ftp.us.debian.org/debian/pool/main/libf/libftdi/libftdi1_0.20-4_armhf.deb -o libftdi1_0.20-4_armhf.deb

RUN curl -L http://ftp.us.debian.org/debian/pool/main/libu/libusb/libusb-0.1-4_0.1.12-30_armhf.deb -o libusb-0.1-4_0.1.12-30_armhf.deb

# The second image is used to deploy the built solution

FROM arm32v7/debian:stretch-slim as exec

WORKDIR /LoRa

# Install the various USB libraries

COPY--from=builder /build/libmpsse/src/libmpsse.so libmpsse.so

COPY--from=builder /build/libmpsse/src/libmpsse.a libmpsse.a

COPY--from=builder /build/libftdi1_0.20-4_armhf.deb.

COPY--from=builder /build/libusb-0.1-4_0.1.12-30_armhf.deb.

COPY--from=builder /build/99-libftdi.rules /etc/udev/rules.d/99-libftdi.rules

RUN install-D -m644 libmpsse.so //usr/local/lib/libmpsse.so

RUN install-D -m644 libmpsse.a //usr/local/lib/libmpsse.a

RUN dpkg -i./libusb-0.1-4_0.1.12-30_armhf.deb

RUN dpkg -i./libftdi1_0.20-4_armhf.deb

RUN ldconfig

# Copy the packet forwarder containing the fully build application

COPY --from=builder /build/packet_forwarder/lora_pkt_fwd/lora_pkt_fwd.

# Copy the various config file supporting US and EU fequencies and configurations

COPY --from=builder /build/packet_forwarder/lora_pkt_fwd/global_conf.json.

COPY local_conf.json.

COPY global_conf.us.json.

COPY global_conf.json global_conf.eu.json

# Copy the

COPY start_pktfwd.sh.

ENTRYPOINT ["./start_pktfwd.sh"]

All the file you need can be found here:

https://github.com/Ellerbach/lora_gateway/tree/master/docker