helium/helium-packet-router

This system is the High-Priority Router (HPR), an Erlang-based service designed to manage LoRaWAN packet routing, roaming, and gateway management. It handles uplink and downlink traffic through multiple protocols, including Semtech UDP (GWMP) and HTTP roaming, while enforcing multi-buy policies and maintaining gateway liveness. The system provides comprehensive operational capabilities such as Prometheus metrics, S3-based reporting, and a CLI for configuration and debugging, packaged for production deployment via Debian and Docker.

Added a new initialization script for RustFS that creates the 'test-bucket' S3 bucket via the local endpoint, ensuring the storage infrastructure is ready for report uploaders.

infra · high confidence

The project now provides a multi-stage Dockerfile for building the release and a slim runtime image, alongside docker-compose configurations for local development and CI testing. A new docker-compose-test.yaml orchestrates the full test suite (xref, eunit, dialyzer, and Common Test suites) in isolated containers against a RustFS S3-compatible storage instance, ensuring consistent test environments. The Makefile has been updated to support these Docker workflows (docker-build, docker-test) and includes workarounds for modern compiler toolchains affecting dependencies like enacl and h3.

(repo-wide) · high confidence

Added HTTP-based roaming capabilities for LoRaWAN gateways, enabling uplink transmission and downlink delivery via HTTP endpoints. This includes a new roaming worker to manage packet batching and transaction states, a downlink stream worker to handle incoming downlink requests from the network server, and utility modules for token generation, authentication headers, and data formatting.

src/protocols/http · high confidence

This change introduces the necessary scripts and configuration files to package the HPR application as a Debian package. It includes pre- and post-installation/upgrade scripts to manage the 'helium' system user, create a symlink for the 'hpr' command in /usr/local/bin, and handle removal. Additionally, it provides a systemd service unit file (hpr.service) to run the application as a background service under the 'helium' user, along with a local configuration file adapted from the previous sys.config.

deb · high confidence

This change introduces the core components for the GWMP (Semtech UDP) protocol, including the \hpr\_gwmp\_sup\ supervisor for managing worker processes, the \hpr\_gwmp\_worker\ gen\_server for handling UDP socket communication and packet routing, and the \semtech\_udp\ module for encoding and decoding protocol messages. This establishes the foundational infrastructure for gateway-to-server communication via the standard Semtech protocol.

src/protocols/gwmp · high confidence

This change adds the foundational Erlang modules for the Helium Packet Router's core data path and operational reporting. It introduces \hpr\_routing\ and \hpr\_routing\_cache\ to handle packet validation, route lookup (including DevAddr range and EUI pair lookups), and caching of routing states to prevent race conditions during route establishment. It adds \hpr\_multi\_buy\ to enforce multi-buy limits using local ETS counters and optional external service checks, supporting both default and custom multi-buy routes. Additionally, it implements \hpr\_packet\_reporter\ and \hpr\_gateway\_liveness\_reporter\ to aggregate and upload packet and gateway liveness data to S3 (or S3-compatible endpoints) using dedicated credentials and compression. Supporting modules include \hpr\_denylist\ for persistent gateway blocking, \hpr\_s3\_client\ for flexible S3 client construction, \hpr\_lorawan\ for LoRaWAN-specific MIC and frame counter validation, and \hpr\_http\_roaming\_register\ for handling HTTP roaming registration signatures.

src · high confidence

Added shell scripts in the scripts/extensions directory (config, denylist, info, trace) that allow users to invoke specific console commands via the relx\_nodetool RPC interface. The config script also extends the default RPC timeout from 60s to 300s if not already overridden, and all scripts detect terminal width for potential formatting needs.

scripts · high confidence

The CLI now includes a comprehensive set of commands for managing the High-Priority Router (HPR) system. Users can configure routes and OUIs (including activation, deactivation, and synchronization), view system information such as public keys and network ID statistics, and trace specific gateways or device addresses for debugging. Additionally, a new gateway denylist feature allows administrators to list, add, remove, or reset blocked gateways, with changes persisted to disk.

src/cli · high confidence

The iot\_config service now includes dedicated Erlang modules for managing High-Priority Roaming (HPR) entities, introducing structured data types and ETS/DETS-backed storage for routes, device address ranges, EUI pairs, and gateway liveness/location. This adds the ability to persist and query route configurations (including multi-buy and protocol details), map device addresses to routes via an optimized bucketed index, track gateway connection timestamps and geographic locations, and handle migrations for legacy storage formats.

_src/grpc/iot\config · high confidence

Added a new metrics module for the HPR (High-Priority Routing) system, introducing Prometheus-compatible counters and histograms for packet up/down events, routing lookups, gRPC connections, multi-buy operations, and ICS updates. The implementation includes ETS-backed storage for device statistics and network ID stats with automatic 24-hour cleanup, a dedicated gen\_server for metric observation, and an HTTP endpoint (/metrics) for Prometheus scraping.

src/metrics · high confidence

The packet router now supports a richer set of downlink and uplink message types via new envelope wrappers and session management structures. Downlink envelopes can now carry not only standard packets but also session offers and packet acknowledgments, enabling the router to signal session state changes and confirm delivery. Upstream, the router now handles gateway registration and explicit session initialization messages, allowing gateways to establish secure, key-based sessions. Additionally, a new liveness report type is introduced to track gateway availability, and packet reports now include payload size and hash details for better telemetry.

_src/grpc/packet\router · high confidence

The system now exposes new Erlang header files that define core data structures and configuration constants. The \hpr\_http\_roaming.hrl\ file introduces the \http\_protocol\ record, enabling HTTP-based roaming with support for specific route IDs, endpoints, flow types, deduplication timeouts, authentication headers, and receiver NSIDs. The \hpr\_metrics.hrl\ file adds a comprehensive set of Prometheus metric definitions, including gauges and histograms for tracking GRPC connections, packet up/down counts, route status, EUI pairs, SKFs, broken routes, multi-buy operations, and device counts. Additionally, \semtech\_udp.hrl\ defines constants for the Semtech UDP protocol, including message types and specific TX ACK error codes, while \hpr.hrl\ establishes application-wide settings such as the IoT config service channel, location and downlink channels, and the default metrics port.

include · high confidence

The system now includes dedicated protocol handlers for HTTP roaming and GWMP, allowing packets to be routed via these specific methods. The \hpr\_protocol\_http\_roaming\ module handles HTTP-based packet forwarding with configurable deduplication and authentication headers, while \hpr\_protocol\_gwmp\ manages GWMP-specific downlink pushes. These are coordinated by a new \hpr\_protocol\_router\ gen\_server, which maintains active streams in an ETS table, implements exponential backoff for connection retries, and performs periodic cleanup of stale or dead gateway streams every 10 minutes to prevent resource leaks.

src/protocols · high confidence

The configuration files have been significantly updated to support production deployment. The main application config (sys.config.src) now uses environment variables for sensitive data (AWS credentials, service endpoints) and operational settings (multi-buy toggle, metrics port), replacing hardcoded test values. New configuration files (ct.config, grpc\_gen.config) have been added to define test service mocks and gRPC code generation plugins. Additionally, the VM arguments (vm.args) have been tuned for high-throughput workloads by increasing the process limit to 2 million, disabling scheduler busy-waiting to reduce CPU overhead, and setting ERL\_FULLSWEEP\_AFTER to 20 to optimize garbage collection for long-running processes.

config · high confidence

Added comprehensive Common Test suites to verify core packet routing and configuration behaviors. The new \hpr\_cli\_config\_SUITE\ tests route synchronization logic, including adding, removing, and activating routes. \hpr\_gateway\_liveness\_reporter\_SUITE\ and \hpr\_packet\_reporter\_SUITE\ validate the reporting of gateway liveness and packet data to S3-compatible storage, ensuring correct file naming, compression, and data integrity. Additional suites cover \hpr\_gateway\_location\ retrieval, \hpr\_metrics\ exposure, \hpr\_packet\_router\_service\ session handling, \hpr\_protocol\_gwmp\ and \hpr\_protocol\_http\_roaming\_packet\ protocol compliance, and \hpr\_protocol\_router\ connection stability.

test · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 43.

• Code Health 95
• Architecture 96
• Maturity 62
• Readiness 47
• Security 50
• Event-Driven 27

• 212 commits — 180 feature/other, 32 fixes

• src/grpc — 59 commits
• (root) — 47 commits
• src/protocols — 44 commits
• src/cli — 12 commits
• .github/workflows — 9 commits
• src/hpr_routing.erl — 7 commits
• config/ct.config — 4 commits
• config/sys.config — 4 commits
• src/hpr.app.src — 4 commits
• config/vm.args — 3 commits
• include/hpr_metrics.hrl — 3 commits
• src/hpr_multi_buy.erl — 3 commits
• src/metrics — 3 commits
• config/sys.config.src — 2 commits
• .github/ISSUE_TEMPLATE — 1 commit
• include/hpr.hrl — 1 commit
• src/hpr_config.erl — 1 commit
• src/hpr_config_worker.erl — 1 commit
• src/hpr_lorawan.erl — 1 commit
• src/hpr_packet_reporter.erl — 1 commit

• fix: * Fix SKF metric (#219)
• fix: 1.4.1 Fixes (#297)
• fix: Add Multi Buy documentation and fix error class handling (#332)
• fix: Devaddr range cache fixes (#328)
• fix: Fix CLI and add info CLI (#92)
• fix: Fix CLI to handle Timestamp (#323)
• fix: Fix cancel GHA name (#107)
• fix: Fix dangling SKF table references that crash route operations (#334)
• fix: Fix for grpc_client_deps (#58)
• fix: Fix give_away (#239)
• fix: Fix hpr_protocol_router crash (#167)
• fix: Fix hpr_protocol_router when stream or channel is dead (#150)
• fix: Fix insert_skf to remove old one (#250)
• fix: Fix keypos (#311)
• fix: Fix net ids export string (#316)
• fix: Fix refresh_skfs to handle error case clause (#298)
• fix: Fix some fullsweep after (#198)
• fix: Fix tests (#314)
• fix: Fix various crashes (#306)
• fix: Macpie/151 fix hpr config cli (#152)
• …and 192 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

helium/helium-packet-router was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.