Skip to content

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.