Skip to content

Latest commit

 

History

History
159 lines (122 loc) · 5.38 KB

entity_switch.md

File metadata and controls

159 lines (122 loc) · 5.38 KB

Switch Entity

A switch entity can turn something on or off and the current state should be readable by the integration driver.

If the state can't be read, the readable option property can be set to false. This should be avoided whenever possible, because the remote either has to assume the current state, or the UI needs to ask the user for the current state.

If the switch controls a light source, then the light entity is usually a better choice.

Features

Name R W Description
on_off ✅ ✅ Default feature of a switch. Always present, even if not specified.
toggle ❌ ✅ Toggle support. If there's no native support, the remote will use the current state of the switch to send the corresponding on or off command.

Attributes

Entity attributes are controlled by features. Multiple features can act on the same attribute. See Events on how to notify the remote about an updated attribute. The attributes have to be listed as properties under attributes with their current value.

Attribute Features Type Values Description
state on_off enum States State of the switch, it's either on or off.
toggle Toggle inverts the current state. If the driver doesn't provide the toggle feature, the remote uses the current value and calls on or off.

States

The switch entity provides the following entity state values:

Value Description
ON The switch is on.
OFF The switch is off.

See common entity states.

Device classes

Optional switch type. This can be used by the UI to represent the entity with a different icon, behaviour etc.

Name Description
outlet The switch represents a switchable power outlet.
switch Generic switch.

Options

Name Type Default Description
readable boolean true If set to false the current state of the switch cannot be read. This will make the switch stateless and the UI might ask the user for the current state.

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.

cmd_id Parameters Description
on - Put the switch in the on state.
off - Put the switch in the off state.
toggle - Toggle the current switch state, either from on -> off or from off -> on.

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of the switch changes.

The following attributes must be included:

Attribute Description
state New entity state.

Command examples

on

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "switch",
    "entity_id": "switch-1",
    "cmd_id": "on"
  }
}

off

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "switch",
    "entity_id": "switch-1",
    "cmd_id": "off"
  }
}

toggle

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "switch",
    "entity_id": "switch-1",
    "cmd_id": "toggle"
  }
}

Event examples

Switched on

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "switch",
    "entity_id": "switch-1",
    "attributes": {
      "state": "on"
    }
  }
}

Switched off

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "switch",
    "entity_id": "switch-1",
    "attributes": {
      "state": "off"
    }
  }
}