• Stars
    star
    280
  • Rank 147,492 (Top 3 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created about 4 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The Helium Gateway

Helium Gateway

ci

The Helium Gateway application is a service designed to run on Linux-based LoRaWAN gateways.

It's intended to run alongside a typical LoRa packet forwarder and to connect via Semtech's Gateway Messaging Protocol (GWMP, using JSON v1 or v2).

In turn, the Helium Gateway application does two things:

  • Periodically sends and witnesses Proof of Coverage beacons, which are reported to the Proof of Coverage ingest oracles
  • connects and routes packets to the Helium Packet Router
                                                                 +-----------+
+-----------+                       +------------+               |  Ingest   |
|           |                       |            |<--- gRPC ---->|  Service  |
|  packet   |<--- Semtech GWMP ---->|   Helium   |               +-----------+
| forwarder |       over UDP        |   Gateway  |               +-----------+
|           |                       |            |<--- gRPC ---->|  Helium   |
+-----------+                       +------------+               |  Router   |
                                                                 +-----------+

NOTE: A DIY Helium Gateway based hotspot is eligible for data rewards only. Proof of coverage rewards are only possible for approved maker hotspots.

Releases

The project builds binary compressed tar release files which are named after the crypto module used and the cpu architecture they were built for. For example helium-gateway-1.0.0-aarch64-unknown-linux-gnu.tar.gz contains the helium_gateway executable with ecc608 support and it's setttings.toml configuration file.

For versions using the ecc608, the crypto module name is not included in the file name. However for TPM variants it is included, for example helium-gateway-1.0.0-x86_64-tpm-debian-gnu.tar.gz

Releases are tagged using semantic versioning with a major.minor.patch form. A alpha/beta release tags may also be issued for early feature/bug development and testing. Makers are not required to pick up alpha/beta releases.

Linux Dependencies

This application requires a Linux-based environment for the following reasons:

  • tokio: the gateway-rs application, written in Rust, depends on Tokio for its runtime. Tokio binds to Linux interfaces such as epoll and kqeueue. It is technically possible to port Tokio to another OS or RTOS (this has been done for Windows), but it would be no simple undertaking.

Installing

If your supported LoRa gateway did not come with helium-gateway pre-installed, manual installation requires you to:

  1. Configure the packet forwarder on the gateway to forward to the helium-gateway application. This varies per gateway but the goal is to set the packet forwarder to forward to the (default) configured helium-gateway on 127.0.0.1 at udp port 1680

  2. Set up ssh acccess to the gateway. Depending on the gateway that may require going through a web interface, while others already have ssh configured.

  3. scp a downloaded and uncompressed release package for the supported platform to the gateway. e.g.

    scp helium_gateway settings.toml <gateway>:/tmp/
  4. ssh into the device and copy the application and configuaration into a suitable location using a command like:

    mkdir /etc/helium_gateway
    mv /tmp/settings.toml /etc/helium_gateway/
    mv /tmp/helium_gateway /usr/bin/
  5. Configure the logging method to use by updating the settings.toml file's [log] section with the logging method to use based on your system. Supported values are stdio or syslog. Note you may need to configure the syslog service on your device to accept the logs.

  6. Configure the region if required. The default region of the gateway is set to UNKNOWN, and fetched based on the asserted location of the gateway. Setting the region to a known region or caching the last fetched region and using the GW_REGION environment variable on startup will allow the gateway to use the correct region for uplinks immediately, while the region parameters are retrieved.

    The supported region values are listed in the region protobuf definition.

    NOTE: Due to TX power regulations, the gateway location needs to be asserted on the blockchain to be able to send downlinks.

  7. Start the service by either starting it manually or hooking it into the init.d, systemd, or equivalent system services for your platform. Consult your platform/linux on how best to do this.

    The startup command for the application is as follows. Note you will need to adjust the path to helium_gateway or the path to the settings file to use for the -c option.

    /usr/bin/helium_gateway -c /etc/helium_gateway/settings.toml server

If this command succeeds the logs on the gateway will show the service starting and the local packet forwarder client connecting to the gateway service.

Supported Targets

The following targets are being built. Adding a new target involves creating a pull request against this repository with the right cpu target tuple.

  • Review the open issues to see if it's already in progress. If not, file an issue. Note that new targets are developed and supported by Helium makers and Community members.
  • Join the #gateway-development channel on Helium Discord and work the the community to add target support.

Note that platforms will be tested much faster if you join the development process!

Target Products
mipsel-unknown-linux-musl CalDigit Light Hotspot
ClodPi Light Hotspot ClodPi
RAK833 EVB Kit
RAK7258 (WisGate Edge Lite)
RAK7249 (WisGate Edge Max)
RAK7240 (WisGate Edge Prime)
Smart Harvest Instruments Light Gateway
mips-unknown-linux-musl Dragino LPS8
Dragino DLOS8
aarch64-unknown-linux-gnu Cotx gateways cotx
Raspberry Pi 3 or 4 running Raspian / Raspberry Pi OS 64 bit or another 64 bit Debian-based Linux distro
arm-unknown-linux-gnueabihf Raspberry Pi 0 or 1 running Raspian / Raspberry Pi OS or another Debian-based Linux distro
armv5te-unknown-linux-musleabi CloudGate
Multitech Conduit MTCDT (mLinux)
armv7-unknown-linux-musleabihf Kerlink Wirnet iFemtoCell Evolution
armv7-unknown-linux-gnueabihf ResIOT X gateways resiot
Raspberry Pi 2, 3, or 4 running Raspian / Raspberry Pi OS or another Debian-based Linux distro
Kona Micro IoT Gateway
Kona Enterprise IoT Gateway
RisingHF RHF2S027 Light Hotspot
x86_64-unknown-linux-gnu Debian x86_64 (ecc608)
LongAP
x86_64-tpm-debian-gnu Debian x86_64 (tpm)
FreedomFi gateway

Building

Use one of the existing releases if you can, or build your own by hand using the instructions below.

If you want to support a new target, please consider submitting a PR to get the target as part of the supported matrix of gateway platforms!

  1. Install rust

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  2. Install cargo cross. The cross command allows for cross compiling to hardware targets using docker image.

    cargo install cross
  3. Build the application binary using the target triplet/profile from the supported targets. Note that debug builds may be to large to run on some targets.

    cargo build --profile <target> --release build

    The resulting application binary is located in

    target/<target>/release/helium_gateway
    

    NOTE The target triplet and profile may not be the same. For example the x86_64-tpm-debian-gnu profile uses the x86_64-unknown-linux-gnu target

Additional usage info

The Helium Gateway application can be configured to suit your hardware/software environment in a variety of ways - either from the command line, using customizations to the settings.toml file or with environment variables. The following sections describe this functionality in more detail as well as more general information on how to use the application.

Settings file

The Helium Gateway application is configured using a TOML settings file. The released settings file can be found in the settings.toml file in this repo. Edit this file with specifics for your target platform and store it either at the default expected locaton /etc/helium_gateway/settings.toml or at a custom location of your choosing. If you store the file in a non default location you will need to pass the -c flag to the helium_gateway application as shown below in the general usage section.

Using the ECC crypto chip

If your gateway is enabled with an ECC608 crypto chip which is set up correctly, you can configure helium_gateway to use the crypto chip for secure key storage and crypto operations.

To use in your settings.toml override the keypair setting to reflect the use of the ECC and specify the bus address and slot to use. For example:

keypair = "ecc://i2c-1:96?slot=0&network=mainnet"

will have helium_gateway use the ECC at the /dev/i2c-1 device driver location, use bus address 96 (which is hex 0x60) and slot 0 for it's crypto operations. While marking the resulting key as a mainnet key. Bus address, slot and network are all optional parameters and default to the above values (only device driver location is required such as ecc://i2c-1).

Note that the file based keypair will no longer be used once the ECC is configured for use.

See the gateway-mfr-rs repo for instructions on configuring, locking, and testing an ECC chip.

It is expected that most gateways will use the same key slot for the onboarding key and the keypair, however this key is also configurable in the same way as the keypair:

onboarding = "ecc://i2c-1:96?slot=0"

The original helium miners use an onboarding key on slot 15:

onboarding = "ecc://i2c-1:96?slot=15"

Envrionment variables

Instead of editing paramaters in the settings.toml file as described above, you can also use environment variables. The environment variable name will be the same name as the entries in the settings file in uppercase and prefixed with "GW_". For example, following on from the above example where we change the region using region = "EU868" in the settings file, setting an environment variable of GW_REGION="EU868" will override the region setting. If the settings are in one of the lower sections such as the [log] section then you need to also include that in the environment variable name such as GW_LOG_LEVEL.

The settings are loaded first from the settings.toml file, and then from environment variables and any duplicates are overriden in the order. Therefore, please note that if you have a setting in both locations, the environment variable will override the settings in the other two locations.

General usage info

Using the Helium Gateway application is pretty simple, and the vast majority of the information you will need to use it can be gleaned by using the --help flag which provides the following output:

Helium Light Gateway

USAGE:
    helium_gateway [FLAGS] [OPTIONS] <SUBCOMMAND>

FLAGS:
        --daemon     Daemonize the application
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -c <config>        Configuration file to use [default: /etc/helium_gateway/settings.toml]

SUBCOMMANDS:
    add       Construct an add gateway transaction for this gateway
    help      Prints this message or the help of the given subcommand(s)
    info      Info command. Retrieve all or a subset of information from the running service
    key       Commands on gateway keys
    server    Run the gateway service

As you can see, apart from the help command, there are four core subcommands that you can pass: add, key, server. The descriptions of what these subcommands do is shown in brief in the above help output, and are explained in more detail in the sections below.

The only option available is the config option using the -c flag. This tells the application where your configuration file is located and can be used as follows whilst passing any of the other commands such as server or add (default is /etc/helium_gateway/settings.toml):

./helium_gateway -c /location/of/config/file server

Lastly you can check the version, read the help information or daemonize the application using the --version, --help and --daemon flags respectively.

Add gateway subcommand

As shown in the help output below, this subcommand is used to construct an add gateway transaction which can subsequently be used with the Helium Wallet application to onboard the gateway to the blockchain. More infomation on this process can be found on the docs article for Data Only Hotspots.

Construct an add gateway transaction for this gateway

USAGE:
helium_gateway add [OPTIONS] --owner <owner> --payer <payer>

FLAGS:
-h, --help Prints help information
-V, --version Prints version information

OPTIONS:
--mode <mode> The staking mode for adding the light gateway [default: dataonly]
--owner <owner> The target owner account of this gateway
--payer <payer> The account that will pay account for this addition

So for example, to construct a dataonly add gateway transaction you would enter the following command at the terminal:

./helium_gateway add --owner WALLET_ADDRESS --payer WALLET_ADDRESS

You need to substitute WALLET_ADDRESS for the wallet address you will use for the owner of the hotspot and the payer of the transaction fees respectively...but please note that the --payer address must be the same as the one you will use to submit the transaction to the blockchain, or the transaction will fail.

The output of this command is a JSON object which looks like the following:

{
  "address": "11TL62V8NYvSTXmV5CZCjaucskvNR1Fdar1Pg4Hzmzk5tk2JBac",
  "fee": 65000,
  "mode": "dataonly",
  "owner": "14GWyFj9FjLHzoN3aX7Tq7PL6fEg4dfWPY8CrK8b9S5ZrcKDz6S",
  "payer": "14GWyFj9FjLHzoN3aX7Tq7PL6fEg4dfWPY8CrK8b9S5ZrcKDz6S",
  "staking fee": 1000000,
  "txn": "CrkBCiEBrlImpYLbJ0z0hw5b4g9isRyPrgbXs9X+RrJ4pJJc9MkSIQA7yIy7F+9oPYCTmDz+v782GMJ4AC+jM+VfjvUgAHflWSJGMEQCIGfugfLkXv23vJcfwPYjLlMyzYhKp+Rg8B2YKwnsDHaUAiASkdxUO4fdS33D7vyid8Tulizo9SLEL1lduyvda9YVRCohAa5SJqWC2ydM9IcOW+IPYrEcj64G17PV/kayeKSSXPTJOMCEPUDo+wM="
}

You can also pass a --mode flag followed by the hotspot type (dataonly | light | full) as shown below:

./helium_gateway add --owner WALLET_ADDRESS --payer WALLET_ADDRESS --mode light

The output of this command will be mostly the same as if you used the default dataonly however you will see that the mode has changed to "mode": "light", and the staking fee amount has changed to "staking fee": 4000000.

The txn field from the JSON object needs to be used as the input to the wallet command helium-wallet hotspot add when you subsequently want to add it to the blockchain. For example, using the above JSON object as an example, you would use the following command:

helium-wallet hotspots add CrkBCiEBrlImpYLbJ0z0hw5b4g9isRyPrgbXs9X+RrJ4pJJc9MkSIQA7yIy7F+9oPYCTmDz+v782GMJ4AC+jM+VfjvUgAHflWSJGMEQCIGfugfLkXv23vJcfwPYjLlMyzYhKp+Rg8B2YKwnsDHaUAiASkdxUO4fdS33D7vyid8Tulizo9SLEL1lduyvda9YVRCohAa5SJqWC2ydM9IcOW+IPYrEcj64G17PV/kayeKSSXPTJOMCEPUDo+wM=

Gateway keys subcommand

This subcommand can be used to get the address and animal name of the gateway from the keys file as shown in the help output below. Note that the helium_gateway server has to be running for this command to work.

Commands on gateway keys

USAGE:
    helium_gateway key <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help    Prints this message or the help of the given subcommand(s)
    info    Commands on gateway keys

Using this is as simple as passing the following command in a terminal from wherever you installed the helium_gateway application:

./helium_gateway key info

The output of this is a JSON object containing the address and animal name of the hotspot as shown below:

{
  "address": "11TL62V8NYvSTXmV5CZCjaucskvNR1Fdar1Pg4Hzmzk5tk2JBac",
  "name": "wide-neon-kestrel"
}

Gateway server

The gateway server subcommand is used to start the gateway service on your device.

Run the gateway service

USAGE:
    helium_gateway server

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

Running it is as simple as:

./helium_gateway server

However as discussed above you can also pass the -c option to tell the service that you are using a different location for your config files:

./helium_gateway -c /location/of/config/file server

More docs and info

There is a wealth of further information on maker hotspot software on the Helium Docs site including information about the gRPC api that allows you to interact with the gateway via the maker app and other services over gRPC rather than via the command line options described above.

More Repositories

1

miner

Miner for the helium blockchain
Erlang
609
star
2

HIP

Helium Improvement Proposals
Jupyter Notebook
582
star
3

helium-wallet-rs

Rust implementation of a helium wallet CLI
Rust
258
star
4

blockchain-core

Erlang
214
star
5

denylist

Shell
201
star
6

plumtree

Epidemic Broadcast Trees
Erlang
193
star
7

hotspot-app

Helium hotspot app for iOS and Android
TypeScript
187
star
8

explorer

A Helium Blockchain Explorer
JavaScript
124
star
9

docs

Helium Documentation
MDX
120
star
10

helium-program-library

Helium programs to run on the Solana blockchain
TypeScript
118
star
11

erlang-libp2p

An Erlang implementation of libp2p swarms
Erlang
111
star
12

helium-js

Official TypeScript packages for interacting with the Helium blockchain
TypeScript
110
star
13

console

A management console to onboard and manage devices running on the Helium blockchain network.
JavaScript
104
star
14

router

router combines a LoRaWAN Network Server with an API for console, and provides a proxy to the Helium blockchain
Erlang
69
star
15

mappers

Mappers Frontend and API
Elixir
68
star
16

erlang-hbbft

Erlang implementation of HoneyBadgerBFT
Erlang
67
star
17

blockchain-etl

Blockchain follower that follows and stores the Helium blockchain
Erlang
64
star
18

longfi-arduino

C++
62
star
19

wallet-app

TypeScript
59
star
20

console-decoders

Payload decoder functions for console.
JavaScript
59
star
21

blockchain-node

A Heilum Blockchain Node
Erlang
58
star
22

network-explorer

TypeScript
57
star
23

angry-purple-tiger

animal-based hash digests for humans
JavaScript
48
star
24

blockchain-http

An http API for the helium blockchain database
Erlang
47
star
25

erlang-dkg

Distributed key generation for Erlang (using pairing based cryptography)
Erlang
41
star
26

erlang-h3

Erlang binding for Uber's H3 spatial coordinate library
Erlang
41
star
27

maker-starter-app

TypeScript
37
star
28

gateway-config

The Helium configuration application. Enables configuring the Helium Hotspot over Bluetooth
Erlang
37
star
29

helium-ledger-app

The official Helium app for the Ledger Nano S
C
32
star
30

helium-vote

TypeScript
30
star
31

helium-ledger-cli

Rust
26
star
32

virtual-lorawan-device

A utility that attaches to a Semtech UDP Host and pretends to be a LoRaWAN Device
Rust
23
star
33

proto

Rust
22
star
34

whitepaper

The Helium Whitepaper
TeX
19
star
35

oracles

Oracles for Helium subDAOs
Rust
19
star
36

gateway-mfr-rs

Rust
18
star
37

angry-purple-tiger-rs

animal-based hash digests for humans.. in rust
Rust
18
star
38

merkerl

A Merkle Tree implementation in Erlang
Erlang
18
star
39

rosetta-helium

Rosetta implementation for helium
Go
18
star
40

longfi-platformio

C++
16
star
41

packet-purchaser

Erlang
16
star
42

relcast

Relcast library
Erlang
15
star
43

gateway_mfr

Erlang Manufacturing Suppport Code
Erlang
15
star
44

erlang-lorawan

Erlang
15
star
45

cargo-elixir

JavaScript
15
star
46

ecc508

Library to communicate with the Microchip cryptoauthentication device
Erlang
14
star
47

lorawan-sniffer

Rust
14
star
48

helium-api-rs

A Rust library for accessing Helium API servers
Rust
14
star
49

erlang-multihash

Erlang implementation of multihash
Erlang
13
star
50

react-native-helium

TypeScript
13
star
51

onboarding-server

JavaScript
13
star
52

erlang-tpke

Threshold encryption
Erlang
11
star
53

helium-console-cli

A command line interface for interacting with Helium Console API
Rust
11
star
54

ebus

An Erlang binding to libdbus
Erlang
11
star
55

libp2p-crypto

Erlang cypto library used by the libp2p system
Erlang
11
star
56

psql-migration

A SQL migration script for Erlang
Erlang
10
star
57

kdtree

Simple kdtree library in erlang
Erlang
10
star
58

semtech-udp

Rust
9
star
59

ecc608-linux-rs

A linux rust library for the i2c ecc508 and ecc608 family of crypto chips
Rust
9
star
60

modular-governance

A modular set of governance contracts on solana
JavaScript
9
star
61

helium-packet-router

Erlang
9
star
62

erlang-erasure

Simple Erlang binding for Jerasure's Reed-Solomon erasure encoding/decoding
C
9
star
63

longfi-core

Platform agnostic implementation of core LongFi primitives.
C
9
star
64

erlang-splicer

Splice 2 sockets together in Erlang
Erlang
9
star
65

stm32-lora-disco-rs

Unofficial Rust Board Support Crate for B-L072Z-LRWAN1
GDB
8
star
66

longfi-erlang

LongFi core bindings for Erlang
C
8
star
67

ecc_compact

Unpatented ECC point compression for NIST p-256 public keys
C
8
star
68

xorf-generator

public key filter tool
Rust
8
star
69

erlang-multiaddr

Erlang implementation of multiaddr
Erlang
8
star
70

longfi-arduino-legacy

C
7
star
71

vincenty

Vincenty's formulae implementation in Erlang
Rust
7
star
72

erlang-pbc

Pairwise crypto
C
7
star
73

erlang-ubx

Erlang support for speaking to ublox gps modules using the ubx protocol
Erlang
6
star
74

lorawan-h3

LoRaWAN regions represented as H3 polyfills
Rust
6
star
75

account-compression-anchor-gen

Anchor generated CPI clients for account compression and bubblegum
Rust
6
star
76

explorer-api

JavaScript
6
star
77

ebus-gatt

A bluetooth gatt server implementation using ebus
Erlang
6
star
78

cortex-mpu

Cortex-M MPU library
Rust
6
star
79

packet-forwarder-test

Rust
6
star
80

erlang-tc

Erlang NIF for threshold_crypto
Erlang
5
star
81

helium-crypto-rs

Rust
5
star
82

well-known

Well known addresses, OUIs, etc. for the Helium network
5
star
83

gwmp-mux

Multiplexer for Semtech's GWMP over UDP
Rust
5
star
84

erl_angry_purple_tiger

Erlang port of angry_purple_tiger
Erlang
5
star
85

erlang-sss

Erlang binding for Shamir Secret Sharing
Erlang
5
star
86

sibyl

Erlang
4
star
87

miner-test

Helium miner testing utilities
Erlang
4
star
88

cream

An Erlang cache backed by the performant Moka library
Erlang
4
star
89

connman

Connection Manager
C
4
star
90

erlang-stats

A NIF wrapper around kthohr/stats
Makefile
4
star
91

ebus-connman

An erlang connman client using ebus
Erlang
4
star
92

helium-foundation-k8s

Helium foundation k8s defs
4
star
93

helium-data

Utilities for processing helium data
Rust
4
star
94

ipython-target-modeling

Testing targeting models
Jupyter Notebook
3
star
95

module-sdk

Libraries and example applications for developing Helium embedded Applications
C
3
star
96

wallet-issues-tracker

Issue tracker for the Helium Wallet app
3
star
97

longfi-st-hal

Helium LongFi Examples Using ST HAL
C
3
star
98

etl-extract

Extracts ETL data that can be used for display or further analysis
Rust
3
star
99

elixir-reed-solomon-erasure

Reed solomon erasure coding NIFs for Elixir
Elixir
3
star
100

intercept

Erlang
3
star