Skip to content

Devices & Telemetry Schema

The devices schema owns physical IoT hardware, firmware lifecycles, attribute catalogs, site/zone placements, time-series sensor telemetry, and zone environmental control modes.

Ownership Split

[devices.device_types] ──► [devices.device_attributes] ──► [devices.attributes]
        ▲                             │ (channel config)          │ (base unit/pollutant)
        │ (model definition)          ▼
[devices.devices] ───────► [devices.user_devices] ───────► [places.sites / zones]
  (physical hardware)         (active placement)             (physical location)
  • devices.devices: Physical hardware units identified by unique serial numbers.
  • devices.device_types & device_type_categories: Normalized catalog families (e.g. AIR, WTR) and models (e.g. ERV, Sense, AirGradient).
  • devices.attributes & device_attributes: Base measurement metadata (temperature, humidity, pm25, co2, vocs) mapped to device-specific reporting channels with conversion offsets and coefficients.
  • devices.user_devices: Links physical devices to sites and optional zones in places.

Telemetry History vs. Latest State

To maintain sub-millisecond dashboard queries at scale, the database decouples historical time-series logs from current state:

  1. Append-Only Telemetry (device_telemetry, zone_telemetry):
  2. Uses high-throughput bigint GENERATED BY DEFAULT AS IDENTITY primary keys.
  3. Stores observed_at, received_at, and numeric value.
  4. Queried via sampled window RPCs (api.get_device_telemetry_samples, api.get_zone_telemetry_samples).
  5. Current State (device_attribute_state, zone_attribute_state, device_settings):
  6. Stores exactly one latest reported value per attribute/channel and latest device settings document.
  7. Emits lightweight PostgreSQL notifications (device_attribute_state_changed, zone_attribute_state_changed) on update for live UI invalidation.

Signed Gateway Telemetry Ingress

Edge gateways ingest telemetry securely via cryptographic authentication:

  • Key Registry: Gateways prove identity using enrolled Ed25519 public keys in devices.device_registry_keys. Private keys never leave the hardware.
  • Signed Ingress Protocol (VBT-GW-REQ-1): The FastAPI edge verifies a strict newline-delimited envelope over the raw body before passing bytes to PostgreSQL.
  • Journaling & Relay Governance: devices.accept_gateway_telemetry(...) verifies payload digest, checks idempotency, records an immutable journal in devices.signed_gateway_telemetry_messages, and enforces co-location relay rules (devices.gateway_relay_associations).

Zone Modes & Autonomous Controls

  • Canonical Modes: devices.zone_modes defines system-level operational states (monitoring, ventilating, protecting, balancing, defending, disinfecting, purging).
  • Decision Audits: devices.zone_decision_evaluations and zone_decision_events store an auditable history of autonomous decision cycles, sensor inputs, and device actuation outcomes.