How to customize a Home Assistant entity

Disclosure: This post contains affiliate links. If you click through and make a purchase, I will earn a commission, at no additional cost to you. Read my full disclosure here.

Close-up of a sound mixing console with various sliders and knobs. The focus is on the central area with white slider controls set against a blue background with numerical level markings. A single orange light indicates active controls or settings.

In a recent guide, I demonstrated how to convert an Aqara/Xiaomi water leak sensor in to a chair occupancy sensor. If you are anything like me, it will annoy you to no ends that the sensor will still report either the status wet or dry, instead of the more fitting detected or clear. After all, I do hope my chair is dry while I work.

A screenshot of the Home Assistant entity manager showing a water leak sensor that is being used as a chair occupancy sensor before it is customized.

While this won't make any difference to how automations and scripts use the sensor, you might want to keep everything nice and tidy. For that reason, I will be showing you how to customize any entity in Home Assistant.

  • Cleaning up Home Assistant entities
  • Changing a Home Assistant sensor's type
  • Changing the sensor name

    Because I use Zigbee2MQTT, which, as the name suggests, uses MQTT to communicate with Home Assistant, the name of the sensor isn't exactly friendly. As demonstrated by the screenshot above, it currently follows a structure frequently used for MQTT. To change the name of an entity, you can click on the edit icon next to it. I have named mine office chair occupancy.

    Once changed, you will be prompted to decide whether you want to rename your entity IDs. This would, for example, change water leak component from binary_sensor.office_sensor_occupancy to binary_sensor.office_chair_occupancy.

    Before you do this, keep in mind that you will need to adjust your automations and scripts that are already using the sensor, as the new ID won't be updated. The same also applies to your Lovelace dashboards.

    Cleaning up Home Assistant entities

    With the entity's name and IDs updated, I like to go ahead and disable any sensors and diagnostic information I don't need. This makes editing the Lovelace UI and automations a faster process, as fewer entities to chose from makes finding the correct one easier.

    In this sensor's case, the temperature reading is absolutely useless, and I also don't need to be informed that the battery is low by an additional sensor. I can do that using just the percentage. Disabling an entity is as easy as opening it app and clicking on the slider.

    Changing a Home Assistant sensor's type

    The final adjustment I want to make is to change the fact that the sensor is reporting my chair to be wet when I'm sitting on it. Technically, it doesn't matter what it reports, as a binary sensor will always report either on or off. Aesthetically, however, there is a difference. Call me vain, but I like my sensors to represent what they are actually doing.

    To do so, you will need to open your configuration.yaml file. At the end of this file, add the following:

      customize: !include customize.yaml    

    You can then create a new file titled customize.yaml in the same folder as the configuration file. Here you can add the sensor you intend to change and add any of the variables found in the documentation. In my case, only two changes were necessary. I decided on a fitting Material Design Icon, and set the device's class to occupancy.

      icon: mdi:seat-outline
      device_class: occupancy

    With the file saved, you will need to restart Home Assistant and your customization should show up immediately. Because you just created the customize.yaml file, this restart is necessary. For any future changes, reloading the YAML configuration from the Server Controls should suffice.

    The customized sensor being displayed in the Home Assistant entity browser.
    A portrait photo oif Liam Alexander Colman, the author, creator, and owner of Home Assistant Guide wearing a suit.

    About Liam Alexander Colman

    is an experienced Home Assistant user who has been utilizing the platform for a variety of projects over an extended period. His journey began with a Raspberry Pi, which quickly grew to three Raspberry Pis and eventually a full-fledged server. Liam's current operating system of choice is Unraid, with Home Assistant comfortably running in a Docker container.
    With a deep understanding of the intricacies of Home Assistant, Liam has an impressive setup, consisting of various Zigbee devices, and seamless integrations with existing products such as his Android TV box. For those interested in learning more about Liam's experience with Home Assistant, he shares his insights on how he first started using the platform and his subsequent journey.


    Leave a comment

    Share to...