Home Assistant

Home Assistant is an open smart home platform that runs on our own hardware and ties devices together through integrations. Instead of keeping part of a building in a vendor cloud, we see and control every sensor, switch, valve and camera from one place, and data stays inside the house.

Three installation types are documented: the project’s own operating system, a container installation, and Core in a Python environment. Our hub runs on a Linux server alongside the services we operate on Docker.

Integrations and entities

The integration is the most basic structural unit: every integration has a unique identifier, its domain, and the entities and actions it provides belong to that domain. Data lives in entities. An entity represents a sensor, an actor or a function, with a state and attributes. The identifier is the domain plus a short name, for example light.living_room, where the part before the dot is the domain. Entities attach to devices, and devices to areas, labels and categories, which is what keeps a larger system readable.

• Most integrations are configured in the user interface and stored in a config entry. What still needs a file lives in configuration.yaml.
• Integrations are graded on a public scale: bronze, silver, gold and platinum, and some are listed without a score, which measures maintenance and error handling rather than how clever a device is.
• Entity names and availability differ per integration, so replacing a device usually means updating references in several places.

Automations, scenes, dashboards

An automation has three parts: a trigger, a condition and an action, built in the visual editor or written as YAML, and ready-made blueprints can be reused. A script is the same sequence of actions, except it runs when it is called; a scene captures the desired state of entities and is activated with the scene.turn_on action.

A dashboard is built from cards bound to entities and is the surface people actually see, so a small number of targeted cards is usually right.

MQTT: one of the buses

MQTT is a publish/subscribe messaging protocol on top of TCP/IP, reached through the MQTT integration. The integration connects to a broker, the documentation recommends Mosquitto, and devices announce themselves over topics. Discovery is enabled by default: a device describes itself in a message published to the homeassistant/<domain>/<id>/config topic, and later state messages update the entity. Birth and last will messages signal that the service started or that a client lost its connection; the broker must support MQTT protocol version 5.

• Zigbee gateways, Wi-Fi devices and some cameras come into our system over this bus too, so replacing a device means reviewing its topics and discovery message.
• MQTT is not the only route: many integrations talk to a device directly, over the local network or a platform specific protocol.

What to watch

• Local control is not a given: several integrations fetch data through the vendor cloud, and if it goes down or the vendor retires the service, the entity becomes unusable. Prefer devices that speak locally.
• Integration quality and maintenance vary, and an older integration may report errors or fall out of date, so the quality scale is a pointer rather than a guarantee.
• Configuration needs maintenance: part of the setup lives in files, a change requires validation and a reload, and a restart interrupts running automations and scripts.
• History is kept by the Recorder, ten days by default, so longer retention means a larger database and a larger backup.
• A backup is an encrypted tar archive, by default in the /backup directory, covering config, share, addons, ssl and media. Restoring needs the key from the backup emergency kit, so a copy belongs outside the machine.

Further reading

• Documentation
• MQTT integration
• Backups

At CyberElectro Home Assistant is the hub on our own hardware, with Zigbee and Wi-Fi devices and some cameras brought into it, and MQTT is one of the buses we talk to them over.