# jgromes/radiolib architecture

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

- Interactive diagram: https://gitdiagram.com/jgromes/radiolib
- Repository: https://github.com/jgromes/radiolib

## Overview

##### Project type and purpose
- RadioLib is an open‑source, cross‑platform embedded library for wireless communication modules.
- It provides drivers (“modules”) for dozens of radio chips, a hardware abstraction layer (HAL), a suite of protocols (AX.25, LoRaWAN, Morse, SSTV, etc.), and utility code (CRC, FEC, crypto).
- It is not a client/server or full‑stack web app; it is a layered C/C++ library designed to run on Arduino, ESP32/8266, RP2040, STM32, and even bare‑metal or RTOS‑based platforms.

##### File structure
Top‐level directories and files:
- src/
– hal/ : platform‐specific HAL headers & implementations (Arduino, RPi, Pico, etc.)
– modules/ : per‑chip drivers (e.g., CC1101, SX127x, LR11x0…)
– protocols/ : digital protocol implementations built atop the module drivers
– utils/ : shared helpers (CRC, FEC, cryptography, general utilities)
– RadioLib.h, Module.h, Hal.h – the public API headers
- examples/ : dozens of sketches demonstrating how to use modules + protocols on Arduino and non‑Arduino platforms
- extras/ : tooling (image converter, spectrum scan), CI scripts, unit tests
- CMakeLists.txt, idf_component.yml, library.json, PlatformIO & Arduino metadata – build system & packaging
- .github/workflows/ – CI pipelines for code analysis, tests, documentation

##### README for additional insights
- Describes supported modules and digital modes (“one radio library to rule them all!”)
- Mentions internal HAL for portability and a consistent, layered API
- Links to API reference, wiki, and status/debug log decoders

1) Application (User Sketch / Non‑Arduino main): calls into ↓
2) Protocol Layer: AX.25, LoRaWAN, Morse, SSTV, etc.
3) Module Drivers: CC1101, SX127x, nRF24, LR11x0, RF69, SX126x, etc.
4) HAL (Hardware Abstraction): ArduinoHal, PiHal, PicoHal, RPi, ESP32, etc.
5) Utilities: CRC, FEC, Cryptography, Utils
6) Build & Packaging: CMake, PlatformIO, Arduino IDE, idf_component
7) Examples & Tests: examples/, extras/test/unit/, extras/ci scripts

- Application → Protocol Layer → Module Drivers → HAL → Physical Hardware
- Protocol Layer ←→ Utilities (for CRC/FEC/crypto)
- Module Drivers ←→ Utilities (timing, bit manipulation)
- Build & Packaging → (configures) → src/, examples/, extras/
- CI workflows → test harness → extras/test unit, examples compilation

c. Architectural patterns & design principles:
- Layered architecture: clear separation of concerns (HAL ↔ Drivers ↔ Protocols ↔ Application)
- Hardware abstraction: isolates MCU specifics in hal/ so modules + protocols remain platform‑agnostic
- Plug‑in modularity: new radio chips live in their own module subdirectory; new protocols in protocols/
- Single public API: RadioLib.h exposes a unified interface regardless of underlying module or protocol

d. Key technologies, frameworks, libraries:
- C++ (headers & implementation files) using idiomatic RTOS‑less design
- CMake for non‑Arduino builds, PlatformIO, Arduino library metadata (library.json, keywords.txt)
- Doxygen for API docs, GitHub Actions for CI (cppcheck, unit tests, doxygen, release)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        Application["Application<br/>(User Sketch / Non‑Arduino)"]:::app
    end
    click Application "https://github.com/jgromes/radiolib/tree/master/examples/"

    %% Protocol Layer
    subgraph "Protocol Layer"
        Protocols["Protocols<br/>(AX.25, LoRaWAN, Morse, SSTV…)"]:::protocol
    end
    click Protocols "https://github.com/jgromes/radiolib/tree/master/src/protocols/"

    %% Module Drivers Layer
    subgraph "Module Drivers Layer"
        Modules["Module Drivers<br/>(CC1101, SX127x, nRF24, …)"]:::drivers
    end
    click Modules "https://github.com/jgromes/radiolib/tree/master/src/modules/"

    %% HAL Layer
    subgraph "Hardware Abstraction Layer"
        HAL["HAL Implementations<br/>(ArduinoHal, PiHal, PicoHal…)"]:::hal
    end
    click HAL "https://github.com/jgromes/radiolib/tree/master/src/hal/"

    %% Utilities Layer
    subgraph "Utilities"
        Utils["Utilities<br/>(CRC, FEC, Crypto, Utils)"]:::utils
    end
    click Utils "https://github.com/jgromes/radiolib/tree/master/src/utils/"

    %% Public API
    subgraph "Public API Headers"
        RadioLibH["RadioLib.h"]:::api
        ModuleH["Module.h"]:::api
        HalH["Hal.h"]:::api
    end
    click RadioLibH "https://github.com/jgromes/radiolib/blob/master/src/RadioLib.h"
    click ModuleH "https://github.com/jgromes/radiolib/blob/master/src/Module.h"
    click HalH "https://github.com/jgromes/radiolib/blob/master/src/Hal.h"

    %% Build & Packaging
    subgraph "Build & Packaging"
        CMake["CMakeLists.txt"]:::build
        ArduinoMeta["Arduino Metadata<br/>(library.json, library.properties, keywords.txt)"]:::build
        ESPIDF["ESP‑IDF Component<br/>(idf_component.yml)"]:::build
    end
    click CMake "https://github.com/jgromes/radiolib/blob/master/CMakeLists.txt"
    click ArduinoMeta "https://github.com/jgromes/radiolib/blob/master/library.json"
    click ArduinoMeta "https://github.com/jgromes/radiolib/blob/master/keywords.txt"
    click ArduinoMeta "https://github.com/jgromes/radiolib/blob/master/library.properties"
    click ESPIDF "https://github.com/jgromes/radiolib/blob/master/idf_component.yml"

    %% Examples & Tests
    subgraph "Examples & Tests"
        Examples["Examples<br/>(Arduino & Non‑Arduino)"]:::test
        UnitTests["Unit Tests<br/>(extras/test/unit/)"]:::test
        CI["CI Workflows<br/>(.github/workflows/)"]:::test
    end
    click Examples "https://github.com/jgromes/radiolib/tree/master/examples/"
    click UnitTests "https://github.com/jgromes/radiolib/tree/master/extras/test/unit/"
    click CI "https://github.com/jgromes/radiolib/tree/master/ .github/workflows/"

    %% Tooling & Extras
    subgraph "Tooling & Extras"
        ImageTool["SSTV Image Converter"]:::extras
        SpectrumTool["SX126x Spectrum Scan"]:::extras
        ModuleTemplateCPP["ModuleTemplate.cpp"]:::extras
        ModuleTemplateH["ModuleTemplate.h"]:::extras
    end
    click ImageTool "https://github.com/jgromes/radiolib/tree/master/extras/SSTV_Image_Converter/"
    click SpectrumTool "https://github.com/jgromes/radiolib/tree/master/extras/SX126x_Spectrum_Scan/"
    click ModuleTemplateCPP "https://github.com/jgromes/radiolib/blob/master/extras/template/ModuleTemplate.cpp"
    click ModuleTemplateH "https://github.com/jgromes/radiolib/blob/master/extras/template/ModuleTemplate.h"

    %% Physical Hardware
    Hardware["Physical Hardware"]:::hardware

    %% Relationships
    Application -->|calls| Protocols
    Protocols -->|uses drivers| Modules
    Modules -->|calls| HAL
    HAL -->|controls| Hardware

    Protocols ---|uses| Utils
    Modules ---|uses| Utils

    CMake -->|configures| Protocols
    CMake -->|configures| Modules
    CMake -->|configures| HAL
    CMake -->|configures| Utils
    ArduinoMeta -->|provides metadata for| Application
    ESPIDF -->|provides metadata for| Application

    CI -->|runs| UnitTests
    CI -->|builds| Examples

    %% Styles
    classDef app fill:#D8BFD8,stroke:#9370DB,color:#000000;
    classDef protocol fill:#FFA500,stroke:#FF8C00,color:#000000;
    classDef drivers fill:#98FB98,stroke:#2E8B57,color:#000000;
    classDef hal fill:#ADD8E6,stroke:#1E90FF,color:#000000;
    classDef utils fill:#FFFFE0,stroke:#DAA520,color:#000000;
    classDef api fill:#FFFACD,stroke:#DAA520,color:#000000;
    classDef build fill:#D3D3D3,stroke:#A9A9A9,color:#000000;
    classDef test fill:#E6E6FA,stroke:#D8BFD8,color:#000000;
    classDef extras fill:#F5F5F5,stroke:#C0C0C0,color:#000000;
    classDef hardware fill:#FFE4E1,stroke:#FF6347,color:#000000;
```
