Hotspot Integration Testing
This guide is intended for companies that have been approved via HIP19, or are considering submitting an application.
Hotspot App Compatibility
For optimal user experience, we recommend Hotspots be equipped with compatible Bluetooth and Wi-Fi functionality. This allows a seamless onboarding experience.
To add your Hotspot to the Hotspot App, submit an issue and a pull request to the Hotspot Github Repo.
In this codebase, you’ll want to modify the onboarding flow to add a UI element that enables users to select your Hotspot type on this screen, add support emails to Diagnostic Reports, and include default antenna TX/RX gain:
Product names on this page should follow Helium branding guidelines and image assets must conform with existing user experience. If you require help, please reach out to the Helium team.
Here is a recommended list of what you should change/add:
- New UI element in src/features/hotspots/setup/HotspotSelectionScreen.tsx
- New picture in src/assets/images
- Hotspot Selection in Add Hotspot page in src/features/hotspots/setup/HotspotSelectionListItem.tsx
- New prompt message for power screen and pairing screen in src/locales/en.ts
- Add a case for your Diagnostics Screen in Onboarding in src/features/hotspots/setup/HotspotSetupDiagnosticsScreen.tsx
- Setup instructions, antenna gain, and Maker names in src/locales/en.ts
- Add Hotspot image in Bluetooth pairing list in src/components/HotspotPairingList.tsx
- Add Support Email to diagnostic reports in src/utils/stakingClient.ts
- Add Hotspot Antenna Type in Hotspot Settings in src/components/HotspotConfigurationPicker.tsx
- Add a case for your Antenna type in Antenna Setup in src/features/hotspots/setupAntennaSetupScreen.tsx
The Helium Hotspot App will start scanning for broadcasting Hotspots. Makers will need to update the
localname with the product name and include the last 6 digits of the MAC identifier. The character limit is 170 but we do not recommend anyone go beyond 25-30 characters in the product name.
localname is the name used on the Found Hotspots page.
Constructing the Transaction
If you’re using Helium’s miner image, constructing a transaction is relatively easy. For testing, you can use the following:
payer = 138LbePH4r7hWPuTnK6HXVJ8ATM2QU71iVHzLTup1UbnPDvbxmr
When testing with this
payer address, adding hotspots and asserting location transactions will be submitted and you’ll see them as pending transactions in the Hotspot App. However, once it reaches the blockchain, the transaction will be discarded as the payer address does not exist in the blockchain’s
chain_var of valid addresses. This ensures no Data Credits are spent on testing, but allows trial and error as Makers finish app integration.
Once submitted, you can view the pending transaction using this API:
By design, this transaction will fail, as this is a test account.
Once you’re ready to proceed, request a Maker account and replace the test payer address with your own maker address.
Requesting a Maker Account
Once you are confident that the transaction is sound and well crafted, request a Maker Account from your DeWi or Helium contact. In your request, include the Maker Name and how many location asserts you will include for your customers. A minimum of
1 included location assertion is required. That value is denoted under
All Maker Accounts are public on the blockchain and can be found here.
Make note of the
Payer address. This is the account address you will burn HNT into to generate DCs for onboarding your Hotspots.
Maker IDs are sequential and cannot be customized.
Funding the Maker Account
In order to fund the Maker account, you’ll need to create a CLI wallet. Once created, fund this wallet with HNT and use this HNT to produce Data Credits for your Hotspots. For each Hotspot onboarded, the transaction fees are as follows:
- Add Gateway:
- Assert Location:
payee in the burn transaction will be your Maker account. This is where the Data Credits will be deposited.
Remember, Data Credits are NON-TRANSFERABLE. Triple check that the
payee address is your correct
Adding Hotspots to the Onboarding Server
When you’re ready to start integration with the Test Maker account with the mobile wallet app, send us details about your Test Hotspot in this JSON format:
"id": "any_number", "mac_eth0": "dc:a6:32:d8:e7:5c", "mac_wlan0": "dc:a6:32:d8:e7:5e", "onboarding_address": "retrieve this b58 address from mine", "rpi_serial": "0000011031311847"
When you move to production, the JSON should be formatted like this. Note the addition of the
"batch": "batch_name", "id": "any_number", "mac_eth0": "dc:a6:32:d8:e7:5c", "mac_wlan0": "dc:a6:32:d8:e7:5e", "onboarding_address": "retrieve this b58 address from mine", "rpi_serial": "0000011031311847"
Wallet App, Onboarding, and Data Credits
While testing, the miner will use the test payer address to construct the
add_gateway transaction. The Hotspot app will take that transaction, sign it, and check the onboarding server to see if the Hotspot
Maker matches and exists.
If it does, the app submits the transaction to the blockchain. If done correctly, you should see a pending transaction here.
Note that the blockchain WILL NOT process this transaction because the payer address is not part of the chain variable of approved Makers. After a short period, the pending transaction will disappear from the API and the app. This is normal and expected.
Prior to production, you will have sent the list of Hotspots to the DeWi or your Helium contact to upload to the Onboarding Server on your behalf. You should also have Data Credits in your Maker account. And if not added already, notify the Helium team to include your Maker address in the chain variable.
The final steps and flow for production onboarding are as follows:
- Update the
minerto use your Maker account as payer.
- Onboard a Hotspot that you know is included in the upload to the Onboarding Server.
- Go through the Onboarding process in the Hotspot app. The app will check the Onboarding server for the Hotspot and verify the Maker ID. The app will then sign the transaction and submit to the blockchain.
- You’ll see a pending transaction in your Maker address.
- The blockchain will process the
assert_locationtransaction and verify that the maker address is in the chain variable.
- The transaction will go through and Data Credits will be deducted from the Maker account.
- The Pending transaction in the Hotspot app will update to Confirmed.
- If the Hotspot
Makerdoes not match, the transaction will silently fail.
- If there are insufficient Data Credits in the maker account, the transaction will silently fail.