Integrations, Devices, and Entities in Home Assistant

Home Assistant organizes information using integrations, devices, and entities that represent the capabilities of our home.

The natural instinct right now is to start linking accounts and adding devices haphazardly. However, to design a maintainable system in the long term, we must stop and understand the system’s internal data model.

Home Assistant is not a simple remote control application; internally it maintains a state machine. To normalize protocols and manufacturers, the core uses an abstraction layer based on integrations, devices, and entities.

If we don’t fully grasp this hierarchy from the very beginning, our future automations will be significantly harder to maintain.

The Abstraction Layer

Home Assistant’s design goal is that when programming the logic of the home, it should be completely irrelevant whether a light bulb is Zigbee, Shelly WiFi, or Matter over Thread.

To achieve this, Home Assistant’s source code abstracts the physical hardware, turning it into standardized software objects.

These concepts are often related, but they do not form a mandatory hierarchy. An integration can create entities without a physical device, and an entity can represent a calculation, a person, or an external service.

Integrations: The Connectors

An integration is the component that connects Home Assistant to a protocol, a manufacturer, or a service. It is similar to a driver, although it can also provide calculations and functions that don’t depend on hardware.

An integration is a code module (written in Python) that knows how to “speak” the specific language of a manufacturer, service, or protocol, and is responsible for translating that communication into Home Assistant’s internal language.

We can classify integrations into several technical categories:

• Hardware/Protocol Integrations: Like ZHA (Zigbee Home Automation) which talks to our USB Dongle, or MQTT, which connects to a messaging broker.
• Provider Integrations (Cloud or Local): Like the Shelly integration (which discovers devices on our local network via CoAP/RPC) or the Tuya integration (which makes HTTP requests to the REST API of their servers).
• Logical or Virtual Integrations: Not all integrations interact with the physical world. There are integrations like Weather (AEMET or OpenWeatherMap), Sun (which calculates solar azimuth and elevation based on our coordinates), or Workday (to know if today is a holiday).

Devices: The Physical Object

Devices usually represent the physical, tangible object we have purchased or built, grouping its different capabilities.

For example, a device could be “The smart plug in the living room” or “The Xiaomi temperature sensor”.

Devices have static properties associated with their hardware:

• Manufacturer
• Model
• Firmware version
• MAC address or network identifier (IEEE in the case of Zigbee).

It is crucial to understand that, at the programming level in Home Assistant, a device rarely does anything by itself. It is simply a logical container that groups functionalities. We don’t “turn on” a device; we turn on the relay inside that device. This brings us to the most important concept of all.

Entities: The Unit of Information and Control

Entities are the absolute core of Home Assistant. They represent the atomic unit of information or control.

A single physical device almost always exposes multiple Entities.

Take, for example, an advanced smart plug (like a Shelly Plug S or a Zigbee plug with energy monitoring). Although physically it’s a single device, in the Home Assistant state machine it will automatically generate several distinct entities:

Entity Domains (entity_id)

To maintain order in the database, each entity in Home Assistant has a unique, non-repeating identifier called entity_id.

This identifier always follows a strict naming convention separated by a dot: domain.object_name.

This entity_id is, in practice, the technical name you will use in automations, templates, and dashboards. Therefore, it’s best to make it readable and stable from the start.

The Domain defines the base behavior and capabilities of that entity in the code. The most common domains we will handle are:

• light.*: Entities that emit light. They support extra attributes like brightness, color temperature, and RGB color (e.g., light.living_room_lamp).
• switch.*: Binary relays. They only accept two states: on or off (e.g., switch.water_heater).
• sensor.*: Sensors for analog values or text strings (e.g., sensor.outdoor_temperature).
• binary_sensor.*: Digital sensors that only have two boolean states, typically on (detected/open) or off (normal/closed). They are used for door sensors, window sensors, or PIR motion detectors.
• climate.*: Thermostats and air conditioning units.

State and Attributes

Finally, within each Entity, the information is divided into two blocks.

The State is the primary value of the entity. For a switch, it will always be on or off. For a temperature sensor, it will be a number (e.g., 22.5).

Attributes are secondary metadata associated with that state at that precise moment. For example, an entity light.tv_led might have the State on, but its Attributes will indicate that the brightness is set to 255 and the color is hexadecimal #FF0000.

Names, Areas, and Mental Order

Home Assistant allows renaming devices and entities from the interface. It may seem trivial, but naming things correctly from the start prevents tremendous chaos as the installation grows.

A simple convention is to use names that indicate location and function: light.living_room_ceiling, sensor.kitchen_temperature, binary_sensor.front_door. There’s no need to become obsessive, but definitely avoid names like sensor.temperature_158d00045ab2c9, because in six months you won’t know if that was the living room, the bathroom, or the storage room.

How They Relate

For a typical physical device, the flow will be:

1. We install an Integration (e.g., ZHA).
2. The integration detects physical hardware on the network and creates a Device (e.g., Zigbee multi-sensor).
3. The integration generates its corresponding Entities (sensor.temperature, sensor.humidity, sensor.battery).
4. Our interfaces and automations read and write to the states of these Entities.