I created a beautiful custom Home Assistant card to control a Xiaomi fan

I recently connected my smart Xiaomi fan to my Home Assistant installation but found the default card in the user interface lacking in design and functionality. So I used this as an excuse to finally create my first own card. Here is how it works and how you can use to control your Xiaomi fan.

The fan

In my last post I described how to connect the Xiaomi Smart fan to Home Assistant. Using the Xiami Fan integration from the HACS community store makes it pretty simple. The integration works well and provides me access to all the fans features. At the end of the post I promised a better solution for the pretty utilitarian standard card though.

It is not the pinnacle of design and can only turn the fan on or off. The rest of the features is hidden behind the detail menu you get when you click on the name. So I started working on my own solution.

If you are thinking about getting the same fan consider buying the hardware via my affiliate link(s). It won’t cost you more and pays for my server costs.
Xiaomi Mi Smart fan 1c

The inspiration

My custom cards design is based on the awesome work from the lovelace-xiaomi-vacuum-card repository. I used it to control my Roborock cleaner Jarvis!

I love the design and the code behind it looks well structured and is easy to understand. It also has a pretty open MIT license so I decided to use that code and update it to my needs. I am looking for a couple of status fields about the mode, speed and overall state of the fan and a couple of buttons to turn it off/on and control the speed.

The custom Xiaomi fan control card

Before I describe the process, you can find the final result on GitHub. I chose home-assistant-xiaomi-fan-card as a name for this card and updated the code to work with the before mentioned integration for the fans. The buttons now call the services provided by that integration (like fan.toggle, fan.oscillate and fan.set_preset_mode) and display the data from the fan (like mode and raw_speed).

I can still adapt the needed buttons in the future but for now this is good enough for me. I can start/stop the fan, enable or disable the swiveling and set the fan to one of the three speed levels. I am also looking to add translations in the future but for now everything is in English and using the values provided by the integration.

To further improve the look of the card I also took a picture of my fan, made the background black and added is it as a background of the card. In my opinion this makes it look really good.

How you can install this card

Of course after making this I also want to share it with the Home Assistant community. If you are looking to use this card there are two ways to install it. In either way you should first follow my guide on how to integrate the fan with Home Assistant.

By copying

The “quick and dirty” solution that will work for everybody is simply going to my GitHub repository for the card and downloading the xiaomi-fan-card.js file. You can then copy this file to the <config>/www directory of your Home Assistant installation. Afterwards just restart Home Assistant and you are ready to use the card.

Via HACS

The other way of installing the card is using the HACS community store. After you installed it according to the directions on their website go to the HACS tab in Home Assistant and click the button on the top right.

Select “Custom repositories” and add the URL https://github.com/OliverHi/home-assistant-xiaomi-fan-card. Now you should be able to find and install this card as home-assistant-xiaomi-fan-card via HACS.

After installation just follow the instructions given by HACS. Usually this means restarting Home Assistant once. Now you are ready to start using it.

How to use the card

After installing the card it needs to be added to a lovelace dashboard to be of any use. I plan to add UI support for this later but for now you need to add it directly via the yaml configuration. Go to your dashboard, use the menu on the top right to click “Edit dashboard” and then “Raw configuration editor”. Now you can add the card here to any cards: part of a tab.

- type: 'custom:xiaomi-fan-card'
  entity: fan.xiaomi_fan_1c

The basic example is pretty simple. Just add an entry with the type of the new card and provide the id of the entity you want to control (in this case fan.xiaomi_fan_1c). This will result in the simple card shown above with a white background.

If you are looking for something a bit more fancy you can also add a background image like this:

- type: 'custom:xiaomi-fan-card'
  entity: fan.xiaomi_fan_1c
  image: /local/img/xiaomi_fan2.jpg

This image has to be in your <config>/www/img folder for this example to work. In my case the final example looks like this.

Future development

I plan to keep working on this from time to time. I am thinking about removing some of the buttons and move some functionality to dropdown menus to make it more minimalistic. I am also looking to add translations and convert the values returned by the API to something more human readable.

It seems to be a bit more complicated but I would also like to add support for creating such a card via the UI and not just via yaml.

If you are able to help out with any of these tasks or have found any other errors please feel free to contact me, or even better: to create a pull request!