Skip to content

Commit 54bf0ef

Browse files
bachyafrenck
bachya
and
frenck
authored
Add AQI rating template sensor example to the PurpleAir docs (#25687)
Co-authored-by: Franck Nijhof <frenck@frenck.nl>
1 parent c472f5e commit 54bf0ef

File tree

1 file changed

+119
-1
lines changed

1 file changed

+119
-1
lines changed

‎source/_integrations/purpleair.markdown

Lines changed: 119 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ ha_integration_type: integration
1515
ha_config_flow: true
1616
---
1717

18-
[PurpleAir](https://www2.purpleair.com/) makes sensors that measure hyper-local air quality data and share it with the public.
18+
[PurpleAir](https://www2.purpleair.com/) makes sensors that measure hyper-local air
19+
quality data and share it with the public.
1920

2021
{% include integrations/config_flow.md %}
2122

@@ -27,3 +28,120 @@ Add Sensor:
2728
Remove Sensor:
2829
description: Untrack a sensor.
2930
{% endconfiguration_basic %}
31+
32+
## Creating an AQI Rating from Raw Particulate Data
33+
34+
The PurpleAir API does not provide AQI data; therefore, the integration does not create
35+
an AQI sensor automatically. However, sensors providing raw particulate data can be used
36+
to create a human-friendly AQI rating sensor.
37+
38+
<div class='note warning'>
39+
The guidelines within this documentation constitute estimates and are intended to help
40+
informed decision making. They should not replace analysis, advice or diagnosis from a
41+
trained medical professional.
42+
</div>
43+
44+
### Understanding EPA Guidelines
45+
46+
The United States Environmental Protection Agency (EPA) provides
47+
[guidelines](https://aqs.epa.gov/aqsweb/documents/codetables/aqi_breakpoints.html) on
48+
correlating the concentration of pollution over a time period to overall "healthiness."
49+
For example, a PM2.5 concentration between 0.0 and 12.0 µg/m³ over a 24-hour period
50+
equates to a "Good" AQI rating.
51+
52+
Therefore, a common strategy would be to use the guidelines for the particulate types
53+
provided by the PurpleAir integration and "merge" them into a single AQI rating.
54+
55+
### Creating Statistics Sensors
56+
57+
With the EPA guidelines in hand, the next step is to create
58+
[`statistics`](/integrations/statistics/) sensors for each particulate sensor you are
59+
interested. This example uses PM2.5 and PM10.0 over a 24-hour period:
60+
61+
<div class='note info'>
62+
The entity IDs provided below are simulated; make sure that you use entity IDs that
63+
actually exist in your Home Assistant instance.
64+
</div>
65+
66+
```yaml
67+
sensor:
68+
- platform: statistics
69+
name: "Average Outdoor PM2.5 (24h)"
70+
entity_id: sensor.sensor_pm2_5_mass_concentration
71+
state_characteristic: mean
72+
max_age:
73+
hours: 24
74+
75+
- platform: statistics
76+
name: "Average Outdoor PM10.0 (24h)"
77+
entity_id: sensor.sensor_pm10_0_mass_concentration
78+
state_characteristic: mean
79+
max_age:
80+
hours: 24
81+
```
82+
83+
### Creating the AQI Rating Sensor
84+
85+
The [`statistics`](/integrations/statistics/) sensors can then be combined into a template
86+
sensor. Note that this example takes a conservative approach: the "worse" of the two
87+
values (PM2.5 or PM10.0) is used to determine the overall rating.
88+
89+
<div class='note info'>
90+
Reminder that the breakpoints used below can be determined from the aforementioned EPA
91+
guidelines.
92+
</div>
93+
94+
{% raw %}
95+
96+
```yaml
97+
sensor:
98+
- name: "Local Outdoor Air Quality"
99+
state: >
100+
{% set pm2_5_avg = states("sensor.average_outdoor_pm2_5_24h") | int %}
101+
{% if 0 <= pm2_5_avg <= 12.0 %}
102+
{% set pm2_5_rating = 0 %}
103+
{% elif 12.0 < pm2_5_avg <= 35.4 %}
104+
{% set pm2_5_rating = 1 %}
105+
{% elif 35.4 < pm2_5_avg <= 55.4 %}
106+
{% set pm2_5_rating = 2 %}
107+
{% elif 55.4 < pm2_5_avg <= 150.4 %}
108+
{% set pm2_5_rating = 3 %}
109+
{% elif 150.4 < pm2_5_avg <= 250.4 %}
110+
{% set pm2_5_rating = 4 %}
111+
{% else %}
112+
{% set pm2_5_rating = 5 %}
113+
{% endif %}
114+
115+
{% set pm10_0_avg = states("sensor.average_outdoor_pm10_0_24h") | int %}
116+
{% if 0 <= pm10_0_avg <= 54.0 %}
117+
{% set pm10_0_rating = 0 %}
118+
{% elif 54.0 < pm10_0_avg <= 154.0 %}
119+
{% set pm10_0_rating = 1 %}
120+
{% elif 154.0 < pm10_0_avg <= 254.0 %}
121+
{% set pm10_0_rating = 2 %}
122+
{% elif 254.0 < pm10_0_avg <= 354.0 %}
123+
{% set pm10_0_rating = 3 %}
124+
{% elif 354.0 < pm10_0_avg <= 424.0 %}
125+
{% set pm10_0_rating = 4 %}
126+
{% else %}
127+
{% set pm10_0_rating = 5 %}
128+
{% endif %}
129+
130+
{% set rating = [pm2_5_rating, pm10_0_rating] | max %}
131+
{% if rating == 0 %}
132+
Good
133+
{% elif rating == 1 %}
134+
Moderate
135+
{% elif rating == 2 %}
136+
Unhealthy for sensitive groups
137+
{% elif rating == 3 %}
138+
Unhealthy
139+
{% elif rating == 4 %}
140+
Very unhealthy
141+
{% else %}
142+
Hazardous
143+
{% endif %}
144+
unique_id: local_outdoor_air_quality
145+
```
146+
147+
{% endraw %}

0 commit comments

Comments
 (0)