Skip to content

NebraLtd/hm-diag

 
 

Repository files navigation

hm-diag: Helium Miner Diagnostics Container

hm-diag is a small website that displays diagnostic information about a hotspot. The website is only accessible if you are on the same network as the hotspot. Some people have exposed their devices publicly but this is not generally advised.

Quick start

Find the IP address of the hotspot using Balena's dashboard or network scanner. The website is available on port 80 so you can simply input the hotspot's IP address in the browser.

Diagnostics JSON Layout

As part of the code the system produces a JSON file which then is used to carry the data over easily to other parts of the system.

Variable Description
AN The Animal Name of the miner
APPNAME The name advertised on BTLE
BA Balena Application Name
BCH Current blockchain height
BN Balena Name, used to identify on balena
BSP Sync percentage
BT If the bluetooth module is detected
BUTTON The GPIO pin of the button on the miner
CELLULAR Whether the device has optional cellular capability
E0 MAC Address of the ETH0 interface
ECC If the ECC Key is detected over I2C
ECCOB If the miner should have an ECC chip on board
FR The hardware frequency
FRIENDLY The Friendly name of the hotspot
FW Firmware running on the unit
ID Balena UUID
LOR If a fault has been found with the LoRa Module
LTE If the LTE Module is detected
MAC Which mac address to print on labels in production
MC If the miner is connected to the Helium Network
MD If the miner is "Dialable" on the network
MH The sync height of the miner
MN NAT Type of the miner
MR Whether the miner is relayed or not
MS If miner is synced within 500 blocks
OK The onboarding key of the miner
PF If overall diagnostics have passed
PK The public key of the miner
RE The detected region plan from the miner (or override)
RESET The reset pin to use for the LoRa Module
serial_number The serial number of the onboard Raspberry Pi or other SBC
SPIBUS The SPI Bus to use for the LoRa Module
STATUS The GPIO Pin of the status LED
TYPE If it is a Full or Light Hotspot
VA ID of the hardware variant
W0 Mac Address of the WLAN0 interface
last_updated When this JSON was last updated (UTC timezone)
firmware_short_hash The related commit short hash of currently running firmware

Local development environment

Because the stack is tightly intertwined with Balena, the easiest way to test the code base on your own Raspberry Pi in your own Balena project.

  • Create a new Balena application (in a personal org):
    • Default device type: Raspberry Pi 3 (using 64 bit OS)
    • Application type: Starter
  • Add a device:
    • Select newest version
    • Development (required for local mode)
    • Click Download Balena OS
  • Use Etcher to flash the downloaded image
  • Insert flash drive into the Raspberry Pi and boot (don't forget to plugin ethernet if necessary)
  • Set env vars for the application in Balena:
    • FREQ: 868, 915, etc.
    • VARIANT: Choose from here
  • Deploy changes to:
    • All devices in application: balena push BALENA_APPLICATION
    • Single device in local mode: balena push UUID.local (this will build on the device and )

If you are on the same network as the Raspberry Pi, enter LOCAL IP ADDRESS from Balena into the browser.

Testing

poetry install --with dev
poetry run pytest --cov=hw_diag --cov=bigquery --cov-fail-under=80
poetry run ruff check hw_diag

Deprecated deployment

This is no longer the recommended way of doing Balena deployments.

  • Add the remote Balena repo:git remote add balena [email protected]:BALENA_USERNAME/BALENA_PROJECT.git
  • Deploy changes: git push balena YourLocalBranch:master

Access from other networks

Balena will generate a public URL for a device if PUBLIC DEVICE URL is toggled from the Balena device dashboard. This is not generally recommended, except for debugging.

Pre built containers

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.

Light hotspot notes

Helium network is transitioning to light hotspot mode. During the transition, there is a possibility of hotspot going back and forth between light and full blockchain sync mode. We support a environment variable (DISPLAY_MINER_INFO) to disable showing blockchain mining information so that administrators can enable/disable its visibility to avoid confusion among their customers.

The envvar default to false. If set and set to anything other than true, following mining information will be hidden:

  • Sync Percentage
  • Miner Connected To Blockchain
  • Height Status
  • Miner Relayed

This is a temporary capability that will be removed when hotspots moves to gateway-rs. Instead validator information will be shown.