# waziup/osirris architecture

> Architecture diagram of the GitHub repository waziup/osirris, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/waziup/osirris
- Repository: https://github.com/waziup/osirris

## Overview

1. **Repository shape**
   This repo is an Arduino-based embedded firmware project, not an application server. The core deliverable is the `Arduino/Osirris_Soil_Sensor` sketch for a WaziAct/WaziDev-style LoRa sensor node, plus vendored Arduino libraries and deployment guides.

2. **Primary runtime boundary**
   The main runtime is the microcontroller firmware in `Arduino/Osirris_Soil_Sensor/Osirris_Soil_Sensor.ino`. That sketch is the orchestration layer: it initializes hardware, reads sensors, builds the uplink payload, and hands it to the radio stack.

3. **Sensor subsystem**
   Sensor access is split into pluggable modules under `Arduino/Osirris_Soil_Sensor/`:
   - `watermark.*` for the soil tension sensor
   - `DS18B20.*` for external soil temperature
   - `TempInternal.*`, `si7021_*`, `CO2_SCD30.*`, `sen0308.*`, `rawAnalog.*` for alternative/optional sensor types
   - `Sensor.*` acts as the common abstraction layer for sensor drivers  
   In the documented OSIRRIS setup, the active pair is Watermark + DS18B20.

4. **Calibration and conversion**
   The Watermark sensor is not just read raw; it has its own calibration support, including `watermark-caltable.xls` / `.xlsx`. That implies a conversion step from analog reading to usable soil-moisture/soil-tension values before transmission.

5. **Power and board configuration**
   `BoardSettings.*` and the various `RadioSettings.h` variants encode hardware-specific configuration: pins, board type, power behavior, and which SX12xx radio family is present. This is the boundary between portable firmware logic and device-specific wiring.

6. **Radio / LoRaWAN subsystem**
   The project supports multiple radio chip families through the SX12XX library and matching config headers:
   - `SX126X_RadioSettings.h`
   - `SX127X_RadioSettings.h`
   - `SX128X_RadioSettings.h`  
   Firmware-side LoRaWAN handling is split between `local_lorawan.*` and `native_at_lorawan.*`, indicating two integration modes: direct radio control from firmware or AT-command-based radio/module control.

7. **Payload encoding**
   The repo vendors `xlpp` and `CayenneLPP`, which strongly suggests the sensor readings are encoded into an XLPP/Cayenne-compatible LoRaWAN payload before uplink. This is the key data-format boundary between device and gateway.

8. **Optional UX / local display**
   Display support is present but secondary: `Adafruit_GFX`, `Adafruit_SSD1306`, and `U8g2` are vendored, so the device can show local status/readings if an OLED is attached. This does not appear to be the main data path, just an optional output channel.

9. **Sleep / low-power behavior**
   `LowPower`, `RTCZero`, and `Arduino_Vcc` indicate the node is designed for battery/solar operation with deep sleep and periodic wakeups. Architecturally, this means the loop is likely event/timer driven: wake, sample, transmit, sleep.

10. **Deployment and cloud boundary**
   The firmware is designed to uplink to a WaziGate, which then handles LoRaWAN decoding and device registration. The README explicitly calls for the `XLPP` codec in WaziGate and then syncing onward to WaziCloud. So the device’s direct responsibility ends at LoRaWAN uplink; decoding and cloud synchronization happen outside the repo.

11. **Alternate sketch path**
   `send_if_online.ino` suggests a secondary firmware variant focused on conditional sending or connectivity-aware behavior. For architecture diagrams, treat it as an alternate entry point rather than a separate subsystem.

12. **Vendored dependencies**
   The `Arduino/libraries` tree contains the project’s embedded dependencies checked into the repo rather than pulled from a package manager. These include sensor drivers, LoRa stack support, crypto/base64 helpers, and display libraries. This makes the repository self-contained for Arduino IDE builds.

13. **Documentation as system boundary**
   The `Guides/` folder is operational documentation for deployment, wiring, WaziGate setup, and irrigation prediction. It does not affect runtime architecture, but it defines the intended system boundary: field sensor node -> WaziGate -> WaziCloud.

Main entry points: [`Arduino/Osirris_Soil_Sensor/Osirris_Soil_Sensor.ino`](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/Osirris_Soil_Sensor.ino) (Main sketch), [`Arduino/Osirris_Soil_Sensor/Sensor.h`](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/Sensor.h) (Sensor core), [`Arduino/Osirris_Soil_Sensor/local_lorawan.h`](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/local_lorawan.h) (Local LoRaWAN), [`Arduino/Osirris_Soil_Sensor/watermark.h`](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/watermark.h) (Watermark)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware"]
  node_sketch["Main sketch<br/>firmware entrypoint"]
  node_alt_sketch["Online send<br/>firmware variant"]
  node_board["Board setup<br/>hw config<br/>[BoardSettings.h]"]
  node_radio_cfg["Radio config<br/>[RadioSettings.h]"]
  node_sensor_core["Sensor core<br/>sensor abstraction<br/>[Sensor.h]"]
  node_watermark["Watermark<br/>soil tension<br/>[watermark.h]"]
  node_ds18b20["DS18B20<br/>soil temp<br/>[DS18B20.h]"]
  node_other_sensors["Other sensors<br/>optional sensors<br/>[TempInternal.h]"]
  node_lorawan_local["Local LoRaWAN<br/>radio stack<br/>[local_lorawan.h]"]
  node_lorawan_at["AT LoRaWAN<br/>radio stack"]
  node_radio_sx126x["SX126X settings<br/>radio profile"]
  node_radio_sx127x["SX127X settings<br/>radio profile"]
  node_radio_sx128x["SX128X settings<br/>radio profile"]
end

subgraph group_libs["Vendored libraries"]
  node_payload["Payload encode<br/>uplink format<br/>[xlpp.h]"]
  node_power["Low power<br/>sleep/power<br/>[LowPower.h]"]
  node_rtc["RTC timing<br/>wake scheduler<br/>[RTCZero.h]"]
  node_vcc["Vcc monitor<br/>battery sense<br/>[Vcc.h]"]
  node_display["Display UI<br/>optional display<br/>[Adafruit_SSD1306.h]"]
end

subgraph group_docs["Guides"]
  node_deployment["Deploy guides<br/>ops docs<br/>[deploy_wazigate.md]"]
end

node_sketch -->|"configures"| node_board
node_sketch -->|"selects"| node_radio_cfg
node_sketch -->|"samples"| node_sensor_core
node_sensor_core -->|"uses"| node_watermark
node_sensor_core -->|"uses"| node_ds18b20
node_sensor_core -.->|"extends"| node_other_sensors
node_watermark -->|"reads pins"| node_board
node_watermark -.->|"powersave"| node_power
node_sketch -->|"encodes"| node_payload
node_sketch -->|"uplinks via"| node_lorawan_local
node_sketch -->|"uplinks via"| node_lorawan_at
node_lorawan_local -->|"can use"| node_radio_sx126x
node_lorawan_local -->|"can use"| node_radio_sx127x
node_lorawan_local -->|"can use"| node_radio_sx128x
node_sketch -->|"sleeps"| node_power
node_sketch -->|"wakes on"| node_rtc
node_sketch -.->|"monitors"| node_vcc
node_sketch -.->|"optional status"| node_display
node_alt_sketch -.->|"variant of"| node_sketch
node_deployment -.->|"depends on"| node_payload

click node_sketch "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/Osirris_Soil_Sensor.ino"
click node_alt_sketch "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/send_if_online.ino/send_if_online.ino.ino"
click node_board "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/BoardSettings.h"
click node_radio_cfg "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/RadioSettings.h"
click node_sensor_core "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/Sensor.h"
click node_watermark "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/watermark.h"
click node_ds18b20 "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/DS18B20.h"
click node_other_sensors "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/TempInternal.h"
click node_payload "https://github.com/waziup/osirris/blob/main/Arduino/libraries/xlpp/src/xlpp.h"
click node_lorawan_local "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/local_lorawan.h"
click node_lorawan_at "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/native_at_lorawan.h"
click node_radio_sx126x "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/SX126X_RadioSettings.h"
click node_radio_sx127x "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/SX127X_RadioSettings.h"
click node_radio_sx128x "https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/SX128X_RadioSettings.h"
click node_power "https://github.com/waziup/osirris/blob/main/Arduino/libraries/LowPower/LowPower.h"
click node_rtc "https://github.com/waziup/osirris/blob/main/Arduino/libraries/RTCZero/src/RTCZero.h"
click node_vcc "https://github.com/waziup/osirris/blob/main/Arduino/libraries/Vcc/Vcc.h"
click node_display "https://github.com/waziup/osirris/blob/main/Arduino/libraries/Adafruit_SSD1306/Adafruit_SSD1306.h"
click node_deployment "https://github.com/waziup/osirris/blob/main/Guides/deploy_wazigate.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sketch,node_alt_sketch,node_board,node_radio_cfg,node_sensor_core,node_watermark,node_ds18b20,node_other_sensors,node_lorawan_local,node_lorawan_at,node_radio_sx126x,node_radio_sx127x,node_radio_sx128x toneBlue
class node_payload,node_power,node_rtc,node_vcc,node_display toneAmber
class node_deployment toneMint
```

## Components

### Firmware

Main Arduino sketch and device-specific modules

- [Main sketch](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/Osirris_Soil_Sensor.ino): firmware entrypoint · Primary firmware orchestration for the sensor node · `Arduino/Osirris_Soil_Sensor/Osirris_Soil_Sensor.ino`
- [Online send](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/send_if_online.ino/send_if_online.ino.ino): firmware variant · Alternate sketch focused on conditional transmission · `Arduino/Osirris_Soil_Sensor/send_if_online.ino/send_if_online.ino.ino`
- [Board setup](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/BoardSettings.h): hw config · Pins, board type, and power-related hardware configuration · `Arduino/Osirris_Soil_Sensor/BoardSettings.h`
- [Radio config](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/RadioSettings.h): radio config · Radio-family selection and device-specific SX12xx settings · `Arduino/Osirris_Soil_Sensor/RadioSettings.h`
- [Sensor core](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/Sensor.h): sensor abstraction · Common interface for sensor drivers and sampling flow · `Arduino/Osirris_Soil_Sensor/Sensor.h`
- [Watermark](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/watermark.h): soil tension · Analog soil-tension sensor driver and calibration-aware conversion · `Arduino/Osirris_Soil_Sensor/watermark.h`
- [DS18B20](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/DS18B20.h): soil temp · External soil temperature driver · `Arduino/Osirris_Soil_Sensor/DS18B20.h`
- [Other sensors](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/TempInternal.h): optional sensors · Alternative or optional sensor drivers used in other builds · `Arduino/Osirris_Soil_Sensor/TempInternal.h`
- [Local LoRaWAN](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/local_lorawan.h): radio stack · Direct firmware-controlled LoRaWAN integration · `Arduino/Osirris_Soil_Sensor/local_lorawan.h`
- [AT LoRaWAN](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/native_at_lorawan.h): radio stack · AT-command based LoRaWAN integration path · `Arduino/Osirris_Soil_Sensor/native_at_lorawan.h`
- [SX126X settings](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/SX126X_RadioSettings.h): radio profile · Settings for SX126x-class radios · `Arduino/Osirris_Soil_Sensor/SX126X_RadioSettings.h`
- [SX127X settings](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/SX127X_RadioSettings.h): radio profile · Settings for SX127x-class radios · `Arduino/Osirris_Soil_Sensor/SX127X_RadioSettings.h`
- [SX128X settings](https://github.com/waziup/osirris/blob/main/Arduino/Osirris_Soil_Sensor/SX128X_RadioSettings.h): radio profile · Settings for SX128x-class radios · `Arduino/Osirris_Soil_Sensor/SX128X_RadioSettings.h`

### Vendored libraries

Checked-in Arduino dependencies used by the firmware

- [Payload encode](https://github.com/waziup/osirris/blob/main/Arduino/libraries/xlpp/src/xlpp.h): uplink format · Encodes readings into XLPP/Cayenne-compatible payloads · `Arduino/libraries/xlpp/src/xlpp.h`
- [Low power](https://github.com/waziup/osirris/blob/main/Arduino/libraries/LowPower/LowPower.h): sleep/power · Deep sleep, wake timing, and battery-aware behavior · `Arduino/libraries/LowPower/LowPower.h`
- [RTC timing](https://github.com/waziup/osirris/blob/main/Arduino/libraries/RTCZero/src/RTCZero.h): wake scheduler · RTC-driven periodic wakeup and alarm support · `Arduino/libraries/RTCZero/src/RTCZero.h`
- [Vcc monitor](https://github.com/waziup/osirris/blob/main/Arduino/libraries/Vcc/Vcc.h): battery sense · Supply voltage monitoring used for power-aware operation · `Arduino/libraries/Vcc/Vcc.h`
- [Display UI](https://github.com/waziup/osirris/blob/main/Arduino/libraries/Adafruit_SSD1306/Adafruit_SSD1306.h): optional display · OLED/status display support for local feedback · `Arduino/libraries/Adafruit_SSD1306/Adafruit_SSD1306.h`

### Guides

Deployment and operational documentation

- [Deploy guides](https://github.com/waziup/osirris/blob/main/Guides/deploy_wazigate.md): ops docs · WaziGate/WaziSense deployment and irrigation guidance · `Guides/deploy_wazigate.md`

## Connections

- Main sketch → Board setup: configures · Loads hardware-specific pins and board behavior
- Main sketch → Radio config: selects · Chooses the appropriate radio configuration
- Main sketch → Sensor core: samples · Coordinates sensor acquisition
- Sensor core → Watermark: uses · Primary soil tension sensor driver
- Sensor core → DS18B20: uses · Primary soil temperature sensor driver
- Sensor core → Other sensors: extends · Alternative optional sensor modules
- Watermark → Board setup: reads pins · Uses board wiring and analog input configuration
- Watermark → Low power: powersave · Supports low-duty-cycle operation
- Main sketch → Payload encode: encodes · Turns sampled values into uplink payloads
- Main sketch → Local LoRaWAN: uplinks via · Direct radio-based LoRaWAN path
- Main sketch → AT LoRaWAN: uplinks via · AT-command LoRaWAN path
- Local LoRaWAN → SX126X settings: can use · SX126x radio profile
- Local LoRaWAN → SX127X settings: can use · SX127x radio profile
- Local LoRaWAN → SX128X settings: can use · SX128x radio profile
- Main sketch → Low power: sleeps · Uses low-power sleep between sampling cycles
- Main sketch → RTC timing: wakes on · Uses RTC alarms or periodic wakeups
- Main sketch → Vcc monitor: monitors · Checks supply voltage for battery operation
- Main sketch → Display UI: optional status · May present local readings or state on OLED
- Online send → Main sketch: variant of · Alternative entry point with connectivity-aware sending
- Deploy guides → Payload encode: depends on · Documents XLPP codec use in gateway decoding