Skip to content

Commit

Permalink
Cleanup pass
Browse files Browse the repository at this point in the history
  • Loading branch information
@jthiller
jthiller committed Sep 13, 2023
1 parent 97c2353 commit c945546
Showing 1 changed file with 80 additions and 106 deletions.
186 changes: 80 additions & 106 deletions docs/network-iot/lorawan-roaming.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,55 +9,28 @@ slug: /iot/lorawan-roaming
---

import useBaseUrl from '@docusaurus/useBaseUrl'
import LegacyContentBanner from '@site/src/theme/LegacyContentBanner'

<LegacyContentBanner />

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

Helium Roaming Services enables public and private LoRaWAN Network providers around the world to
leverage Helium’s ubiquitous coverage.

## Helium Roaming Architecture

<!-- TODO: helium network roaming _does_ follow LoRaWAN Roaming 1.1 spec. add links and info here. --->

<!-- TODO: Helium can forward packets for a given NetID following the 1.1 spec. --->

<!-- TODO: what is a NetID -->

---

## Roaming Integration Overview

Considering the entire global network, this can become a large number of Hotspots. In practice, only
a small percentage of Helium Gateways will be routing packets for a roaming partner NetID
simultaneously.

Helium provides one or more IPs from where the connections will originate. Once the IP and port for
the host listening for Semtech GWMP connections over UDP are provided, packets will start arriving
at the specified host.

---
public and private LoRaWAN Network providers wanting to expand their coverage without deploying
additional infrastructure.

## Roaming Quickstart

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
The [Helium Config Service](https://github.com/helium/oracles/tree/main/iot_config) 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 we know which join requests to send your way
- **DevAddr ranges** — so we know which uplinks to send your way
- **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).

Let’s do some setup with the CLI.
### CLI

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

```bash
$ git clone https://github.com/helium/helium-config-service-cli.git
Expand All @@ -67,11 +40,12 @@ Let’s do some setup with the CLI.
$ cargo b --release
```

2. 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`)
1. 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
1. 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:
Expand All @@ -82,38 +56,41 @@ Let’s do some setup with the CLI.
$ 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, so only you can create/modify/delete routes. Run this command twice for 1) owner keypair and
2) delegate kepair and name files accordingly. Run
`./main env generate-keypair <key file name>.bin.` and you should find a file called
1. 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:
```bash
$ ./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.
**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.
5. Next, make sure you have a Helium Wallet.
**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.
1. Next, make sure you have a Helium Wallet.
[You can download them here](https://wallet.helium.com/).
6. Contact the Helium Foundation with your public key and Helium Wallet address via email at
1. Contact the Helium Foundation with your public key and Helium Wallet address via email at
[[email protected]](mailto:[email protected]) 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
1. 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`
1. Fill in `http://mainnet-config.helium.io:6080/` for `Config Service Host`
1. Fill in the path `./keypair.bin` for `Keypair Location`
1. Fill in your NET ID for `Net ID`
1. Fill in your OUI for `Assigned OUI`
1. Fill in the number of multi-buy you want for `Default Max Copies` as a default for your
routes.
1. Fill in the multi-buy value you want for `Default Max Copies` as a default for your routes.
1. 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
Expand All @@ -122,81 +99,78 @@ Let’s do some setup with the CLI.
<img
src={useBaseUrl('img/open-lns/roaming-setup-env-variables.png')}
style={{ maxHeight: 350, minWidth: 0, flex: '1 1 auto' }}
className="add-shadow add-shadow-margin"
/>
<figcaption>
<a>Setting Environment Variables shown in a Terminal window.</a>.
</figcaption>
<figcaption>Setting Environment Variables shown in a Terminal window.</figcaption>
</figure>
8. 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. 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`
1. You can then see the empty route template. It should look like this, except that you should be
seeing your own Net ID, assigned OUI, max_copies in there:
seeing your Net ID, assigned OUI, and max_copies:
<figure className="screensnippet-wrapper">
<img
src={useBaseUrl('img/open-lns/roaming-setup-generate-route.png')}
style={{ maxHeight: 350, minWidth: 0, flex: '1 1 auto' }}
className="add-shadow add-shadow-margin"
/>
<figcaption>
<a>Route Creation shown in a Terminal window.</a>.
</figcaption>
<figcaption>Route Creation as shown in a Terminal window.</figcaption>
</figure>
9. Next, let’s define DevAddr range so packet router knows which uplinks to route to your endpoint.
1. 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:
```bash
$ ./main route devaddrs add -s <start> -e <end> --route-id <route-id> -- commit
$ ./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:
1. Next, let’s define EUI pairs so packet router knows which join requests to route to your
endpoint. You can run:
```bash
$ ./main route euis add --route-id <route-id> -d <dev-eui> -a <app-eui> --commit
```
```bash
$ ./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:
1. Next, let’s define the endpoint that you use for ingesting traffic. You can run:
```bash
$ ./main route update server --host <host> --port <port> --route-id <route-id> --commit
```
```bash
$ ./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:
```bash
$ ./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
1. Lastly, define other relevant parameters for HTTP roaming. You can run:
```bash
$ ./main route update http --dedupe-timeout <dedupe-timeout> --path <url path> --auth-header <auth-header> --route-id <route-id> --commit
```
1. 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.
**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.

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 burn HNT directly to your OUI. Select payment method, connect wallet,
specify 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 you escrow account is properly fundend, you can utilize the Sphere tool by entering
your OUI number and viewing the associated keys.
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](/tokens/data-credit-portal) 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.
1. Select the DC assets in the wallet
1. 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.
1. Enter your payer key and the DC amount you wish to delegate.
1. 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.

0 comments on commit c945546

Please sign in to comment.