Device settings

Device page anatomy

Go to Settings → Devices & services → Devices, then select any device card to open its device page.

A typical device page has 6 sections:

1. Device information: The name, manufacturer, model, firmware version, integration, and assigned area. The three-dot menu in the upper-right corner contains additional commands.
2. Controls: Devices you can actively control, such as switches and lights, have prominent controls.
3. Entities: Every entity created by the device. A Zigbee switch might expose switch.* for control, sensor.*_battery for battery level, and update.*_firmware for firmware.
4. Automations, scenes, and scripts: These show where the device is used. They provide quick links for editing and a checklist of what removal could affect.
5. Related: Links near the bottom may open Logbook and History.
6. Diagnostics: Diagnostic data is usually a JSON file intended for integration maintainers when troubleshooting.

Rename devices and entities

1. Rename the device

   On the device page, select the pencil icon in the upper-right corner and change Name. If you have not overridden an entity's name, its display name may adopt the new device name as its prefix.

   Warning: Renaming a device does not automatically change its entity IDs. Home Assistant keeps them stable so an automation that refers to light.old_name does not break when you change only the display name. Change each entity ID separately if necessary.

2. Rename the entity and its entity ID

   Select an entity on the device page, then open its settings. You can edit Name, which appears in the interface, and Entity ID, which automations and dashboards use. If Home Assistant offers to update references in dashboards, automations, and scripts, select that option and test every affected item.

   

3. Choose a distinctive icon

   In the entity settings, enter mdi:xxx in the Icon field. Examples include mdi:lightbulb-outline, mdi:ceiling-light, and mdi:desk-lamp. Browse available icons at pictogrammers.com/library/mdi/.

Manage entities

A device can expose many entities, especially an environmental sensor or a multipurpose Zigbee switch. Use these guidelines to keep them organized:

• Entities you use → Give each one a clear name, assign it to an area, and add relevant labels.
• Entities you rarely view, such as battery level → Leave them enabled, or apply a Battery label so you can monitor them together.
• Entities you never use, such as unwanted diagnostic entities → Hide or disable them after reviewing the differences below.

You can manage entities in two places:

1. Device page: Review all entities associated with one device.
2. Settings → Devices & services → Entities: Review the complete entity registry and filter it by domain, integration, status, or label.

Disable vs. hide vs. delete

Which option should you use?

• If you do not need an entity now but may want it later, hide it.
• If an unused entity creates unnecessary updates or log entries, disable it—for example, an unneeded Z-Wave diagnostic entity.
• If the physical device has been permanently removed, delete the device from its device page or remove it through the integration. Deleting only an entity often has no lasting effect because the integration can create it again.

Firmware updates (update entities)

Supported integrations expose firmware updates as update.* entities alongside other entities on the device page.

1. Check for available updates

   Check the Updates card or open Settings → System → Updates. A supported device also shows its update.* entity on the device page.

   

2. Create a backup first (Chapter 9)

   A failed Zigbee or Z-Wave firmware update can leave a device unusable. A 3-minute backup costs far less than pairing and configuring the device again, although a Home Assistant backup cannot recover the device's firmware. Review the release notes and the manufacturer's recovery instructions before updating.

3. Select “Install”

   Battery-powered devices such as contact and motion sensors sleep for much of the time. An integration may queue the update until the device wakes; follow its instructions rather than repeatedly starting the update.

4. Verify the result

   Return to the device page and check the firmware version. If it has not changed, the update may still be queued or may have failed; review the update entity and logs.

Diagnostics & Repairs

Home Assistant provides two useful troubleshooting resources:

1. Download diagnostics

On the device page, open the upper-right ⋮ menu and select “Download diagnostics.” The resulting JSON file contains states, attributes, and integration data. Home Assistant redacts known sensitive fields, but you should still review the file before attaching it to a GitHub issue or community post.

2. Repairs

Open Settings → System → Repairs. Home Assistant raises repair issues when, for example, an integration stops working, an app is outdated, entities are duplicated, or the database becomes too large. Open an issue, read its explanation, and follow the guided repair instead of assuming that every issue has a one-click fix.

Reconfigure or remove a device

Reconfigure

If the integration supports it, open the ⋮ menu on the device page and select “Reconfigure” to update an IP address, key, or API token without removing the configuration entry. For ZHA or Zigbee2MQTT devices, follow the integration's documented device-management process to re-interview a device and restore missing or damaged entities.

Remove one device

On the device page, open the ⋮ menu and select “Delete.” The result depends on the integration: a Zigbee integration may remove the node from its network, while a cloud integration may discover it again during the next account sync.

Remove an entire integration entry

Under Settings → Devices & services → Integrations, open the configuration entry's menu and select “Delete.” Home Assistant warns that all devices and entities provided by that entry will be deleted. Review them and create a backup before confirming.

FAQ