The whole schema, in one place.

01The three messages.

oat-ods has three message types, and a receiver tells them apart by msg_type. The first carries a reading. It holds one measurement: value, what it measured, when, and the sensor that took it, named by its own hardware id:

{
  "schema": "oat-ods/0.3",
  "msg_type": "observation",              // default; may be omitted
  "observed_at": "2026-06-25T14:30:00Z",
  "stream": {
    "id": "A4:C1:38:0D:1E:2F",            // the sensor's own hardware id (here its BLE MAC)
    "name": "GVH5075_1E2F",               // only a name the sensor advertises itself
    "location": "Greenhouse 2"            // optional: typed at setup, describes the node
  },
  "measurement": "temperature",
  "value": 24.31,
  "unit": "Cel",
  "agg": { "window_s": 60, "samples": 28, "method": "mean" },
  "source": {
    "tier": "oat-ble-listener",
    "gateway_id": "oat-greenhouse-2",     // the node's setup name (its hardware id if none)
    "physical_id": "A4:C1:38:0D:1E:2F",   // the same hardware id, kept as provenance
    "brand": "Govee", "model": "H5075",
    "battery_pct": 88, "rssi": -78
  }
}

The second is a batch, and it is what a real node actually sends. A node with several sensors does not open a request per reading: it wraps them in one signed body. Each entry in messages is a complete observation minus the envelope keys, so if you can parse the message above you can parse these:

{
  "schema": "oat-ods/0.3",
  "msg_type": "batch",
  "sent_at": "2026-07-26T05:26:00Z",      // when the BODY was sent
  "seq": 3000004,                         // monotonic per body; replay detection
  "source": {                             // node-level provenance, stated once
    "tier": "oat-ds18b20-node",
    "gateway_id": "walkin-1",
    "farm_id": "riverbend-farm",          // the operator: one grower, many gateways
    "fw": "OAT-DS18B20-Node/2.0.4"
  },
  "messages": [
    { "observed_at": "2026-07-26T05:26:00Z",   // per MESSAGE, never on the envelope
      "stream": { "id": "ds18b20:28ff641f8c1a3b02" },
      "measurement": "temperature", "value": 3.44, "unit": "Cel",
      "agg": { "window_s": 60, "samples": 6, "method": "mean" },
      "source": { "physical_id": "ds18b20:28ff641f8c1a3b02",
                  "brand": "Analog Devices", "model": "DS18B20" } }
  ]
}

The third is a status message: how a node says it is alive without any reading riding along (§04). Same envelope, no stream/measurement/value:

{
  "schema": "oat-ods/0.3",
  "msg_type": "status",
  "state": "online",                      // "online" | "offline"
  "observed_at": "2026-06-25T14:30:00Z",
  "source": { "tier": "oat-ble-listener", "gateway_id": "oat-greenhouse-2",
              "device_id": "oat-3c8a1fa77d14" },  // the physical board (efuse MAC)
  "health": { "uptime_s": 86400, "boot_count": 3, "reset": "poweron",
              "free_heap": 142000, "rssi": -71, "push_ok": 1440, "push_fail": 2,
              "transport": "https", "tls_ok": true, "chip": "ESP32-C6" }
}

02Every field.

The complete field set. A consumer must ignore fields it doesn't recognize — that rule is what lets the format grow without breaking anything downstream.

“obs.” = required on an observation; “status” = required on a status message; “one of” = source needs at least one of gateway_id / physical_id.

03The full vocabulary.

This is the part a single sketch never shows you: every measurement the schema knows, 50 of them, each bound to the open standards it profiles — the SenML unit, the Home Assistant device class, the QUDT quantity kind, and the UCUM code. We chose these names; we did not invent them. The table is generated from measurands.json, so it is always exactly what the devices emit.

Open by construction. measurement is not a closed list. A device may send a measurement that isn't here yet; the schema asks only for a non-empty string, and a key the dictionary hasn't mapped is forwarded raw (its own name, no unit) rather than dropped — so nothing is ever lost, and new keys surface for adding to the table. source: derived rows (dewpoint, VPD) are computed by the endpoint, never sent by a node.

04Knowing a node is alive.

A node reports liveness with a status message, borrowing the idea from Eclipse Sparkplug. Over a webhook it POSTs state:"online" on boot and on a heartbeat; over MQTT it sets a Last Will of state:"offline" so the broker announces a drop automatically.

The heartbeat interval is a fixed constant of the format: 60 seconds, written here and not carried in the payload — because a packet that never arrives can't declare its own cadence. For an endpoint to detect absence it must know the expected beat in advance. Treat > 3× the cadence (180 s) with no heartbeat as a liveness alarm, not a single missed beat. Monitoring is always the endpoint's job; the node just reports.

A status message may carry a health object — the node's honest self-report:

When the gateway carries other sensors.

Two kinds of OAT gateway push readings that are not their own: the BLE Listener hears Bluetooth sensors, and the LoRa Gateway hears LoRa Field Nodes, each of which may carry thirty probes. Nothing about the format changes for an endpoint, and that is deliberate. Four rules make it work:

• One observation per reading, always. A field node with three soil probes and an air sensor arrives as four streams, each under that sensor’s own hardware id (ds18b20:28ff…, sht30:0a1b…). The endpoint never sees the node’s sensor list, only streams, and a probe added tomorrow is simply a new stream on the next batch.
• Stream ids are hardware ids, so they survive the radio. A probe moved from a Wi-Fi node to a LoRa node keeps its id and therefore its history. The map from a serial number to a place and a depth is the endpoint’s to hold; no node names anything.
• The carrier’s link quality rides in source. rssi and battery on a carried reading describe the field node or BLE sensor that sent it, not the gateway’s Wi-Fi. A LoRa field node also gets a stream of its own (its 8-hex unit id) carrying rssi, snr, voltage and uptime as gauges.
• Absence is a stream that stops. The gateway’s own heartbeat says the gateway is alive. A carried sensor has no heartbeat; when its node falls silent for three of its cycles the gateway releases its streams and they stop appearing in batches. Treat a stream that has not appeared for three of its usual intervals as stale — the same rule as §04, applied per stream.

A fifth source of carried readings is a pod: any board that prints readings in the oat-line grammar on a serial port, cabled to a field node or a gateway. Every OAT sketch prints its readings that way by default, so a Radio Sensor Listener cabled to a LoRa node carries an AcuRite’s streams to the house under the station’s own id. To an endpoint, a pod’s streams are indistinguishable from wired ones.

Counters arrive as running totals. A rain gauge, a water meter, a lightning detector and an energy monitor report a cumulative value (rain_total, lightning_total, energy), sent with agg.method: "last". The amount for any period is the endpoint’s subtraction: new total minus the last total it stored for that stream. Three cases: normal, a small positive difference; reset, the new total is smaller (batteries pulled, or the device’s counter wrapped) — take the new value as the new baseline and never report a negative; gap, readings were missed — the difference is still right, which is the whole reason totals are sent rather than increments. A device that reports increments instead (the Tempest’s rain per minute) uses rainfall with agg.method: "sum", and those are simply added. The field says which rule applies; an endpoint never guesses. Home Assistant’s Utility Meter helper implements exactly this.

The over-air frame between a field node and its gateway is not oat-ods and is not an endpoint’s concern; it is documented on the field node page for anyone building a node. The next schema revision adds an optional source.via carrying the node id on each carried reading, so an endpoint can group a node’s streams without parsing ids.

05The shared device library.

Every Open Agriculture Technology sketch — the BLE listener, the SDI-12 reader, the analog and Modbus readers — links one shared library, oat_ods, to build these messages. It is header-only (ArduinoJson 7), carries no transport of its own (your sketch owns the HTTP or MQTT send), and holds the native / SenML / flat / status encoders, plus Home Assistant discovery helpers that no sketch calls yet. Write a new device and it pours into the same envelope: only the transducer differs. That is one envelope, every sketch.

You get the library two ways, so a sketch always compiles as-is:

• Inside every sketch. Each download from the Sketches bundles lib/oat_ods/ alongside the project, and its platformio.ini already points at it (lib_extra_dirs = ../lib). Unzip, build, flash — nothing else to fetch.
• On its own, here. Grab the library by itself to drop into your own project's lib/ folder, or just to read the source.

06How it travels.

The identical message reaches an endpoint two ways, and a device offers whichever suits your setup — the receiver can’t tell them apart. Pick by what you already run:

The MQTT binding is worth spelling out. The topic is keyed on the node's name and the sensor's own hardware id, so a replacement sensor arrives on a new topic and whatever reads it (Home Assistant, your endpoint) maps it to the same place; each value is published retained, so a new subscriber always gets the latest reading immediately; and node liveness rides its own topic with a Last Will the broker publishes on a dropped connection:

# one retained message per stream + measurement
oat/{gateway_id}/{stream.id}/{measurement}

# example
oat/oat-greenhouse-2/A4:C1:38:0D:1E:2F/temperature   → {"value": 24.31, …}

# node liveness — Last Will publishes "offline" automatically on a dropped connection
oat/{gateway_id}/status                            → {"state":"online"}

Running Home Assistant? Declare each topic above as an MQTT sensor in YAML with value_template: "{{ value_json.value }}" and the status topic for availability. The oat_ods library carries helpers that build Home Assistant discovery configs, but no OAT sketch sends them today, so entities are declared, not discovered. Either way the payload is the same oat-ods message, and there’s a runnable subscriber for it in the next section.

07A receiver you can run.

The other end is just as simple, and there’s a runnable reference for both transports (§06). Copy one, set a couple of environment variables, and start it.

Webhook. Drop-in HTTP endpoints that accept oat-ods over a POST: set one secret and run. Both handle single messages and batches, verify an optional oat1 HMAC signature over the raw body (so the key is never sent, safe even over plain HTTP), and reject replays by sequence number.

MQTT. Subscribers that connect to your broker and print every reading as it lands. Retained messages arrive the moment they subscribe, so a fresh start immediately shows the latest value for every stream, and the status topic is read as liveness. Auth is the broker’s job (username / password + TLS), not a per-message signature.

Want to watch messages land without writing anything? Point a device (or curl) at the live test endpoint and see each reading arrive, judged against the schema.

08Conformance & versioning.

A message is oat-ods/0.3 conformant when an observation carries schema, observed_at, stream.id, measurement, value, and a source with at least one of gateway_id / physical_id; any unit is a SenML symbol; and each message holds exactly one measurement. Validate against the JSON Schema with any standard validator.

The version lives in the schema tag, oat-ods/{major}.{minor}. New optional fields or new measurements bump the minor; a breaking change bumps the major. Because consumers ignore unknown fields, minor growth never breaks a receiver already in the field. The highest-leverage promise is that the format is trivially consumable: fetch the schema, validate, generate a receiver in minutes — the bet is on the source being clean, not on any one destination persisting.

09Every artifact.

Everything we publish for oat-ods, in one place: