Entities

An entity is the smallest thing in Home Assistant that has a state: one temperature reading, one light, one lock. Users build their automations, dashboards, and voice commands out of entities, so they are the most visible part of any integration you write.

Entities come in domains, like sensor, light, or climate. Each domain is an entity platform: a base class with its own properties, features, and states, that every integration implements in the same way. That shared shape is what makes a light from one brand work exactly like a light from another one, in the interface, in automations, and in voice assistants.

These pages are for developers who build or maintain an integration, or work on an entity platform itself. They assume you know Python and have a development environment running. To learn how an integration sets up its platforms and creates entities in the first place, start with integrations.

1. Your integration creates entity objects in a platform module, like sensor.py, and passes them to async_add_entities.
2. Home Assistant registers each entity in the entity registry, links it to its device, and gives it an entity ID.
3. The entity keeps its data up to date, by polling or push, and writes its state to the state machine.
4. Users control it through actions, which call methods on your entity, like async_turn_on.
5. When the integration unloads, the entity is removed, and cleans up after itself.

Read these first. They apply to every entity, whatever its domain.

• The entity class: the base class, the three ways to set properties, and the generic properties.
• Naming entities: has_entity_name, translated names, friendly names, and entity IDs.
• Updating state: polling, push, writing the state, and availability.
• Entity lifecycle: the hooks that run when an entity is added, changed, and removed.
• State and attributes: what ends up in the state object, and what to keep out of it.
• Icons: icon translations and the icon property.
• The entity registry: unique IDs, devices, entity categories, and disabled entities.

Every platform page has the same structure: what the entity represents, its properties, its supported features, the methods you implement, its states, and an example. Where the frontend shows a domain in its own way, the page links to its more-info view in the Design area.

• Sensor: a measured or read value, like a temperature or a power reading.
• Binary sensor: something that is on or off, like an open door or detected motion.
• Event: something that happens, like a button press or a doorbell ring.
• Weather: current conditions and forecasts.
• Device tracker: where a device is, or whether it is home.
• Geolocation: events with a location from an external feed.
• Calendar: events with a start and an end.
• Air quality: deprecated, use sensors instead.

• Light
• Climate
• Fan
• Humidifier
• Water heater

• Cover: blinds, shades, garage doors, and gates.
• Valve: water and gas valves.
• Lock
• Alarm control panel
• Siren

• Media player: speakers, TVs, and receivers.
• Camera: still images and live streams.
• Image: a still image that changes now and then.

• Remote: send commands to other devices.
• Infrared: shared infrared transmitters and receivers.
• Radio frequency: shared RF transmitters.

• Conversation: agents that understand and answer what people say to Assist.
• Speech-to-text
• Text-to-speech
• Wake word detection
• Assist satellite: devices that listen and talk back.
• AI task: generate data or images with a model.

• Vacuum
• Lawn mower
• Update: firmware and software updates.

• Switch: turn something on or off.
• Button: trigger a single action.
• Number, select, and text: set a value on a device.
• Date, date and time, and time: set a moment on a device.
• Scene: activate a scene stored on a device.
• To-do list: a list of items with a status.
• Notify: send a message.

Choose the platform that matches what the thing really is, not the one that is easiest to implement. A pump that turns on and off is a switch, but a valve is a valve, and a light is a light, even if both only turn on and off. The right platform gives users the right controls, gives voice assistants the right device type, and gives you the right features as the device grows. Each platform page says when it is, and isn't, the right fit.

If no platform fits, or a platform misses something many devices have, don't work around it with attributes. Propose a change in the architecture discussions first. See proposing changes to an entity model.

• Questions while building an entity? Ask in the #core channel on the Home Assistant Discord.
• Want to add a feature, state, or device class to a domain? Open a discussion in the architecture repository. When a decision is made, it is recorded there as an architecture decision record.
• Found a bug in an entity platform? Open an issue in the core repository.