This i a fork of https://github.com/denysdovhan/purifier-card

This fork introduces several key enhancements and modifications to the original Purifier Card for Home Assistant, making it more tailored to Xiaomi air purifiers and adding specific functionalities that were not present in the original version.

1. Xiaomi-Specific Enhancements Fan Speed Control:

The fan speed is now controlled using the xiaomi_miot.set_miot_property service. The slider directly adjusts the fan speed by converting the percentage to the corresponding Xiaomi-specific speed value (from 0 to 14) and sends it via the siid and piid parameters. The card automatically sets the preset mode to "Favorite" whenever the fan speed is adjusted, ensuring compatibility with Xiaomi's operation modes. Preset Mode Display:

The slider percentage value is dynamically replaced with "Auto" or "Sleep" when these preset modes are selected, providing a clearer and more intuitive interface.

2. Custom Naming Configurable Entity Name: Users can now set a custom name for the purifier entity through the card's configuration. If a custom name is provided, it will be displayed on the card; otherwise, the default friendly_name of the entity will be shown.

3. Shortcut Enhancements Preset and Speed Shortcuts: The card includes shortcuts for preset modes like Auto, Sleep, and Favorite, as well as direct speed controls (e.g., 25%, 50%, 75%, and 100%). Each shortcut adjusts the fan speed accordingly and updates the slider to reflect the new value.

4. General Improvements Simplified Code Structure: The code has been streamlined to focus specifically on Xiaomi devices, reducing complexity and potential conflicts with other brands or models. Enhanced Error Handling: Added better handling and logging for service calls, particularly around fan speed and preset mode adjustments.

Summary of New Capabilities The updated version of the Purifier Card is optimized for Xiaomi air purifiers, offering direct control over fan speed, preset modes, and other Xiaomi-specific features. It also includes enhanced customization options, allowing users to set custom names and create specialized shortcuts like filter resets, all within a simplified and more user-friendly interface. This version is ideal for users who primarily operate Xiaomi air purifiers and need a more integrated and seamless control experience within Home Assistant.

Purifier Card

Air Purifier card for Home Assistant Lovelace UI

By default, the Home Assistant does not provide any card for controlling air purifiers. This card displays the state and allows to control your air purifier.

Installing

💡 Tip: If you like this project and want to get some stickers and postcards, consider giving me a tip for the time I spent building this project:

HACS

This card is available in HACS (Home Assistant Community Store).

Just search for Purifier Card in the plugins tab.

Manual

1. Download purifier-card.js file from the latest-release.

2. Put purifier-card.js file into your config/www folder.

3. Add a reference to purifier-card.js in Lovelace. There's two way to do that:

   1. Using UI: Configuration → Lovelace Dashboards → Resources → Click Plus button → Set Url as /local/purifier-card.js → Set Resource type as JavaScript Module.

   2. Using YAML: Add the following code to lovelace section.

      resources:
        - url: /local/purifier-card.js
          type: module

4. Add custom:purifier-card to Lovelace UI as any other card (using either editor or YAML configuration).

Using the card

This card can be configured using Lovelace UI editor.

1. In Lovelace UI, click 3 dots in top left corner.
2. Click Configure UI.
3. Click Plus button to add a new card.
4. Find Custom: Purifier Card in the list.
5. Choose entity.
6. Now you should see the preview of the card!

Sorry, no support for shortcuts and stats in visual config yet.

Typical example of using this card in YAML config would look like this:

type: 'custom:purifier-card'
entity: fan.purifier
name: some name on the card
stats:
  - attribute: filter_life_remaining
    unit: '%'
    subtitle: Filter Remaining
  - attribute: motor_speed
    unit: RPM
    subtitle: Motor Speed
  - entity_id: sensor.purifier_filter_life
    value_template: '{{ (value | float(0) / 3600) | round(1) }}'
    unit: hours
    subtitle: Filter Life
shortcuts:
  - name: Silent
    icon: 'mdi:weather-night'
    preset_mode: Silent
  - name: 25%
    icon: 'mdi:circle-slice-2'
    percentage: 25
  - name: 50%
    icon: 'mdi:circle-slice-4'
    percentage: 50
  - name: 75%
    icon: 'mdi:circle-slice-6'
    percentage: 75
  - name: 100%
    icon: 'mdi:circle-slice-8'
    percentage: 100
  - name: Auto
    icon: 'mdi:brightness-auto'
    preset_mode: Auto
show_name: true
show_state: true
show_toolbar: true
compact_view: false

Here is what every option means:

Name	Type	Default	Description
type	string	Required	custom:purifier-card
entity	string	Required	An entity_id within the fan domain.
name	string	Optional	Name of the purifier.
show_name	boolean	true	Show friendly name of the purifier.
show_state	boolean	true	Show state of the purifier.
show_preset_mode	boolean	true	Show preset mode of the purifier in the header.
show_toolbar	boolean	true	Show toolbar with shortcuts.
compact_view	boolean	false	Compact view without image.
aqi	object	Optional	Custom entity or attribute for AQI value.
stats	array	Optional	Custom per state stats for your purifier cleaner
shortcuts	object	Optional	Custom shortcuts for your purifier cleaner.

aqi object

Name	Type	Default	Description
entity_id	string	Optional	An entity_id with state, i.e. sensor.current_aqi.
attribute	string	Optional	An attribute which should be used to get AQI value.
unit	string	Optional	An unit of measurement to display.

You can also combine attribute with entity_id to extract an attribute value of specific entity.

stats object

You can use any attribute of purifier or even any entity by entity_id to display by stats section. Not only that, but you can also combine attribute with entity_id to extract an attribute value of specific entity:

Name	Type	Default	Description
entity_id	string	Optional	An entity_id with state, i.e. sensor.purifier_aqi.
attribute	string	Optional	Attribute name of the stat, i.e. filter_left.
value_template	string	Optional	Jinja2 template returning a value. value variable represents the entity_id or attribute state.
unit	string	Optional	Unit of measure, i.e. hours.
subtitle	string	Optional	Friendly name of the stat, i.e. Filter.

shortcuts object

You can define custom scripts for custom actions or add shortcuts for switching presets and percentages via shortcuts option.

Name	Type	Default	Description
name	string	Optional	Friendly name of the shortcut, i.e. Switch to Auto.
icon	string	Optional	Any icon for shortcut button.
service	string	Optional	A service to call, i.e. script.clean_air.
target	object	Optional	A HassServiceTarget, to define a target for the current service call.
service_data	object	Optional	service_data for service call
percentage	object	Optional	A percentage to switch to, i.e. 27, etc. See entity's percentage_step for valid values.
preset_mode	object	Optional	A speed to switch to, i.e. Auto, etc

The card will automatically try to figure out which one of shortcuts is currently active. The shortcut will be highlighted when:

1. It's a service.
2. entity's percentage attribute is equal to shortcut's percentage.
3. entity's preset_mode attribute is equal to shortcut's preset_mode.

Theming

This card can be styled by changing the values of these CSS properties (globally or per-card via [card-mod][card-mod]):

Variable	Default value	Description
--pc-background	var(--ha-card-background, var(--card-background-color, white))	Background of the card
--pc-primary-text-color	var(--primary-text-color)	Vacuum name, stats values, etc
--pc-secondary-text-color	var(--secondary-text-color)	Status, stats units and titles, etc
--pc-icon-color	var(--secondary-text-color)	Colors of icons
--pc-slider-path-color	var(--round-slider-path-color)	Color of the slider path
--pc-slider-bar-color	var(--round-slider-bar-color)	Color of the slider bar
--pc-toolbar-background	var(--vc-background)	Background of the toolbar
--pc-toolbar-text-color	var(--secondary-text-color)	Color of the toolbar texts
--pc-toolbar-icon-color	var(--secondary-text-color)	Color of the toolbar icons
--pc-divider-color	var(--entities-divider-color, var(--divider-color))	Color of dividers
--pc-spacing	10px	Paddings and margins inside the card

Styling via theme

Here is an example of customization via theme. Read more in the Frontend documentation.

my-custom-theme:
  pc-background: '#17A8F4'
  pc-spacing: 5px

Styling via card-mod

You can use [card-mod][card-mod] to customize the card on per-card basis, like this:

type: 'custom:purifier-card'
style: |
  ha-card {
    --pc-background: #17A8F4;
    --pc-spacing: 5px;
  }
  ...

Animations

I've added an animation for this card to make it alive:

How did I make this animation? It's a long story…

1. I took original gif file from here.
2. Then I tweaked image levels to make the background black and purifier white.
3. Then I inverted colors on the gif.
4. Then I've split the gif by frame.
5. Then I removed the background of the image frame by frame using remove.bg.
6. Then I upscaled each of those images using icons8.com/upscaler.
7. Then I put up all of those images back in a single gif.
8. Profit!

Archive with images from all of these steps can be found here.

Supported languages

This card supports translations. Please, help to add more translations and improve existing ones. Here's a list of supported languages:

• English
• Українська (Ukrainian)
• Türkçe (Turkish)
• Français (French)
• Norsk (Norwegian)
• Polski (Polish)
• Български (Bulgarian)
• 简体中文 (Simplified Chinese)
• Deutsch (German)
• Català (Catalan)
• Русский (Russian)
• Italiano (Italian)
• 繁體中文 (Traditional Chinese)
• Čeština (Czech)
• Dutch (Netherlands)
• Español (Spanish)
• Your language?

Supported models

This card relies on basic fan services, like toggle, turn_on, turn_off, etc. It should work with any air purifier, however I can physically test it only with my own purifier.

If this card works with your air purifier, please open a PR and your model to the list.

• Air Purifier 4 Pro
• Air Purifier 4 Lite
• Air Purifier 4 Compact
• Air Purifier 3/3H
• Air Purifier 2/2H/2S
• Air Purifier Pro

Development

Want to contribute to the project?

First of all, thanks! Check contributing guideline for more information.

Inspiration

This project is heavily inspired by:

• MacBury Smart House — basically, this project is a refinement of MacBury's custom card.

Huge thanks for their ideas and efforts 👍

License

MIT © Denys Dovhan