Capability: Sensor - Numeric

This capability description describes a generic numeric sensor node, and derived unit-specific sensors.

Numeric sensors introduction

A sensor node measures a single sensor value. The value is published under the property value. The descriptions vary by the type of value measured. Depending on the type of sensor, some properties and/or requirements my vary.

They are very strictly defined, allowing only for a single unit or format attribute. This allows MQTT based querying of specific sensor types, without having to parse the device description.

Examples

A Homie device with 1 node as a temperature sensor.

Minimal example

This minimal example only implements the required properties.

Description:

{
  "homie": "5.0",
  "name": "Super Car",
  "version": 7,
  "nodes": {

    "engine-temp": {
      "$profile": ["homie-sensor-temperature/1/0"],
      "name": "Engine temperature",
      "value": {
        "settable": false,
        "retained": true,
        "unit": "°C",
        "type": "float",
        "format": "0:40:0.5",
      }
    }

  }
}

Topics:

homie/5/supercar/$state             → "ready"
homie/5/supercar/$description       → "{... the above json doc ...}"
homie/5/supercar/engine-temp/$profile/homie-sensor-temperature/1 → "0"
homie/5/supercar/engine-temp/value  → "75.0"

Full example

This example implements a sensor including all optional properties.

Description:

{
  "homie": "5.0",
  "name": "Super Car",
  "version": 7,
  "nodes": {

    "engine-temp": {
      "$profile": ["homie-sensor-temperature/1/0"],
      "name": "Engine temperature",
      "value": {
        "settable": false,
        "retained": true,
        "unit": "°C",
        "type": "float",
        "format": "0:120:0.5"
      },
      "raw": {
        "settable": true,
        "retained": true,
        "unit": "°F",
        "type": "float",
        "format": "0:248"
      },
      "raw-topic": {
        "settable": true,
        "retained": true,
        "type": "string"
      },
      "offset": {
        "settable": true,
        "retained": true,
        "type": "float"
      },
      "factor": {
        "settable": true,
        "retained": true,
        "type": "float"
      }

    }
  }
}

Topics:

homie/5/supercar/$state                 → "ready"
homie/5/supercar/$description           → "{... the above json doc ...}"
homie/5/supercar/engine-temp/$profile/homie-sensor-temperature/1 → "0"
homie/5/supercar/engine-temp/value      → "75.0"
homie/5/supercar/engine-temp/raw        → "167"
homie/5/supercar/engine-temp/raw-topic  → "homeassistant/sensor/some/topic"
homie/5/supercar/engine-temp/offset     → "-32"
homie/5/supercar/engine-temp/factor     → "0.555556"

Virtual sensors

Sensors can be virtual sensors, in the sense that the value is not actually measured, but set by a Homie controller. The profile takes this into account by allowing the (raw) value to be settable in those cases.

For example;

a virtual temperature sensor that is set by a controller as the averaga value of all temperature sensors in a room.
a virtual motion sensor called "ground-floor", that has state "presence" as long as any of the sensors on the ground floor is tripped.

By implementing the optional raw property the sensor values become settable, and hence the same profile can be used as a virtual sensor.

homie-sensor-numeric/1/0

This is the common version if no specific profile is available. The profile name is: homie-sensor-numeric/1/0.

Description

A numerical sensor is a sensor for any numerical type data, eg. speed, temperature, volume etc. The type is not further specified, because it can be set using the regular unit attribute on the value. In a similar way the limits and precision can be specified using the format property.

The most basic implementation will only have a value property. There are more advanced options that support calibration, and virtual sensors of this type.

Specifically typed sensors are available for the most common formats. Each with their own profile name and version. The Node layout is the same for all, they only differ by supported unit types

Required properties

value

The value property (required) is the property that holds the sensor value (after calibration).

attributes	value	remark
property-id	"`value`"
settable	`false`	virtual sensors can set the `raw` property.
retained	`true`
unit		the `unit` attribute on this property MUST be specified, see the Homie specification for most common supported units.
format		the `format` attribute SHOULD be specified for precision, minimum and maximum values.
type	"`float`"	To represent integers, us the `format` attribute

If any of the calibration properties are present, then the value is calculated as:

value = (raw-value + offset) * factor

The offset defaults to 0 if not present, and the factor defaults to 1 if not present.

Optional properties

raw

The raw property (optional) is the property that holds the raw sensor value, before calibration.

Note:: This property becomes REQUIRED when any of the following properties are present; raw-topic, offset, or factor.

attributes	value	remark
property-id	"`raw`"
settable	`true`/`false`	mostly non-settable, except for virtual sensors.
retained	`true`
type	`float`
unit		Can be any unit, but most likely the same as the `value` property (or a corresponding type, eg. `°F` as the `raw` type, with `°C` as the `value` type)

raw-topic

The "raw-topic" property (optional) is an MQTT topic where the raw-value should be fetched (by subscribing to it). This allows for creating Homie sensors from any MQTT topic in the system.

The behaviour when receiving a value update from the subscription should be as if the "raw" property was settable, and received a value on its "/set" topic. If the value is set to an empty string, then the topic subscription should be cancelled.

attributes	value	remark
property-id	"`raw-topic`"
settable	`true`
retained	`true`
type	`string`
unit

offset

The offset property (optional) is used to calibrate the raw sensor value. See value for calibration calculation.

attributes	value	remark
property-id	"`offset`"
settable	`true`
retained	`true`
type	`float`
unit

factor

The factor property (optional) is used to calibrate the raw sensor value. See value for calibration calculation.

attributes	value	remark
property-id	"`factor`"
settable	`true`
retained	`true`
type	`float`
unit