dantegpt / helium_docs

Documentation for DIY helium hotspots

Building a Development Hotspot

---

(the unofficial guide)

---

---

Prelude:

This is based off of conversations with a number of Helium employees who graciously contributed their time to work with me on getting the process of onboarding a DIY hotspot to the Helium network down on paper. If something is off-base, or doesn't work on your setup, please lemme know, and I will try to get the docs rectified.

Toward the end of this guide, you will see something about resetting your concentrator... this is dependent on what hardware you are using, and should be the only part of the guide that is variable. I welcome reset scripts for whatever setup you are using.

The reset2245.sh script included in this repo may be called as follows:

./reset2245.sh start 17

Thanks, folks!

-Travis

This guide walks through the steps required to build a Development Hotspot that can send and receive packets over the wireless network, but not perform any blockchain mining functions.

---

Download Raspbian Lite from https://www.raspberrypi.org/downloads/raspbian/

Current tested release is:

Raspbian Buster Lite
====================
Minimal image based on Debian Buster
Version:September 2019
Release date:2019-09-26
Kernel version:4.19
Size:435 MB

Using balena etcher (or whatever SD flashing tool you prefer), burn the Buster Lite image to a Micro SD card (64GB recommended, and remember, faster is better. Test your cards, kids!)

https://www.balena.io/etcher/

Once that completes without errors, we need to do a couple things. Etcher should have unmounted your card, so go ahead and eject that and reinsert. You will most likely see a series of popups from the OS telling you that you need to format/it can't read/etc... Close these all down.

If you are using Windows, you should see a "boot" partition that has auto-mounted.

Goto this partition and create a txt file with the following name (and no ".txt" extension):

ssh

We now need to create another txt file with the following name "wpa_supplicant.conf"

Good. Now, in order to add the contents to this new file (that will allow us to connect to your local wifi network), we need to edit it with a program that does line-endings correctly (read: not notepad)

VS Code works well for this, as do many others.

Open the newly created config file, and enter the following (replacing the obvious):

country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
    ssid="your_real_wifi_ssid"
    psk="your_real_password"
}

There are mechanisms to conceal the plaintext password here (search NTLM password hash), but that's outside the doc scope.

Alright... save that file down, and eject the card.

Now, understand that the two files we just created are only valid for the next boot, so make sure you have a decent power supply for the RPi (2.5A or better preferred), ensure your antenna is connected to your concentrator (and is sexed correctly), and power the thing up.

Give it just a bit to boot, then use an application such as "fing" https://www.fing.com/products/fing-app to discover the new device's IP address.

SIDENOTE:

If you are on a Windows box and would like to have read/write access to volumes on the SD card not natively available to you, there is a commercial utility available. They have a trial, but even afterwards, you may use it at a reduced data rate (which works for any purposes we have here) *insert standard "I don't have anything to do w/ them disclaimer here

https://www.paragon-software.com/home/linuxfs-windows/

This will allow you to access the rootfs partition:

And edit the wpa_supplicant.conf file

At this point, we should have the IP of the new RPi install, and can SSH in with the access we established.

Using Putty (or any other client you prefer) https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html ,

Connect to the RPi  on the IP address we located above (in the case of this example, 192.168.0.120)

Accept the message:

And enter "raspberry" for the password

The default Raspian image has a small swapfile of 100MB, which on a Pi with 1GB or less of RAM is insufficient for building some of the dependencies, such as RocksDB. To increase the swap size, first stop the swap:

sudo dphys-swapfile swapoff

Edit the swapfile configuration as root

sudo nano /etc/dphys-swapfile

and change the CONF_SWAPSIZE:

CONF_SWAPSIZE=1024

Save the file (ctrl-x), then reboot:

sudo reboot

Next, enable SPI and I2C by running

sudo raspi-config

and selecting Interfacing Options. Enable I2C and SPI from within the menu system. (also change your password, keyboard setup, etc at this point)

Let's go ahead and update our install with:

sudo apt-get update

First, you'll need git. If you don't have it installed:

sudo apt-get install git

Clone the git repository:

git clone https://github.com/helium/miner.git

You will need to install the dependencies listed below in order to use the Miner.

INSTALL ERLANG

---

Miner has been tested against Erlang OTP 21.3.

To install OTP 21.3 in Raspbian, we'll first acquire the Erlang package from Erlang Solutions and then install the dependencies:

(expect errors after the second command here... that's why we use the force in the third)

wget https://packages.erlang-solutions.com/erlang/debian/pool/esl-erlang_22.1.6-1~raspbian~buster_armhf.deb

Install various other dependencies:

(if you get a failure here, try it again. Dealing with mirrors is sometimes unreliable)

sudo apt-get install libdbus-1-dev autoconf automake libtool flex libgmp-dev cmake libsodium-dev libssl-dev bison libsnappy-dev libclang-dev doxygen

sudo dpkg -i esl-erlang_22.1.6-1~raspbian~buster_armhf.deb

sudo apt-get install -f

We are also going to install screen to simplify things a bit later.

sudo apt-get install screen

COMPILE THE MINER

---

Once the Miner has been cloned and Erlang installed, we can create a release using rebar3. Rebar will handle all the Erlang dependencies and build the application.

Before we can do this, however, we need to set up some keys for GitHub.

Paste the text below, substituting in your GitHub email address.

ssh-keygen -t rsa -b 4096 -C "[email protected]"

This creates a new ssh key, using the provided email as a label.

When you're prompted to "Enter a file in which to save the key," press Enter. This accepts the default file location.

Ensure the ssh-agent is running:

eval $(ssh-agent -s)

Add your SSH private key to the ssh-agent.

ssh-add ~/.ssh/id_rsa

Then go ahead and add this to your GitHub account:

https://help.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account

Copy your key from:

~/.ssh/id_rsa.pub

And go put it into GitHub:

Click this button and add the key you just generated:

Use the following to test your SSH connection to GitHub:

ssh -T [email protected]

Now we need to change the repo we are using for rocksdb...

cd miner

nano rebar.lock

Ctrl-w (find/where) rocksdb

Change the repo and SHA over to the following:

{<<"rocksdb">>,{git,"https://github.com/amirhaleem/erlang-rocksdb",{ref,"9f29d6e20d7f4f93a6157730a11fa9211e670e87"}},3},

After all of this, you should be able to run the following and build: (this will take a while, and just ignore warnings)

cd miner
./rebar3 as prod release

Once this completes, you're ready to run the Miner.

Using the Miner

---

Congrats! You've installed the Miner 🚀 Now it's time to make some things happen.

EDITING THE CONFIGURATION

---

The sys.config will need to be edited to match your configuration. Assuming you aren't using Helium Hotspot hardware you'll need to change the following lines of the configuration file:

nano _build/prod/rel/miner/releases/0.1.0/sys.config

Change the following settings:

{key, {ecc, [{key_slot, 0}, {onboarding_key_slot, 15}]}}, %% don't make this the last line in the stanza because sed and keep it on one line

should be changed to:

{key, undefined},

and:

{use_ebus, true},

should be changed to:

{use_ebus, false},

You should also edit log_root, base_dir and update_dir to be appropriate for whatever you prefer on your system.

STARTING UP

---

We are now going to make use of screen (some shortcuts here http://www.pixelbeat.org/lkdb/screen.html ) that we installed earlier.

sudo  su
screen

Start new screens with Ctrl-a c

Then, we can simply use Ctrl-a (0-9) to switch or Ctrl-a n for next

Ctrl-a ESC to use the pg keys

You can run the Miner in the background, or via an interactive console.

To run in the background:

_build/prod/rel/miner/bin/miner start

To run via the interactive console:

_build/prod/rel/miner/bin/miner console

(If you run in console mode, you'll need to open another terminal to execute any other commands. use screen)

CHECKING THE PEER-TO-PEER NETWORK

---

The Helium blockchain uses an Erlang implementation of libp2p. Because we expect Hotspot hardware to be installed in a wide variety of networking environments erlang-libp2p includes a number of additions to the core specification that provides support for NAT detection, proxying and relaying.

The first order of business once the Miner is running is to see if you're connected to any peers, whether your NAT type has been correctly identified, and that you have some listen addresses:

_build/prod/rel/miner/bin/miner peer book -s

As long as you have an address listed in listen_addrs and some peers in the table at the bottom, you're connected to the p2p network and good to go.

LOADING THE GENESIS BLOCK

---

First, you need a genesis block from either the main network, or the Pescadero testnet. Get them here: mainnet or pescadero.

NOTE: those are not links to the actual files!

You need to hit the links, download the files, and then transfer those over to the  RPi.

Once you've downloaded it, you'll need to use the CLI to load the genesis block in to your local miner: (use a fully qualified address)

_build/prod/rel/miner/bin/miner genesis load <path_to_genesis>

After the genesis block has been loaded, you should be able to check your block height and see at least the genesis block:

_build/prod/rel/miner/bin/miner info height

The first number is the election epoch, and the second number is the block height of your miner.

Installing packet_forwarder and lora_gateway from Source

---

Once you have miner running, you'll need packet_forwarder and lora_gateway to receive packets via SPI and the RAK2245 board and deliver them to the miner via UDP.

Clone the git repository:

git clone https://github.com/Lora-net/packet_forwarder
git clone https://github.com/Lora-net/lora_gateway

And download the following configuration file:

https://github.com/illperipherals/helium_docs/blob/master/global_conf.json

ONE QUICK CHANGE

Go into the file we pulled from https://github.com/Lora-net/lora_gateway/blob/master/libloragw/src/loragw_spi.native.c and modify line 56 to read:

#define SPI_SPEED       2000000

Now we are ready to build.

COMPILE THE PACKET FORWARDER and GATEWAY

Go into the packet_forwarder directory and and run:

./compile.sh

Once that wraps up, we can just run:

sudo ./lora_pkt_fwd

---

Conclusion

That's it! Once you have miner and packet forwarder running, you've built a Development Hotspot that can send and receive LoRaWAN packets, and interact with the blockchain to deliver packets to their correct destination.

You may use

tail -f /var/data/log/miner/console.log

if you want console output in a screen.

---