michaelowens/hm-diag

Helium Miner Diagnostics

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

pip install -r test-requirements.txt
pytest
flake8 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:

• hm-diag on DockerHub
• hm-diag on GitHub Packages

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.