AirGradient

The AirGradient integration will fetch data from your AirGradient devices. AirGradient creates indoor and outdoor air quality monitors that enable you know if the air quality is healthy or not. They measure metrics such as PM2.5, CO2, TVOCs, and NOx. Both the software and hardware are open-source, allowing you to customize or extend the device functionality.

Use cases

• Monitor indoor and outdoor air quality.
• Warn to open windows when CO2 levels are too high.
• Control ventilation systems based on air quality.

Supported devices

• AirGradient DIY Air Quality Monitor
• AirGradient Indoor Air Quality Monitor
• AirGradient Outdoor Air Quality Monitor

Configuration

To add the AirGradient device to your Home Assistant instance, use this My button:

AirGradient can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.

Supported functionality

Below is a complete overview of the entities this integration provides.

Available sensors

The integration will fetch data from each device. The following sensors are supported:

• Carbon dioxide
• Humidity
• Nitrogen index
• PM0.3 count
• PM1 density
• PM2.5 density
• PM10 density
• Raw nitrogen
• Raw total volatile organic compounds
• Raw PM2.5
• Signal strength
• Temperature
• Total volatile organic compounds index

A number of configuration entities are available as sensors to automate with if you control the device via the AirGradient dashboard instead of set it to control locally.

• CO2 automatic baseline calibration days
• NOx learning offset
• Total volatile organic compounds learning offset
• Data used for the LED bar
• LED bar brightness
• Display temperature unit
• Display brightness

Available configuration entities

The integration provides a few configuration entities to customize the device experience. The settings are only available when the configuration source is set to local. The following entities are supported:

• Display temperature unit
• Display brightness
• LED bar brightness
• Requesting CO2 calibration
• Requesting LED bar test
• Toggling sharing metrics with AirGradient
• Configuration source
• Data used for the LED bar
• Display PM standard
• CO2 automatic baseline calibration days
• NOx learning offset
• Total volatile organic compounds learning offset

Updates

The AirGradient integration provides an update entity that checks for firmware updates for your AirGradient device. To install the update, the device needs to be rebooted.

Data updates

This integration uses local pollingData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more], meaning it checks for changes to all entities by regularly communicating with the AirGradient device.

The integration will retrieve data from the device every minute.

The updates for the device are checked once every hour.

Actions

This integration does not provide additional actions. All actions available for this integration are provided by their respective entities.

Examples

The following examples show how to use the AirGradient integration in Home Assistant automations. These examples are just a starting point, and you can use them as inspiration to create your own automations.

Notify when the CO2 level is too high

The following example sends a notification to your mobile device when the CO2 level exceeds 1000 ppm.

automation:
  - alias: "Notify when CO2 level is too high"
    triggers:
      - trigger: numeric_state
        entity_id: sensor.airgradient_carbon_dioxide
        above: 1000

    actions:
      - action: notify.mobile_app_your_device
        data:
          title: "High CO2 Level Alert"
          message: >
            The CO2 level is too high at {{ states('sensor.airgradient_carbon_dioxide') }} ppm.
            Please consider ventilating the room.

Known limitations

The AirGradient integration currently has the following limitations:

• The update entity is not able to install updates automatically. You will need to reboot the device manually after installing the update.

Troubleshooting

If you’re experiencing issues with your AirGradient integration, try these general troubleshooting steps:

1. Make sure your AirGradient is powered on and properly connected to your home network.
2. If the integration shows as unavailable, try restarting both your AirGradient and Home Assistant.

Removing the integration

This integration follows standard integration removal, no extra steps are required.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three-dot menu. Then, select Delete.