Data Only Hotspot Setup with Dragino PG1301 and Raspberry Pi

A Data Only Hotspot is a type of Hotspot that participates on the Helium Network by transferring data from the end devices (LoRaWAN nodes). The Data Only Hotspots are eligible for Network Data Transfer Rewards but not Proof of Coverage Rewards.

This guide covers all the steps needed to set up a Data Only Hotspot using a Raspberry Pi and Dragino PG1301 hat.

warning

Data Only Hotspots cannot earn $HNT, at least for now, and after milestone 2 they will earn $HNT only for Device Packet Transfer. Remember to keep an eye on Light Hotspots - BETA and the #gateway-development channel on the Helium Discord Server to check how the development process evolves.

Getting started

This process assumes you have some basic Linux skills, can use a text editor and understand what a service is. You should be able to use programs like scp to move data between the Raspberry Pi and other computers on your network.

What we will be doing is :

installing the LoRa Packet Forwarder service from Dragino to use the Concentrator hat
installing the Helium Gateway service to move data between the packet forwarder and the Helium network
configure everything
verify everything is working

Hardware

Raspberry Pi 4. Other faimilies of Pi may work, but this has only been tested on the Pi 4 Model B.
Dragino 10 channels - LoRaWAN GPS Concentrator for Raspberry Pi

Software

We will be using the following:

Fresh Raspbian Buster image
lorapktfwd package from Dragino Downloads Site
Latest helium-gateway package release from Helium ending in --raspi234.deb

Configure the Raspberry Pi

Use the Raspberry Pi Configuration application and enable the SPI kernel module in the Interface Options section. This is located in the GUI from the Applications Menu under Preferences
Reboot to apply the changes

If you haven't done so, attach the Dragino PG1301 to the Raspberry Pi with the power off, attach the antenna, then power on.

Install the LoRa Packet Forwarder Service

Open the web browser and download lorapktfwd_v1.1.deb from the Dragino Downloads Site
Open a terminal window and install the package using dpkg
```
sudo dpkg -i lorapktfwd_v1.1.deb
```
Verify lorapktfwd is running using systemctl
```
sudo systemctl status lorapktfwd
```

Example:

pi@raspberrypi:~ $ cd Downloads
pi@raspberrypi:~/Downloads $ sudo dpkg -i lorapktfwd_v1.1.deb
Selecting previously unselected package lorapktfwd.
(Reading database ... 98868 files and directories currently installed.)
Preparing to unpack lorapktfwd_v1.1.deb ...
Unpacking lorapktfwd (1) ...
Setting up lorapktfwd (1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/lorapktfwd.service → /lib/systemd/system/lorapktfwd.service.
pi@raspberrypi:~/Downloads $
pi@raspberrypi:~/Downloads $ sudo systemctl status lorapktfwd
  lorapktfwd.service - packet forwarder
   Loaded: loaded (/lib/systemd/system/lorapktfwd.service; enabled; vendor preset: enabled)
   Active: active (running) since Wed 2021-10-06 10:58:26 EDT; 5min ago
 Main PID: 1443 (lora_pkt_fwd)
    Tasks: 5 (limit: 4915)
   CGroup: /system.slice/lorapktfwd.service
           └─1443 /usr/bin/lora_pkt_fwd

Oct 06 11:03:29 raspberrypi lora_pkt_fwd[1443]: REPORT~ ### [DOWNSTREAM] ###
Oct 06 11:03:29 raspberrypi lora_pkt_fwd[1443]: REPORT~ # PULL_DATA sent: 3 (0.00% acknowledged)
Oct 06 11:03:29 raspberrypi lora_pkt_fwd[1443]: REPORT~ # PULL_RESP(onse) datagrams received: 0 (0 bytes)
Oct 06 11:03:29 raspberrypi lora_pkt_fwd[1443]: REPORT~ # RF packets sent to concentrator: 0 (0 bytes)
Oct 06 11:03:29 raspberrypi lora_pkt_fwd[1443]: REPORT~ # TX errors: 0
Oct 06 11:03:29 raspberrypi lora_pkt_fwd[1443]: REPORT~ # BEACON queued: 0
Oct 06 11:03:29 raspberrypi lora_pkt_fwd[1443]: REPORT~ # BEACON sent so far: 0
Oct 06 11:03:29 raspberrypi lora_pkt_fwd[1443]: REPORT~ # BEACON rejected: 0
Oct 06 11:03:29 raspberrypi lora_pkt_fwd[1443]: REPORT~ ### [PPS] ###
Oct 06 11:03:29 raspberrypi lora_pkt_fwd[1443]: REPORT~ # SX1301 time (PPS): 302479992
pi@raspberrypi:~/Downloads $

Install the Helium Gateway Service

Download the latest helium-gateway release package from https://github.com/helium/gateway-rs/releases ending in -raspi234.deb
Install the package
```
sudo dpkg -i helium-gateway-v1.0.0-alpha.18-raspi234.deb
```
Replace helium-gateway-v1.0.0-alpha.18-raspi234.deb with the version you downloaded.
Verify the gateway is running
```
sudo systemctl status helium_gateway
```

Example:

pi@raspberrypi:~/Downloads $ sudo dpkg -i helium-gateway-v1.0.0-alpha.18-raspi234.deb
Selecting previously unselected package helium_gateway.
(Reading database ... 98957 files and directories currently installed.)
Preparing to unpack helium-gateway-v1.0.0-alpha.18-raspi234.deb ...
Unpacking helium_gateway (1.0.0~alpha.18) ...
Setting up helium_gateway (1.0.0~alpha.18) ...
Created symlink /etc/systemd/system/multi-user.target.wants/helium_gateway.service → /lib/systemd/system/helium_gateway.service.
pi@raspberrypi:~/Downloads $
pi@raspberrypi:~/Downloads $ sudo systemctl status helium_gateway
  helium_gateway.service - Helium Gateway
   Loaded: loaded (/lib/systemd/system/helium_gateway.service; enabled; vendor preset: enabled)
   Active: active (running) since Wed 2021-10-06 11:51:03 EDT; 35s ago
 Main PID: 2121 (helium_gateway)
    Tasks: 2 (limit: 4915)
   CGroup: /system.slice/helium_gateway.service
           └─2121 /usr/bin/helium_gateway -c /etc/helium_gateway server

Oct 06 11:51:03 raspberrypi helium_gateway[2121]: updated routing to height 1042530, module: dispatcher
Oct 06 11:51:03 raspberrypi helium_gateway[2121]: starting, oui: 13, uri: http://46.246.38.248:8080/, public_key: 115ZS5of9wsV3M5sH3mePp9NVnKayUXG7qT2W7Sn4KJLMzd3eMr, module: router
Oct 06 11:51:03 raspberrypi helium_gateway[2121]: starting, oui: 12, uri: http://54.219.236.122:8080/, public_key: 112ewJNEUfSg3Jvo276tMjzFC2JzmmZcJJ32CWz2fzYqbyCMMTe1, module: rout
Oct 06 11:51:03 raspberrypi helium_gateway[2121]: starting, oui: 9, uri: http://13.37.13.24:8080/, public_key: 11afuQSrmk52mgxLu91AdtDXbJ9wmqWBUxC3hvjejoXkxEZfPvY, module: router
Oct 06 11:51:03 raspberrypi helium_gateway[2121]: starting, oui: 9, uri: http://44.238.156.97:8080/, public_key: 11w77YQLhgUt8HUJrMtntGGr97RyXmot1ofs5Ct2ELTmbFoYsQa, module: router
Oct 06 11:51:03 raspberrypi helium_gateway[2121]: starting, oui: 6, uri: http://185.34.141.6:8080/, public_key: 11awcuSbVURPkXX3FbKC7KF6bgEPRZqqPzv1FTEYABMLttUr13E, module: router
Oct 06 11:51:03 raspberrypi helium_gateway[2121]: starting, oui: 4, uri: http://54.193.165.228:8080/, public_key: 11263KvqW3GZPAvag5sQYtBJSjb25azSTSwoi5Tza9kboaLRxcsv, module: route
Oct 06 11:51:03 raspberrypi helium_gateway[2121]: starting, oui: 2, uri: http://54.176.88.149:8080/, public_key: 1124CJ9yJaHq4D6ugyPCDnSBzQik61C1BqD9VMh1vsUmjwt16HNB, module: router
Oct 06 11:51:03 raspberrypi helium_gateway[2121]: starting, oui: 1, uri: http://52.8.80.146:8080/, public_key: 112qB3YaH5bZkCnKA5uRH7tBtGNv2Y5B4smv1jsmvGUzgKT71QpE, module: router
Oct 06 11:51:04 raspberrypi helium_gateway[2121]: no update found, module: updater
pi@raspberrypi:~/Downloads $

Configure the LoRa Packet Forwarder

These steps assume the US915 region. For other regions, replace with your region locale configuration in Step 2.

Change directory to the /etc/lora-gateway directory
```
cd /etc/lora-gateway
```
Copy the US915 Band 2 configuration from the cfg subdirectory as global_conf.json
```
cp cfg/dragino/global_conf.us915_1.json global_conf.json
```
Generate a unique gateway ID based on the MAC address of one of your network interface(s). Use the following bash syntax to help create one.
```
echo `ip a | grep 'link/ether' | cut -d ' ' -f 6 | sed 's/://g'` | tr a-z A-Z
```
This command will generate you one or more unique values you can use for the gateway EUI.

In the below example, you see two values (DCA6328XXX6F and DCA6328XXX70) because there is an active wired and wireless interface on the Raspberry Pi. It doesn't matter which one you use, as all MAC addresses are globally unique.

The goal here is to guarantee a unique gateway ID in the network.

pi@raspberrypi:~/Downloads $ cd /etc/lora-gateway/
pi@raspberrypi:/etc/lora-gateway $ cp cfg/dragino/global_conf.us915_1.json global_conf.json
pi@raspberrypi:/etc/lora-gateway $ echo `ip a | grep 'link/ether' | cut -d ' ' -f 6 | sed 's/://g'` | tr a-z A-Z
DCA6328XXX6F DCA6328XXX70
pi@raspberrypi:/etc/lora-gateway $

In the next step we will be using the DCA6328XXX70 value as an example. Do not use the example value from this documentation, it will not work.

Point the LoRa Packet Forwarder to the Helium Gateway

By default the LoRa Packet Forwarder from Dragino is configured to work with the Things Network. Here we will configure it to talk to the Helium gateway you installed on the Raspberry Pi.

Use a text editor and open the /etc/lora-gateway/local_conf.json file
Replace the current value for gateway_ID with (one of) the values generated in the previous step and append the value FFFF to the end. The reason we append FFFF to the end is the gateway ID is required to be 16 characters, and the unique MAC address generated is only 12. Again, this guarantees your gateway ID will be unique in the network.
Add the server_address key with the value 127.0.0.1
Add the serv_port_up key with the value 1680
Add the serv_port_down key with the value 1680

You should have something that resembles the following in your /etc/lora-gateway/local_conf.json file. Be sure to double check the JSON syntax and have the key/values separated by commas and the {} characters match up.

   {
     "gateway_conf": {
          "gateway_ID": "DCA6328XXX70FFFF",
          "server_address": "127.0.0.1",
          "serv_port_up": 1680,
          "serv_port_down": 1680
     }
   }

For reference, the server address being used is the local machine (127.0.0.1, also called localhost) and port 1680 is the port the helium service is communicating on. Don't use the value assigned by your router or the public IP address.

When you are finished make sure to save and exit the file.

Configure the Helium Gateway Region

The default region of the helium_gateway service is US915, so you can continue with the next section if you are using this one. Otherwise, you must set your region frequency in /etc/helium_gateway/settings.toml. Add the following line at the beginning of the file:

region = "<region>"

Possible values are:

US915 | EU868 | EU433 | CN470 | CN779 | AU915 | AS923_1 | AS923_2 | AS923_3 | AS923_4 | KR920 | IN865

For instance, if your region is EU868 the content in settings.toml must be.

region = "EU868"

[log]
method = "syslog"
level = "info"
timestamp = false

[update]
platform = "raspi234"

Activate The Changes

Now, reboot the Raspberry Pi to restart the services and verify that everything starts at boot time and is working.

Post-Reboot Checks

You can view the log file of the LoRa Packet Forwarder by opening a terminal window and running
```
journalctl -u lorapktfwd
```
You can view the log file of the Helium Gateway by opening another terminal window and running
```
journalctl -u helium_gateway
```

Use the spacebar to scroll thru the logs, and Ctrl-C to get back to the command prompt.

Congradulations, your LoRa Packet Forwarder and Helium Gateway service is setup! At this point your LoRa radio will be able to pass radio traffic between the network and the Helium gateway. Any devices you registered via the Helium console should now be live. Your hotspot will not appear on the map. Before adding your hotspot to the blockchain, please check and backup your configuration.

Check and Backup your Configuration

To view your gateway address and unique animal name assigned to you

helium_gateway key info

Example:

$ helium_gateway key info
{
"address": "13XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"name": "unique-animal-name"
}

Backup your gateway key to another machine/media for recovery purposes. The file /etc/helium_gateway/gateway_key.bin contains the key.

warning

If you lose this key, you will not be able to use this hotspot anymore in case there is a problem on your hostpot (SD card corrupted, etc). You will need to generate a new key and lose your existing animal name/hostpot configuration

Testing the packet transfer with an end device

If you have an end device (LoRaWAN node), you can check if the hotspot can transfer packets through the network. In other words, you can check if the devices can send data to the Helium Console. The Helium Console is where you can provision and manage the end devices, so the nodes need to be registered to start using the network.

Some comments and recommendations about the Helium Console

At least for now, it is recommended to use the staging console instead of the production one when we are transferring data through Data Only hotspots. You can differentiate them for the URL they use, console.helium.com for production, and staging-console.helium.wtf for staging. Don't be surprised if you find some differences between those console flavors, basically staging is where the new features are tested before their rollout to production.

important

If the device you will use for testing is registered on the production console, it's better to delete it from there to avoid any unexpected behavior.

To register your end device on the console, you can follow the steps described on Adding Devices.

What's next?

At this point, after you verified your Data Only Hotspot is working, it is ready to be added to the blockchain! You can find more information about that process here.