Device Configuration in OpenSonde

A top-level overview of how devices, device models, and parameters are configured in OpenSonde — what the building blocks are, how they fit together, and how a device goes from a defined product to something reporting readings.

1. Purpose & audience

This document is written for OEM partners. OpenSonde is a white-label environmental telemetry platform: OEMs ship physical devices that report into OpenSonde. Today, the configuration that defines what a device is and what it measures — device models and the parameters (sensors) each model exposes — is set up internally.

The goal is to eventually expose an OEM control panel: a self-service app where OEMs can define and manage their own device models and configure the sensors each model reports, rather than that being set up internally. Before we build that, OEMs need a clear picture of how the current setup works — that is what this document provides. See §5 for what maps to the future control panel.

2. The building blocks

Configuration is layered from generic and reusable down to the readings a device sends:

Building block	What it is
Global parameter	A parameter available across the platform (pH, temperature, EC…), with a canonical unit and number formatting. Defined once and reused everywhere.
Device model	A kind of device (e.g. "BOB") — the product definition, including how often it should report.
Model's sensors	The parameters a model exposes: which sensors that kind of device has, and the wire key each sensor uses.
Device	A specific, registered unit that is live and owned by someone.
Device's sensors	The parameters on that specific device — what it actually reports, and how each is labelled.
Readings	The values a device sends in over time.

Two ideas are worth internalising up front:

1. A model is a template. When a device is registered, the model's sensor list is copied onto the device. From then on the device's sensors are its own and can be tuned per unit, independent of the model.
2. One global parameter can be reused by many sensors. A device with two temperature probes has two sensors that both use the single temperature global parameter — reusing its unit and formatting — while telling themselves apart by their wire key and display label. See §4.

flowchart LR
    GP["Global parameters<br/>(pH, temperature, EC…)"] -->|"chosen for a model"| M["Device model<br/>(e.g. BOB)"]
    M -->|"copied on registration"| D["Device<br/>(a specific unit)"]
    D -->|"reports over time"| R["Readings"]

The wire key

Each sensor has a wire key — the short identifier a device's firmware uses for that sensor in the data it sends (e.g. t0, ph). OpenSonde matches incoming values to a device's sensors by this key, so the keys a model defines must line up with what the firmware actually sends. A key can differ from the global parameter's name, which is what lets two temperature probes on one device (t0, t1) map to the same temperature parameter.

3. How a device gets configured and reports

flowchart TD
    subgraph def["Model definition (internal today)"]
        M1["Create a device model"] --> M2["Add its sensors<br/>(parameter + wire key)"]
    end

    subgraph reg["Registration"]
        R1["A device is created for a model"] --> R2["The model's sensors are<br/>copied onto the device"]
    end

    subgraph ing["Reporting"]
        I1["Device sends readings,<br/>each value tagged with a wire key"] --> I2["Each value is matched<br/>to one of the device's sensors"]
        I2 -->|match| I3["Reading stored"]
        I2 -->|no match| I4["Value ignored"]
    end

    subgraph disp["Display"]
        D1["Readings shown per sensor,"] --> D2["formatted with the parameter's<br/>unit + decimals, and its label"]
    end

    def --> reg --> ing --> disp

1. Model definition — a model is created and its sensors added (each a parameter plus the wire key the firmware will send). Today this is done internally.
2. Registration — when a device is created for a model, the model's sensors are copied onto the device. The template's wire key becomes the device's starting key; from there the device's sensors are its own and can be edited per device (e.g. relabelling).
3. Reporting — a device sends readings, each value tagged with a wire key. OpenSonde matches each value to one of the device's sensors and stores it. Values whose key doesn't match a configured sensor are ignored.
4. Display — readings are shown per sensor, formatted using the parameter's unit and decimal places and labelled with the sensor's display name (or the parameter's default label if none is set).

4. Worked example: BOB

"BOB" is the primary model most current devices use. It has two temperature probes — air and water — that both use the single temperature parameter, but need distinct wire keys and labels.

BOB's model defines temperature twice, with different wire keys:

Sensor	Parameter	Wire key
Temperature probe 1	Temperature	t0
Temperature probe 2	Temperature	t1

On a registered device those become two sensors that can be labelled independently:

Wire key	Label
t0	Air Temperature
t1	Water Temperature

Both reuse the temperature parameter for unit (°C) and formatting, while the wire key routes each firmware value to the right sensor and the label distinguishes them in the UI. BOB's other sensors (pH, EC, turbidity, salinity, total dissolved solids, ORP, tilt/orientation, …) are ordinary single-sensor parameters whose wire key matches the parameter and which use its default label.

This is why a sensor carries its own wire key and label rather than relying solely on the global parameter.

5. Configuration today, and the planned OEM control panel

Everything that defines a product and its sensors is currently set up internally:

Capability	Today (internal)	Planned OEM control panel
Global parameters	Created/edited internally (unit, decimals)	Shared library; OEMs pick from it (org-specific parameters possible)
Device models	Created/edited internally	OEMs manage their own models
Model's sensors	Parameters + wire keys attached to a model internally	OEMs configure what each model reports
Per-device tuning	Sensors seeded from the model, editable	Same, surfaced to OEMs/customers
Provisioning	Not yet built	OEMs register their manufactured units (serial/secret) against a model before they are claimed

The building blocks above are expected to stay the same; the OEM control panel is primarily a matter of exposing them to OEMs with the right scoping and permissions. Provisioning — linking a manufactured unit to a model before it is claimed — is the one area not yet implemented.