helium-multi-gateway

A multi-gateway aggregator for the Helium LoRaWAN network. It accepts connections from multiple LoRaWAN gateways via the Semtech UDP protocol, manages per-gateway keypairs, and routes packets to the Helium packet router over gRPC.

Each gateway must have a unique MAC ID, as this is used to pair the gateway to a cryptographic keypair (created automatically on first connection). A single instance of this application supports one LoRaWAN region at a time; to serve gateways in multiple regions, run separate instances with different configurations.

Installing from Debian package

Download the .deb from the CI artifacts (each successful run uploads helium-multi-gateway-deb), then install it:

sudo dpkg -i helium-multi-gateway_*.deb

This will:

install the binary to /usr/bin/helium-multi-gateway
install a default config to /etc/helium-multi-gateway/settings.toml
install a systemd unit and enable/start the service

Verify the service is running:

sudo systemctl status helium-multi-gateway
sudo journalctl -u helium-multi-gateway -f

Configuration

The configuration file lives at /etc/helium-multi-gateway/settings.toml:

keys_dir = "/var/lib/helium-multi-gateway/keys"
region = "US915"
api_addr = "127.0.0.1:4468"

[gwmp]
addr = "0.0.0.0"
port = 1680

[router]
uri = "http://mainnet-router.helium.io:8080/"
queue = 100

[log]
level = "info"

Changing the region

Edit the region field to match your deployment. Common values:

Region	Description
`US915`	United States 915 MHz
`EU868`	Europe 868 MHz
`AU915`	Australia 915 MHz
`AS923_1`	Asia 923 MHz (group 1)
`KR920`	South Korea 920 MHz
`IN865`	India 865 MHz

After editing, restart the service:

sudo systemctl restart helium-multi-gateway

API key authentication

The REST API supports optional API key authentication via X-API-Key header. Two separate keys can be configured independently:

Setting	Protects	Endpoints
`read_api_key`	Read-only access	`GET /gateways`, `GET /gateways/{mac}`, `GET /metrics`
`write_api_key`	Write/signing access	`POST /gateways/{mac}/sign`

# Optional: protect read endpoints
# read_api_key = "your-read-key"

# Optional: protect the signing endpoint
write_api_key = "your-write-key"

If a key is not set, those endpoints remain open. The CLI subcommands automatically send the appropriate key from the config file.

REST API

The API listens on api_addr (default 127.0.0.1:4468).

`GET /gateways`

List all known gateways.

curl http://127.0.0.1:4468/gateways

{
  "gateways": [
    {
      "mac": "AABBCCDDEEFF0011",
      "public_key": "...",
      "connected": true,
      "connected_seconds": 3600,
      "last_uplink_seconds_ago": 5
    }
  ],
  "total": 1,
  "connected": 1
}

`GET /gateways/{mac}`

Get status for a single gateway. The MAC is 16 hex characters.

curl http://127.0.0.1:4468/gateways/AABBCCDDEEFF0011

`POST /gateways/{mac}/sign`

Sign arbitrary data with a gateway's keypair. The request and response bodies are base64-encoded.

curl -X POST http://127.0.0.1:4468/gateways/AABBCCDDEEFF0011/sign \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-write-key' \
  -d '{"data": "<base64-encoded-data>"}'

{
  "signature": "<base64-encoded-signature>"
}

`GET /metrics`

Prometheus-formatted metrics.

curl http://127.0.0.1:4468/metrics

CLI

Many of the REST endpoints above can be exercised through the CLI. The CLI connects to the running server's API, so the service must be running.

helium-multi-gateway [OPTIONS] <COMMAND>