Skip to content
CAI
Software that uses CAICheck a score

helium/helium-packet-router

41.0

Weak · 15 November 2026

14.5k

lines of production code

Erlang

primary language

4

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

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.