Helium Miner Packet Forwarder
This is a Python app that uses prebuilt utilities to detect the correct concentrator chip and region, then start the concentrator accordingly.
hm-pktfwd builds off three other repos which each built a portion of the code required to run the packet forwarder.
reset_lgw.sh is a shared tool that is used on all concentrator chip versions.
On sx1301 chips, its is recommended that the script is run before each time the concentrator is started.
On chips that use sx1302_hal, the reset script is run automatically when the concentrator starts and is expected to be located in the same directory as the lora_pkt_fwd module.
reset_lgw is used by all concentrators, and inspired by the upstream versions. That said, it is different from the originals, context specific to hm-pktfwd, and moved to this repo to avoid confusion about its intention. Additional context here.
You can typically find the exact region plan you need to use at What Helium Region or on the Helium Miner GitHub repo however the table below provides a rough guide...
| Region Plan | Region |
|---|---|
| AS923_1 | Most of Asia |
| AS923_2 | Vietnam and Indonesia |
| AS923_3 | Phillipines and Cuba |
| AS923_4 | Israel |
| AU915 | Australia, New Zealand and South America |
| CN470 | China |
| EU868 | Europe, Middle East and some of Africa |
| EU433 | Parts of Africa and Asia |
| IN865 | India and Pakistan |
| KR920 | South Korea |
| RU864 | Russia |
| US915 | North America |
Please note:
| Region Plan | Region |
|---|---|
| CN779 | NOT YET SUPPORTED |
The following environment variables control various aspects of the program's operation.
| Variable | Default | Required | Description |
|---|---|---|---|
| VARIANT | - | Yes | See variants |
| SX1301_REGION_CONFIGS_DIR | - | Yes | Path to sx1301 configs |
| SX1302_REGION_CONFIGS_DIR | - | Yes | Path to sx1302 configs |
| UTIL_CHIP_ID_FILEPATH | - | Yes | Path to [chip_id](https://github.com/NebraLtd/sx1302_hal/tree/69811057222f6f9cf8929ebfdb7fc6e36cc2618d/util_chip_id |
| RESET_LGW_FILEPATH | - | Yes | Path to reset.sh. The same file is used for all sx130x versions. |
| ROOT_DIR | - | Yes | Directory the app will be run from. Should be the same location. global_conf.json will also be copied here. |
| SX1302_LORA_PKT_FWD_FILEPATH | - | Yes | Path to built sx1302 lora_pkt_fwd executable. |
| SX1301_LORA_PKT_FWD_DIR | - | Yes | Directory that contains sx1301 lora_pkt_fwd executables for all SPI buses. |
| LORA_PKT_FWD_BEFORE_CHECK_SLEEP_SECONDS | 5 | No | Duration after starting lora_pkt_fwd before establishing if it started successfully. |
| LORA_PKT_FWD_AFTER_SUCCESS_SLEEP_SECONDS | 30 | No | Duration to poll status after concentrator starts successfully. |
| LORA_PKT_FWD_AFTER_FAILURE_SLEEP_SECONDS | 2 | No | Duration to wait before restarting when concentrator exits with 0. If it exits with code greater than 0, program exits and container restarts. |
| LOGLEVEL | DEBUG | No | TRACE, DEBUG, INFO, WARN, etc. |
| REGION_FILEPATH | /var/pktfwd/region | No | Path where hm-miner writes the region. |
| DIAGNOSTICS_FILEPATH | /var/pktfwd/diagnostics | No | File containing "true" or "false" for whether lora_pkt_fwd is successfully running or not. |
| AWAIT_SYSTEM_SLEEP_SECONDS | 5 | No | How long app sleeps before starting concentrator. |
| SENTRY_KEY | False | No | Key for Sentry. Sentry inactive if key is False. |
| REGION_OVERRIDE | False | No | Region override. eg US915. |
| BALENA_ID | From Balena | No | Only used with Sentry. |
| BALENA_APP_NAME | From Balena | No | Only used with Sentry. |
This repo automatically builds docker containers and uploads them to two repositories for easy access:
The images are tagged using the docker long and short commit SHAs for that release. The current version deployed to miners can be found in the helium-miner-software repo.
When developing, it is faster to build locally instead of relying on the pre-built container to generate.
# Cross-compile
docker buildx build --platform linux/arm64/v8 --progress=plain -t DOCKERHUB_USER/hm-pktfwd .
# To stop at an intermediary stage
docker buildx build --platform linux/arm64/v8 --progress=plain --target pktfwd-builder -t pktfwd-builder .
# Tag and push image
docker image tag docker.io/DOCKERHUB_USER/hm-pktfwd DOCKERHUB_USER/hm-pktfwd:0.0.X
docker push DOCKERHUB_USER/hm-pktfwd:0.0.XHardware Requirements: An ARM64 based device.
Software Requirements:
- Docker (instructions)
- Docker Compose (instructions)
git
With the dependencies installed, do the following:
$ git clone https://github.com/NebraLtd/hm-pktfwd.git
$ cd hm-pktfwd
$ docker build . -t hm-pktfwd
Once you've built the image, we need to do a bit of prep work to mock the environment:
$ mkdir -p /var/pktfwd
$ echo region_eu868 | sudo tee -a /var/pktfwd/region
We're now finally ready to start up the containers using:
$ docker-compose up