Concepts

OpenSense has a small data model on purpose. Once you understand these seven nouns, the rest of the manual reads as a sequence of CRUD endpoints around them.

Account

The top-level container. One human, one billing relationship. An account holds one or more sites and zero or more integrations (Telegram bot, email list, webhooks, Stripe). Account-level concerns: billing, login email, API token issuance for owner-scoped operations.

Site

A site is a physical location. One street address, one timezone, one vertical preset (HACCP, Legionella, server-room, climate, energy). A chain of three cafés would model itself as three sites under one account.

Site-level concerns: floor-plan image, opening hours (for "out-of-hours" alarm escalation), default report recipients.

Device

A device is a hardware unit that emits measurements: a Shelly H&T, an Efento NS-T, a homebrew ESP32. One device may carry one or more sensors — the H&T has temperature and humidity built in; an ESP32 with three DS18B20 probes carries three channels.

Device-level concerns: ingest token (rotatable), reporting cadence, hardware serial / MAC, firmware version (reported by the device when it sends).

A device belongs to exactly one site at a time. Moving a device to a new site does not rewrite history — past readings remain associated with the old site, which is what HACCP auditors expect.

Sensor

A sensor is a logical input on a device. The H&T has two sensors: one temperature, one humidity. A clamp meter has three sensors (one per phase).

Sensor-level concerns: kind (temperature, humidity, CO₂, leak, voltage, current, power, pressure), unit (the unit the device reports in; we do not re-unit), display name (Walk-in fridge — front shelf).

Channel

A channel is a sensor + the rules attached to it. The split exists because the same sensor can play different roles over time. When you move a walk-in fridge probe from a +4 °C wine room to a –18 °C freezer, the underlying sensor is the same but the channel's thresholds change. The audit trail records the channel state at the time of each measurement.

Channel-level concerns: operating range ([ok_min, ok_max]), warning range ([warn_min, warn_max], optional), grace period (how long out-of-range before alarm), severity escalation.

Measurement

The atom. A (channel_id, ts, value) tuple. Stored in TimescaleDB. Indexed by channel and time. Append-only. No edits, no deletes — corrections are new rows tagged correction_of = <id>.

Alert

An alert is one event in the rule engine: channel X entered ALARM at T, channel X cleared at T+45 min. Alerts are first-class — they are not derived from the measurement stream at read time, they are persisted. This is what makes the audit trail reproducible: an auditor running the same query a year later sees the same events.

A note on kind

Some channels measure quantities that are unbounded on the warm side (temperature in a fridge — too warm is bad, too cold is fine in practice). Others are bounded on both sides (humidity in a museum — too dry cracks wood; too damp grows mould). The rule engine treats both as [ok_min, ok_max] ranges; you simply set ok_min = -∞ (or, in practice, -100) when only the upper bound matters.

What is not modelled

• User beyond a single email per account. We are not a team product yet. Multiple recipients exist for alerts and reports, but they are bare emails / Telegram IDs, not user accounts. This will change once the Team tier ships.
• Inventory. OpenSense does not know what is in the fridge, only the temperature of the fridge. HACCP auditors do not ask "what was on shelf 3", they ask "was the fridge at the right temperature".
• Hardware location within a site. A device has a free-text label; there is no floor-plan coordinate system. A photo on the device page is the intended way to disambiguate "front fridge" from "back fridge".