LoRaWAN Roaming on Helium

The Helium Network, the largest LoRaWAN Network in the world, is an attractive Network to other public and private LoRaWAN Network providers wanting to expand their coverage without deploying additional infrastructure.

Roaming Quickstart

The Helium Config Service stores LoRaWAN routing information on the Helium IoT Network. Each roaming user is registered in the Config Service under their Net ID and may define multiple routes for their data. Each route contains information such as:

• DevEUI+AppEUI pairs — so the network knows which join requests to send your way
• DevAddr ranges — so the network knows which uplinks to send your way
• Server endpoint + port — so we know where to send packets to

There are two ways of interacting with the Config Service, directly through GRPC APIs or through CLI (command-line-interface).

CLI

1. Run the following commands to pull & build the latest config service CLI:

   $ git clone https://github.com/helium/helium-config-service-cli.git
   $ curl https://sh.rustup.rs -sSf | sh
   $ source "$HOME/.cargo/env"
   $ cd helium-config-service-cli
   $ cargo b --release

2. The CLI program helium-config-service-cli will be built in the ./target/release folder inside the helium-config-service-cli directory. Renaming the program as main is a timesaving measure and will be used throughout the remainder of this guide. (Rename it by running mv helium-config-service-cli main from the build directory)

3. Now that we have the CLI binary, let’s just put it in a separate folder. This is recommended only for simplicity's sake. Just copy main into the folder you created. You can reference the following commands:

   $ cd ..
   $ mkdir cli-testing
   $ cd cli-testing
   $ cp ../helium-config-service-cli/target/release/main .

4. Let’s generate the keypairs you’ll be using to authenticate your interactions with the config service. These keys allow only you to create/modify/delete routes. Run this command twice for 1) owner keypair and 2) delegate keypair and name files accordingly. Run ./main env generate-keypair <key file name>.bin and you should find a file called <key file name>.bin. Print out the public key of your keypair by running:

   $ ./main env info --keypair <key file name>.bin

   Delegate Keypair: The delegate key is actively used to create and manage routes. In case it is ever compromised, it can be updated using the owner key.

   Owner Keypair: The owner key is irreplaceable and should be kept safe, secure, and private at all times. If lost or compromised, you could lose your OUI.

   Payer Keypair: The third keypair, the payer keypair, corresponds to your Helium wallet addresses. The public wallet address (payer key) is used to keep your wallet and OUI funded.

5. Next, make sure you have a Helium Wallet. You can download them here.

6. Contact the Helium Foundation with your public key and Helium Wallet address via email at hello@helium.foundation for the information needed in the next steps.

7. Next, let’s initialize some environment variables so that you don’t have to tell the CLI the same thing over and over again in later commands:

   1. Run ./main env init
   2. Fill in http://mainnet-config.helium.io:6080/ for Config Service Host
   3. Fill in the path ./keypair.bin for Keypair Location
   4. Fill in your NET ID for Net ID
   5. Fill in your OUI for Assigned OUI
   6. Fill in the multi-buy value you want for Default Max Copies as a default for your routes.
   7. Then export the environment variables. This needs to be done manually. You will see something like this and just add export to each line and run it. For instance, you would run export HELIUM_MAX_COPIES=15 variable. Do NOT put a space around the = sign

   

   Setting Environment Variables shown in a Terminal window.

8. Now, you are ready to generate your first route. Routes contain the necessary information for the network to know how to route a packet — DevEUI+AppEUI (for routing join requests), DevAddr range (for routing uplinks), Endpoint (so we know where to send the packet to), etc.

   1. Run ./main route new --commit
   2. You can then see the empty route template. It should look like this, except that you should be seeing your Net ID, assigned OUI, and max_copies:

   

   Route Creation as shown in a Terminal window.

9. Next, let’s define DevAddr range so packet router knows which uplinks to route to your endpoint. Just use your OUI’s assigned DevAddr range, which you can get by running ./main org get. Afterwards, run:

   $ ./main route devaddrs add -s <start> -e <end> --route-id <route-id> --commit

10. Next, let’s define EUI pairs so packet router knows which join requests to route to your endpoint. You can run:

    $ ./main route euis add --route-id <route-id> -d <dev-eui> -a <app-eui> --commit

11. Next, let’s define the endpoint that you use for ingesting traffic. You can run:

    $ ./main route update server --host <host> --port <port> --route-id <route-id> --commit

12. Lastly, define other relevant parameters for HTTP roaming. You can run:

    $ ./main route update http --dedupe-timeout <dedupe-timeout> --path <url path> --auth-header <auth-header> --route-id <route-id> --commit

13. Fund your OUI
    You will need to keep your OUI funded with a minimum of 3.5 million data credits (equivalent to $35 USD) at all times to ensure data transfer. If the balance falls below
    3.5 million data credits your OUI may be locked.

To fund your OUI, you will delegate data credits to your payer key (Helium public wallet address). Your delegated data credits will then be held in an escrow account. To delegate data credits to your OUI, you can utilize one of the following options:

• Use the Sphere tool to pay with a credit card (USA only)
• Use the Sphere to convert HNT directly to your OUI. Select a payment method, connect a wallet, specify the quantity, and enter your OUI.
• Delegate data credits directly from the Helium wallet.
  1. Make sure you have a data credit balance. If necessary, swap HNT for DCs using the “Swap” feature in the wallet app.
  2. Select the DC assets in the wallet
  3. Click “delegate” and select the “IOT subDAO”.
     Make sure to select the IoT SubDao. Data credits delegated to the MOBILE subDAO can not be used to pay for IoT traffic.
     Note: You can only delegate data credits once, and if you delegate to the Mobile Subdao this cannot be undone.
  4. Enter your payer key and the DC amount you wish to delegate.
  5. Swipe to delegate
     Note: You need a small amount of SOL to complete any transaction. You can fund your wallet by sending SOL to your Solana address in the Helium Wallet App.

To confirm your escrow account is properly funded, you can utilize the Sphere tool by entering your OUI number and viewing the associated keys.