Build a Packet Forwarder
Packet Forwarder Architecture
To be a Helium Hotspot, there are three principal components to know about:
- Packet Forwarder: this is a utility that interacts with the radio front-end and sends and receives raw radio packets with the Helium Miner.
- Hotspot Client: the Helium blockchain comes into the picture here; the hotspot client is responsible for routing packets to the appropriate Router entering into microtransactions brokered via gRPC.
- Router: a Helium compatible LoRaWAN Network Server ("LNS"); this component is interested in receiving the packets relating to its devices and handles downlink responses when appropriate.
Any device that can run an 8 channel LoRa front-end (such as SX1301 or SX1302) can be used to participate in the Helium Network. The Hotspot Client is designed to send and receive packets using the Semtech GateWay Messaging Protocol (GWMP), making it compatible with almost every LoRaWAN Gateway on the Market.
Many off-the-shelf LoRaWAN Gateways work very well and using one of them gives you one less thing to worry about as the Packet Forwarder is set up and ready to go.
This guide, however, is for those that want a more hands-on experience. We will essentially be assembling a LoRaWAN Gateway with discrete parts, loading up an open-source Linux distribution, compiling the Packet Forwarder, and running it all ourselves. In short, we'll be learning Gateways that hard way!
Example Custom Hardware
If you don’t have your own hardware yet, we recommend using a Raspberry Pi 4B running the latest 64-bit RaspiOS image.
We recommend this configuration in particular if you are interested in running the Hotspot on the Gateway itself; it's easy to run our Docker image from Quay on a 64-bit ARM system. If you choose to run the Hotspot elsewhere, it's possible to downgrade all the way to a Pi0, for example, since you will only be running the Packet Forwarder on the Gateway.
RAKwireless sells multiple "PiHats" that provide the 8-channel front-end:
Or you can check out their WisGate Developer line where they provide bundles:
- the D4H/D4H+/D4HP are all based on the RAK2287
Ultimately, which configuration works for you depends on your situation, but all of them will work with this guide with little adjustment.
Preparing the SD Card
You can create an SD card from this image by looking for the recently inserted SD card in your system.
$ ls -al /dev | grep sd
Generally, the timestamp is enough to indicate which device is the SD card. Next, write the image to the SD card. For example:
dd if=~/2020-08-20-raspios-buster-arm64.img of=/dev/sdX bs=1M
Use the command
sync to make sure the filesystem is written before trying to remove the SD card.
sync command returns, you can eject and remove the SD card from your system.
With a keyboard, mouse, and monitor plugged in, power on the Raspberry Pi. Proceed through the guided RaspiOS setup where you will update your password, configure your Wi-Fi, etc.
Enable SPI and I2C using the raspi-config tool:
Interface Options, and enable
SPI from within the menu system. This is also a
good time to enable SSH if you want it.
Installing the Semtech Packet Forwarder
Depending on which SX130x radio you are running, you will want to select the appropriate Packet Forwarder application.
Packet Forwarder SX1302
Pull down Helium's fork of the SX1302 Packet Forwarder:
$ git clone https://github.com/helium/sx1302_hal.git
Go into the directory and build:
$ cd sx1302_hal
Next, go into the the packet_forwarder directory, where we will create a link to the reset script:
$ cd packet_forwarder
$ ln -s ../tools/reset_lgw.sh reset_lgw.sh
We will also create a link to the appropriate regional configuration. For example:
$ ln -s global_conf.json.sx1250.US915 global_conf.json
We are now ready to test the start-up. From
If you get the following output, you are good to go:
INFO: [main] concentrator started, packet can now be received
INFO: concentrator EUI: 0x????????????????
You are now ready to set up the Hotspot client.