From 6c08cda73e119ea4c79d8f3c0c52107333541c48 Mon Sep 17 00:00:00 2001 From: Ray Ozzie Date: Fri, 25 Mar 2016 13:11:44 -0400 Subject: [PATCH] xxx --- README.md | 70 +++++++++++++++++++++++++++++++++---------------------- build.sh | 2 +- 2 files changed, 43 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 8c0b7b1..c64f979 100644 --- a/README.md +++ b/README.md @@ -2,49 +2,63 @@ Resin Dockerfile & scripts for [The Things Network](http://thethingsnetwork.org/) gateways based on the iC880a concentrator with a Raspberry Pi host, connected using SPI. -## Instructions +## PREREQUISITES -- Download [Raspbian Jessie](https://www.raspberrypi.org/downloads/) -- Follow the [installation instruction](https://www.raspberrypi.org/documentation/installation/installing-images/README.md) to create the SD card -- Start your RPi connected to Ethernet -- Plug the iC880a (**WARNING**: first power plug to the wall socket, then to the gateway DC jack, and ONLY THEN USB to RPi!) -- From a computer in the same LAN, `ssh` into the RPi using the default hostname: +1. Build one or more RPi + IMST iC880A SPI gateways as described in **Hardware Setup** here: https://github.com/ttn-zh/ic880a-gateway/tree/spi +2. Create and sign into an account at http://resin.io, which is the central "device dashboard". By using this dashboard you will be able to create the "boot SD" for your Raspberry pi. When you use that SD card, Resin will recognize that Raspberry Pi as belonging to you, will then deliver the gateway software to your RPi, and will subsequently keep your RPi up-to-date with future updates to the gateway software. +3. Clone **this** github repo to your mac/pc. That desktop repo will be subsequently used to instruct resin.io what software to place on your gateway(s). - local $ ssh pi@raspberrypi.local +## PREPARING YOUR FIRST GATEWAY DEVICE FOR RESIN.IO -- Disable graphical boot mode and reboot: +1. On resin.io, create an "Application" for managing your TTN gateway devices. I'd suggest that you give it the name "ttngw", select the appropriate device type (i.e. Raspberry Pi 2 or Raspberry Pi 3), and click "Create New Application". You only need to do this once, after which you'll be able to manage one or many gateways of that type. +2. You'll then be brought to the Device Management dashboard for that Application. Follow the instructions to create a boot SD for your Raspberry Pi. (Pro Tip: Use a fast microSD card and a USB 3 adapter if you can, because it can take a while to copy all that data. Either that, or be prepared to be very patient.) Note that during the long process of waiting for the "sudo dd" command, if you're using a Mac you can press "Ctrl T" which will give you an interim progress report. +3. When the (long) process of writing the image to the SD card completes, insert it into your Raspberry Pi, connect it to the network with Ethernet, and power it up. +4. After several minutes, on the resin.io Devices dashboard you'll now see your device - first in a "Configuring" state, then "Idle". Click it to open the Devices control panel. +5. If you like, enter any new Device Name that you'd like, such as "gateway-1". - $ sudo raspi-config +## PREPARING YOUR FIRST GATEWAY DEVICE FOR TTN -- Configure locales and time zone: +1. Click the "Environment Variables" section at the left side of the screen. This will allow you to configure environment parameters for this and only this device, and which will be appropriately inserted into this device's "local_conf.json" with lowercase tuple names derived from the appropriate uppercase environment names beginning with "GW_". For example, for a gateway with no GPS, the MINIMUM environment variables that you should configure at this screen should look something like this: - $ sudo dpkg-reconfigure locales - $ sudo dpkg-reconfigure tzdata + DEVICE ENVIRONMENT VARIABLES + Name Value -- Remove desktop-related packages: + GW_CONTACT_EMAIL yourname@yourdomain.com + GW_DESCRIPTION your-gateway-1 + GW_REGION EU + GW_REF_LATITUDE 52.376364 + GW_REF_LONGITUDE 4.884232 + GW_REF_ALTITUDE 3 - $ sudo apt-get install deborphan - $ sudo apt-get autoremove --purge libx11-.* lxde-.* raspberrypi-artwork xkb-data omxplayer penguinspuzzle sgml-base xml-core alsa-.* cifs-.* samba-.* fonts-.* desktop-* gnome-.* - $ sudo apt-get autoremove --purge $(deborphan) - $ sudo apt-get autoremove --purge - $ sudo apt-get autoclean - $ sudo apt-get update +## TRANSFERRING TTN GATEWAY SOFTWARE TO RESIN SO THAT IT MAY BE DOWNLOADED ON YOUR DEVICES -- Create new user for TTN and add it to sudoers +1. On your Mac or PC, in terminal, change your working directory to the directory that is the clone of **this** git repo. +2. Now, type the command that you'll see displayed in the edit control in the upper-right corner of the Resin devices dashboard for your device. This command "connects" your local directory to the resin GIT service, which uses GIT to "receive" the gateway software from TTN, and it looks something like this: - $ sudo adduser ttn - $ sudo adduser ttn sudo + git remote add resin youraccount@git.resin.io:youraccount/yourapplication.git -- Logout and login as `ttn` and remove the default `pi` user +3. Type the following commands into terminal to "push" the TTN files up to resin.io: - $ sudo userdel -rf pi + git add . + git -m "first upload of ttn files to resin" + git push resin master -- Clone the installer and start the installation +5. What you'll now see happening in terminal is that this "git push" does an incredible amount of work: - $ git clone https://github.com/ttn-zh/ic880a-gateway.git ~/ic880a-gateway - $ cd ~/ic880a-gateway - $ sudo ./install.sh + a) It will upload a Dockerfile, a "build script", and a "run script" to resin + b) It will start to do a "docker build" using that Dockerfile, running it within a QEMU ARM virtual machine on the resin service. + c) In processing this docker build, it will run a "build.sh" script that downloads and builds the packet forwarder executable from source code, for RPi+iC880A-SPI. + d) When the build is completed, you'll see a unicorn ASCII graphic displayed in your terminal. +6. Now, switch back to your device dashboard, you'll see that your Raspberry Pi is now "updating" by pulling the Docker container from the resin.io service. Then, after "updating", you'll see the gateway's log file in the window at the lower right corner. You'll see it initializing, and will also see log output each time a packet is forwarded to TTN. You're done! + +## PRO TIPS + +- At some point if you would like to add a second gateway, third gateway, or a hundred gateways, all you need to do is to add a new device to your existing Application. You needn't upload any new software to Resin, because Resin already knows what software belongs on the gateway. So long as the environment variables are configured correctly for that new device, it'll be up and running immediately after you burn an SD card and boot it. + +- Resin will automatically restart the gateway software any time you change the environment variables. You'll see this in the log. Also, note that Resin restarts the gateway properly after power failures. If the packet forwarder fails because of an error, it will also automatically attempt to restart. + +- If you'd like to update the software across all the gateways in your device fleet, simply do another "git push resin master", which will rebuild the software # Credits diff --git a/build.sh b/build.sh index a4b0c40..ed9f667 100755 --- a/build.sh +++ b/build.sh @@ -1,6 +1,6 @@ #! /bin/bash -# Stop on the first sign of trouble +# Stop on the first sign of trouble! set -e echo "The Things Network RPi + IC880A Gateway Builder/Installer"