HamShield: LoRa Edition on Raspberry Pi

HamShield: LoRa Edition is a powerful addition to the Raspberry Pi. However, the setup process is not exactly straight forward when you look on the web. Don't sweat though, we wrote an easy-to-use guide to help you along.

Prepping HamShield: LoRa Edition 

Instead of soldering up the typical Arduino Uno header, you will want to place a female 2x20 (40 pin) header on the HamShield. You will want this header facing down with the tin can module on the top. This way, you can press the HamShield directly on the Raspbery Pi. 

You can use any modern Raspberry Pi, including Pi Zero W or the traditional Raspberry Pis. For low cost installations, and lower power consumption, we recommend the Raspberry Pi Zero WH (which we carry in our store).

Alternatively, if you want to permanently attach the HamShield: LoRa Edition to a Raspberry Pi, you can simply solder the Raspberry Pi headers directly into the HamShield, like we did. While you can press them together for a tight fit (incidentally, this will make no electrical contact between the components on both boards), you may want to put in some spacers so you can connect up HDMI and USB for diagnostic purposes.

If you are going to place your Raspberry Pi in a remote location (ie: roof top, tower top, etc), you will probably want to do one of the following:

  • Use an outdoor rated DC power cable with a higher voltage (ie: 12V) and regulate voltage once it reaches your Raspberry Pi. We suggest using a Raspberry Pi car power supply for this
  • Connect up a solar panel with ample wattage and use a charge controller with a deep cycle battery
  • Use a 5V panel with solar energy harvester, booster, and lithium battery charger

Installing Raspberry Pi Software

Find a microSD card of at least 4GB (8GB recommended) and download the latest Raspbian Lite image available. At the time of writing, we used Raspbian Buster Lite. This version does not contain the desktop and has a minimal installation of software, making it useful for embedded applications such as this one.

https://www.raspberrypi.org/downloads/raspbian/

You will want to unzip this package somewhere so you have the .img file.

You will also need a way to write the image file to the SD card. A great way to do this is Etcher. It runs on Windows, Mac, and Linux. You can download this free tool here: https://www.balena.io/etcher/

After installing Etcher, run the program and select the image file we downloaded (should end in .img). Select the SD card in your computer by clicking Select Target, and then click Flash! ... this will take a while so be patient. Ignore any warning dialogs as these are typical.

Windows Note: Once the flashing is complete, the disk will mount again, and will ask if you wish to format the disk. Do not click this as this will format your new image with a blank windows formatted partition!

Configuring Your Pi

You can actually do quite a bit of configuration by modifying the contents of the SD card. This way you won't have to connect a keyboard to your Raspberry Pi. Simply look for the Boot disk and open up config.txt in Notepad or TextEdit (depending on your computer).

Inside config.txt, remove the # from dtparam=spi=on -- this will enable SPI on boot, so we can talk to HamShield: LoRa Edition.

Next, create a blank text file called ssh. You don't need anything in this file. This tells the Raspberry Pi to start ssh on boot.

Lastly, you will want to configure your WiFi. Create a text file called wpa_supplicant.conf with the exact contents, but make sure you change your WiFi name and password to your own:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
network={
    ssid="YOUR_NETWORK"
    psk="YOUR_PASSWORD"
    key_mgmt=WPA-PSK
}

 

Connect It All Up

Connect the HamShield: LoRa Edition to the raspberry pi and insert the SD card you just programmed. Connect power. Optionally, you can connect HDMI video and a usb keyboard. If you ordered our starter kit for Raspberry Pi, these two items come included. Make sure you connect the micro USB cable to something that can source ample amount of power. While they advise a 2 amp power supply, we have gotten away with using one of the USB ports on our PlayStation, TV or computer USB. 

 

Once it is booted, you can either look on your screen or connect to your router and look for "raspberry-pi". This is the IP address of the Raspberry Pi.

 

Optional: While optional, you can type in ifconfig and add the mac address for wlan0 to your router's DHCP static addresses. This way, your Raspberry Pi always is given a predictable address.

Switch to a Different Computer to Finish the Install

Go to another computer with ssh.

If its Windows 10, click "type here to search" and type in powershell. This is a linux-like command line that is built into all modern versions of windows. You can also install applications such as putty. 

If it is Mac OSX, ssh is also built in. Click the spotlight (magnifying glass) and type in terminal.

For both Windows 10 and OSX, the command to access the Raspberry Pi is the same. Type:

ssh pi@xx.xx.xx.xx (replace the xx's with the IP address of the Pi)

after a short delay, you will see a password prompt. Type in raspberry.

Note: Raspberry Pi uses a very insecure default password that should be changed, depending on who has access to our WiFi network and how paranoid you are of malicious activity. You can use passwd to change your password if you wish.

Since the Lite version is, well, light, we will need to install some basic software. Type each of these commands, one after another, until all of the installations are complete. Since the library requires Python 3, we will be using pip3.

sudo apt-get install python-pip python3-pip

sudo apt-get install python-dev python3-dev

pip3 install RPi.GPIO

pip3 install spidev

pip3 install pyLoRa

For amateur radio use, we do not use the encryption components of LoRa libraries. However, it may be used in the future for signing messages to prevent malicious attacks and check message integrity, which is permitted per FCC.

Editing Configuration File

The board configuration file is really annoying to edit, but you can typically find it here: /home/pi/.local/lib/python2.7/site-packages/SX127x/board_config.py

You can edit it by typing:

nano /home/pi/.local/lib/python2.7/site-packages/SX127x/board_config.py

Arrow down until you see class BOARD:

You will want to change the values to the following:

DIO0 = 6 # RaspPi GPIO 6
DIO1 = 17 # RaspPi GPIO 17
DIO2 = 18 # RaspPi GPIO 18
DIO3 = 27 # RaspPi GPIO 27
RST = 5 # RaspPi GPIO 5
LED = 13 # RaspPi GPIO 13 connects to the LED and a resistor (1kohm or 330ohm)

We don't make use of the LED, for DIO1-3, so those can remain the same.

Hit control-o, enter and then control-x

Running The Example

You are now ready to run your first example. 

Type in nano loratest.py and enter this into the text editor:

from SX127x.LoRa import *
from SX127x.board_config import BOARD
BOARD.setup()
lora = LoRa()
lora.set_mode(MODE.STDBY)
print lora.get_version() # this prints the sx127x chip version
print lora.get_freq() # this prints the frequency setting

Hit control-o to write the file, enter and control-x to exit.

Type in python3 loratest.py. You should get the following output:

pi@raspberrypi:~ $ python loratest.py
Mode <- SLEEP
Mode <- FSK_STDBY
Mode <- SLEEP
Mode <- STDBY
18
434.0

Your HamShield: LoRa Edition is now working with Raspberry Pi! If you get an error message such as:

pi@raspberrypi:~ $ python loratest.py
Traceback (most recent call last):
File "loratest.py", line 1, in <module>
from SX127x.LoRa import *
File "/home/pi/.local/lib/python2.7/site-packages/SX127x/LoRa.py", line 77, in <module>
class LoRa(object):
File "/home/pi/.local/lib/python2.7/site-packages/SX127x/LoRa.py", line 79, in LoRa
spi = BOARD.SpiDev() # init and get the baord's SPI
File "/home/pi/.local/lib/python2.7/site-packages/SX127x/board_config.py", line 90, in SpiDev
BOARD.spi.open(spi_bus, spi_cs)
IOError: [Errno 2] No such file or directory

It is likely that your config.txt file did not instruct the Raspberry Pi to start the SPI overlay. You can type this command to get it working instead:  sudo raspi-config noninit do_spi 0