# lorabasics/basicstation architecture

> Architecture diagram of the GitHub repository lorabasics/basicstation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lorabasics/basicstation
- Repository: https://github.com/lorabasics/basicstation

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Platform Layer
    subgraph "Platform Layer" 
        direction TB
        SysLinux["Platform Abstraction (sys_linux.c/h)"]:::plat
        SysLogLinux["Linux Logging Integration (sys_log.c)"]:::plat
        SysFIFO["FIFO & Remote Shell (cmdfifo.c, rmtsh.c)"]:::plat
        WebLinux["Web Interface (web_linux.c)"]:::plat
    end

    %% Station Core
    subgraph "Station Core" 
        direction TB
        StationMain["Entry Point & Daemon Control (station_main.c)"]:::core
        ConfigMgr["Configuration Manager (s2conf.c/h)"]:::core
        ParamStore["Parameter Storage FS (fs.c/h)"]:::core
        LoggingCore["Core Logging Interface (log.c, sys.c)"]:::core
        TimeSync["Time Synchronization (timesync.c/h)"]:::core
        SelfTests["Self-Test Suite (selftests.c/h)"]:::core
    end

    %% Radio Abstraction Layer
    subgraph "Radio Abstraction Layer" 
        direction TB
        RALGeneric["Generic API (ral.c/h)"]:::ral
        RALLGW["Semtech Glue v1.x (ral_lgw.c)"]:::ral
        RALLGW2["Semtech Glue v2.x (ral_lgw2.c)"]:::ral
        RALMaster["Master/Slave (ral_master.c, ral_slave.c)"]:::ral
        RALDriver["libloragw/Corecell Drivers"]:::ral
    end

    %% Network & Protocol Stack
    subgraph "Network & Protocol" 
        direction TB
        TLSLayer["TLS Layer (tls.c/h)"]:::net
        TCHandler["TC Protocol Handler (tc.c/h)"]:::net
        CUPSHandler["CUPS Protocol Handler (cups.c/h)"]:::net
        HTTPServer["HTTP/HTTPS Server (httpd.h, web.c/h)"]:::net
        JSON["JSON Handling (uj.c/h)"]:::net
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Concentrator["Concentrator Hardware (SPI/USB)"]:::ext
        LNS["LNS (TC over WebSocket/TLS)"]:::ext
        CUPSServer["CUPS Server (HTTPS/TLS)"]:::ext
    end

    %% Simulation & Examples
    subgraph "Examples & Simulation"
        direction TB
        Simulation["Simulation Env (examples/simulation/)"]:::infra
        Station2PKFwd["Station2Pkfwd Bridge"]:::infra
    end

    %% Build & Test Infrastructure
    subgraph "Build & Test Infra"
        direction TB
        BuildSystem["Makefiles, setup.gmk, Dockerfile"]:::infra
        CI["CI Workflow & Tests (regr-tests/)"]:::infra
    end

    %% Connections
    StationMain -->|orchestrates| ConfigMgr
    StationMain -->|orchestrates| ParamStore
    StationMain -->|orchestrates| LoggingCore
    StationMain -->|orchestrates| TimeSync
    StationMain -->|orchestrates| SelfTests
    StationMain -->|uses| RALGeneric
    StationMain -->|uses| TLSLayer

    %% Platform to Core
    SysLinux -->|provides threads/timers/sockets| StationMain
    SysLogLinux -->|integrates logging| LoggingCore
    SysFIFO -->|provides remote shell| StationMain
    WebLinux -->|provides web API| HTTPServer

    %% RAL to Platform
    RALGeneric -->|calls| RALLGW
    RALGeneric -->|calls| RALLGW2
    RALGeneric -->|calls| RALMaster
    RALMaster -->|uses| SysLinux
    RALGeneric -->|drives| Concentrator
    RALDriver -->|driver libs| RALLGW
    RALDriver -->|driver libs| RALLGW2

    %% Network flows
    StationMain -->|sends/receives| TCHandler
    StationMain -->|requests config| CUPSHandler
    TCHandler -->|over WebSocket/TLS| LNS
    CUPSHandler -->|over HTTPS/TLS| CUPSServer
    HTTPServer -->|serves| Simulation
    TLSLayer -->|wraps| TCHandler
    TLSLayer -->|wraps| CUPSHandler

    %% JSON usage
    TCHandler -->|parses/serializes| JSON
    CUPSHandler -->|parses/serializes| JSON
    HTTPServer -->|parses/serializes| JSON

    %% Simulation & Bridge
    Simulation -->|injects frames| RALGeneric
    Simulation -->|emulates servers| LNS
    Station2PKFwd -->|bridges| TCHandler
    Station2PKFwd -->|connects to| LNS

    %% Build & CI
    BuildSystem -->|builds| StationMain
    CI -->|tests| StationMain
    CI -->|runs| Simulation

    %% Click Events
    click StationMain "https://github.com/lorabasics/basicstation/blob/master/src-linux/station_main.c"
    click ConfigMgr "https://github.com/lorabasics/basicstation/blob/master/src/s2conf.c"
    click ConfigMgr "https://github.com/lorabasics/basicstation/blob/master/src/s2conf.h"
    click ParamStore "https://github.com/lorabasics/basicstation/blob/master/src/fs.c"
    click ParamStore "https://github.com/lorabasics/basicstation/blob/master/src/fs.h"
    click LoggingCore "https://github.com/lorabasics/basicstation/blob/master/src/log.c"
    click LoggingCore "https://github.com/lorabasics/basicstation/blob/master/src/sys.c"
    click SysLogLinux "https://github.com/lorabasics/basicstation/blob/master/src-linux/sys_log.c"
    click TimeSync "https://github.com/lorabasics/basicstation/blob/master/src/timesync.c"
    click TimeSync "https://github.com/lorabasics/basicstation/blob/master/src/timesync.h"
    click SelfTests "https://github.com/lorabasics/basicstation/blob/master/src/selftests.c"
    click SelfTests "https://github.com/lorabasics/basicstation/blob/master/src/selftests.h"
    click RALGeneric "https://github.com/lorabasics/basicstation/blob/master/src/ral.c"
    click RALGeneric "https://github.com/lorabasics/basicstation/blob/master/src/ral.h"
    click RALLGW "https://github.com/lorabasics/basicstation/blob/master/src/ral_lgw.c"
    click RALLGW2 "https://github.com/lorabasics/basicstation/blob/master/src/ral_lgw2.c"
    click RALMaster "https://github.com/lorabasics/basicstation/blob/master/src-linux/ral_master.c"
    click RALMaster "https://github.com/lorabasics/basicstation/blob/master/src-linux/ral_slave.c"
    click RALDriver "https://github.com/lorabasics/basicstation/tree/master/deps/lgw/"
    click RALDriver "https://github.com/lorabasics/basicstation/tree/master/deps/lgw1302/"
    click TLSLayer "https://github.com/lorabasics/basicstation/blob/master/src/tls.c"
    click TLSLayer "https://github.com/lorabasics/basicstation/blob/master/src/tls.h"
    click TCHandler "https://github.com/lorabasics/basicstation/blob/master/src/tc.c"
    click TCHandler "https://github.com/lorabasics/basicstation/blob/master/src/tc.h"
    click CUPSHandler "https://github.com/lorabasics/basicstation/blob/master/src/cups.c"
    click CUPSHandler "https://github.com/lorabasics/basicstation/blob/master/src/cups.h"
    click HTTPServer "https://github.com/lorabasics/basicstation/blob/master/src/httpd.h"
    click HTTPServer "https://github.com/lorabasics/basicstation/blob/master/src/http.h"
    click HTTPServer "https://github.com/lorabasics/basicstation/blob/master/src/web.c"
    click HTTPServer "https://github.com/lorabasics/basicstation/blob/master/src/web.h"
    click JSON "https://github.com/lorabasics/basicstation/blob/master/src/uj.c"
    click JSON "https://github.com/lorabasics/basicstation/blob/master/src/uj.h"
    click SysLinux "https://github.com/lorabasics/basicstation/blob/master/src-linux/sys_linux.c"
    click SysLinux "https://github.com/lorabasics/basicstation/blob/master/src-linux/sys_linux.h"
    click SysFIFO "https://github.com/lorabasics/basicstation/blob/master/src-linux/cmdfifo.c"
    click SysFIFO "https://github.com/lorabasics/basicstation/blob/master/src-linux/commands.c"
    click SysFIFO "https://github.com/lorabasics/basicstation/blob/master/src-linux/rmtsh.c"
    click WebLinux "https://github.com/lorabasics/basicstation/blob/master/src-linux/web_linux.c"
    click Simulation "https://github.com/lorabasics/basicstation/tree/master/examples/simulation/"
    click Station2PKFwd "https://github.com/lorabasics/basicstation/tree/master/examples/station2pkfwd/"
    click BuildSystem "https://github.com/lorabasics/basicstation/tree/master/makefile"
    click BuildSystem "https://github.com/lorabasics/basicstation/blob/master/setup.gmk"
    click BuildSystem "https://github.com/lorabasics/basicstation/tree/master/Dockerfile"
    click CI "https://github.com/lorabasics/basicstation/tree/master/regr-tests/"
    click CI "https://github.com/lorabasics/basicstation/blob/master/.github/workflows/regr-tests.yml"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#2f6f9f,color:#0a2f5a;
    classDef ral fill:#d9ead3,stroke:#6a994e,color:#264d23;
    classDef net fill:#fce5cd,stroke:#bf7530,color:#7a3519;
    classDef plat fill:#e2f0d9,stroke:#5a7d3c,color:#2e471c;
    classDef ext fill:#f4cccc,stroke:#cc4a3b,color:#7f1c1c;
    classDef infra fill:#d9d2e9,stroke:#5a4e85,color:#2e1a4e;
```
