States: add unavailable and unknown (#34809)

* States: add unavailable and unknown * rephrase intro * Make states lowercase * Update source/_integrations/humidifier.markdown Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com> * Revert "Make states lowercase" This reverts commit daf7f06630c4a2cc1f7e7fe5d043d9754a79cd1d. * Apply bold to the UI string of state names * Climate: fix grammar --------- Co-authored-by: Klaas Schoute <klaas_schoute@hotmail.com>
2025-07-23 09:17:06 +00:00 · 2024-09-18 15:36:17 +02:00 · 2024-09-18 15:36:17 +02:00 · 89b5af33bd
commit 89b5af33bd
parent 758bb538df
34 changed files with 156 additions and 14 deletions
--- a/source/_integrations/air_quality.markdown
+++ b/source/_integrations/air_quality.markdown
@ -31,3 +31,8 @@ The platforms cover the following levels (if they are available):
 ## The state of an air quality entity

 The state of an air quality entity represents the concentration of particles in the air that are 2.5 microns or fewer in diameter. The state is a number. The number is followed by the unit of measurement (micrograms per cubic meter: "µg/m³"). For example, *PM2.5: 4 µg/m³*. In this example, the state is 4.
+
+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
--- a/source/_integrations/alarm_control_panel.markdown
+++ b/source/_integrations/alarm_control_panel.markdown
@ -35,6 +35,9 @@ An alarm panel entity can have the following states. Not all integrations implem
 - **Arming**: The alarm is in the process of being armed.
 - **Disarming**: The alarm is in the process of being disarmed.
 - **Triggered**: The alarm has been triggered.
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+

 ## Actions

--- a/source/_integrations/binary_sensor.markdown
+++ b/source/_integrations/binary_sensor.markdown
@ -33,6 +33,11 @@ or using an [input boolean helper](/integrations/input_boolean).

 A binary sensor can have two states: **on** or **off**. However, in the frontend, they might not be called **on** or **off**, but use an alternative term to be more meaningful in context. For example, hot/cold, locked/unlocked. The meaning of an **on** or **off** state depends on the device class.

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ### Device class

 {% include integrations/device_class_intro.md %}
--- a/source/_integrations/button.markdown
+++ b/source/_integrations/button.markdown
@ -36,6 +36,11 @@ The state of a button is a timestamp showing the date and time of the last time
 Screenshot showing the state of a button entity in the developer tools.
 </p>

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 Because the {% term state %} of a button entity in Home Assistant is a timestamp, it
 means we can use it in our automations. For example:

--- a/source/_integrations/calendar.markdown
+++ b/source/_integrations/calendar.markdown
@ -40,6 +40,11 @@ The state shows whether or not there is an active event:
 - On: The calendar has an active event.
 - Off: The calendar does not have an active event.

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## Automation

 Calendar [Triggers](/docs/automation/trigger) enable {% term automation %} based on an
--- a/source/_integrations/camera.markdown
+++ b/source/_integrations/camera.markdown
@ -36,6 +36,8 @@ A camera can have the following states. Not all camera integrations support all
 - **Streaming**: The camera transmits a live play-back of the video data it is recording.
 - **Recording**: The camera is currently capturing video content.
 - **Idle**: The camera is not currently capturing video content.
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Actions

--- a/source/_integrations/climate.markdown
+++ b/source/_integrations/climate.markdown
@ -15,9 +15,9 @@ The **Climate** {% term integration %} allows you to control and monitor HVAC (h

 {% include integrations/building_block_integration.md %}

-## The state of a HVAC entity
+## The state of an HVAC entity

-A HVAC entity can have the following states, depending on the specific climate device and its capabilities.
+An HVAC entity can have the following states, depending on the specific climate device and its capabilities.

 - **Off**: The device is turned off.
 - **Heat**: The device is set to heat to a target temperature.
@ -26,6 +26,8 @@ A HVAC entity can have the following states, depending on the specific climate d
 - **Auto**: The device is set to a schedule, learned behavior, AI.
 - **Dry**: The device is set to dry/humidity mode.
 - **Fan only**: The device only has the fan on. No heating or cooling is taking place.
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Actions

--- a/source/_integrations/cover.markdown
+++ b/source/_integrations/cover.markdown
@ -28,6 +28,9 @@ A can have the following states:
 - **Open**: The cover has reached the open position.
 - **Closing**: The cover is in the process of closing to reach a set position.
 - **Closed**: The cover has reached the closed position.
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+

 How the state of a cover is represented in the frontend depends on the device class.

--- a/source/_integrations/date.markdown
+++ b/source/_integrations/date.markdown
@ -26,6 +26,11 @@ The state of a date entity is the actual date value.
 Screenshot showing the state of a date in the developer tools. In the example shown, the state is January 1, 2020; in the format YYYY-MM-DD.
 </p>

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## Actions

 ### Date actions
--- a/source/_integrations/datetime.markdown
+++ b/source/_integrations/datetime.markdown
@ -26,6 +26,11 @@ The state of a date/time entity is the actual date and time value.
 Screenshot showing the state of a date/time entity in the developer tools. In the example shown, the state is January 1, 2020 at 12:00 in the format YYYY-MM-DD T HH:MM:SS.
 </p>

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## Actions

 ### datetime actions
--- a/source/_integrations/device_tracker.markdown
+++ b/source/_integrations/device_tracker.markdown
@ -118,6 +118,11 @@ A device tracker with **router** as a source can have one of two states: **Home*
 Screenshot showing the state of a device tracker entity in the developer tools.
 </p>

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## `device_tracker.see` action

 The `device_tracker.see` action can be used to manually update the state of a device tracker:
--- a/source/_integrations/event.markdown
+++ b/source/_integrations/event.markdown
@ -30,13 +30,18 @@ The event entity can capture these events in the physical world and makes them a

 ## The state of an event entity

-The event entity does not capture a state such as `on` or `off`. Instead, an event entity keeps track of the timestamp when the emitted event has last been detected.
+The event entity does not capture a state such as **On** or **Off**. Instead, an event entity keeps track of the timestamp when the emitted event has last been detected.

 <p class='img'>
  <img src='/images/integrations/event/event_timestamp.png' alt='Event entity with timestamp value in state and event type "pressed"'>
  Event entity with a timestamp value in state and event type "pressed".
 </p>

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 Because the state of an event entity in Home Assistant is a timestamp, it means we can use it in our automations. For example:

 ```yaml
--- a/source/_integrations/fan.markdown
+++ b/source/_integrations/fan.markdown
@ -17,7 +17,12 @@ The **Fan** {% term integration %} allows you to control and monitor fan devices

 ## The state of a fan entity

-The state of a fan entity can be either `on` or `off`.
+The state of a fan entity can be either **On** or **Off**.
+
+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Actions

--- a/source/_integrations/humidifier.markdown
+++ b/source/_integrations/humidifier.markdown
@ -23,7 +23,12 @@ The **Humidifier** {% term integration %} is built for the controlling and monit

 ## The state of a humidifier entity

-The state of a humidifier entity can be either `on` or `off`.
+The state of a humidifier entity can be either **On** or **Off**.
+
+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Device class

--- a/source/_integrations/image.markdown
+++ b/source/_integrations/image.markdown
@ -18,3 +18,8 @@ The **Image** {% term integration %} allows other integrations to display a stat
 ## The state of an image entity

 The state of an image entity is a timestamp, showing the date and time when the image was last changed.
+
+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
--- a/source/_integrations/image_processing.markdown
+++ b/source/_integrations/image_processing.markdown
@ -19,6 +19,11 @@ Image processing enables Home Assistant to process images from [cameras](/integr

 For face recognition applications, the state of an image processing entity can be the name of the detected person or motion that was detected.

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## ALPR

 ALPR entities have a vehicle counter attribute `vehicles` and all found plates are stored in the `plates` attribute.
--- a/source/_integrations/lawn_mower.markdown
+++ b/source/_integrations/lawn_mower.markdown
@ -24,6 +24,8 @@ A lawn mower entity can have the following states:
 - **Paused**: The lawn mower was active and is now paused.
 - **Returning**: The lawn mower is returning to the dock.
 - **Error**: The lawn mower encountered an error while active and needs assistance.
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Actions

--- a/source/_integrations/lock.markdown
+++ b/source/_integrations/lock.markdown
@ -28,6 +28,8 @@ A lock entity can have the following states:
 - **Locked**: The lock is currently locked.
 - **Locking**: The lock is in the process of being locked.
 - **Unlocking**: The lock is in the process of being unlocked.
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Actions

--- a/source/_integrations/media_player.markdown
+++ b/source/_integrations/media_player.markdown
@ -31,6 +31,8 @@ A media player can have the following states:
 - **Paused**: The media player has an active media and is currently paused
 - **Standby**: The media player is in a low power state, accepting commands.
 - **Buffering**: The media player is preparing to start playback of media.
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Actions

--- a/source/_integrations/notify.markdown
+++ b/source/_integrations/notify.markdown
@ -26,6 +26,11 @@ The state of a notify entity is the date and time when a message was last sent.
 Screenshot showing the state of a notify entity in the developer tools.
 </p>

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## Action

 The legacy `notify` platform will expose a generic `notify` action that can be called to send notifications.
--- a/source/_integrations/number.markdown
+++ b/source/_integrations/number.markdown
@ -27,6 +27,11 @@ If you are looking for a way to create a number entity, please take a look at th

 The state of a number entity is a number.

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## Device class

 {% include integrations/device_class_intro.md %}
--- a/source/_integrations/remote.markdown
+++ b/source/_integrations/remote.markdown
@ -11,7 +11,7 @@ ha_codeowners:
 ha_integration_type: entity
 ---

-The **Remote** {% term integration%} keeps track of the remotes in your environment, captures their state, and allows you to control them.
+The **Remote** {% term integration%} manages the state of the remote entities and allows you to control them.

 - Maintains a state per remote and a combined state `all_remotes`.
 - Registers actions `remote/turn_on`, `remote/turn_off`, `remote/toggle`, and `remote/send_command` to control remotes.
@ -20,7 +20,12 @@ The **Remote** {% term integration%} keeps track of the remotes in your environm

 ## The state of a remote entity

-The state of a remote entity can be either `on` or `off`.
+The state of a remote entity can be either **On** or **Off**.
+
+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Use the actions

--- a/source/_integrations/scene.markdown
+++ b/source/_integrations/scene.markdown
@ -30,6 +30,11 @@ an action.
 Screenshot showing the state of a scene entity in the developer tools.
 </p>

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## Scenes created by integrations

 Some integrations like [Philips Hue](/integrations/hue), [MQTT](/integrations/mqtt), and [KNX](/integrations/knx) provide scenes. You can activate them from the Home Assistant UI or via as an action. In this case, the integration provides the preferred states to restore.
--- a/source/_integrations/select.markdown
+++ b/source/_integrations/select.markdown
@ -11,7 +11,7 @@ ha_codeowners:
 ha_integration_type: entity
 ---

-The **Select** {% term integration %} keeps track of the `select` {% term entities %} in your environment, their state, and allows
+The **Select** {% term integration %} manages the state of the select entities and allows
 you to control them. This integration allows other integrations to offer
 a limited set of selectable options for the entity.

@ -26,6 +26,11 @@ The state of a select entity is the value of the currently selected option.
 Screenshot showing the state of a select entity in the developer tools.
 </p>

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## Actions

 The select {% term entity %} exposes additional {% term actions %} to control the entity in, for example,
--- a/source/_integrations/siren.markdown
+++ b/source/_integrations/siren.markdown
@ -18,7 +18,12 @@ The **Siren** {% term integration %} is built for the controlling and monitoring

 ## The state of a siren entity

-The state of a siren entity can be either `on` or `off`.
+The state of a siren entity can be either **On** or **Off**.
+
+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Actions

--- a/source/_integrations/stt.markdown
+++ b/source/_integrations/stt.markdown
@ -18,3 +18,8 @@ A speech-to-text (STT) entity allows other integrations or applications to strea

 Every speech-to-text entity keeps track of the timestamp of when the last time
 the speech-to-text entity was used to process speech.
+
+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
--- a/source/_integrations/switch.markdown
+++ b/source/_integrations/switch.markdown
@ -18,7 +18,7 @@ related:
    title: Dashboard
 ---

-The **Switch** {% term integration %} keeps track of the states of the switches in your environment and allows you to control them.
+The **Switch** {% term integration %} manages the state of the switch entities and allows you to control them.

 - Maintains a state per switch and a combined state `all_switches`.
 - Registers actions `switch.turn_on`, `switch.turn_off`, and `switch.toggle` to control switches.
@ -27,7 +27,12 @@ The **Switch** {% term integration %} keeps track of the states of the switches

 ## The state of a switch entity

-The state of a switch {% term entity %} can be either `on` or `off`.
+The state of a switch {% term entity %} can be either **On** or **Off**.
+
+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Device class

--- a/source/_integrations/time.markdown
+++ b/source/_integrations/time.markdown
@ -26,6 +26,11 @@ The state of a time {% term entity %} is a timestamp in the format HH:MM:SS.
 Screenshot showing the state of a time entity in the developer tools.
 </p>

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## Actions

 ### Time actions
--- a/source/_integrations/todo.markdown
+++ b/source/_integrations/todo.markdown
@ -40,6 +40,11 @@ incomplete items in the list.
 Screenshot showing the state of a to-do list entity in the developer tools.
 </p>

+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
 ## Blueprint to add an item to a dedicated list

 This blueprint allows you to create a script to add an
--- a/source/_integrations/update.markdown
+++ b/source/_integrations/update.markdown
@ -27,10 +27,15 @@ For a list of {% term integrations %} offering update entities, on the integrati
 ## The state of an update entity

 The state of an update {% term entity %} reflects whether an update is available or not.
-When the state is `on`, it means there is an update available; when everything
-is up-to-date, the state is `off`.
+When the state is **On**, it means there is an update available; when everything
+is up-to-date, the state is **Off**.

-Additionally, the following state attributes are exposed to provide more
+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
+
+The following state attributes are exposed to provide more
 information on the update state:

 - `title`: The title/name of the available software or firmware. As the device
--- a/source/_integrations/vacuum.markdown
+++ b/source/_integrations/vacuum.markdown
@ -25,6 +25,8 @@ A vacuum {% term entity %} can have the following states:
 - **Idle**: The vacuum is not paused, not docked, and does not have any errors.
 - **Paused**: The vacuum was cleaning but was paused without returning to the dock.
 - **Returning**: The vacuum is done cleaning and is currently returning to the dock, but not yet docked.
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Actions

--- a/source/_integrations/valve.markdown
+++ b/source/_integrations/valve.markdown
@ -29,6 +29,8 @@ The valve {% term entity %} can have the following states:
 - **Closed**: The valve is fully closed.
 - **Closing**: The valve is in the process of closing.
 - **Stopped**: The valve has stopped moving before reaching a fully open or closed position.
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Device class

--- a/source/_integrations/wake_word.markdown
+++ b/source/_integrations/wake_word.markdown
@ -26,3 +26,8 @@ The state of a wake word detection {% term entity %} is a timestamp showing the
 <img src='/images/integrations/wake_word/state_wake-word.png' alt='Screenshot showing the state of a wake word detection entity in the developer tools' />
 Screenshot showing the state of a wake word detection entity in the developer tools.
 </p>
+
+In addition, the entity can have the following states:
+
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.
--- a/source/_integrations/water_heater.markdown
+++ b/source/_integrations/water_heater.markdown
@ -31,6 +31,8 @@ A water heater entity can have the following states:
 - **Heat pump**: Heat pump is the slowest to heat, but it uses less energy.
 - **Gas**: Gas only mode. This mode uses the most energy.
 - **Off**: The water heater is off.
+- **Unavailable**: The entity is currently unavailable.
+- **Unknown**: The state is not yet known.

 ## Actions