Skip to content

Air Quality on Your Dashboard

The SEN65 reads particulate matter, VOC, and NOx, and the AQI component turns your PM readings into a single NowCast AQI number. Putting those on a Home Assistant dashboard gives you a live air quality monitor, and one small automation can nudge you when it's time to open a window. Everything here uses cards and triggers that ship with Home Assistant, so there's nothing to install.

Before you start

Level 1 is the everyday display. Level 2 adds a gauge and an alert on top. Open your dashboard, click the pencil in the top right to start editing, then follow whichever level you like.

Level 1: Tile cards

Difficulty: Level 1

A Tile card is the small, modern card with an icon, a name, and the current reading. You'll add one each for the readings you check most.

  1. With the dashboard in edit mode, click Add Card and open the By entity tab.
  2. Search starter kit and check the readings you want: PM <2.5µm, VOC Index, NOx Index, and NowCast AQI are a good starting set. (1)
  3. Click Tile to lay them out, then click Save.
  1. The preview fills in with the live reading as soon as you pick an entity, so you can confirm you grabbed the right ones.
Tile cards in YAML

Edit any card and choose Show code editor to paste one in. Swap in your own entity names; yours usually follow sensor.<device-name>_nowcast_aqi.

type: tile
entity: sensor.esphome_starter_kit_pm_2_5um
---
type: tile
entity: sensor.esphome_starter_kit_nowcast_aqi

Level 2: A NowCast AQI gauge

Difficulty: Level 2

A Gauge card shines when a higher reading really does mean worse, and NowCast AQI is exactly that: one 0-500 number where bigger is worse. The dial runs green to red as the air degrades.

  1. Click Add Card and search for Gauge.
  2. Set Entity to your NowCast AQI sensor and give it a Name like Living Room AQI.
  3. Set Minimum to 0 and Maximum to 500, the full AQI range.
  4. Toggle on Display as needle gauge, then turn on Severity and set green at 0, yellow at 51, and red at 101. (1)
  1. Those cutoffs follow the EPA AQI categories: 0 to 50 is Good, 51 to 100 is Moderate, and 101 and up is Unhealthy for Sensitive Groups or worse. Red is your cue to act.
Gauge card in YAML 
type: gauge
entity: sensor.esphome_starter_kit_nowcast_aqi
min: 0
max: 500
needle: true
severity:
  green: 0
  yellow: 51
  red: 101
name: Living Room AQI

Level 2: A bad-air alert

Difficulty: Level 2

A dashboard only helps when you're looking at it. This one automation watches the NowCast AQI and pushes a notification to your phone when it crosses into unhealthy air, so you find out from another room. (1)

  1. Want it to act, not just alert? Add a second action, switch.turn_on on a smart-plug purifier or fan, plus a matching automation that turns the plug off when the AQI drops back under 100. The same one-trigger pattern also covers the readings the AQI leaves out: point a Numeric state trigger at the VOC Index above 100 or the NOx Index above 1 to catch cooking and cleaning as they happen.

  2. Click the button below to open Settings → Automations & scenes, then click + Create automation → Create new automation:

    Open your Home Assistant instance and show your automations.

  3. Click + Add trigger, search Numeric state, and pick the Numeric state trigger.

    • Entity → your NowCast AQI sensor
    • Above → 100
    • For → 5 minutes (1)
    1. The For duration means the AQI has to stay above 100 for five straight minutes before the automation fires, so a quick spike from searing a steak rides out and only air that's actually staying bad reaches your phone.

  4. Under Then do, click + Add action, search Notifications, and pick Send a notification via device for your phone.

    • Message → Air quality is unhealthy (NowCast AQI {{ states('sensor.esphome_starter_kit_nowcast_aqi') }}). Time to ventilate.
    • Title → Air Quality Alert

  5. Name the automation Air quality alert and click Save.

Automation in YAML

Select Edit in YAML from the automation's three-dot menu to see or paste the raw config. Your entity IDs will differ.

alias: Air quality alert
triggers:
  - trigger: numeric_state
    entity_id: sensor.esphome_starter_kit_nowcast_aqi
    above: 100
    for:
      minutes: 5
actions:
  - action: notify.mobile_app_your_phone
    data:
      title: Air Quality Alert
      message: >-
        Air quality is unhealthy (NowCast AQI
        {{ states('sensor.esphome_starter_kit_nowcast_aqi') }}). Time to
        ventilate.
mode: single

New to ESPHome? We're here to help.

Stuck on a step or want to show off what you built? Ask questions and share projects with the Apollo community.

Join our Discord Community Forum