Standard Devices
Gridone is designed to drive any device through its extensible driver system. However, some device categories are so common in buildings (thermostats, heat pumps, weather stations...) that they deserve first-class support.
Standard devices are devices whose driver declares a type matching one of the registered standard schemas. When a driver has a type, Gridone enforces that its attributes conform to the expected schema — giving you a consistent data model and a purpose-built UI out of the box.
How it works
Driver type declaration
A driver opts into a standard type by setting the type field:
id: my-thermostat-driver
vendor: Acme
model: T-1000
transport: mqtt
type: thermostat # ← declares this driver as a standard thermostat
attributes:
- name: temperature
data_type: float
# ...
Schema validation
When a driver is registered with a type, Gridone validates its attributes against the corresponding standard schema:
- Required attributes must be present with the correct name and data type.
- Optional attributes may be omitted, but if present they must match the expected data type.
- Drivers may define additional attributes beyond the standard schema — the schema only constrains what must exist, not what can exist.
A schema only ever imposes attribute names and data types — never physical units or value ranges. Gridone is unit-agnostic: it makes no assumption about the unit a device reports for a given attribute. Any unit shown in the tables below is purely illustrative (e.g. a temperature is a float, whether the device reports °C or °F).
Validation runs at driver registration time. If an attribute is missing or has the wrong type, the driver is rejected with a clear error message.
Multiple-instance attributes
Some standard schemas support multiple-instance attributes — useful for devices with repeated components (e.g., multiple compressors in a heat pump). These attributes use a suffix convention:
- Numeric suffix:
compressor_suction_temperature_1,compressor_suction_temperature_2 - Alphabetic suffix:
compressor_suction_temperature_A,compressor_suction_temperature_B
The schema field defines the base name; the driver provides suffixed variants.
Built-in UI
Standard devices get dedicated graphical representations in the Gridone UI, with both a preview card (shown in device lists) and a control panel (shown in device detail). These display device data using domain-specific visuals rather than generic attribute tables.
Non-standard attributes are still accessible through the generic attribute view.
Standard values
Gridone is by default agnostic of which values device attributes take. However, some standard devices take the same set of values — like a thermostat's operating mode (heat, cool, …). To improve user experience and extensibility, we define recommended (standard) values on some attributes for standard devices.
Note: These are recommended values, not hard-enforced (a driver can still use arbitrary values). But standard values get a custom, meaningful rendering in the UI, and make reuse easier: users know what values to expect for an attribute based on the device type.
Standard device types
The following standard types are currently registered.
Thermostat
Key: thermostat
A climate control device that reads ambient temperature and allows setting a target temperature within configurable bounds.
| Attribute | Data type | Required | Description |
|---|---|---|---|
temperature |
float | yes | Current ambient temperature |
temperature_setpoint |
float | yes | Desired target temperature |
temperature_setpoint_min |
float | yes | Minimum allowed setpoint |
temperature_setpoint_max |
float | yes | Maximum allowed setpoint |
onoff_state |
bool | yes | Power on/off state |
mode |
string | yes | Operating mode (Standard values: heat, cool, fan, auto, idle — no current heating or cooling demand) |
fan_speed |
string | no | Fan speed (Standard values: low, medium, high, auto) |
UI behavior: The control panel displays the current temperature and setpoint, with increment/decrement controls that respect the min/max bounds. Mode and power state are also shown and controllable.
Air-to-Water Heat Pump (AWHP)
Key: awhp
An air-to-water heat pump with water-side metrics and optional refrigerant circuit monitoring.
| Attribute | Data type | Required | Multiple | Description |
|---|---|---|---|---|
onoff_state |
bool | yes | no | Operating state |
unit_run_status |
string | yes | no | Run status (e.g., running, idle) |
mode |
string | yes | no | Operating mode (Standard values: heat, cool, fan, auto, idle — no current heating or cooling demand) |
inlet_temperature |
float | yes | no | Water inlet temperature |
outlet_temperature |
float | yes | no | Water outlet temperature |
setpoint_temperature |
float | yes | no | Target water temperature |
outdoor_temperature |
float | no | no | Ambient outside temperature |
compressor_suction_temperature |
float | no | yes | Refrigerant suction temperature |
compressor_suction_pressure |
float | no | yes | Refrigerant suction pressure |
compressor_discharge_temperature |
float | no | yes | Refrigerant discharge temperature |
compressor_discharge_pressure |
float | no | yes | Refrigerant discharge pressure |
condenser_saturated_refrigerant_temperature |
float | no | yes | Condenser saturated temperature |
condenser_refrigerant_pressure |
float | no | yes | Condenser pressure |
evaporator_saturated_refrigerant_temperature |
float | no | yes | Evaporator saturated temperature |
evaporator_refrigerant_pressure |
float | no | yes | Evaporator pressure |
Attributes marked Multiple = yes support suffixed instances (e.g., compressor_suction_temperature_1, compressor_suction_temperature_A) for multi-circuit or multi-compressor units.
UI behavior: The control panel displays a schematic of the refrigerant circuit (evaporator, compressor, condenser, expansion valve) with live temperature and pressure values, plus water-side metrics (inlet, outlet, setpoint).
Weather Sensor
Key: weather_sensor
An outdoor weather station providing ambient conditions data.
| Attribute | Data type | Required | Description |
|---|---|---|---|
temperature |
float | yes | Ambient temperature |
weather_code |
int | yes | WMO weather interpretation code |
wind_speed |
float | yes | Wind speed |
wind_direction |
int | yes | Wind direction |
humidity |
float | yes | Relative humidity |
UI behavior: The control panel displays the weather condition with an icon derived from the WMO code, a prominent temperature reading, wind speed with compass direction, and humidity.
Air Extractor
Key: air_extractor
An air extraction unit (extracteur / tourelle) that removes stale air from a space.
| Attribute | Data type | Required | Description |
|---|---|---|---|
onoff_state |
bool | no | Power on/off state (running/stopped) |
fan_speed |
float | no | Fan speed — variable-speed units |
flow_switch |
bool | no | Air-flow proven by a differential-pressure switch |
flow_switch is a flow-proving status, not a measurement: it confirms the fan is actually moving air, catching a broken belt, seized motor, or fully blocked filter even when commanded on. Running state is derived from fan_speed (> 0) or onoff_state when present.
Faults (e.g. a general fault synthesis) are not part of the standard schema yet; drivers declare them as non-standard attributes for now.
UI behavior: The control panel shows the running state, plus the fan speed when available.
Single-Flux Air Handling Unit (CTA simple flux)
Key: ahu_single_flux
An air handling unit with a single supply air-treatment train (filter, coil, fan) and no heat recovery.
| Attribute | Data type | Required | Description |
|---|---|---|---|
supply_air_temperature |
float | yes | Supply air temperature |
supply_air_temperature_setpoint |
float | yes | Supply air temperature setpoint (the heating setpoint on dead-band units) |
supply_fan_speed |
float | yes | Supply fan speed |
onoff_state |
bool | no | Power on/off state |
hvac_mode |
string | no | Operating mode |
supply_air_temperature_cooling_setpoint |
float | no | Cooling setpoint on units regulating in a dead band |
outdoor_air_temperature |
float | no | Fresh/outdoor air temperature |
supply_air_pressure |
float | no | Supply duct pressure |
supply_air_pressure_setpoint |
float | no | Supply duct pressure setpoint |
supply_air_flow |
float | no | Supply air flow |
supply_air_flow_setpoint |
float | no | Supply air flow setpoint |
supply_air_humidity |
float | no | Supply air relative humidity |
extract_air_temperature |
float | no | Return air temperature, if fitted |
extract_air_pressure |
float | no | Return duct pressure |
extract_fan_speed |
float | no | Return fan speed |
supply_flow_switch |
bool | no | Supply fan air flow proven by a differential-pressure switch |
extract_flow_switch |
bool | no | Return fan air flow proven |
outdoor_air_damper_open |
bool | no | Fresh air damper open (limit switch) |
supply_air_damper_open |
bool | no | Supply damper open (limit switch) |
supply_prefilter_clogged |
bool | no | Supply pre-filter clogged |
supply_filter_clogged |
bool | no | Supply filter clogged |
supply_filter_differential_pressure |
float | no | Pressure drop across the supply filter |
heating_valve |
float | no | Heating coil valve opening |
heating_water_flow |
float | no | Water flow through the heating coil |
heating_water_supply_temperature |
float | no | Heating coil water inlet temperature |
heating_water_return_temperature |
float | no | Heating coil water outlet temperature |
heating_power |
float | no | Thermal power delivered by the heating coil |
heating_energy |
float | no | Cumulative heating energy |
cooling_valve |
float | no | Cooling coil valve opening |
cooling_water_flow |
float | no | Water flow through the cooling coil |
cooling_water_supply_temperature |
float | no | Cooling coil water inlet temperature |
cooling_water_return_temperature |
float | no | Cooling coil water outlet temperature |
cooling_power |
float | no | Thermal power delivered by the cooling coil |
cooling_energy |
float | no | Cumulative cooling energy |
The optional vocabulary is the single-flux subset of ahu_double_flux; see there for the conventions on filters, flow switches and coil loops.
UI behavior: The control panel displays the supply air temperature and setpoint, fan speed, and coil valve positions.
Double-Flux Air Handling Unit (CTA double flux)
Key: ahu_double_flux
An air handling unit with both supply and extract air trains and an energy-recovery exchanger. A superset of ahu_single_flux; the required extract_air_temperature and extract_fan_speed distinguish it from the single-flux type.
| Attribute | Data type | Required | Description |
|---|---|---|---|
supply_air_temperature |
float | yes | Supply air temperature |
supply_air_temperature_setpoint |
float | yes | Supply air temperature setpoint (the heating setpoint on dead-band units) |
supply_fan_speed |
float | yes | Supply fan speed |
extract_air_temperature |
float | yes | Extract/return air temperature |
extract_fan_speed |
float | yes | Extract fan speed |
onoff_state |
bool | no | Power on/off state |
hvac_mode |
string | no | Operating mode |
supply_air_temperature_cooling_setpoint |
float | no | Cooling setpoint on units regulating in a dead band |
outdoor_air_temperature |
float | no | Fresh/outdoor air temperature |
exhaust_air_temperature |
float | no | Exhaust (rejected) air temperature |
supply_air_pressure |
float | no | Supply duct pressure |
supply_air_pressure_setpoint |
float | no | Supply duct pressure setpoint |
extract_air_pressure |
float | no | Extract duct pressure |
extract_air_pressure_setpoint |
float | no | Extract duct pressure setpoint |
supply_air_flow |
float | no | Supply air flow |
supply_air_flow_setpoint |
float | no | Supply air flow setpoint |
extract_air_flow |
float | no | Extract air flow |
extract_air_flow_setpoint |
float | no | Extract air flow setpoint |
supply_air_humidity |
float | no | Supply air relative humidity |
extract_air_humidity |
float | no | Extract air relative humidity |
extract_air_co2 |
float | no | CO₂ concentration in the extract air (demand-controlled ventilation) |
supply_flow_switch |
bool | no | Supply fan air flow proven by a differential-pressure switch |
extract_flow_switch |
bool | no | Extract fan air flow proven |
outdoor_air_damper_open |
bool | no | Fresh air damper open (limit switch) |
supply_air_damper_open |
bool | no | Supply damper open (limit switch) |
supply_prefilter_clogged |
bool | no | Supply pre-filter clogged |
supply_filter_clogged |
bool | no | Supply filter clogged |
extract_filter_clogged |
bool | no | Extract filter clogged |
supply_filter_differential_pressure |
float | no | Pressure drop across the supply filter |
extract_filter_differential_pressure |
float | no | Pressure drop across the extract filter |
heating_valve |
float | no | Heating coil valve opening |
heating_water_flow |
float | no | Water flow through the heating coil |
heating_water_supply_temperature |
float | no | Heating coil water inlet temperature |
heating_water_return_temperature |
float | no | Heating coil water outlet temperature |
heating_power |
float | no | Thermal power delivered by the heating coil |
heating_energy |
float | no | Cumulative heating energy |
cooling_valve |
float | no | Cooling coil valve opening |
cooling_water_flow |
float | no | Water flow through the cooling coil |
cooling_water_supply_temperature |
float | no | Cooling coil water inlet temperature |
cooling_water_return_temperature |
float | no | Cooling coil water outlet temperature |
cooling_power |
float | no | Thermal power delivered by the cooling coil |
cooling_energy |
float | no | Cumulative cooling energy |
exchanger_utilization |
float | no | Energy exchanger utilization — heat and cool recovery |
exchanger_efficiency |
float | no | Energy exchanger efficiency, as reported by the controller |
Only the five-attribute core is required. The optional vocabulary names what deployed units actually expose, so that the synoptic can place each reading on the equipment it belongs to: a flow or a pressure drop on its filter, a limit switch on its damper, a water loop under its coil.
Flow switches (supply_flow_switch, extract_flow_switch) are flow-proving statuses, not measurements — the same concept as air_extractor.flow_switch: they confirm the fan is actually moving air. onoff_state stays the unit-level verdict.
Filters are the one alarm-like state named by the schema, because the synoptic has to know which filter to colour. Declare *_filter_clogged with kind: fault (as liquid_detector does for liquid_detected): the attribute satisfies the schema and the platform's fault machinery picks it up unchanged. Units that measure the pressure drop instead report *_filter_differential_pressure.
Coil loops describe the water side of each coil: *_valve is the position, *_water_flow, *_water_supply_temperature and *_water_return_temperature the hydraulics, *_power the thermal power delivered and *_energy its cumulative counterpart. Units come from the driver, never from the name.
exchanger_utilization is a reported value (e.g. recovery wheel speed or bypass position), never computed by Gridone. The exchanger recovers energy in both directions — heat in winter and coolth (free-cooling) in summer — so the name is direction-neutral. exchanger_efficiency is likewise the controller's own figure.
All other faults and alarms (frost, smoke, fire damper, fan trips, command/feedback discrepancies, general fault synthesis) are not part of the standard schema; drivers declare them as fault attributes under whatever name the site uses.
UI behavior: The control panel displays both supply and extract air temperatures, fan speeds, coil valve positions, and exchanger utilization.
Liquid Detector
Key: liquid_detector
A probe reporting conductive liquid at its sensing point — typically under a riser, a plant-room valve set, a drip tray or a bathroom floor.
| Attribute | Data type | Required | Description |
|---|---|---|---|
liquid_detected |
bool | yes | Conductive liquid bridging the probe |
Named for what the sensor can actually tell. A conductive probe cannot distinguish water from glycol, condensate or coolant, and the tray it sits in often holds one of those — so the reading is liquid_detected, even where the UI label reads "leak detector" because that is what the trade calls the product.
The schema holds a single attribute on purpose: a detector answers one question. Probes that also report ambient conditions (temperature, humidity) or a battery level declare those as non-standard attributes.
Declare the reading as a fault. The recommended driver shape marks liquid_detected as an alert-severity fault attribute:
- name: liquid_detected
kind: fault
severity: alert
data_type: bool
# healthy_values defaults to [false] for a bool — dry is healthy
Fault attributes go through standard-schema validation exactly like standard ones, so this satisfies the schema while handing the alarm to the platform: the device reads as faulty, the severity tint and fault badge appear on the fleet card and device header, the attribute gets a row in Active faults with how long it has been active, and fault notifications dispatch. Nothing about the alarm is the standard component's job.
UI behavior: The preview card and the control panel show a drop glyph and a plain verdict — filled and water-blue when liquid is present, outlined and muted when dry. The alarm colour (red) is deliberately not used here: it belongs to the fault chrome around the reading, so the two carry different information instead of repeating each other.
Pump
Key: pump
A circulator, booster or process pump — from a 41-point smart variable-speed unit down to a motor wired to two dry contacts.
| Attribute | Data type | Required | Description |
|---|---|---|---|
onoff_state |
bool | yes | Running state |
head |
float | no | Delivered head |
volume_flow |
float | no | Delivered flow |
speed |
float | no | Pump speed |
operating_hours |
float | no | Cumulative run time |
control_mode |
string | no | Regulation mode (constant pressure, proportional, fixed speed…) |
setpoint |
float | no | Configured setpoint |
actual_setpoint |
float | no | Setpoint in force after external influence |
power |
float | no | Electrical power draw |
energy |
float | no | Cumulative electrical energy |
motor_current |
float | no | Motor current |
liquid_temperature |
float | no | Pumped-liquid temperature |
starts |
float | no | Cumulative number of starts |
motor_voltage |
float | no | Motor voltage |
Only onoff_state is required, and that is the design. head, volume_flow and speed are exposed by every surveyed source and would, on coverage alone, be required — but every surveyed source is a smart variable-speed pump, and a building is full of pumps that are not. Requiring the hydraulic trio would make every dry-contact circulation and booster pump untypable.
Whether it turns is the only thing true of every pump.
Consequently a driver must degrade: a dry-contact pump declares onoff_state and nothing else from this schema, and the UI renders what is present rather than a grid of dashes.
Faults are not schema fields. A standard schema describes what a device measures; alarms are orthogonal infrastructure that already works on any attribute of any name through kind: fault. A pump's fault and warning contacts are declared by its driver and surface through the generic machinery — badge, severity tint, active-fault row, notifications — without the type contract naming them. Each site maps its own fault points, whatever they are called:
- name: fault # any name; the schema never sees it
kind: fault
severity: alert
data_type: bool
- name: warning
kind: fault
severity: warning
data_type: bool
healthy_values defaults to [false] for a bool, so an open contact is healthy. Dry-contact wiring is not always normally-open: on NC wiring a closed contact (true) means healthy, and the driver must say so explicitly, or the pump ships permanently faulted.
- name: fault
kind: fault
severity: alert
data_type: bool
healthy_value: true # NC contact: closed is healthy
Declare the polarity from the wiring rather than inverting with a codec — healthy_values is what the fault machinery reads, and a codec would leave the recorded series inverted too.
UI behavior: The control panel draws the pump itself — volute, motor, impeller — and places each reading where it physically belongs: liquid temperature on the suction side, speed and electrical draw at the motor, head and flow at the discharge. Health colours are deliberately absent; the pump is drawn in the hydraulic accent when turning and muted when stopped, leaving red, amber and green to the fault machinery that owns them. A dry-contact pump renders the pump alone.
Heat Meter
Key: heat_meter
A thermal energy meter on a hot or chilled water circuit. The contract follows EN 1434, the European standard for heat meters: a meter computes energy from the volume that flows through it and the temperature difference across the circuit, so every compliant meter exposes the same small set of readings.
| Attribute | Data type | Required | Description |
|---|---|---|---|
index |
float | yes | Cumulative thermal energy counter |
volume |
float | no | Cumulative volume |
power |
float | no | Instantaneous thermal power |
flow |
float | no | Instantaneous flow |
supply_temperature |
float | no | Supply water temperature |
return_temperature |
float | no | Return water temperature |
delta_t |
float | no | Supply and return temperature difference |
Only index is required. The energy counter is what defines a heat meter; everything else is optional so that a meter exposing only part of the set can still be typed. The counter is named index, as on the electricity meter.
One circuit, one counter. Some devices meter heat as a side function and ship two counters, one for heating and one for cooling (an energy valve, a pump with built-in metering). A device sits on one circuit, so its driver maps that circuit's counter to index and keeps the other one as an extra, non-standard attribute.
UI behavior: The control panel shows a tile for each reading the driver declares, in the unit the driver declares. A declared reading with no value yet shows a dash; a reading the driver does not declare gets no tile. The fleet card leads with the power, then the index.
PMS Monitor
Key: pms_monitor
A hotel room as its property management system (PMS) sees it. Gridone never reads the PMS: a push (the Agrid dashboard's PMS handler, or any integration) sends each room's snapshot to a webhook transport, and the device holds the last value of every key it received.
| Attribute | Data type | Required | Description |
|---|---|---|---|
pms_room_name |
string | yes | The room's name on the PMS side, which may differ from the device name |
occupied |
bool | yes | Whether a guest is checked into the room |
guest_count |
int | yes | Guests checked in, 0 when the room is available |
next_arrival_at |
string | no | ISO 8601 datetime of the next expected arrival, empty when none is scheduled |
room_type |
string | no | The room type as the PMS labels it, a code or a name, shown as is |
cleaning_status |
string | no | Housekeeping state: CLEAN, DIRTY, PICKUP, IN_PROGRESS, INSPECTED, OUT_OF_ORDER or OUT_OF_SERVICE |
A boolean, not a booking status. The PMS decides what "occupied" means (a check-in, not a reservation), so the schema carries its verdict rather than a reservation state Gridone would have to interpret.
The two room fields are optional because not every PMS exposes them. cleaning_status is a fixed set, the common ground of the PMS vendors' housekeeping states, so the UI can translate it; room_type is free text because every hotel names its types differently.
UI behavior: The fleet card leads with the occupancy (Occupied with the guest count, Available with the next arrival). The control panel repeats that lead, then shows the cleaning status with a glyph and a translated label, and the room type as the PMS wrote it. A status outside the known set is shown as is. An attribute the driver does not declare gets no tile.