waziup/osirris

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.