Maker Gateway-rs Upgrade Guide

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.

As the miner image transitions to being a gateway-rs-only container, it will stop obeying settings from the sys.config file that most Hotspot Makers use to notify the miner instance of Hotspot settings. To help Makers with this transition, a list of common configuration items that were previously configured via sys.config are provided along with alternates that will work for gateway-rs. These configuration items can be set when invoking the miner container or when running gateway-rs as a stand-alone executable.

Gateway-rs Configuration

At startup, gateway-rs configures itself via two methods: from environment variables and from a settings.toml file. By default, the settings file will be expected in the location /etc/helium_gateway/settings.toml, but this can be overridden with the -c flag. However, it is not recommended that Makers replace the default settings.toml file as it contains other important key items that may change from time to time. Instead, we recommend that Makers supply any necessary override items via environment variables.

In general, any item in the settings.toml file can be overridden by supplying an environment variable to gateway-rs with a name that is similar to the setting being overridden by prefixing the settings keyword with the characters GW_.

Example

To override the keypair item in settings.toml with the value example://override, supply the environment variable GW_KEYPAIR=example://override to gateway-rs at startup.

Note: Previous versions of gateway-rs included both a default.toml and settings.toml. All configurations are now only made in settings.toml.

Quick Reference Summary

These are the configuration variables to migrate from miner to gateway-rs:

Erlang Source	Erlang Variable	gateway-rs Environment	Default Value
sys.config	miner:radio_device	GW_LISTEN	127.0.0.1:1680
sys.config	miner:jsonrpc_port	GW_API	127.0.0.1:4467
sys.config	blockchain:key	GW_KEYPAIR	None
Environment	REGION_OVERRIDE	GW_REGION	None

Key Configuration

Like the miner, gateway-rs requires a cryptographic key to identify and authenticate itself on the Helium Network. Most Makers have likely relied on the default miner key settings, which instructed the miner to use the cryptographic identity locked in slot 0 of an ECC608 chip on I2C bus #1 at I2C address 0x60/96. For these Makers this old default would have sufficed.

Unlike the miner, however, gateway-rs does not have any default key setting. Therefore, as a Maker you must specifically provide gateway-rs with an appropriate setting for your platform.

If your platform deviated from the miner defaults, then you are likely familiar with the settings that had to be adjusted in the blockchain:key override in sys.config. But, for the sake of completeness, we'll illustrate all the settings that could have been adjusted in that scheme and show how they are encoded in the scheme used by gateway-rs.

For example, if the Erlang miner had been configured with:

{ blockchain, [
    { key,
        { ecc, [
            {key_slot, 2},
            {onboarding_key_slot, 12},
            {bus, "i2c-5"},
            {address, 83}
        ]}
    }
]}

Then the equivalent gateway-rs ECC608 configuration would be via these two environment variables:

GW_KEYPAIR=ecc://i2c-5:83?slot=2
GW_ONBOARDING=ecc://i2c-5:83?slot=12

Radio Region

The region variable is the default region used when the Hotspot does not have an asserted location. Makers need to ensure that the region is set correctly for the region in which the Hotspot is sold to ensure correct beaconing behavior.

Under the miner regime, the default radio region was adjusted via the REGION environment variable. In gateway-rs it is specified via the GW_REGION environment variable.

For example, if the Erlang miner had been configured to use the US915 region by default:

REGION=US915

Then the equivalent gateway-rs configuration would be via the environment variable:

GW_REGION=US915

Packet Forwarder Bind Port

The default address at which gateway-rs listens for UDP packets from the packet forwarder has not changed (host 127.0.0.1, port 1680). However, if you need to change the host or port binding from this default then you will need to supply a GW_LISTEN environment variable.

For example, if the Erlang miner had been configured with:

{miner, [ {
        {radio_device, {{0, 0, 0, 0}, 1699, deprecated, deprecated}}

then the equivalent gateway-rs configuration would be via the environment variable:

GW_LISTEN=0.0.0.0:1699

Logging

Before the migration, miner handled writing logs to disk. Post migration, helium_gateway outputs on stdout as it has before. It is up to the Maker to integrate with their system's logging setup. Capturing log output and writing to disk may be handled with a log manager such as journald or syslogd.

CLI

The CLI has changed for a few commands, notably the helium_gateway info command that some makers may use now takes a list of info entries to return. The helium_gateway info --help output documents what keys are available.

System Startup

Since gateway-rs no longer releases as an installable package it is up to the maker to integrate the executable with their system startup setups, (like procd or tini, systemd depending on the operating system setup)

Firewall Configurations

Makers using outbound firewall rules to restrict outbound connections should allow the following outbound ports:

Purpose	Outbound Port Used
Configuration Service	TCP/6080
Entropy Oracle	TCP/7080
Packet Router	TCP/8080
Packet Ingest	TCP/9080