// DISCLAIMER: This is a work in progress until this line of text is removed. If you want to either provide feedback or just add/adjust content, feel free to do so.
Welcome to Home Assistant!
The purpose of this guide is to cover the basics of how Home Assistant (“HA”) works and how to use it effectively, all while introducing you to the official documentation. The goal is to increase your knowledge enough so that you can refer to the official documentation and understand what it says and how to follow it.
Links to the relevant portions of the official docs will be included throughout this guide and it is strongly recommended that you follow those links in another browser window (right click and select “open in new tab”) while reading this guide. This way you will know where to get the information you need when you have more specific questions. Unlike the official documentation, this guide is intended to be read from start to finish.
Fundamental Elements of HA
Terminology can be bewildering to start with. You can find a glossary here:
Entities
You likely installed HA so that you could control some things inside your home. In HA, physical “things” are called devices. A device might be a smart plug, or it might be a smart refrigerator, or even your electric vehicle. But in HA, devices aren’t the fundamental building block. Instead they are merely containers for the fundamental elements in HA, and those elements are called entities.
An entity in HA is the lowest-level object that can be monitored or changed. You should prefer entities over devices - your system will be much easier to maintain.
Every entity will have a state which is the primary piece of information reported by that entity. So for example, a smart plug device could contain the following entities each with their own state:
-
A power sensor: This shows the current power being consumed by whatever is plugged into this smart plug. In other words, this is a read-only entity.
-
A switch. This is used to turn the plug
onoroffand is also used to show whether the plug is currentlyonoroff. In other words, you can control this entity and you can also read the state of this entity.
Entities can have a friendly name (like “Hallway Light”) but they will be uniquely described by an entity_id which is of the form domain.object_id.
Entity IDs are always lowercase, with no special symbols or spaces other than underscores and the single period that separates the domain from the object ID.
The object ID can contain numbers, but issues can occur if it begins with a number so this is discouraged.
The domain must be one from a list of existing domains described here (or else a domain provided by a custom integration, to be discussed later). The most common domains you should become familiar with are:
-
sensor(link): this is a read-only entity. Could be a number (e.g. temperature) or text or really anything else less than 255 characters. -
binary_sensor(link): also read-only, but restricted to 2 main states:onandoff. Most commonly used for motion sensors and contact sensors (door or window sensors). For example, a door contact sensor can tell you if the door is open or closed, but you can’t use HA to close the door. -
switch(link): similar to abinary_sensorin that it is restricted to 2 states, but this entity can be controlled. This could be the entity used to turn a smart plugon&off, and the same entity will also tell you if it is currentlyonoroff. -
cover(link): this is the domain that will be used for a garage door or for blinds. Essentially, anything that can be controlled to be in the states “closed” or “open”. This also has support for things that can be set to some percentage of closed or open. -
climate(link): This is used primarily for thermostats which control heat and air conditioning in your house.
An entity_id can be changed (and changing it to something that makes sense for you is a good idea), but its initial value will be provided by the integration that brought it into HA. Which leads us to…
Integrations
At this point you may be asking yourself “How do I get entities (or devices containing a bunch of entities) into HA?” Well, the answer is: Using Integrations. All entities (and devices) are brought into HA by way of integrations. So you need to set up an integration first if you want to add some device or entity into HA. The main ways a device can communicate to HA is through one of the following mediums:
- Z-Wave
- Zigbee
- Thread
- Bluetooth
- Wifi or Ethernet
- MQTT
You will need an integration to allow that communication to happen. In some cases (Z-wave, Zigbee, Thread, Bluetooth) you will need specific hardware to allow the smart device to communicate with your HA server. In your HA interface, head over to Settings → Devices & Services and then click the Add Integration button. You can follow the official tutorial if you need a walk-through. You can also find a list of all the supported integrations here. If you can’t find what you need, you could also try community-contributed integrations using HACS, but beware that quality can be hit or miss. If you want a stable and consistent experience, try to stick with the official integrations.
But besides adding physical devices to your HA instance, entities that are not part of any physical device can be created as well. But they are still provided by an integration. For example, maybe we want to create sensor entity that polls a webpage (https://icanhazdadjoke.com/) to retrieve a joke of the day. We can use the RESTful integration for that, and it will create an entity that isn’t tied to a device.
Entities, States, Attributes
Now you know how to get your devices and entities into HA, but how do you do anything with them? First you need to understand what they are in detail. Let’s start with a device. Here’s a screenshot of a device called “Master Bedroom Fan”. In this case, it is a Z-Wave Fan switch and so the device & entities are provided by the Z-wave integration.
In the center column, every item listed in any of those center cards is an entity. If I click on the icon or text for the Master Bedroom Fan in the Controls card, the entity’s card will pop up:
If I click the gear icon in the top right, I can see and edit some of the properties of this entity:
There we see the
entity_id that we discussed earlier. In this case it is fan.master_bedroom_fan.
We can close that popup and go back and click on any of the other entities in the other cards. The entity named “Last seen” in the Diagnostic card has an entity_id of sensor.master_bedroom_fan_last_seen.
OK, great. There’s got to be a better way to get information about entities than going into each integration and clicking on each entity. And there is.
First, we’ll look at the “normal” way to view entities, and that is with the entities table. This can be found from Settings → Devices & Services and then clicking Entities tab up on top. That will result in a long list of all the entities on your system:
You can click on any entity and you’ll get the same popup that you saw when accessing it from the Devices view.
But, there’s a better way. For this, we need to enable advanced mode for the user we are currently logged in as (assuming we have admin rights). In the sidebar menu, click on your user name in the lower left. You will see some user settings, and one of those is “Advanced mode”. Turn that toggle on. Now, have have access to Developer Tools from the sidebar menu. The developer tools are going to be necessary if you want to do anything exciting with HA:
The best way to look at the details of an entity are by using Developer tools → States. Here, you will find every entity in your HA instance, along with its state and all of its attributes.
And when you click the hyperlink for any entity, it will allow you to change the state and/or attributes… sort of.
How HA Works, a Brief Overview
Before we go changing an entity’s state (or attributes), let’s step back and discuss how HA operates. The dev docs do a pretty good job with a high level overview, but let’s just start out with the State Machine. This part of HA is where all the states (and attributes) of all your entities are stored. Think of it as the immediate memory of HA. Want to know what the current state of your sensor.outdoor_thermometer_temperature entity is? It is in the State Machine. The State Machine will contain the current state object for every entity. The state object contains a whole bunch of information about the entity, like its state, when it was last changed, when it last reported, what its name is, what all of its attributes are, etc. I highly recommend skimming over those docs at that link because you will soon see how valuable that information is, and you’ll want to refer back to it many times.
Now let’s talk about what the state machine is not. The state machine only contains the current state of your entities. It has no idea what has transpired previously, other than some of the entity properties that are in the state machine like “last changed” that give some indication on how stale the information might be. This is important, because any automation that you decide to make can only utilize information in the state machine. I’ll come back to that point later. So, the state machine doesn’t have access to historical data, even if that data is being recorded (which it will be, 10 days by default, by the recorder integration). You might think that would handicap what you can do with automations, but it absolutely does not. More on that later, in the automations section.
The “immediate memory” of HA is the state machine, so what is the spinal cord? That would be the event bus. The event bus is where things happen. If the state of an entity changes (for example the sensor.outdoor_thermometer_temperature state changed from 20 to 21 degrees), there will be an event fired on the event bus with information about that. You can listen for events, or fire events, on the event bus using Developer tools → Events. I won’t go into more detail here because it isn’t very often that you should need to interface with the event bus.
A common chain of events in HA would be:
- Integration gets an updated state from a physical device
- That component tells the state machine to update the state
- State machine updates its own memory, and then fires a
state_changedevent on the event bus - Other components (like automations) can then react if they are listening for that event
Now back to the states of entities, which is what brought us here: In Developer tools → States you can change the state of an entity… sort of. By that, I mean you can overwrite the values that are currently in the state machine. So you’re just wiping the short term memory of the state machine regarding that one value and providing a different value. And that will only persist until the integration responsible for that entity provides a new value. For some devices & integrations that could happen in seconds, and for others it could be minutes or hours. But eventually, whatever you attempted to “overwrite” will be itself overwritten by the integration that actually controls that entity.
However, this is a great tool that is very handy when testing out automations. If you don’t want to, or can’t, change the state of a sensor, then you can just override it on this page, and HA will think the actual value has really changed. You can then change it back when you are done, or wait for the integration to refresh it with a new value whenever it is next updated. Which now leads us to…
Automations
In HA there are 3 key parts to an automation. The docs cover this into pretty well, but we’ll cover it here also because it is very important.
-
Triggers: In the UI is this is the “When” section. Think of this like firing the starting pistol in a race. You can have triggers that happen in quick succession, but there is no such thing as an automation that “stays triggered”. Even if you hold down the trigger of the starting pistol, it only fires the one time. You have to let go of the trigger before you can pull it again. This concept applies to all the different types of triggers that can be used. You can have as many triggers as you want listed here. If any one of them trip, the automation moves to the next section (the conditions). So the triggers are essentially “logical OR”.
-
Conditions: In the UI, this is called the “And If” section. Every condition in this space has to evaluate as TRUE for the automation to continue. So these are all “logical AND”. If the automation is fired by a trigger, but there is at least one condition in this section that is FALSE, then HA doesn’t consider the automation to have run. Every automation is itself an entity, and each has a property called
last_triggered. That property is only updated if there is a trigger and everything in the conditions section is met. In other words, the automation has to reach the Actions section. -
Actions. This is where the action happens… obviously. However, besides simply listing actions like
light.turn_on, you can also use logic here for more complex automations. You could use an if/then/else logic block (which will then include conditions) and that can all be in the Action section of an automation…
To be continued
