This article may contain affiliate links. If you buy through these links, the price is the same for you and the store pays me a small commission that helps keep Tecnoyfoto running.
When you look at a living-room bulb, you see a device that can be on, off, or set to a particular brightness. Home Assistant must represent those properties in a form that the interface, automations, and history can query. It does this with entities, states, and attributes.
You also need a way to request changes: turn the bulb on, turn it off, or adjust its brightness.
These terms appear throughout the interface and in YAML. If you do not distinguish them, you may try to control an entity by its display name, compare an attribute as though it were the state, or change a state in Tools while believing you have sent a command to the physical device.
By the end of this chapter, you will know how to locate an entity, interpret what Home Assistant knows about it, and run a test action before using it in an automation. We will not build the complete door automation yet; first, we will verify that every part exists and responds as expected.
From a physical device to its representation in Home Assistant
A device usually represents a physical product or connected service: a bulb, smart plug, motion sensor, thermostat, or phone. An integration is the component that lets Home Assistant communicate with a technology or service and create internal representations of it.
An entity represents one function, measurement, or control point. A single device can provide several entities. For example, an environmental sensor might create:
sensor.bedroom_temperature
sensor.bedroom_humidity
sensor.bedroom_battery
All three entities may belong to the same device, but each has its own state. The temperature might be 21.7, the humidity 48, and the battery level 92.
The reverse isn’t necessarily true either. A helper created in the interface, a template entity, or an automation can exist without a separate physical device behind it. In our practice environment, binary_sensor.course_front_door is virtual: it behaves like a door sensor during the exercises even though no magnetic contact is attached.
This distinction matters in YAML. Conditions and actions usually point to specific entities because entities have states and accept operations. A device helps organize and relate its entities, but its device record does not replace their entity IDs.
The entity_id: an entity’s internal address
Each entity has an identifier with two parts separated by a period:
light.course_living_room
The first part is the domain:
light
The second identifies the object within that domain:
course_living_room
The complete form, light.course_living_room, is the entity_id.
A domain is more than a category label
The domain identifies the kind of entity and determines which states, capabilities, and actions are available.
light.course_living_room
binary_sensor.course_front_door
sensor.course_living_room_temperature
switch.course_fan
light represents a controllable light. binary_sensor represents a sensor with two primary states. sensor exposes a measurement or another value. switch represents a controllable switch.
This explains why a light uses actions from the light domain while our virtual fan, represented as a switch, uses switch actions. The fact that both can be turned on does not make their capabilities interchangeable.
The visible name and the entity_id are not the same
The interface might display “Living room light,” “Course living-room light,” or any name you chose. In YAML, we need the entity’s identifier:
entity_id: light.course_living_room
This would not work as a target:
entity_id: Living room light
The second line is still valid YAML because its value is a string. The error is at the Home Assistant layer: no entity has the identifier Living room light.
An entity_id is lowercase and usually uses underscores between words. Do not infer it from the name displayed on a card. Copy it from an entity selector or Tools.
entity_id and unique_id are also not equivalent
Some screens show a unique identifier supplied by the integration. This unique_id helps the entity registry recognize the same entity across restarts and makes the entity manageable from the interface. It is not the value to place in target.entity_id.
To control or query an entity in this course, we will use its full entity_id, including both domain and object ID.
The state: a single main value at every moment
Every entity has exactly one current state. A light is usually on, off, or unavailable. A temperature sensor might be 21.5. A person entity might be home, not_home, or the name of a zone.
We can imagine these entities at a given moment:
light.course_living_room → off
binary_sensor.course_front_door → on
sensor.course_living_room_temperature → 21.5
switch.course_fan → off
binary_sensor.course_someone_home → on
Even if a temperature looks like a number, the state we will consult with the tools and many templates is presented as a string. Later we will learn to convert it safely when we need to perform calculations.
The interface may present a state differently
Our door sensor uses on and off internally, but the interface may display “Open” and “Closed.” The stored state has not changed. Home Assistant knows that the entity’s device class is door and presents the state in a more human-friendly form.
That is why you should not blindly copy the word shown on a card into a condition. In Tools, you can inspect the state Home Assistant actually uses at runtime.
The same principle applies to units. A card might display 21.5 °C, but the main state is the numeric-looking value, while the unit is usually stored in a separate attribute.
unknown and unavailable are states that you should expect
An entity may be unknown when Home Assistant does not yet have a known value. It may be unavailable when the entity exists but is not available, for example because a device is disconnected or an integration cannot obtain data.
These are not necessarily YAML errors. They are real states that automations—and especially robust templates—must account for. In this chapter, we will learn to recognize them. In the template chapter, we will prevent numeric conversions from failing when they appear.
Attributes: state-related information
The state can only contain one main value. An entity may need more information to describe its current situation. That information is stored in attributes.
A light that is on could be represented conceptually like this:
entity_id: light.example_lamp
state: "on"
attributes:
brightness: 180
color_mode: brightness
friendly_name: "Example lamp"
The state answers the main question: Is it on? Attributes add context: brightness, color mode and visible name.
A temperature sensor can show:
entity_id: sensor.course_living_room_temperature
state: "21.5"
attributes:
unit_of_measurement: "°C"
device_class: temperature
friendly_name: "Course living room temperature"
The unit_of_measurement attribute allows the interface to interpret and present the value correctly. device_class describes the type of measurement. friendly_name provides the visible name.
Not every entity has the same attributes. An integration may add or remove attributes depending on the current state and available capabilities. Inspect the actual entity instead of assuming that an example from the internet matches your device exactly.
An attribute is not a second entity
If a light includes brightness: 180, there does not necessarily exist an entity called sensor.example_lamp_brightness. The brightness is part of the light state object.
Some integrations create a separate entity for a measurement; others expose it as an attribute. The correct way to query it depends on how the integration models the device.
Tools are not only for programmers
Home Assistant groups several testing and diagnostic features under Tools. Two are essential from the beginning:
- States, to see which entities Home Assistant knows about and what values they currently have.
- Actions, to run an operation in a controlled way before placing it in an automation.
Later we will also use YAML, Templates and Events. The name of the section may intimidate, but these tools are designed precisely to check what happens without having to build a complete automation for each test.
States: observe what Home Assistant sees
Open Settings → Tools → States and search for:
binary_sensor.course_front_door
The screen shows the entity_id, current state, and attributes. Next, turn on the internal control:
input_boolean.course_front_door_open
The door sensor should change to on. Turn the control off, and the sensor should return to off. Other parts of the interface may translate those states, but this screen shows the representation our automations will use.
Repeat the observation with:
sensor.course_living_room_temperature
Change input_number.course_living_room_temperature and note which part updates. The state contains the value; the unit remains in an attribute.
“Set state” does not control the device
The States tool lets you enter a state or modify attributes manually. This changes Home Assistant’s internal representation at that moment; it does not send a command to the physical device.
If you manually set a bulb’s state to on, the physical bulb does not have to turn on. Home Assistant will temporarily treat its representation as on until the integration publishes an update and overwrites the simulated state.
Manual modification can produce state change events and activate automations. It is useful for certain tests, but it must be used knowing what is being simulated. To ask a real entity to act, we will use the Actions tool.
Actions: asking Home Assistant to do something
An action represents an operation Home Assistant can run. Action names usually combine a domain and an operation:
light.turn_on
light.turn_off
switch.turn_on
switch.turn_off
The dot separates the domain from the specific action. light.turn_on does not identify an entity: it identifies the operation of turning on one or more lights. The target is indicated separately.
In the Actions tool, select light.turn_on and choose as your target:
light.course_living_room
In YAML mode, the call has this form:
action: light.turn_on
target:
entity_id: light.course_living_room
Run the action, then return to States. light.course_living_room should now be on. The light in our practice environment is virtual, but the action follows the same model you would use with a physical bulb.
Now turn it off:
action: light.turn_off
target:
entity_id: light.course_living_room
Run a second test with the fan:
action: switch.turn_on
target:
entity_id: switch.course_fan
The action belongs to the switch domain because the practice fan is represented as a switch. We would use fan.turn_on only if the entity belonged to the fan domain.
Action, target, and data serve different purposes
In a complete call three pieces usually appear:
action: light.turn_on
target:
entity_id: light.example_dimmable
data:
brightness_pct: 60
actionanswers “Which operation should run?”targetanswers “Which entity, device, or area should receive it?”datacontains parameters for the operation, such as a brightness percentage.
The virtual light of the course only needs to be turned on and off, so we will not use its brightness as a test. The example shows why entity_id should not be placed inside data: the target and parameters are blocks with different responsibilities.
A state and an action are not the same thing
This distinction is worth pausing on because it will be the basis of automations:
State: What Home Assistant knows now.
Action: what we ask Home Assistant to do.
A condition can check whether binary_sensor.course_someone_home is on. An action can call light.turn_on for a light. The condition does not turn anything on, and the action alone does not describe the previous state.
Running an action also does not guarantee that the physical device responds. It may be disconnected, reject the command, or take time to report its new state. When diagnosing an automation, we will distinguish between “Home Assistant ran the action” and “the entity confirmed the expected result.”
Before using an entity in YAML, check four things
When you adapt an example to your home, don’t just replace names.
- The exact
entity_id. Copy it from Home Assistant. - The domain. A
switchentity does not necessarily support the same actions as alightorfanentity. - The actual states. Note whether the entity uses
on,off,home, a number, or other values. - The available attributes. Do not assume that your integration exposes the same attributes as the example.
This procedure prevents many failures that are wrongly blamed on YAML. A file can be perfectly indented while referring to an entity that does not exist or expecting a state that never occurs.
Read one action line by line
We can now interpret this block precisely:
action: light.turn_on
target:
entity_id: light.course_living_room
action and target are keys in the same map. The value of action identifies the turn_on operation in the light domain. target opens a nested map, where entity_id identifies the entity that will receive the operation.
And we can also detect the problem of this one:
action: switch.turn_on
target:
entity_id: light.course_living_room
The indentation is correct, and a YAML parser can read the block. The problem is semantic: it applies a switch action to an entity in the light domain. We must choose an action that matches both the entity’s domain and the operation we want.
Exercise: observe, classify and act
Perform all three parts without yet creating an automation.
Part 1: inventory of entities
Search for these entities in States:
binary_sensor.course_front_door
sensor.course_living_room_temperature
light.course_living_room
switch.course_fan
binary_sensor.course_someone_home
For each note:
- Domain.
- Object ID after the period.
- Current state.
- Two attributes, if available.
- If it represents a measurement, a binary observation or a control.
Part 2: choose States or Actions
Decide which tool you would use first:
- You want to know what internal state an open door represents.
- You want to turn on a real light.
- You want to temporarily simulate a change to see whether a state trigger fires.
- You want to find out what parameters
light.turn_onaccepts. - You want to check the unit of a temperature sensor.
Part 3: fix the action calls
These two calls are valid YAML, but do not control the practice environment entities correctly:
action: switch.turn_on
target:
entity_id: light.course_living_room
action: light.turn_on
target:
entity_id: Living room light
Correct them, run them from Actions, and verify the result in States.
See the explained solution
To turn on the light we use an action of the light domain and its real entity_id:
action: light.turn_on
target:
entity_id: light.course_living_room
To turn on the virtual fan we use the domain switch:
action: switch.turn_on
target:
entity_id: switch.course_fan
In Part 2, States is the right tool for observing the door’s internal state and the temperature entity’s attributes. Actions is the right tool for turning on the bulb and inspecting or testing an action. Setting a state manually can simulate a change, but remember that it does not control the physical device.
Checking States after each action keeps two steps separate: first we request the operation, and then we observe Home Assistant’s resulting representation.
What should you take from this chapter?
An entity is a function, measurement, or control point that Home Assistant identifies with an entity_id. The domain before the period describes its type and determines its states, capabilities, and actions.
Each entity has a single main state and can add related attributes. The interface can translate or combine that information, so the States screen is the right place to check what Home Assistant actually sees.
The States tool allows you to observe and simulate a temporary representation; the Actions tool executes operations. Manually changing a state does not mean sending a command to the device.
We now know how to read YAML and verify the components we will place inside it. In the next chapter, we will build our first complete home automation in the interface and then read its YAML line by line: opening the door will be the trigger, and turning on the light will be the action.