From 16b78bbb44f318f82cce6cafd02652f33ddbc123 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Mon, 13 Jul 2026 16:08:04 -0500 Subject: [PATCH] Add SEN65 air quality Everyday Use page (#1032) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New "Air Quality on Your Dashboard" page under the Starter Kit Everyday Use section: Level 1 Tile cards, Level 2 NowCast AQI gauge, and a Level 2 bad-air alert automation using a native numeric_state trigger. Per-section collapsed YAML and scoped annotations. Gifs to be added later. ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) --- .../air-quality-on-your-dashboard.md | 137 ++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 138 insertions(+) create mode 100644 docs/products/ESPHome-Starter-Kit/everyday-use/air-quality-on-your-dashboard.md diff --git a/docs/products/ESPHome-Starter-Kit/everyday-use/air-quality-on-your-dashboard.md b/docs/products/ESPHome-Starter-Kit/everyday-use/air-quality-on-your-dashboard.md new file mode 100644 index 0000000000..936f4342ca --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/everyday-use/air-quality-on-your-dashboard.md @@ -0,0 +1,137 @@ +--- +title: Air Quality on Your Dashboard +description: >- + Put your SEN65's air quality readings on a Home Assistant dashboard and get a + push notification when the air goes bad, all with built-in cards and a native + automation. +--- +# Air Quality on Your Dashboard + +The [SEN65](../modules/breakout-addons/sen65-air-quality-sensor.md) 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. + +!!! note "Before you start" + + * Your SEN65 is wired to the Breakout Module and added to Home Assistant. If not, start with the [SEN65 Air Quality Sensor](../modules/breakout-addons/sen65-air-quality-sensor.md) page, then [Connect to Home Assistant](../tutorials/connect-to-home-assistant.md). + * For the gauge and the alert, add the **NowCast AQI** sensor from the [SEN65 YAML](../modules/breakout-addons/sen65-air-quality-sensor.md#add-to-esphome-device-builder). The particulate, VOC, and NOx tiles work without it. + +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. + +??? note "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._nowcast_aqi`. + + ```yaml + 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. + +??? note "Gauge card in YAML" + + ```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. + +1. 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.](https://my.home-assistant.io/badges/automations.svg)](https://my.home-assistant.io/redirect/automations/) + +2. 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. + +3. 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` + +4. Name the automation `Air quality alert` and click **Save**. + +??? note "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. + + ```yaml + 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 + ``` + +--8<-- "_snippets/community-help.md" diff --git a/mkdocs.yml b/mkdocs.yml index f248e772cc..d8741b2c39 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -556,6 +556,7 @@ nav: - Everyday Use: - Motion-Activated Room Lights: products/ESPHome-Starter-Kit/everyday-use/motion-activated-room-lights.md - Temperature on Your Dashboard: products/ESPHome-Starter-Kit/everyday-use/temperature-on-your-dashboard.md + - Air Quality on Your Dashboard: products/ESPHome-Starter-Kit/everyday-use/air-quality-on-your-dashboard.md - Button Toggles a Room Light: products/ESPHome-Starter-Kit/everyday-use/button-toggles-room-light.md - Trash Night Reminder: products/ESPHome-Starter-Kit/everyday-use/trash-night-reminder.md - Play a Tune from Home Assistant: products/ESPHome-Starter-Kit/everyday-use/play-a-tune-from-home-assistant.md