netceteragroup/rpi-ttn-gateway

Docker image for Raspberry PI TTN gateway based on Hypriot

Raspberry PI TTN gateway

Raspberry PI TTN gateway image based on Hypriot. This dockerfile is heavily influenced by the install script from The Things Network iC880a-based gateway.

Hardware Preperation

This image is made for and tested on a Raspberry Pi 3 together with a IMST-iC880 SPI LoRaWAN concentrator.

OS preparation

Here are the steps to get the host environment ready for this image:

1. Download the latest HypriotOS from here: https://blog.hypriot.com/downloads/
2. Install it on a SD card. Etcher is a easy-to-use tool for this: https://etcher.io/
   • Optional: place an empty ssh file in the root of the SD card to enable SSH access to the Pi
3. Put the SD card into your Raspberry Pi and power it up
4. Login with user pirate and password hypriot Note: default keyboard layout is QWERTY. If you are using a QWERTZ keyboard make sure you use the correct 'y' in the password
   • For SSH access: once the Pi has fully booted (the blinking LEDs have calmed down) it shows up with the default hostname black-pearl in your network.
5. Run sudo apt-get update && sudo apt-get install raspi-config kbd. During setup you can choose a different keyboard layout if you need
6. Run sudo raspi-config to
   • Set correct timezone: 4 Localisation Options > I2 Change Timezones
   • Enable SPI interface: 5 Interfacing Options > P4 SPI > Yes
7. Restart the Pi
8. Find the Pi MAC address and generate gateway EUI (required in next step) by running cat /sys/class/net/eth0/address | awk -F\: '{print $1$2$3"fffe"$4$5$6}'. This turns the 48-bit MAC address into EUI-64, splits it in half and injects fffe (e.g. b827eb8684a2 → b827ebfffe8684a2).
9. Run

   docker run -it --privileged --net=host --restart=always \
   -e PI_RESET_PIN=<optional-see-explanation-below> \
   -e TTN_GATEWAY_SERVER_URL=<optional-see-explanation-below> \
   -e GATEWAY_EUI=<EUI-identified-in-previous-step> \
   -e GATEWAY_LAT=YOUR_LATITUDE \
   -e GATEWAY_LON=YOUR_LONGITUDE \
   -e GATEWAY_ALT=YOUR_ALTITUDE \
   -e GATEWAY_EMAIL=YOUR_EMAIL \
   -e GATEWAY_NAME=YOUR_GATEWAY_NAME \
   netceteragroup/rpi-ttn-gateway

   • PI_RESET_PIN may or may not be required depending on how the concentrator is connected to the Pi. The default reset pin configured by the start script is 25. Installations with simple backplanes such as the one from Gnz can go with the default value. More elaborate backplanes might rewire the reset pin. The one from CH2i for example uses 17. Hence, you would say docker run ... -e PI_RESET_PIN=17 ....
   • TTN_GATEWAY_SERVER_URL URL of the TTN API endpoint server to use, the default is eu1.cloud.thethings.network. Server address for other regions are listed here: https://www.thethingsindustries.com/docs/getting-started/ttn/addresses/

Running as a deamon

Item 9 above documents the Docker run command. If you would rather want to run the TTN container in daemon mode rather than interactive mode you would replace -dt with -it. This will put the Docker container process into the background and not block the CLI but you won't see the log output that normally spills to the console.

docker logs <container-id> could make that visible again if necessary. Or docker attach <container-id>. Or docker exec -i <container-id> /bin/bash and then poke around the container.

Building the image yourself

To build a (potentially customized) image yourself do as follows:

$ git clone https://github.com/netceteragroup/rpi-ttn-gateway
$ cd rpi-ttn-gateway
$ docker build -t <your-handle-here>/rpi-ttn-gateway .

<your-handle-here> can be anything that is uniquely you (e.g. name) but you might also use rpi-ttn-gateway w/o any "prefix".

Security considerations

Just a few obvious measures you can/should think about before you release your new gateway into the wild.

• It does help if the gateway is connected to the internet through a private network that's hard to penerate.
• Change the default password: connect to the Pi and run passwd to use a custom password.
• Change the default hostname: edit /boot/device-init.yaml and modify the hostname attribute (source).

rpi-ttn-gateway's Issues

Consider droping optional config params

The only mandatory config params for a TTN gateway are:

• reset pin
• gateway EUI
• region i.e. TTN server

We can either

• leave it as-is to (potentially) be future proof or (again potentially) support non-TTN backends OR
• dump everything not strictly required thereby slimming our code and documentation

Concentrator won't start

I followed the instructions, but I'm getting the following error when starting the container:

INFO: [main] Starting the concentrator
ERROR: [main] failed to start the concentrator
/usr/bin/entry.sh: line 93: fg: job has terminated

Any hints on what I might be doing wrong?

Document Docker daemon mode

I suspect that most people would rather want to run the TTN container in daemon mode rather than interactive mode (-dt vs. -it). It would run in the background and not block the CLI but you won't see the log output that normally spills to the console.

docker logs <container-id> could make that visible again if necessary. Or docker attach <container-id>. Or docker exec -i <container-id> /bin/bash and then poke around the container.

Suggest password change in README

It is kind of irresponsible to not at least point out that the RPi password should be changed. Or these gateways will become easy targets for malware attacks

Run CI only when the Dockerfile actually changes

Helpful: $TRAVIS_COMMIT_RANGE
https://github.com/facebook/react/blob/master/.travis.yml#L19
https://github.com/opencontainers/runtime-spec/blob/8831b203606aa74d2bf5274108816dde7629fa6f/.travis.yml#L16

Avoid usage of "latest" or git-master dependencies

In the docker file we use "FROM resin/rpi-raspbian" which uses the latest release of the rpi-raspbian image. This can introduce instability when the parent image has changed in the meantime. Similarly cloning the master version of a git-repo in the Dockerfile can lead to inconsistent behavior if no tag has been used. If the image is built at different points in time the resulting image can look different with every build.

This can be compared to a maven release which should not have dependencies to any unreleased version of other libraries.

In addition the image on dockerhub should get tagged not just with "latest" but with versions

Thanks to @marschall for the input.

Here some more reading about the topic:
https://medium.com/@mccode/the-misunderstood-docker-tag-latest-af3babfd6375
http://blog.benhall.me.uk/2015/01/dockerfile-latest-tag-anti-pattern/
http://container-solutions.com/docker-latest-confusion/

Document how to persist container log files

The TTN script generates log output (quite a bit) that is lost if you don't persist it manually. If the container runs in daemon mode (see #17) you might want to mount the host OS and pipe the output to a host OS file. Down side: might contribute to SD card corruption in the long run.

Make the TTN server configurable

Currently we're setting the EU server statically at https://github.com/netceteragroup/rpi-ttn-gateway/blob/master/Dockerfile#L35.

We should allow users to pick a region (not the actual hostname) based on their country as per:

router.eu.thethings.network # EU 433 and EU 863-870
router.us.thethings.network # US 902-928
router.cn.thethings.network # China 470-510 and 779-787
router.au.thethings.network # Australia 915-928 MHz

Reference: https://www.thethingsnetwork.org/forum/t/new-addresses-for-cloud-services-update-your-gateways/1813

Document simple gateway EUI command

Rather than documenting the manual way to extract-and-build the EUI we could also document the following command: cat /sys/class/net/eth0/address | awk -F\: '{print $1$2$3"fffe"$4$5$6}'.

Make reset pin configurable

The first user to pull the image already ran into this: #5.