Number Entity

The number entity holds a single numeric value which can be read and set. It is the writable counterpart of the sensor entity and the numeric counterpart of the select entity.

The value range, step size, and unit are defined by the integration driver in the entity options. The Remote renders a number entity as a slider or as a value field with increment and decrement buttons, depending on where it is used:

• On a profile page the entity is shown with its default representation. The display_mode option is a hint for the preferred representation, see Display Mode.
• In an activity user interface, the number widget shows the entity with its default representation, and the slider widget can be bound to the value feature. Both can be positioned freely in the page grid.
• The Remote 3 touch-slider can be assigned to the value feature.

Typical use cases are device settings which don’t fit any other entity, for example an amplifier’s bass level, the zoom of a camera, a projector’s lens shift, the speed of a fan, or a custom “scene intensity” value.

Features

• R: readable
  • ✅ Feature has a readable attribute to retrieve the current value.
• W: writeable
  • ✅ Feature has one or multiple commands to set the value.

If the current value cannot be read from the device, the readable option can be set to false. See Options.

The transition feature is optional and must only be set if the device supports it. Without it, the duration parameter of the set_value command is not offered to the user, e.g. in the command editor of the web-configurator. The Remote offers a separate set-value command with a transition time for entities with the transition feature; the driver always receives set_value.

Attributes

States

The state attribute is optional for a number entity and defaults to ON if not specified.

The number entity only supports the ON state and the common entity states.

Device Classes

The optional device class specifies the type of the value. It is used by the UI to show a matching default icon, a default unit and to format the value. If not specified, the number entity is a generic number, and the unit option defines the unit label.

The device classes are kept in sync with the sensor entity: a device class has the same name, default unit and meaning in both entities. New device classes are added to both entities, unless a class only makes sense for one of them, like the binary sensor device class.

• The unit option overrides the default unit of the device class.
• There is no automatic unit conversion: value, min, max and step are always in the unit of the entity. Unlike the sensor entity, a temperature number entity is not converted between °C and °F.

Options

The option vocabulary is similar to the number field in the driver setup settings, with the following differences:

• The step size option is called step instead of steps.
• unit is a plain text instead of a language text.
• min and max have a default value. An unbounded range must be set explicitly with null.

Notes:

• The options are static and are read when the entity is configured in the Remote. If the value range of a device changes, the integration driver has to send an updated entity definition with the entity_available event. Dynamic ranges in the entity attributes are not supported.
  • 🚧 The entity_available event is not yet supported by the Remote. Until then, an updated entity definition is only applied when the Remote retrieves the available entities with the get_available_entities request.
• The step size should be compatible with decimals. A step size of 0.5 requires at least 1 decimal place to show every possible value.
• With readable: false the Remote does not expect an entity_change event after a command and shows the last value sent to the driver. The increment and decrement commands don’t send a value: the Remote shows the last value plus or minus the step option, clamped at min and max. This is only for display, the command is still sent without a value. This should be avoided whenever possible.

Value format

The UI rounds the value for display only and always shows it with the same number of decimal places:

• With the decimals option, the value is shown with exactly this number of decimal places. E.g. 21 with decimals: 1 is shown as 21.0.
• Without the decimals option, the number of decimal places of step, min and max is used. E.g. a step size of 0.5 shows 1 decimal place, a step size of 1 with min: 0.5 or max: 2.5 as well.

Calculated values should be rounded to the step size, or at least to 15 significant digits, to remove floating point artifacts like 1.499999999999997.

User overrides

The following options can be overridden by the user in the web-configurator. See user overrides.

Display Mode

The display_mode option is a hint for the default representation of the number entity, e.g. on a profile page or in the entity control screen. It is comparable to the mode attribute of a Home Assistant number entity.

• With auto, the UI uses the number of positions (max - min) / step to choose the representation: up to 256 positions are rendered as a slider, more positions as a stepper. This is the same threshold as in Home Assistant.
• An unbounded number entity, with min or max set to null, is always rendered as a stepper. It cannot be used as a target for the slider widget or the Remote 3 touch-slider.
• The display mode doesn’t apply to a slider widget in an activity user interface, or to the Remote 3 touch-slider. These are explicitly chosen by the user.
• The UI may ignore the hint, e.g. if there isn’t enough space for a slider.
• The user can override the display mode. The display mode of the user takes precedence over the option of the integration driver. If neither is set, auto is used.
• A number widget in an activity user interface can set its own display_mode. A slider or stepper of the widget takes precedence over the user override and the option of the integration driver.

Integration API

Commands

The integration driver has to implement a handler for the entity_command message to process the following command requests in msg_data.cmd_id.

The increment and decrement commands are used for physical button mappings, e.g. VOLUME_UP and VOLUME_DOWN, and for D-pad navigation when a slider widget has the focus, if the screen offers D-pad navigation. The Remote does not calculate the new value itself, since the driver knows the actual value of the device.

Events

The entity_change event must be emitted by the integration driver if the state or the value of the number entity changes. Either after an entity_command or if the value has been updated otherwise, e.g. externally through a user or another system.

The following attributes are supported:

At least one attribute must be specified in the entity_change message. If the entity state and the value attribute changed at the same time, they may both be included in the same message. It’s also valid to always send every attribute.

If the entity becomes unavailable or the value is unknown, value should be set to null. Otherwise the Remote keeps the last value.

The Remote shows the value set by the user immediately and then follows the value attribute in the entity_change event. If the driver doesn’t confirm the new value within a few seconds, the UI falls back to the last known value. Exception: with option readable: false the UI keeps the value sent to the driver. Drivers should therefore send the entity_change event as soon as the device has applied the new value.

Entity definition examples

Generic number entity with a custom unit:

{
  "entity_id": "amp-1_bass",
  "entity_type": "number",
  "device_id": "amp-1",
  "name": {
    "en": "Bass"
  },
  "options": {
    "min": -10,
    "max": 10,
    "step": 0.5,
    "decimals": 1,
    "unit": "dB"
  }
}

Number entity with a transition time for the set_value command:

{
  "entity_id": "light-1_scene_intensity",
  "entity_type": "number",
  "features": ["value", "transition"],
  "name": {
    "en": "Scene intensity"
  },
  "options": {
    "min": 0,
    "max": 100,
    "step": 1,
    "unit": "%"
  }
}

Number entity with a device class and its default unit A, preferably shown as a stepper:

{
  "entity_id": "wallbox-1_charging_current",
  "entity_type": "number",
  "device_class": "current",
  "name": {
    "en": "Charging current"
  },
  "options": {
    "min": 6,
    "max": 32,
    "step": 1,
    "display_mode": "stepper"
  }
}

Unbounded counter without an upper limit:

{
  "entity_id": "coffee_counter",
  "entity_type": "number",
  "name": {
    "en": "Coffee cups"
  },
  "options": {
    "min": 0,
    "max": null,
    "step": 1
  }
}

Command examples

set_value

{
  "kind": "req",
  "id": 129,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "number",
    "entity_id": "amp-1_bass",
    "cmd_id": "set_value",
    "params": {
      "value": 2.5
    }
  }
}

With a transition time, requires the transition feature:

{
  "kind": "req",
  "id": 129,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "number",
    "entity_id": "light-1_scene_intensity",
    "cmd_id": "set_value",
    "params": {
      "value": 80,
      "duration": 2000
    }
  }
}

increment

{
  "kind": "req",
  "id": 130,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "number",
    "entity_id": "amp-1_bass",
    "cmd_id": "increment"
  }
}

If the step parameter is not specified, the step option of the entity is used.

decrement

{
  "kind": "req",
  "id": 131,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "number",
    "entity_id": "amp-1_bass",
    "cmd_id": "decrement",
    "params": {
      "step": 1
    }
  }
}

Event examples

Value changed

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "number",
    "entity_id": "amp-1_bass",
    "attributes": {
      "value": 2.5
    }
  }
}

Entity becoming unavailable

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "number",
    "entity_id": "amp-1_bass",
    "attributes": {
      "state": "UNAVAILABLE",
      "value": null
    }
  }
}

Entity coming online with the current value

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "number",
    "entity_id": "amp-1_bass",
    "attributes": {
      "state": "ON",
      "value": 0
    }
  }
}