UKHAS Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Beginners Guide to Tracking using LoRa ======

Many flights now use LoRa (Long Range modem) devices for tracking, either instead of or in addition to RTTY tracking.  This is a short guide on how to receive and upload (to the UKHAS servers) live tracking data and/or images (SSDV) from a balloon sending out LoRa telemetry/SSDV.


===== Hardware =====

The minimum needed to receive and decode LoRa are:

  * LoRa Transceiver
  * Microcontroller with SPI interface
  * Suitable antenna
  * Power

These are some examples of working systems that people have built:

  * AVR + LoRa + 2-line LCD + battery power - see [[http://www.daveakerman.com/?p=1682|this example]]
  * AVR + LoRa + FTDI USB-TTL adapter for connection to a PC/Mac
  * AVR + LoRa + Bluetooth + LiPo - see [[https://twitter.com/daveake/status/514148991760478208|this example]]
  * Raspberry Pi + LoRa - see [[http://www.daveakerman.com/?p=1719|this]]
  * Pi + LoRa + GPS + touchscreen LCD - see [[http://www.daveakerman.com/?p=1905|this]]

Some just show the balloon position; some also upload telemetry/SSDV to the UKHAS servers, and some offer a distance/direction to the balloon or even road navigation.


===== Software =====

Basic software for LoRa can be very simple, since the LoRa modules do the hard work of decoding the radio signals into data.  All that's needed is some code to set the frequency and mode of the LoRa device ("mode" being broadly equivalent to baud rate, USB/LSB etc. for RTTY), test for when a packet has been received, accept that packet and then do something with it.  A simple AVR or PIC processor with SPI interface and a few hundred bytes or so of RAM is enough for this.

Most though, receivers need to be able to upload to the internet, which of course requires some sort of internet connection.  Whilst these exist for microcontrollers, it's easier to use something like a Raspberry Pi that has a LAN interface built-in, or can be used with a USB-connected WLAN device.  The software then needs to be able to decide the type of incoming packet (e.g. telemetry or SSDV or something else) and then upload to the correct server.  The rest of this article explains how to build such a device (a LoRa HAB gateway) using a Raspberry Pi, one or two LoRa modules on a suitable board, an internet connection, and this [[https://github.com/PiInTheSky/lora-gateway|LoRa gateway software]].


===== Gateway - Hardware =====

It's simple to build a gateway using a Pi prototyping board and one or two LoRa modules.  Most LoRa HAB flights use the 434MHz [[https://store.uputronics.com/index.php?route=product/product&path=61&product_id=69|HopeRF RFM98]] but some use the 868Mhz [[https://store.uputronics.com/index.php?route=product/product&path=61&product_id=70|HopeRF RFM95]].  Connections to the Pi are simple:

  * LORA     PI
  * 3.3V    3.3V Power
  * GND     Ground
  * MOSI    MOSI
  * MISO    MISO
  * NSS     CE0 for module 0, CE1 for module 1
  * SCK     SLCK
  * DIO0    Pin 22 (BCM 25, WiringPi 6) for module 0, Pin 36 (BCM 16, Wiring Pi 27) for module 1
  * DIO5    Pin 18 (BCM 24, WiringPi 5) for module 0, Pin 32 (BCM 12, Wiring Pi 26) for module 1

Or you can [[https://store.uputronics.com/index.php?route=product/product&path=61&product_id=68|buy a board designed for the task]].

===== Gateway - Software =====

Install Raspbian on an SD card as usual, and boot the Pi from it.  Then run:

<code>sudo raspi-config</code>

and enable SPI.

If you are using Raspbian Lite (recommended if you are dedicating the Pi to this task so don't need the X desktop) then you need to install git:

<code>sudo apt-get install git</code>

Install WiringPi as follows

<code>cd
git clone git://git.drogon.net/wiringPi 
cd wiringPi
./build</code>

Install SSDV (to decode and store images locally):

<code>cd
git clone https://github.com/fsphil/ssdv.git
cd ssdv
sudo make install</code>

Install these libraries:

<code>sudo apt-get install libcurl4-openssl-dev
sudo apt-get install libncurses5-dev</code>

Finally, install the gateway software itself:

<code>cd
git clone https://github.com/PiInTheSky/lora-gateway.git
cd lora-gateway
make
cp gateway-sample.txt gateway.txt</code>


===== Gateway - Configuration =====

==== System Configuration ====

All configuration items are held in /home/pi/lora-gateway/gateway.txt which you can edit with any text editor (e.g. vim, nano if you're a noob, or emacs if you're a bit weird).  The first part of the file contains general configuration for the installation, which normally you would only need to edit once:

<code>tracker=YOUR_CALLSIGN - Put in whatever you like for the callsign (e.g. your ham radio callsign or IRC nick)
EnableHabitat=Y - Leave this is "Y" for "Yes" to upload telemetry to Habitat.  "N" is useful for payload testing.
EnableSSDV=Y - Leave this is "Y" for "Yes" to upload SSDV to the SSDV server.  "N" is useful for payload testing.
JPGFolder=ssdv - this is the folder (relative to /home/pi/lora-gateway) where SSDV images will be stored.
LogTelemetry=Y - Leave this as "Y" to append telemetry to /home/pi/lora-gateway/telemetry.txt
LogPackets=Y - Leave this as "Y" to append packet information to /home/pi/lora-gateway/packets.txt
CallingTimeout=60 - If the tracked payload uses calling mode, then the gateway will return to original frequency (calling channel) after this number of seconds.
ServerPort=6004 - The program emits JSON tracker telemetry to this port.
Latitude=0.0 - Your position
Longitude=0.0 - Your position
Antenna=Watson W-50 - Your antenna</code>

If your LoRa board has LEDs on it, you may be able to control them using these settings:

<code>NetworkLED=<wiring pi pin>.  Is on if the gateway detects an active network connection
InternetLED=<wiring pi pin>.  Is on if the gateway detects an internet connection
ActivityLED_0=<wiring pi pin>.  Flashes on when a packet is received on LoRa module 0
ActivityLED_1=<wiring pi pin>.  Flashes on when a packet is received on LoRa module 1</code>


==== Channel Configuration ====

The remainder of the file has 2 sections, 1 each for the 2 possible LoRa modules.

Parameters in each of these sections have "_0" or "_1" at the end.  "_0" refers to the module connected to the SPI CE0 pin on the Pi, while "_1" refers to the module connected to the SPI CE1 pin.  The dual-LoRa board mentioned above has large CE0 and CE1 labels so you know which is which.  Obviously, if you have one module but configure the wrong one, it's not going to work.

If you use a board other than the one mentioned earlier, you may need to tell the gateway which Pi pins connect to the DIO0/DIO5 pins on the LoRa modules.  The gateway software assumes, unless told otherwise, that the pins listed above (in the Gateway - Hardware section) are connected; if not then use the DIO0_x= and DIO5_x settings below.

**If your LoRa board is soldered correctly but the software isn't receiving data from the module(s), then these settings are most likely wrong.**

<code>frequency_<n>=<freq in MHz>.  This sets the frequency for LoRa module <n> (0 for first, 1 for second).  e.g. frequency_0=434.450
AFC_<n>=<Y/N>.  Enables or disables automatic frequency control (retunes by the frequency error of last received packet).
mode_<n>=<mode>.  Sets the "mode" for the selected LoRa module.  This offers a simple way of setting the various
                LoRa parameters (SF etc.) in one go.  The modes are:
                0 = (normal for telemetry)  Explicit mode, Error coding 4:8, Bandwidth 20.8kHz, SF 11, Low data rate optimize on
                1 = (normal for SSDV)       Implicit mode, Error coding 4:5, Bandwidth 20.8kHz,  SF 6, Low data rate optimize off
                2 = (normal for repeater)   Explicit mode, Error coding 4:8, Bandwidth 62.5kHz,  SF 8, Low data rate optimize off
                3 = (normal for fast SSDV)  Explicit mode, Error coding 4:6, Bandwidth 250kHz,   SF 7, Low data rate optimize off
                4 = Test mode not for normal use.
                5 = (normal for calling mode)   Explicit mode, Error coding 4:8, Bandwidth 41.7kHz, SF 11, Low data rate optimize off
SF_<n>=<Spreading Factor>  e.g. SF_0=7
Bandwidth_<n>=<Bandwidth>.  e.g. Bandwidth_0=41K7.  Options are 7K8, 10K4, 15K6, 20K8, 31K25, 41K7, 62K5, 125K, 250K, 500K
Implicit_<n>=<Y/N>.  e.g. Implicit_0=Y
Coding_<n>=<error_coding>.  e.g. Coding_0=5 (4:5)
lowopt_<n>=<Y/N>.  Enables or disables low data rate optimization.
power_<n>=<power>.  This is the power setting used for uplinks.  Refer to the LoRa manual for details on setting this.  ** Only set values that are legal in your location (for EU see IR2030) **
UplinkTime_0=<seconds>.  When to send any uplink messages, measured as seconds into each cycle.
UplinkCycle_0=<seconds>.  Cycle time for uplinks.  First cycle starts at 00:00:00.  So for uplink time=2 and cycle=30, any transmissions will start at 2 and 32 seconds after each minute.</code>