helium/helium-packet-router
41.0
Weak · 15 November 2026
14.5k
lines of production code
Erlang
primary language
4
measurements over time
What this system is
This system is a Helium Packet Router that manages LoRaWAN uplink and downlink traffic through multiple protocol handlers, including Semtech UDP, HTTP roaming, and GWMP. It provides intelligent routing capabilities such as multi-buy logic, gateway denylisting, and session management, while persisting configuration data via ETS and DETS. The service exposes operational visibility through Prometheus metrics and CLI diagnostics, and supports production deployment via Docker containers and Debian packages.
Features
Add Debian packaging support with systemd integration
This change introduces Debian package build support via a new .mk file and associated control scripts. It adds pre/post install and upgrade hooks to manage a system user ('helium') and symlink the 'hpr' binary to /usr/local/bin, ensuring the command is available in the PATH. A systemd service unit file (hpr.service) is included to run the application as the 'helium' user with specific resource limits and logging configurations. Additionally, the application configuration file has been moved from config/sys.config to deb/local.conf to align with the packaging structure.
deb · high confidence
Add HTTP roaming, metrics, and protocol definitions
This change introduces new Erlang header files that define core data structures and constants for the system. It adds the \http\_protocol\ record in \hpr\_http\_roaming.hrl\ to support HTTP-based roaming with fields for routing, deduplication, and authentication. It defines a comprehensive set of Prometheus metrics (gauges, histograms, counters) in \hpr\_metrics.hrl\ for monitoring GRPC connections, packet flows, multi-buy decisions, and gateway liveness. It also establishes Semtech UDP protocol constants and error codes in \semtech\_udp.hrl\, and updates \hpr.hrl\ with configuration keys for the IoT config service, location, downlink, and multi-buy channels, as well as the default metrics port.
include · high confidence
Add RustFS initialization script for S3 bucket setup
Added a new initialization script (init.sh) for the RustFS infrastructure component that creates the 'test-bucket' S3 bucket using the local endpoint at http://rustfs:9000, ensuring the bucket exists before report uploaders begin writing data.
infra · high confidence
Docker support and CI test infrastructure
Added Dockerfile, .dockerignore, and environment templates to enable containerized builds and runtime for the Helium Packet Router. Introduced docker-compose.yaml for local development with a rustfs S3-compatible storage fixture, and docker-compose-test.yaml to run the full test suite (xref, eunit, dialyzer, and Common Test suites) in isolated containers against that fixture. Updated the Makefile with new targets (docker-build, docker-test, docker-run, grpc) and configured rebar.config to support these workflows, including test profile dependencies and coverage export.
(repo-wide) · high confidence
HTTP roaming protocol support
Added HTTP-based roaming capabilities for LoRaWAN devices, including uplink payload construction, downlink message handling, and authentication header management. The implementation introduces a new roaming worker to manage packet buffering and transmission, a supervisor for worker lifecycle, and a dedicated downlink stream worker to receive and process incoming downlink data via gRPC streaming.
src/protocols/http · high confidence
Introduce GWMP protocol implementation with UDP worker supervision
This change adds the core components for the GWMP (Semtech UDP) protocol support, including a supervisor (\hpr\_gwmp\_sup\) to manage dynamic UDP worker processes and a worker (\hpr\_gwmp\_worker\) that handles the bidirectional communication with gateways. The implementation includes the \semtech\_udp\ module for encoding and decoding protocol packets (push\_data, pull\_data, pull\_resp, etc.) and introduces stream monitoring logic to track gateway connectivity and handle reconnections, enabling the system to receive uplinks and send downlinks via the standard Semtech protocol.
src/protocols/gwmp · high confidence
Introduce new gRPC packet router envelope and session types
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. On the uplink side, envelopes now handle gateway registration and session initialization messages alongside standard packets, allowing gateways to establish secure sessions with session keys and nonces. These changes provide the structural foundation for session-based routing and enhanced downlink control within the gRPC interface.
_src/grpc/packet\router · high confidence
Introduces gateway denylist, liveness reporting, and multi-buy routing logic
The Packet Router now supports operator-controlled gateway denylists that persist across restarts via Dets, allowing specific gateways to be blocked from sending uplinks. It also tracks gateway liveness and periodically uploads compressed reports to S3 for monitoring. Additionally, the system implements custom multi-buy logic with ETS-backed caching and gRPC channels to manage packet duplication limits per hotspot/region, while introducing a routing cache to handle concurrent packet processing and prevent race conditions during route establishment.
src · high confidence
New CLI extension scripts for console management
Added four new shell scripts in the scripts/extensions directory—config, denylist, info, and trace—that allow users to interact with the hpr\_console via the relx\_nodetool RPC interface. The config script specifically extends the default relx RPC timeout from 60 to 300 seconds if not already overridden, while the other scripts provide direct command execution capabilities for managing configuration, denylists, information retrieval, and tracing.
scripts · high confidence
New HPR CLI commands for configuration, tracing, and diagnostics
The CLI now includes a comprehensive set of commands for managing the High-Priority Routing (HPR) system. Users can configure routes and OUIs (activate, deactivate, refresh, sync), manage the gateway denylist (add, remove, reset), and trace traffic by gateway, DevAddr, or EUI. Additionally, new info commands allow exporting connected hotspot IPs and network ID statistics to JSON files, and the public key can be displayed directly.
src/cli · high confidence
New HPR-specific metrics and stats tracking
Added new modules to track High-Priority Relay (HPR) system performance and state. The \hpr\_metrics\ module exposes Prometheus histograms and counters for packet up/down events, routing lookups, gRPC connections, multi-buy decisions, ICS updates, and gateway location reports. The \hpr\_device\_stats\ module maintains an ETS table of device keys with timestamps, automatically purging entries older than 24 hours to provide an approximate daily device count. The \hpr\_netid\_stats\ module tracks Network ID usage counts, also with automatic 24-hour cleanup. A new \hpr\_metrics\_handler\ exposes these metrics via a \/metrics\ HTTP endpoint for Prometheus scraping.
src/metrics · high confidence
New IoT config storage modules for routes, EUI pairs, and DevAddr ranges
The iot\_config service now includes dedicated storage modules (hpr\_route\_storage, hpr\_eui\_pair\_storage, hpr\_devaddr\_range\_storage) that persist route configurations, EUI pairs, and DevAddr ranges in ETS tables with DETS checkpointing. These modules handle data hydration on startup, support migration from legacy formats (e.g., char lists to binaries for route IDs), and provide efficient lookup and indexing capabilities for the routing system.
_src/grpc/iot\config · high confidence
New protocol router and gateway protocol implementations
The system now includes a new protocol router (\hpr\_protocol\_router\) that manages gRPC streams to network servers, featuring automatic cleanup of stale connections every 10 minutes and backoff logic for connection failures. Additionally, new protocol handlers have been added for GwMP (\hpr\_protocol\_gwmp\) and HTTP Roaming (\hpr\_protocol\_http\_roaming\), enabling the system to send uplink packets to gateways and remote network servers respectively, with retry logic and specific handling for gateway locations and authentication headers.
src/protocols · high confidence
Behavioural changes
Production configuration overhaul with environment variable injection and VM tuning
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
Test coverage
Expanded test coverage for packet routing, configuration, and reporting components
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 cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 43 → 41 (-1.9)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.
Lenses
- Code Health 74 → 72 (-1.4)
- Architecture 97 → 97 (+0.0)
- Maturity 67 → 71 (+3.6)
- Readiness 42 → 42 (-0.0)
- Security 66 → 51 (-15.3)
- Event-Driven 27 → 27 (+0.0)
Resolved (2)
- No ADRs found
- Off-boarding risk: anonymized user #1
New (25)
- Edited copies of one member (3 members, 14+ corresponding lines) (src/grpc/iot_config/hpr_devaddr_range_storage.erl)
- Edited copies of one member (3 members, 34+ corresponding lines) (src/grpc/iot_config/hpr_route_stream_worker.erl)
- Edited copies of one member (4 members, 13+ corresponding lines) (src/grpc/packet_router/hpr_packet_up.erl)
- Edited copy of a member (10 corresponding lines) (src/cli/hpr_cli_config.erl)
- Edited copy of a member (10 corresponding lines) (src/cli/hpr_cli_denylist.erl)
- Edited copy of a member (11 corresponding lines) (src/grpc/iot_config/hpr_devaddr_range_storage.erl)
- Edited copy of a member (12 corresponding lines) (src/cli/hpr_cli_config.erl)
- Edited copy of a member (12 corresponding lines) (src/grpc/iot_config/hpr_gateway_location.erl)
- Edited copy of a member (14 corresponding lines) (src/grpc/iot_config/hpr_eui_pair_storage.erl)
- Edited copy of a member (15 corresponding lines) (src/grpc/iot_config/hpr_devaddr_range_storage.erl)
- Edited copy of a member (18 corresponding lines) (src/grpc/iot_config/hpr_gateway_liveness_storage.erl)
- Edited copy of a member (25 corresponding lines) (src/grpc/iot_config/hpr_devaddr_range_storage.erl)
- Edited copy of a member (3 corresponding lines) (src/grpc/iot_config/hpr_devaddr_range_storage.erl)
- Edited copy of a member (3 corresponding lines) (src/grpc/iot_config/hpr_devaddr_range_storage.erl)
- Edited copy of a member (3 corresponding lines) (src/grpc/iot_config/hpr_eui_pair_storage.erl)
- Edited copy of a member (3 corresponding lines) (src/hpr_routing_cache.erl)
- Edited copy of a member (4 corresponding lines) (src/grpc/iot_config/hpr_devaddr_range_storage.erl)
- Edited copy of a member (4 corresponding lines) (src/protocols/gwmp/semtech_udp.erl)
- Edited copy of a member (5 corresponding lines) (src/grpc/iot_config/hpr_gateway_liveness_storage.erl)
- Edited copy of a member (9 corresponding lines) (src/grpc/iot_config/hpr_devaddr_range_storage.erl)
- …and 5 more
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
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.
About this page
- The score is its most recent published measurement, taken on 15 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 83f7b645d91f9b5742c3961da4339f457c879127 — the exact code this score is about.
- Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.65+preprod-3c33c1882dc1.