# Helium IoT Hotspot Setup Guide A Helium IoT Hotspot transfers data from nearby LoRaWAN devices and earns HNT for that traffic. This guide builds one with a Raspberry Pi and a RAK2287 concentrator on balena. This guide covers all the steps needed to set up a Hotspot using a Raspberry Pi and a RAK concentrator (RAK2287) and the Pi Hat running on balena. This configuration can be achieved by installing the **_gatewayrs_** and **_packet forwarder_** services open sourced by [Nebra](https://github.com/nebraltd) and using balenaOS and [balenaCloud](https://balena.io/). ## Getting started ### Hardware - Raspberry Pi 0/2/3/4 or balenaFin - SD card in case of the Raspberry Pi - [RAK 2287 LoRa concentrator SPI based](https://store.rakwireless.com/products/rak2287-lpwan-gateway-concentrator-module) and [RAK2287 Pi HAT](https://store.rakwireless.com/products/rak2287-pi-hat) **Important**: To use the concentrator module with a Raspberry Pi HAT, you must make sure to order the variation with the SPI interface. ### Software - [balena.io account](https://dashboard.balena-cloud.com/) - [balenaEtcher](https://balena.io/etcher) ## Deploy the code Run this Hotspot with balena.io by deploying it to a balenaCloud application. You can do it in one click by using the button below: Follow the instructions, click `Add a Device` and flash an SD card with that balenaOS image downloaded from balenaCloud. Enjoy the magic 🌟Over-The-Air🌟! Find the [repository with the source code](https://github.com/mpous/helium-data-hotspot) if you would like to clone and deploy from your computer or you would like to contribute. ## Configure the device ### Device Variables Once the device is online on balenaCloud and the services `packet-forwarder` and `gateway-rs` are downloaded and installed, go to `Device Variables`. - Create the variable for all the services `VARIANT` with your hardware definition. During the test is being used a Raspberry Pi 4 with RAK2287 LoRa concentrator and the `VARIANT` is defined `DIY-RAK2287`. This `VARIANT` is compatible with any Raspberry Pi. You can find the list of hardware compatible combinations on [GitHub](https://github.com/NebraLtd/helium-hardware-definitions). - Create the variable for all the services `REGION_OVERRIDE` with your LoRa region (e.g. `EU868`). You can find a list of LoRa regions compatible on [GitHub](https://github.com/NebraLtd/hm-pktfwd). ### Test the Hotspot Once the Device Variables are properly set up, the Hotspot should be running showing some errors on connecting to the network on the balenaCloud Logs. To check that the Hotspot has been generated correctly, go to the `Terminal` and select the `gateway-rs` service, then introduce: `helium_gateway key info` And you will get something like this: `{ "address": , "name": }` At this point, your Hotspot is ready to join the Helium IoT Network. ### Join the Helium IoT Network To join the Helium IoT Network, at the moment only the Helium CLI Wallet can be used. The Helium Wallet App is still not compatible. Follow [these instructions](https://github.com/mpous/helium-data-hotspot/#join-the-helium-blockchain-with-your-data-only-hotspot) to add your Hotspot on the Helium IoT Network. ## Check the Hotspot Now that the Hotspot has been added to the Helium IoT Network it should be visible in the Helium Wallet. If you create a Helium Device, then go to the [Helium Console](https://console.helium.com/) and Inspect packages from your device to confirm that the Hotspot is the one that relays the data from your Devices. You also will be able to see on the balenaCloud logs that UPLINK messages have been relayed to the Helium OUI. ## Manage your gateway_key It's extremely important that at this point, with the Hotspot added on the Helium IoT Network you backup the `gateway_key`. If you lose this key, you will not be able to use this hotspot anymore in case there is a problem on your Hotspot (SD card corrupted, etc.). ### Backup your gateway_key.bin file Follow these instructions to back up your `gateway_key.bin` file of your Hotspot. - Open an SSH session to the "host-os" on balenaCloud Terminal. - Type this command and keep note of the (YOUR INSTANCE)_miner-storage: `ls /var/lib/docker/volumes`. - Type this command to get a link to download the gateway key (note to replace the YOUR INSTANCE part with the container number that you got from the previous command). `curl -F "file=@/var/lib/docker/volumes/(YOUR INSTANCE)_miner-storage/_data#/gateway_key.bin" https://file.io` - Use the outputted file.io link to securely download your swarm key. The link only works **one** time. ### Restore your gateway_key.bin file on your new file Follow these instructions to restore your `gateway_key.bin` key into your new hotspot. - Open an SSH session to the "host-os" on balenaCloud Terminal. - Type this command and keep note of the (YOUR INSTANCE)_miner-storage information: `ls /var/lib/docker/volumes`. - Navigate to where the swarm_key is stored `cd /var/lib/docker/volumes/(YOUR INSTANCE)_miner-storage/_data#/`. - Remove the original `gateway_key.bin` file `rm gateway_key.bin`. - Reboot miner and you will see it restored and working. - Upload your `gateway_key.bin` that you wish to restore onto file.io and do `curl -LJO [FILE.IO UPLOAD LINK]`. ## Contributions Thank you to Nebra for developing and balenifying the Helium Hotspot, Helium developers community, Jose from RAK, Travis and Joseph from balena to work on the dbus + conman issues.