How lorabasics/basicstation works
Project Type and Purpose
• This is a gateway firmware/daemon written in portable C, implementing a LoRaWAN gateway.
• It runs on Linux-based hosts (e.g., Raspberry Pi, Corecell, PicoCell) and interfaces with Semtech concentrator hardware over SPI or USB.
• It implements two principal backend protocols: TC (transport/control) for real-time data forwarding to an LNS and CUPS for remote provisioning, configuration, and updates.
Main Architectural Layers and Components
A. Station Core
• station_main.c: entry point, daemon control (fork, respawn)
• Configuration manager (s2conf.c/h)
• Parameter storage (fs.c/h)
• Logging (sys_log.c, log.c)
• Time synchronization (timesync.c)
• Self-test suite (selftests.c)
B. Radio Abstraction Layer (RAL)
• ral.c/h: generic API for command/response
• ral_lgw.c, ral_lgw2.c, ral_master/slave (src-linux): glue to libloragw or corecell drivers
• libloragw (in deps/lgw, deps/lgw1302) for v1.x, v2.x, Corecell
C. Network & Protocol Stack
• TLS layer (tls.c/h) using mbedTLS (deps/mbedtls)
• TC Protocol handler (tc.c/h) over WebSocket (wss://)
• CUPS Protocol handler (cups.c/h) over HTTPS/REST
• HTTP/HTTPS server components (httpd.h, web.c/h) for interactive shell or local API
• JSON handling (uj.c/h) for messages
D. Platform-Specific Module
• src-linux/sys_linux.c/h: thread, timers, sockets on Linux
• sys_fifo, sys_log integration
E. Examples & Simulation
• examples/simulation: Python scripts (sim.py) driving a simulated station and CUPS/TC server
• station2pkfwd: Python bridge from Station’s protocol to legacy Pkfwd LNS
F. Build & Test Infrastructure
• Makefiles & setup.gmk for cross-compile
• Dockerfile for reproducible build
• GitHub Actions workflow (regr-tests.yml) for regression tests
• regr-tests: end-to-end, hardware-in-the-loop tests with certificate/key fixtures
Component Relationships and Data Flows
• Station Core invokes the RAL to send/receive LoRa packets.
• RAL drives the Concentrator hardware via SPI/USB (libloragw or corecell driver).
• Received LoRa frames → Core → TC Protocol → Remote LNS (via WebSocket/TLS).
• Station fetches config (channel plan, updates) via CUPS Protocol → CUPS Server (HTTPS/TLS).
• Local logs, metrics, or interactive shell → served by embedded HTTP server if enabled.
• All outgoing/incoming TLS traffic is handled by mbedTLS.
• Configuration files and certificates reside on local FS.
Architectural Patterns & Design Principles
• Layered Architecture: clear separation between core logic, hardware abstraction, networking, and platform specifics.
• Portable Core + Thin Platform Layer: all platform-dependent code sits in src-linux or prep scripts; core is pure ISO-C.
• Modular Protocol Handlers: separate modules for TC, CUPS, HTTP, JSON parsing.
• Event-Driven Loop: station_main orchestrates timed events (self-tests, time sync) and I/O callbacks.
• No Incoming Connections: all external comms are outbound, using secure TLS channels.
Putting It All Together
• If desired, add a bottom lane showing Build/Test Infrastructure (Makefiles, Docker, regr-tests) as supporting components.