This is a python interface to the Semtech SX127x long range, low power transceiver family.

The SX127x has both LoRa and FSK capabilities. Here the focus lies on the LoRa spread spectrum modulation hence only the LoRa modem interface is implemented so far (but see the roadmap below for future plans).

Spread spectrum modulation has a number of intriguing features:

• High interference immunity
• Up to 20dBm link budget advantage (for the SX1276/7/8/9)
• High Doppler shift immunity

More information about LoRa can be found on the LoRa Alliance website. Links to some LoRa performance reports can be found in the references section below.

Primary difference from mayeranalytics version is I've modified the hardware interface layer to be an object passed to the LoRa library on instantiation. This makes writing portable code (hopefully) a little easier.

Currently I'm targeting:

• PiLoraGateway RPi2 shield, from Hab Supplies.
• Custom LoRa shields for Arduino's running some SPI-UART bridge firmware (see arduino/spibridge) Both of which have RFM98W modules, which have a re-branded Semtech SX1276 IC.

Currently both of these shields only have DIO0 and DIO5 wired up, so the IO configuration in the LoRa module needs to be changed when switching beween TX and RX.

First import the modules

from SX127x.LoRa import *
# <hardwaretype> can be either piloragateway or spibridge
from SX127x.hardware_<hardwaretype> import HardwareInterface

then set up the board GPIOs

hw = HardwareInterface()

The LoRa object is instantiated and put into the standby mode

lora = LoRa(hw)
lora.set_mode(MODE.STDBY)

Registers are queried like so:

print lora.version()        # this prints the sx127x chip version
print lora.get_freq()       # this prints the frequency setting 

and setting registers is easy, too

lora.set_freq(433.0)       # Set the frequency to 433 MHz 

In applications the LoRa class should be subclassed while overriding one or more of the callback functions that are invoked on successful RX or TX operations, for example.

class MyLoRa(LoRa):

  def __init__(self, verbose=False):
    super(MyLoRa, self).__init__(verbose)
    # setup registers etc.

  def on_rx_done(self):
    payload = self.read_payload(nocheck=True) 
    # etc.

In the end the resources should be freed properly

hw.teardown()

Most functions of SX127x.Lora are setter and getter functions. For example, the setter and getter for the coding rate are demonstrated here

print lora.get_coding_rate()                # print the current coding rate
lora.set_coding_rate(CODING_RATE.CR4_6)     # set it to CR4_6

@todo

Make sure SPI is activated on you RaspberryPi: SPI pySX127x requires these two python packages:

• RPi.GPIO for accessing the GPIOs, it should be already installed on a standard Raspian Linux image
• spidev for controlling SPI

In order to install spidev download the source code and run setup.py manually:

wget https://pypi.python.org/packages/source/s/spidev/spidev-3.1.tar.gz
tar xfvz  spidev-3.1.tar.gz
cd spidev-3.1
sudo python setup.py install

At this point you may want to confirm that the unit tests pass. See the section Tests below.

You can now run the scripts. For example dump the registers with lora_util.py:

rasp$ sudo ./lora_util.py
SX127x LoRa registers:
 mode               SLEEP
 freq               434.000000 MHz
 coding_rate        CR4_5
 bw                 BW125
 spreading_factor   128 chips/symb
 implicit_hdr_mode  OFF
 ... and so on ....

The interface to the SX127x LoRa modem is implemented in the class SX127x.LoRa.LoRa. The most important modem configuration parameters are:

Most set_* functions have a mirror get_* function, but beware that the getter return types do not necessarily match the setter input types.

The register addresses are defined in class SX127x.constants.REG and we use a specific naming convention which is best illustrated by a few examples:

Hardware related definition and initialisation are located in SX127x.board_config.BOARD. If you use a SBC other than the Raspberry Pi you'll have to adapt the BOARD class.

The SX127x is put in RXCONT mode and continuously waits for transmissions. Upon a successful read the payload and the irq flags are printed to screen.

usage: rx_cont.py [-h] [--ocp OCP] [--sf SF] [--freq FREQ] [--bw BW]
                  [--cr CODING_RATE] [--preamble PREAMBLE]

Continous LoRa receiver

optional arguments:
  -h, --help            show this help message and exit
  --ocp OCP, -c OCP     Over current protection in mA (45 .. 240 mA)
  --sf SF, -s SF        Spreading factor (6...12). Default is 7.
  --freq FREQ, -f FREQ  Frequency
  --bw BW, -b BW        Bandwidth (one of BW7_8 BW10_4 BW15_6 BW20_8 BW31_25
                        BW41_7 BW62_5 BW125 BW250 BW500). Default is BW125.
  --cr CODING_RATE, -r CODING_RATE
                        Coding rate (one of CR4_5 CR4_6 CR4_7 CR4_8). Default
                        is CR4_5.
  --preamble PREAMBLE, -p PREAMBLE
                        Preamble length. Default is 8.

A small payload is transmitted in regular intervals.

usage: tx_beacon.py [-h] [--ocp OCP] [--sf SF] [--freq FREQ] [--bw BW]
                    [--cr CODING_RATE] [--preamble PREAMBLE] [--single]
                    [--wait WAIT]

A simple LoRa beacon

optional arguments:
  -h, --help            show this help message and exit
  --ocp OCP, -c OCP     Over current protection in mA (45 .. 240 mA)
  --sf SF, -s SF        Spreading factor (6...12). Default is 7.
  --freq FREQ, -f FREQ  Frequency
  --bw BW, -b BW        Bandwidth (one of BW7_8 BW10_4 BW15_6 BW20_8 BW31_25
                        BW41_7 BW62_5 BW125 BW250 BW500). Default is BW125.
  --cr CODING_RATE, -r CODING_RATE
                        Coding rate (one of CR4_5 CR4_6 CR4_7 CR4_8). Default
                        is CR4_5.
  --preamble PREAMBLE, -p PREAMBLE
                        Preamble length. Default is 8.
  --single, -S          Single transmission
  --wait WAIT, -w WAIT  Waiting time between transmissions (default is 0s)

Execute test_lora.py to run a few unit tests.

Please feel free to comment, report issues, or contribute!

Contact me via my company website Mayer Analytics and my private blog mcmayer.net.

Follow me on twitter @markuscmayer and @mayeranalytics.

pySX127x is still in the development phase. The current version is 0.1.

95% of functions for the Sx127x LoRa capabilities are implemented. Functions will be added when necessary. The test coverage is rather low but we intend to change that soon.

It turns out the HopeRF has a family of LoRa capable transceiver chips RFM92/95/96/98 that have identical or almost identical SPI interface as the Semtech SX127x family.

The pySX127x project will therefore be renamed to pyLoRa at some point.

• Semtech SX1276/77/78/79 - 137 MHz to 1020 MHz Low Power Long Range Transceiver
• Modtronix inAir9
• Spidev Documentation
• Make: Tutorial: Raspberry Pi GPIO Pins and Python

• Extreme Range Links: LoRa 868 / 900MHz SX1272 LoRa module for Arduino, Raspberry Pi and Intel Galileo
• UK LoRa versus FSK - 40km LoS (Line of Sight) test!

• An Introduction to Spread Spectrum Techniques
• Theory of Spread-Spectrum Communications-A Tutorial (technical paper)

© 2015 Mayer Analytics Ltd., All Rights Reserved.

The license is GNU AGPL.

pySX127x is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

pySX127x is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You can be released from the requirements of the license by obtaining a commercial license. Such a license is mandatory as soon as you develop commercial activities involving pySX127x without disclosing the source code of your own applications, or shipping pySX127x with a closed source product.

You should have received a copy of the GNU General Public License along with pySX127. If not, see http://www.gnu.org/licenses/.