Breathing Easy: Integrating Air Quality Data with Home Assistant

In today's world, monitoring the air we breathe is becoming increasingly important for our health and well-being. Factors like pollution, pollen, wildfires, and even indoor activities can significantly impact air quality. Integrating this crucial environmental data into your smart home allows you to gain awareness and take proactive steps to improve your indoor environment automatically.

Why Integrate Air Quality Data into Home Assistant?

Beyond simple monitoring, bringing air quality metrics like the Air Quality Index (AQI) and Particulate Matter (PM2.5) into Home Assistant unlocks powerful automation possibilities:

• Automate Air Purifiers: Automatically turn on or adjust the speed of air purifiers when air quality deteriorates.
• Control Ventilation: Trigger ventilation systems (like HRVs/ERVs) based on indoor or outdoor air quality.
• Receive Alerts: Get notified on your phone or smart displays when air quality reaches unhealthy levels.
• Manage Windows/Doors: Get reminders or even automate smart windows/blinds to close when outdoor air quality is poor (e.g., during pollen season or wildfire smoke events).
• Visualize Data: Display real-time and historical air quality trends on your Home Assistant dashboards.

This integration transforms your smart home from just being convenient to actively contributing to a healthier living space.

Choosing Your Air Quality Data Source

There are two primary ways to get air quality data into Home Assistant:

1. External APIs: Integrate data from public air quality monitoring networks via APIs like OpenAQ. This requires no hardware purchase but relies on the availability of nearby sensors and the API's reliability.
2. Local Sensors: Install your own air quality sensor, such as a PurpleAir sensor (popular for outdoor use) or various indoor sensors (e.g., from Aqara, Airthings, or integrated via ESPHome). This provides data specific to your location and microenvironment.

For this guide, we'll focus on integrating data from a PurpleAir sensor, a widely used and relatively affordable option that provides detailed particulate matter readings often used for AQI calculations. The principles can often be adapted for other sensor types or API integrations.

Prerequisites

• An operational Home Assistant instance.
• Network connectivity (Wi-Fi for most sensors).
• A PurpleAir sensor (either one you own or data from a public sensor near you that shares data).
• An optional PurpleAir API key (free for non-commercial use) is needed for polling data, especially from public sensors or for accessing historical data. You can obtain one from the PurpleAir website.

Integration Method: Using the PurpleAir Integration

The easiest way to integrate PurpleAir data is by using the dedicated PurpleAir integration available for Home Assistant. While sometimes built-in, many specific hardware integrations start life in the Home Assistant Community Store (HACS). We'll proceed assuming it's available via HACS, which is a common path for community-developed integrations.

Note: Check the official Home Assistant Integrations page first. If PurpleAir is listed there, use the standard Configuration -> Integrations flow. If not, proceed with the HACS method.

Step 1: Install HACS (If You Haven't Already)

If HACS is not yet installed on your Home Assistant instance, follow the official HACS documentation to add it. This typically involves adding a custom repository and restarting Home Assistant.

Step 2: Add the PurpleAir Integration via HACS

Once HACS is installed and configured:

1. Navigate to the HACS panel in your Home Assistant sidebar.
2. Go to the "Integrations" section.
3. Click the "+ Explore & Download Repositories" button.
4. Search for "PurpleAir".
5. Click on the "PurpleAir" integration entry.
6. Click the "Download" button on the repository page.
7. Select the latest version and click "Download".
8. Restart Home Assistant after the download is complete. This is crucial for the integration to be recognized.

Step 3: Configure the PurpleAir Integration

After Home Assistant restarts:

1. Go to "Settings" -> "Devices & Services".
2. Click the "+ Add Integration" button.
3. Search for "PurpleAir" and select it.
4. A configuration dialog will appear. You'll need to provide the necessary details:
   • Poll Method: You can choose between using a Sensor ID or Latitude/Longitude.
     • Sensor ID: If you know the specific ID of your sensor or a nearby public one. Find this by going to the PurpleAir Map, clicking on a sensor, and looking at the URL (the number after ?sensor=).
     • Latitude/Longitude: Use the coordinates of your location. The integration can often find the nearest sensor this way.
   • API Key: Enter your optional PurpleAir API Read Key if you have one and want to use it for potentially faster updates or access to historical data (required for polling by Lat/Lon in some configurations). Leave blank if you are polling by Sensor ID without an API key (though using a key is recommended).
   • Station Name (Optional): Give this integration instance a custom name (e.g., "Outdoor Air Quality").
   • Polling Interval (Optional): Adjust how often Home Assistant fetches data (default is usually sufficient).
   • Other options: Depending on the integration version, you might have options for indoor/outdoor placement, averaging methods, etc. Configure these based on your sensor setup.
5. Submit the configuration. Home Assistant should now discover entities provided by the integration.

Understanding PurpleAir Entities in Home Assistant

Once configured, the PurpleAir integration will create several sensor entities in Home Assistant, typically including:

• sensor.purpleair_your_sensor_name_pm25_aqi: The calculated AQI based on the PM2.5 reading. This is often the most useful metric for general automation.
• sensor.purpleair_your_sensor_name_pm25_a_ug_m3: Raw PM2.5 concentration from one of the sensor's channels (PurpleAir sensors have two).
• sensor.purpleair_your_sensor_name_pm25_b_ug_m3: Raw PM2.5 concentration from the second channel.
• sensor.purpleair_your_sensor_name_temperature_f or _c: Temperature reading from the sensor.
• sensor.purpleair_your_sensor_name_humidity: Humidity reading.
• sensor.purpleair_your_sensor_name_pressure_in_hg or _hpa: Pressure reading.
• Other entities may exist depending on the sensor model and integration version (e.g., PM1.0, PM10, different AQI calculations).

Focus on the AQI and PM2.5 entities (_pm25_aqi and _pm25_a_ug_m3 or _b_ug_m3, or an averaged one if available) as these are the most common indicators of air quality relevant for health and automation.

Automation Ideas Leveraging Air Quality Data

Here are some examples of automations you can create:

Automation 1: Turn on Air Purifier When Indoor Air Quality Deteriorates

Assuming you have an indoor air quality sensor (e.g., an Aqara TVOC sensor, or maybe you brought your PurpleAir sensor indoors temporarily) or use the outdoor data as a proxy:

automation:
  - alias: Turn on air purifier if indoor AQI is high
    description: ''
    trigger:
      - platform: numeric_state
        entity_id: sensor.your_indoor_air_quality_sensor_aqi # Replace with your sensor
        above: 100 # Example threshold for 'Unhealthy for Sensitive Groups' or 'Unhealthy'
    condition:
      - condition: time
        # Optional: Only run during occupied hours, e.g., daytime
        after: '07:00'
        before: '22:00'
    action:
      - service: switch.turn_on # Or fan.turn_on, depending on your purifier entity type
        entity_id: switch.your_air_purifier_entity # Replace with your purifier entity
      - service: notify.mobile_app_your_phone
        data:
          title: "Air Quality Alert"
          message: "Indoor air quality is unhealthy (AQI {{ states('sensor.your_indoor_air_quality_sensor_aqi') }}). Turning on air purifier."
    mode: single

Automation 2: Notify About Poor Outdoor Air Quality

Useful during wildfire season or high pollen counts:

automation:
  - alias: Notify about poor outdoor air quality
    description: ''
    trigger:
      - platform: numeric_state
        entity_id: sensor.purpleair_outdoor_aqi # Replace with your outdoor sensor AQI entity
        above: 150 # Example threshold for 'Unhealthy'
    condition:
      # Optional: Add a condition to prevent frequent notifications, e.g., if already notified recently
      - condition: state
        entity_id: input_boolean.outdoor_aq_alert_sent # Requires an input_boolean helper
        state: 'off'
    action:
      - service: notify.mobile_app_your_phone # Or your preferred notification service
        data:
          title: "Outdoor Air Quality Alert"
          message: "Outdoor air quality is unhealthy (AQI {{ states('sensor.purpleair_outdoor_aqi') }}). Consider closing windows."
      - service: input_boolean.turn_on
        entity_id: input_boolean.outdoor_aq_alert_sent
      - delay:
          hours: 4 # Delay before allowing another notification
      - service: input_boolean.turn_off
        entity_id: input_boolean.outdoor_aq_alert_sent
    mode: single

Remember to replace entity IDs and thresholds with values appropriate for your setup and location. You can find standard AQI thresholds (Good, Moderate, Unhealthy for Sensitive Groups, Unhealthy, Very Unhealthy, Hazardous) from environmental agencies like the EPA.

Best Practices for a Reliable Air Quality Integration

• Sensor Placement: For outdoor sensors, follow manufacturer guidelines regarding placement to get accurate readings (away from walls, vents, etc.). For indoor sensors, place them in living areas at breathing height, away from direct drafts, heaters, or kitchens/bathrooms unless you specifically want to monitor those areas.
• Network Reliability: Ensure your sensor has a stable Wi-Fi connection. A dropping connection will lead to stale data in Home Assistant.
• API Key Usage: If polling public sensors or if recommended by the integration, use an API key. Be mindful of any rate limits associated with free keys.
• Understand Data Latency: PurpleAir data is typically updated frequently (every few minutes), but the polling interval in Home Assistant adds some latency. Consider this when setting automation thresholds.
• Monitor Integration Status: Periodically check the integration settings in Home Assistant for any errors or warnings. Keep HACS integrations updated.
• Handle Missing Data: In automations, consider using conditions that check if the sensor entity's state is unavailable or unknown before acting, to avoid errors during outages.
• Visualize Trends: Use the History or Recorder integration in Home Assistant to store air quality data and visualize trends over time. This helps you understand typical patterns in your environment.

Conclusion

Integrating air quality data, whether from personal sensors like PurpleAir or public API feeds, adds a valuable dimension to your Home Assistant smart home. It moves beyond comfort and convenience to actively manage an important aspect of your health and living environment. By following these steps, you can set up a reliable system to monitor air quality and automate your home to respond intelligently, ensuring you and your family can breathe a little easier.