Skip to main content

Getting started with Roaming

Config Service is an Oracle service that stores all routing information on the Helium IoT Network. Each roaming partner is registered in the Config Service under their Net ID, and may define multiple routes. Each route contains information such as

  • DevEUI+AppEUI pairs — so we know which join requests to send your way
  • DevAddr ranges — so we know 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).

Let’s do some setup with the CLI.

  1. Run this to pull & build the config service cli
git clone
curl -sSf | sh
source "$HOME/.cargo/env"
cd helium-config-service-cli
cargo b --release
  1. You can then find the built binary file helium-config-service.cli under ./target/release inside the helium-config-service-cli directory. I’d rename it into short such as main so you can type less words ( you can rename it by running mv helium-config-service-cli main)

  2. Now that we have the CLI binary, let’s just put it in a separate folder. This is recommended only for simplicity 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 .
  1. Let’s generate the keypair you’ll be using to authenticate your interactions with the config service, so only you can create/modify/delete routes. Run ./main env generate-keypair --commit and you should find a file called keypair.bin. Print out the public key of your keypair by running

    ./main env info --keypair keypair.bin
  2. Next, make sure you have a Helium Wallet. You can download them here.

  3. Contact the Helium Foundation with your public key and Helium Wallet address via email at for the information needed in the next steps.

  4. 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 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 number of multi-buy 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
  5. Now, you are ready to generate your first route. Routes contain necessary information for us 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 you own Net ID, assigned OUI, max_copies in there
  6. 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
  7. 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
  8. 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
  9. 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