denysdovhan/purifier-card

[!IMPORTANT]

I don't own an air purifier anymore.

I still maintain this card. I will be fixing bugs, maitaining dependencies and styles. However, new features won't be actively developed anymore.

If you have an air purifier and are willing to contribute, you are welcome.

Purifier Card

[!NOTE] 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.

Sponsorship

Your generosity will help me maintain and develop more projects like this one.

• 💖 Sponsor on GitHub
• ☕️ Buy Me A Coffee
• Bitcoin: bc1q7lfx6de8jrqt8mcds974l6nrsguhd6u30c6sg8
• Ethereum: 0x6aF39C917359897ae6969Ad682C14110afe1a0a1

Installing

HACS

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

Just search for Purifier Card in the plugins tab.

Manual

Click to show how to manually add to dashboard resources

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
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:

aqi object

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:

shortcuts object

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

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]):

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)
• Slovenčina (Slovak)
• Português (Portuguese)
• 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 (in alphabetical order).

• Air Purifier 4 Pro
• Air Purifier 3/3H
• Air Purifier 2/2H/2S
• Air Purifier Pro
• Blueair Classic 480i/680i
• Coway Airmega 300S/400S (using IoCare custom component)
• Dyson Pure Cool/Cool Link/Cool Desk/Cool Link Desk (using Dyson custom integration)
• Dyson Pure Humidify+Cool (using Dyson custom integration)
• Dyson Purifier Hot+Cool HP2 De-NOx (using Dyson custom integration)
• Honeywell H-Cat Air Purifier (using Local Tuya integration)
• Ikea Starkvind
• Levoit Air Purifier (Core 200S) (partially)
• Levoit Air Purifier (Core 400S)
• Philips AirPurifier AC3858/50 (partially)
• Philips AirPurifier AC4221/11 (using philips-airpurifier-coap cutom component)
• SmartMI Air Purifier
• Winix AM90 Wi-Fi Air Purifier
• Your purifier?

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