Skip to content

Latest commit

 

History

History
128 lines (93 loc) · 8.07 KB

routing.md

File metadata and controls

128 lines (93 loc) · 8.07 KB
Raw

Routing

This document describes the routing mechanism implemented post HIP 70.

Basics

  1. Each Hotspot connects to a global Geo DNS Load Balancer 1 (LB). The LB then redirects each Hotspot to a cluster of Helium Packet Routers (HPR) in its own region. Ex: If a Hotspot is in San Francisco it will get round-robin2 to the North America Cluster, if another is in Paris France, it will get round-robin to the EU cluster. Note that each region may have a different number of servers to accomodate for load.
  2. Each HPR gets its routing information from Config Service (see Routing Configuration).
  3. Data is then routed to appropriate end-user's LoRaWAN Network Server (LNS)3.
flowchart LR
    subgraph USA
        H1(Hotspot 1)
        HPRUS(HPRs US)
    end
    subgraph EU
        H2(Hotspot 2)
        H3(Hotspot 3)
        HPREU(HPRs EU)
        HPREU(HPRs EU)
        
    end
    subgraph Global
        LB(Load Balancer)
        CS(Config Service)
    end
    subgraph LNSs
        LNS1(LoRaWAN Network Server 1)
        LNS2(LoRaWAN Network Server 2)
    end
    H1 --> LB
    H2 --> LB
    H3 --> LB
    LB -->|Hotspot 1| HPRUS
    LB -->|Hotspot 2| HPREU
    LB -->|Hotspot 3| HPREU
    HPRUS --> LNSs
    HPREU --> LNSs
    HPRUS <--> CS
    HPREU <--> CS
Loading

Configuration

All of the device routing information is contained in the Config Service (CS). The CS can be interacted via CLI or directly using the Proto APIs.

OUI

At the top of it all is the Org (or OUI) which defines a few things, like the owner, payer, and delegate keys (see here).

Upon request, an OUI is created and assigned by the Helium Foundation. You can, at this point, purchase Device Addresses or DevAddrs. If you would like to roam on the Helium network and already have your own LoRaWAN Net ID see here.

Route

Routes tells each HPR exactly where to send data packets. To create a Route we recommend using the Helium Config Service CLI.

  1. You will need to set your net_id, it should match the one assigned to you when you OUI was created.
  2. Set its oui.
  3. Set a server see here.
    1. Set a host and port
    2. Pick a protocol
      1. packet_router is used to talk to (legacy) Helium Router/Console
      2. gwmp (GateWay Message Protocol) is used to talk to Chirpstack
      3. http_roaming see here.
  4. Set default max_copies, maximum number of packet copies bought by HPR. Ex: if an uplink is seen by multiple Hotspots, how many copies of that packet will be purchased.
  5. Set active, enable and disable route.

Joins / EUIs

What are EUIS?

Device EUI and App EUI (aka EUIs) can be managed via the update_euis service. These are usually handled by the LNS. Helium's Router/Console already supports it and Chirpstack work is in progress.

Note: Any LNS or other entities that need to modify Routes or associated information need to be allowed to do so via a delegate key. Each service in the proto file should list the permission. This allows for programatic update without need for the OUI owner to do everything manually.

Uplinks / DevAddr Ranges

A DevAddr Range is a combination of start_addr and an end_addr that allows Routes to be confined to a specific range. Fox example, if my OUI is contained from 16#00000000 to 16#0000000A, I could create 2 Routes:

  1. Route 1: 16#00000000 to 16#00000005
  2. Route 2: 16#00000006 to 16#0000000A

Notes:

  • DevAddr ranges are inclusive on both sides.
  • DevAddr ranges can overlap.
  • If no range is set, by default, the Route will be set to the entire range of the OUI.

It is recommended to set a DevAddr Range and to avoid overlapping (even if allowed) as this will slow down data delivery to the LNSs.

Session Key Filters

What is a LoRaWAN Network Session Key?

A Session Key Filter (SKF) allows HPR to verify individual packets (without being able to decode the data). SKFs ensure that the packets are getting sent to the correct LNS, as well as charging the right account.

SKFs are usually kept up to date programatically by the LNS (API).

Note: Each SKF has a max_copies field which is the same concept as outlined previously in Route but is device specific. SKF max_copies takes precendent over a Route's max_copies. For example if the route defines max_copies to 1, and a device on that route has its SFK max_copies set to 5, up to 5 copies will be delivered for that device. However, setting a SKF max_copies to 0 will cause that device to use the Route's max_copies settings. If you are trying to not route packets for a device, the SKF for that device should be removed entirely.

Multi Buy

Multi buy or max_copies is the maximum number of copies, seen by different Hotspots, that can be bought by HPR. It can be set at 2 levels as seen previously, either Route or SKF.

A Multi Buy Service (MBS) is used as a distributed counter to make sure the proper number of copies is purchased. This service exists due to the fact that, Hotspots that are in close proximity might be connected to different HPRs in the cluster.

Note: If the MBS goes down, HPR will mark the packets as free to avoid charging users more than it should. This will also not reward Hotspots.

flowchart LR
    subgraph Sub Region
        HPR1(HPR 1)
        HPR2(HPR 2)
        HPR3(HPR 3)
        HPR4(HPR 4)
        MBS1(Multi Buy Service)
    end
    HPR1 <--> MBS1
    HPR2 <--> MBS1
    HPR3 <--> MBS1
    HPR4 <--> MBS1
Loading

Footnotes

  1. A Geo DNS load balancer is a tool that uses the location of the Hotspot to direct their requests to the best server or data center. It combines DNS and load balancing to optimize traffic distribution based on geography, reducing latency and improving user experience. ↩

  2. Round-robin algorithm evenly distributes requests among servers in a cyclic manner for balanced workload. ↩

  3. A LoRaWAN Network Server is a central component in a LoRaWAN network that manages devices data, routing, security, and communication between LoRaWAN devices and application servers. It handles device registration, data validation, encryption, and ensures data reaches the correct destination for processing. ↩