Initial release v2.1.0

Air Quality Card for Home Assistant with WHO-based thresholds, gradient graphs, and visual configuration editor.
2026-02-11 10:42:34 -05:00 · 2026-02-11 10:42:34 -05:00 · ef2922a1f6
commit ef2922a1f6
4 changed files with 1239 additions and 0 deletions
--- a/21
+++ b/21
@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/README.md
+++ b/README.md
@ -0,0 +1,168 @@
+# Air Quality Card
+
+A custom Home Assistant Lovelace card for monitoring indoor air quality with beautiful gradient graphs and WHO-based health thresholds.
+
+![Air Quality Card Preview](https://raw.githubusercontent.com/KadenThomp36/air-quality-card/main/images/preview.png)
+
+## Features
+
+- **Real-time monitoring** of CO2, PM2.5, humidity, and temperature
+- **Gradient-colored graphs** that change color based on air quality levels
+- **Interactive hover/touch** to see historical values at any point
+- **Health-based thresholds** following WHO 2021 guidelines and ASHRAE standards
+- **Actionable recommendations** like "Open Window" or "Run Air Purifier"
+- **Tap to expand** - click any graph to open the full Home Assistant history view
+- **Visual configuration editor** - no YAML required
+
+## Installation
+
+### HACS (Recommended)
+
+1. Open HACS in Home Assistant
+2. Click on "Frontend"
+3. Click the three dots in the top right and select "Custom repositories"
+4. Add the repository URL: `https://github.com/KadenThomp36/air-quality-card`
+5. Select "Lovelace" as the category
+6. Click "Add"
+7. Search for "Air Quality Card" and install it
+8. Refresh your browser
+
+### Manual Installation
+
+1. Download `air-quality-card.js` from the latest release
+2. Copy it to `/config/www/air-quality-card/air-quality-card.js`
+3. Add the resource in Home Assistant:
+   - Go to Settings → Dashboards → Resources
+   - Add `/local/air-quality-card/air-quality-card.js` as a JavaScript Module
+
+## Configuration
+
+### Using the Visual Editor
+
+1. Add a new card to your dashboard
+2. Search for "Air Quality Card"
+3. Configure the entities using the visual editor
+
+### YAML Configuration
+
+```yaml
+type: custom:air-quality-card
+name: Office Air Quality
+co2_entity: sensor.air_quality_co2
+pm25_entity: sensor.air_quality_pm25
+humidity_entity: sensor.air_quality_humidity
+temperature_entity: sensor.air_quality_temperature
+air_quality_entity: sensor.air_quality_index
+recommendation_entity: sensor.air_quality_recommendation
+hours_to_show: 24
+```
+
+### Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `name` | string | No | "Air Quality" | Card title |
+| `co2_entity` | string | Yes | - | CO2 sensor entity ID |
+| `pm25_entity` | string | Yes | - | PM2.5 sensor entity ID |
+| `humidity_entity` | string | No | - | Humidity sensor entity ID |
+| `temperature_entity` | string | No | - | Temperature sensor entity ID |
+| `air_quality_entity` | string | No | - | Overall air quality index entity |
+| `recommendation_entity` | string | No | - | Recommendation template sensor |
+| `hours_to_show` | number | No | 24 | Hours of history to display (1-168) |
+
+## Recommendation Sensor
+
+For the best experience, create a template sensor that provides recommendations. Add this to your `configuration.yaml`:
+
+```yaml
+template:
+  - sensor:
+      - name: "Air Quality Recommendation"
+        unique_id: air_quality_recommendation
+        state: >
+          {% set co2 = states('sensor.YOUR_CO2_SENSOR') | float(0) %}
+          {% set pm25 = states('sensor.YOUR_PM25_SENSOR') | float(0) %}
+          {% set humidity = states('sensor.YOUR_HUMIDITY_SENSOR') | float(0) %}
+          {% if co2 > 1500 %}
+            Ventilate Now
+          {% elif pm25 > 35 %}
+            Run Air Purifier
+          {% elif pm25 > 25 and co2 > 1000 %}
+            Air Purifier + Ventilate
+          {% elif pm25 > 25 %}
+            Run Air Purifier
+          {% elif co2 > 1000 %}
+            Open Window
+          {% elif humidity < 30 %}
+            Too Dry
+          {% elif humidity > 60 %}
+            Too Humid
+          {% elif co2 > 800 or pm25 > 15 %}
+            Consider Ventilating
+          {% else %}
+            All Good
+          {% endif %}
+```
+
+## Health Thresholds
+
+### CO2 (Carbon Dioxide)
+| Level | Range | Color | Meaning |
+|-------|-------|-------|---------|
+| Excellent | < 600 ppm | Green | Fresh outdoor air levels |
+| Good | 600-800 ppm | Light Green | Well-ventilated space |
+| Moderate | 800-1000 ppm | Yellow | Acceptable, consider ventilation |
+| Elevated | 1000-1500 ppm | Orange | May affect concentration |
+| Poor | > 1500 ppm | Red | Ventilation needed |
+
+### PM2.5 (Fine Particulate Matter)
+Based on WHO 2021 Air Quality Guidelines:
+| Level | Range | Color | Meaning |
+|-------|-------|-------|---------|
+| Excellent | < 5 µg/m³ | Green | WHO annual guideline |
+| Good | 5-15 µg/m³ | Light Green | WHO 24-hour guideline |
+| Moderate | 15-25 µg/m³ | Yellow | Slightly elevated |
+| Elevated | 25-35 µg/m³ | Orange | Consider air purifier |
+| Poor | > 35 µg/m³ | Red | Air purifier recommended |
+
+### Humidity
+| Level | Range | Color | Meaning |
+|-------|-------|-------|---------|
+| Too Dry | < 30% | Orange | Use humidifier |
+| Dry | 30-40% | Light Green | Acceptable |
+| Comfortable | 40-50% | Green | Ideal range |
+| Humid | 50-60% | Light Green | Acceptable |
+| Too Humid | > 60% | Orange | Improve ventilation |
+
+## Supported Devices
+
+This card works with any air quality sensor that provides entities for CO2 and PM2.5. Tested with:
+
+- IKEA VINDSTYRKA / ALPSTUGA (via Matter)
+- Aqara TVOC Air Quality Monitor
+- Xiaomi Air Quality Monitor
+- SenseAir S8
+- Any ESPHome-based air quality sensor
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/KadenThomp36/air-quality-card.git
+
+# The card is vanilla JavaScript with no build step required
+# Simply edit air-quality-card.js and test in Home Assistant
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Credits
+
+- Thresholds based on [WHO 2021 Air Quality Guidelines](https://www.who.int/publications/i/item/9789240034228)
+- CO2 recommendations based on [ASHRAE Standard 62.1](https://www.ashrae.org/technical-resources/bookstore/standards-62-1-62-2)
--- a/air-quality-card.js
+++ b/air-quality-card.js
--- a/hacs.json
+++ b/hacs.json
@ -0,0 +1,6 @@
+{
+  "name": "Air Quality Card",
+  "render_readme": true,
+  "filename": "air-quality-card.js",
+  "homeassistant": "2024.1.0"
+}