Attributes
An attribute is one value a device exposes: a temperature, a setpoint, a running state. Each entry under a driver's attributes list declares how that value is read, written, decoded and presented.
attributes:
- name: temperature_setpoint
data_type: float
read: HR0
write: HR0
codecs:
- byte_convert: float32 big_endian
polling_group: core
label:
default: Setpoint
translations: { fr: Consigne }
description: Requested room temperature # a bare string is the `default`
group: setpoints
unit: °C
- name: fault
kind: fault
severity: alert
data_type: bool
read: HR3
healthy_value: true # NC contact: closed is healthy
Core fields
| Field | Required | Description |
|---|---|---|
name |
yes | Attribute identifier. Keys the driver's attributes: a repeated name keeps the last entry only |
data_type |
yes | float, int, bool or str |
read |
yes | Transport address for reading |
write |
no | Transport address for writing. Omit for a read-only attribute |
read_write |
no | Shorthand that fills both read and write with the same address. An explicit read or write next to it keeps its own value |
codecs |
no | Ordered list of codecs, applied in order on read and reversed on write when reversible (see Reversible vs non-reversible). Each entry is a single-key object (- json_pointer: /path) |
polling_group |
no | Name of an update_strategy.polling_groups entry that polls this attribute. Must exist in the driver, see Polling groups |
push |
no | true subscribes to the value instead of polling it. Only consulted on hybrid pull+push transports (e.g. OPC-UA); push-only transports subscribe every attribute, pull-only transports ignore it. Default false |
Every attribute needs a read address: write-only attributes do not exist. An unknown data_type or an unknown key inside a metadata object is rejected when the driver is loaded. An unknown attribute-level key (a misspelt value_lables) is rejected when the attribute is edited through the API, but dropped silently when the driver is loaded from a file.
Kind and faults
kind says what an attribute is for. It defaults to standard when absent.
| Kind | Description |
|---|---|
standard |
A plain value. Default |
fault |
A fault indicator. The device is reported faulty while the value is not one of healthy_values. See Active faults |
internal |
Generated by Gridone (e.g. connection status). Rejected in a driver |
A kind: fault attribute takes two extra fields:
| Field | Description |
|---|---|
severity |
info, warning or alert. Default warning |
healthy_value / healthy_values |
The values meaning "no fault", as one scalar (healthy_value) or a list (healthy_values). Declaring both is rejected. When neither is set the default depends on data_type: [false] for bool, [0] for int, [""] for str. A float fault has no default: without an explicit list, every value counts as faulty |
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.
Presentation metadata
Every attribute may carry optional presentation metadata. It is stored with the driver and never interpreted by Gridone. Unknown keys inside these objects are rejected.
The texts (label, description, group, value_labels) are the driver's, identical for every device of the driver, so the API also serves them once per driver as its labels document. Each device carries a driver_revision that moves whenever the driver changes; clients cache the labels under it and read them again only then. Device attributes carry none of label and description: a client that names an attribute reads the driver's labels document.
| Field | Description |
|---|---|
label |
Display name. An object with a required default (1–200 characters) and optional translations keyed by language tag (fr, en, fr-CA; lowercase 2–3 letter language, optional subtags). A bare string is accepted as a shortcut for { default: <string> }. Clients resolve the exact tag, then the base language, then default |
description |
Longer help text, same shape as label |
user_confirmation |
Consequence text shown before a write is sent, same shape as label. See Human confirmation |
group |
snake_case key (^[a-z][a-z0-9_]*$, 64 characters max) grouping related attributes together |
unit |
Free unit symbol, 1–16 characters (°C, %, W, kWh, m³/h). Gridone has no unit nomenclature yet: the symbol is displayed as-is |
value_labels |
bool attributes only. A list of {value, label} entries naming the two states, where label has the same shape as label above. Both true and false must be labelled exactly once; 0 / 1 are rejected, not coerced. Stored and served with false first, whatever the authored order. A list rather than a map keyed by the value, because JSON has no boolean keys |
- name: running
data_type: bool
read: HR2
value_labels:
- value: true
label: { default: Running, translations: { fr: Marche } }
- value: false
label: { default: Stopped, translations: { fr: Arrêt } }
Measurement
measurement says what a numeric reading measures, so Gridone can compute its energy. It is optional and only accepted on int and float attributes. Its unit is the attribute's unit. Unknown keys are rejected.
| Key | Description |
|---|---|
kind |
index (a cumulative counter: energy is the difference between two readings, the delta operator), power (a rate: energy is its integral over time) or other. Required. A declared index refuses integral, a declared power refuses delta |
sign |
positive (never negative; an index only goes up, or wraps at its rollover) or signed (may go negative, an index go down, as on a two-way meter). Default positive |
resolution |
The smallest step the reading shows, in its unit. Positive number. An index going down by no more than it is rounding, not a drop |
rollover_modulus |
Where an index wraps back to 0: a counter showing 0 to 999 has a modulus of 1000, never 999. Positive number, a whole number on an int attribute (1000000.0 is read as 1000000). Only on an index that is not signed |
- name: index
data_type: int
read: HR10
unit: kWh
measurement:
kind: index
rollover_modulus: 1000000
An index that goes down reads as unknown (counter_decreased), never as a negative consumption, unless the drop is within resolution or is a wrap: more than half the rollover_modulus and less than all of it. Changing an attribute's unit or codecs (a patch, a package install, a device moved to another driver) records a discontinuity on the attribute's history from that moment: no consumption is computed across it. The change is refused if that record cannot be stored. Changing measurement does not: it applies to the whole history. See the energy rules of the timeseries package.
Write constraints
write_constraints declares the values a writable int or float attribute accepts. Declare at least one of step, minimum or maximum.
| Key | Description |
|---|---|
step |
Positive number, or { attribute: <name> } to use the current value of another int/float attribute (a device's configurable precision). Accepted values are whole multiples of step, counted from 0, not from minimum. With step: 0.5, 21.5 is accepted and 21.3 refused |
minimum |
Inclusive lower bound: a number, or { attribute: <name> } to use the current value of another int/float attribute of the same driver |
maximum |
Inclusive upper bound, same forms as minimum |
sentinels |
Values that bypass the bounds and step checks (256 max). See Command validation |
All three also accept an expression. A boolean or string, a step of 0 or less, or a constant minimum above a constant maximum is rejected.
- name: temperature_setpoint
data_type: float
read_write: HR0
write_constraints:
step: 0.5
minimum: { attribute: temperature_setpoint_min }
maximum: 30
- name: temperature_setpoint_min
data_type: float
read: HR1
The service enforces these constraints on every write, from the UI, API commands, CLI and automations alike, before anything reaches the device. A write whose referenced step or bound is unknown (the attribute has no value yet, or is missing on the device), or whose referenced step is not positive, is refused rather than let through unchecked.
Constraints are validated when the driver is loaded or edited: a constraint on a non-numeric attribute, a bound referencing a missing or non-numeric attribute, or a self-reference is rejected. Renaming a referenced attribute updates the references that point at it; deleting one is refused while another attribute still bounds itself on it.
Command validation
default_value, write_rules, write_options and value_mapping declare what a write may do beyond numeric bounds: conditions on sibling attributes, a finite list of choices, and mappings between user-facing and device values. See declarative command validation.
Firmware and hardware support
supported_when is an optional condition over observed attributes of this device,
using the command condition language. It applies to reads
and writes, including read-only attributes. For example, a driver may name the
exact verified builds that implement a field:
- name: revision
data_type: str
read: GET /revision
- name: optional_limit
data_type: float
read_write: GET /limit
supported_when:
op: in
value: { attribute: revision }
values: [verified-build-a, verified-build-b]
Use verified identities/capabilities, not a guessed ordering of hashes or version strings. Conditions may combine firmware, hardware and variant observations. All references must exist in the driver; capability/mapping cycles and candidate references are rejected when loading it. Renames preserve these references.
The public write_state.support is supported, unsupported or unknown.
A false condition means not supported; a missing or stale identity observation
means support not yet known. Both refuse writes and active reads of the
conditional field; neither permits rules to use a cached value for it. Acquisition
reads the identity dependencies first and then reads supported dependencies. A
missing response alone never proves a capability is absent. A driver without
supported_when keeps its previous behavior.
Supported status is not proof that the attribute has been read. Its current value can still be unavailable, invalid or stale. The attribute panes and command reasons distinguish unsupported capability from missing compatibility data.