Skip to main content

Build a Packet Forwarder

This page has not been fully updated to represent the latest state of the Helium Network following the migration to Solana on April 18, 2023.
warning

The ability to earn from Proof of Coverage with anything other than a Full Hotspot is not supported.

Building your own packet forwarder enables Data transfer rewards only, if and only if you complete the setup process here.

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!

This guide is experimental and for advanced users only, and you may run into various issues trying to get this working.

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. Once the sync command returns, you can eject and remove the SD card from your system.

Preparing RaspiOS​

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: sudo raspi-config

Select Interface Options, and enable I2C and 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
$ make

Next, go into 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 ~/sx1302_hal/packet_forwarder try:

$ ./lora_pkt_fwd

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.