# ricaun/loranow architecture

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

- Interactive diagram: https://gitdiagram.com/ricaun/loranow
- Repository: https://github.com/ricaun/loranow

## Overview

##### Project Type and Purpose
- Type: An open‐source Arduino/ESP library for Node↔Gateway LoRa communication.
- Purpose: Expose a simple API (LoRaNow class) on microcontroller sketches, implement a state machine, checksum, ID management, and wrap the lower‐level Arduino‐LoRa driver.

##### File Structure
- Root files (README.md, API.md, library.properties): define metadata, documentation, API.
- src/: core library code
– LoRaNow.cpp/.h: public API, state machine, packet framing.
– utility/: wrapper around Sandeep Mistry’s Arduino‐LoRa (LoRa.cpp/.h) and helper routines (LoRaUtilities).
- examples/: sketches for Node and Gateway on Arduino, ESP8266, ESP32.
- keywords.txt: Arduino IDE integration.
- License, Gitignore: ancillary.

##### README for Insights
- API: LoRaNow.setPins(), setFrequency(), send(), receive()
- Layers: Sketch → LoRaNow → Arduino‐LoRa → RFM95W hardware
- Hardware: MCU (Arduino/ESP) + RFM95W LoRa module.

##### Main Components
a. MCU Application (Sketch)
b. LoRaNow Library (LoRaNow class + utilities)
c. Underlying Arduino‐LoRa Driver (external dependency)
d. LoRa Radio Module (RFM95W)
e. Radio Link (air interface)
f. Gateway Application (another MCU running LoRaNow)

##### Relationships & Interactions
- Sketch calls LoRaNow API
- LoRaNow manages state machine, frames payload (ID, checksum)
- LoRaNow invokes Arduino‐LoRa driver to send/receive raw bytes
- Driver toggles SPI lines to RFM95W module
- RFM95W transmits over radio link to other nodes/gateway
- Incoming packets reverse through driver → LoRaNow parsing → Sketch callback

##### Architectural Patterns & Principles
- Layered abstraction (API → library internals → hardware driver → physical radio)
- State machine pattern for TX/RX management
- Plug-and-play extensibility via utility wrappers
- Separation of concerns: framing & protocol in LoRaNow, RF details in Arduino-LoRa

##### Relevant Technologies
- C++ classes (LoRaNow, LoRa, LoRaUtilities)
- Arduino IDE integration (library.properties, keywords.txt)
- Platforms: AVR (Arduino), ESP8266, ESP32
- RFM95W LoRa transceiver via SPI

##### Detailed Component Breakdown
– Sketch Layer: examples/LoRaNow_Node.ino, _Gateway.ino
– LoRaNow Core: src/LoRaNow.{h,cpp}
– Utilities: src/utility/LoRa*.{h,cpp}
– External Driver: Arduino-LoRa (indicate as third-party)
– Hardware: RFM95W pins (SS, DIO0, SPI lines)
– Radio Medium: 868/915 MHz band

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Sketch Layer"
        NodeSketch["Node Example\nLoRaNow_Node.ino"]:::software
        GatewaySketch["Gateway Example\nLoRaNow_Gateway.ino"]:::software
        ESP32Gateway["ESP32 Gateway\nLoRaNow_Gateway_ESP32.ino"]:::software
        ESP32GatewayPins["ESP32 Gateway setPins\nLoRaNow_Gateway_ESP32_setPins.ino"]:::software
        ESP8266Gateway["ESP8266 Gateway\nLoRaNow_Gateway_ESP8266.ino"]:::software
    end

    subgraph "LoRaNow Core Library"
        LoRaNow["LoRaNow Core Library\nsrc/LoRaNow.h/.cpp"]:::software
    end

    subgraph "Utility Wrappers"
        LoRaWrapper["Arduino-LoRa Wrapper\nsrc/utility/LoRa.h/.cpp"]:::software
        LoRaUtils["LoRa Utilities\nsrc/utility/LoRaUtilities.h/.cpp"]:::software
    end

    ArduinoLoRa["Arduino-LoRa Driver\n(third-party)"]:::external
    MCU["MCU (Arduino/ESP)"]:::hardware
    RFM95["RFM95W Module\n(SS, DIO0, SPI)"]:::hardware
    Radio["Radio Link\n868/915MHz"]:::cloud

    NodeSketch -->|"calls API"| LoRaNow
    GatewaySketch -->|"calls API"| LoRaNow
    ESP32Gateway -->|"calls API"| LoRaNow
    ESP32GatewayPins -->|"calls API"| LoRaNow
    ESP8266Gateway -->|"calls API"| LoRaNow

    LoRaNow -->|"invokes"| LoRaWrapper
    LoRaNow -->|"utilizes"| LoRaUtils
    LoRaWrapper -->|"calls driver"| ArduinoLoRa
    ArduinoLoRa -->|"SPI"| RFM95
    RFM95 -->|"RF"| Radio
    Radio -->|"RF"| RFM95
    RFM95 -->|"SPI"| ArduinoLoRa
    ArduinoLoRa -->|"raw bytes"| LoRaWrapper
    LoRaWrapper -->|"hands data"| LoRaNow
    LoRaNow -->|"onReceive() callback"| NodeSketch
    LoRaNow -->|"onReceive() callback"| GatewaySketch

    click NodeSketch "https://github.com/ricaun/loranow/blob/master/examples/LoRaNow_Node/LoRaNow_Node.ino"
    click GatewaySketch "https://github.com/ricaun/loranow/blob/master/examples/LoRaNow_Gateway/LoRaNow_Gateway.ino"
    click ESP32Gateway "https://github.com/ricaun/loranow/blob/master/examples/LoRaNow_Gateway_ESP32/LoRaNow_Gateway_ESP32.ino"
    click ESP32GatewayPins "https://github.com/ricaun/loranow/blob/master/examples/LoRaNow_Gateway_ESP32_setPins/LoRaNow_Gateway_ESP32_setPins.ino"
    click ESP8266Gateway "https://github.com/ricaun/loranow/blob/master/examples/LoRaNow_Gateway_ESP8266/LoRaNow_Gateway_ESP8266.ino"
    click LoRaNow "https://github.com/ricaun/loranow/blob/master/src/LoRaNow.h"
    click LoRaNow "https://github.com/ricaun/loranow/blob/master/src/LoRaNow.cpp"
    click LoRaWrapper "https://github.com/ricaun/loranow/blob/master/src/utility/LoRa.h"
    click LoRaWrapper "https://github.com/ricaun/loranow/blob/master/src/utility/LoRa.cpp"
    click LoRaUtils "https://github.com/ricaun/loranow/blob/master/src/utility/LoRaUtilities.h"
    click LoRaUtils "https://github.com/ricaun/loranow/blob/master/src/utility/LoRaUtilities.cpp"

    classDef software fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef hardware fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFD700,stroke:#000,stroke-width:1px
    classDef cloud fill:#FFA500,stroke:#000,stroke-width:1px
```
