purpleair.yaml

sensor purple_rest:
  - platform: rest
    name: "PurpleAir"

    # Inspired by: https://chrisjrn.com/2021/05/27/adding-a-purpleair-monitor-to-home-assistant/
    # (but modified for a local connection)
    #
    # See https://community.home-assistant.io/t/purpleair-air-quality-sensor/146588 for a huge discussion
    # on various approaches. Must of this is inspired by that thread.
    #
    # See https://docs.google.com/document/d/15ijz94dXJ-YAZLi9iZ_RaBwrZ4KtYeCy08goGBwnbCU/edit#
    # for a lot of details on the sensor fields.

    # Substitute in the URL of the sensor you care about. You may need to look in your
    # router to figure out its IP address.
    resource: http://192.168.7.202/json

    # Since it is local, query as often as you want
    scan_interval: 15

    # Set this sensor to be the uptime value. It doesn't really matter, but the REST
    # sensor doesn't support a unique_id, so I find it harder to work with. So all
    # of the important stuff is represented as template sensors below.
    value_template: >
      {{ value_json["uptime"] }}
    unit_of_measurement: "s"
    state_class: total
    # The value of the sensor can't be longer than 255 characters, but the
    # attributes can.  Store away all the data for use by the templates below.
    json_attributes:
      - current_dewpoint_f
      - pressure
      - current_humidity
      - current_temp_f
      - pm2.5_aqi
      - pm2.5_aqi_b
      - pm2_5_atm # PM2.5_CF_ATM_ug/m3, Channel A
      - pm2_5_atm_b # PM2.5_CF_ATM_ug/m3, Channel B
      - pm2_5_cf_1 # PM2.5_CF_1_ug/m3, Channel A
      - pm2_5_cf_1_b # PM2.5_CF_1_ug/m3, Channel B
      - pm1_0_atm # PM1.0_CF_ATM_ug/m3, Channel A
      - pm1_0_atm_b # PM1.0_CF_ATM_ug/m3, Channel B
      - pm1_0_cf_1 # PM1.0_CF_ATM_ug/m3, Channel A
      - pm1_0_cf_1_b # PM1.0_CF_ATM_ug/m3, Channel B
      - pm10_0_atm # PM10.0_CF_ATM_ug/m3, Channel A
      - pm10_0_atm_b # PM10.0_CF_ATM_ug/m3, Channel B
      - pm10_0_cf_1 # PM10.0_CF_1_ug/m3, Channel A
      - pm10_0_cf_1_b # PM10.0_CF_1_ug/m3, Channel B
      - p_0_3_um # 0.3um/dl, Channel A
      - p_0_3_um_b # 0.3um/dl, Channel B
      - p_0_5_um # 0.5um/dl, Channel A
      - p_0_5_um_b # 0.5um/dl, Channel B
      - p_1_0_um # 1.0um/dl, Channel A
      - p_1_0_um_b # 1.0um/dl, Channel B
      - p_2_5_um # 2.5um/dl, Channel A
      - p_2_5_um_b # 2.5um/dl, Channel B
      - p_5_0_um # 5.0um/dl, Channel A
      - p_5_0_um_b # 5.0um/dl, Channel B
      - p_10_0_um # 10.0um/dl, Channel A
      - p_10_0_um_b # 10.0um/dl, Channel B

template:
  - sensor:
      - unique_id: "purpleair_calculated_pm25_aqi"
        name: "PurpleAir PM2.5 AQI (calculated)"
        device_class: aqi
        state: >
          {% macro calcAQI(Cp, Ih, Il, BPh, BPl) -%}
            {{ (((Ih - Il)/(BPh - BPl)) * (Cp - BPl) + Il)|round|int }}
          {%- endmacro %}
          {% if not is_number(states('sensor.purpleair_pm25_ugm3')) %}
            unknown
          {% else %}
            {% set pm25 = states('sensor.purpleair_pm25_ugm3') | float %}
            {% if pm25 > 1000 %}
              invalid
            {% elif pm25 > 350.5 %}
              {{ calcAQI(pm25, 500.0, 401.0, 500.0, 350.5) }}
            {% elif pm25 > 250.5 %}
              {{ calcAQI(pm25, 400.0, 301.0, 350.4, 250.5) }}
            {% elif pm25 > 150.5 %}
              {{ calcAQI(pm25, 300.0, 201.0, 250.4, 150.5) }}
            {% elif pm25 > 55.5 %}
              {{ calcAQI(pm25, 200.0, 151.0, 150.4, 55.5) }}
            {% elif pm25 > 35.5 %}
              {{ calcAQI(pm25, 150.0, 101.0, 55.4, 35.5) }}
            {% elif pm25 > 12.1 %}
              {{ calcAQI(pm25, 100.0, 51.0, 35.4, 12.1) }}
            {% elif pm25 >= 0.0 %}
              {{ calcAQI(pm25, 50.0, 0.0, 12.0, 0.0) }}
            {% else %}
              invalid
            {% endif %}
          {% endif %}
        unit_of_measurement: "AQI"

  - sensor:
      - unique_id: "purpleair_calculated_pm25_aqi_epa_smoke"
        name: "PurpleAir PM2.5 AQI (calculated, EPA)"
        icon: mdi:smoke
        device_class: aqi
        state: >
          {% macro calcAQI(Cp, Ih, Il, BPh, BPl) -%}
            {{ (((Ih - Il)/(BPh - BPl)) * (Cp - BPl) + Il)|round|int}}
          {%- endmacro %}
          {% if not is_number(states('sensor.purpleair_pm25_ugm3_epa_smoke')) %}
            unknown
          {% else %}
            {% set pm25 = states('sensor.purpleair_pm25_ugm3_epa_smoke') | float %}
            {% if pm25 > 1000 %}
              invalid
            {% elif pm25 > 350.5 %}
              {{ calcAQI(pm25, 500.0, 401.0, 500.0, 350.5) }}
            {% elif pm25 > 250.5 %}
              {{ calcAQI(pm25, 400.0, 301.0, 350.4, 250.5) }}
            {% elif pm25 > 150.5 %}
              {{ calcAQI(pm25, 300.0, 201.0, 250.4, 150.5) }}
            {% elif pm25 > 55.5 %}
              {{ calcAQI(pm25, 200.0, 151.0, 150.4, 55.5) }}
            {% elif pm25 > 35.5 %}
              {{ calcAQI(pm25, 150.0, 101.0, 55.4, 35.5) }}
            {% elif pm25 > 12.1 %}
              {{ calcAQI(pm25, 100.0, 51.0, 35.4, 12.1) }}
            {% elif pm25 >= 0.0 %}
              {{ calcAQI(pm25, 50.0, 0.0, 12.0, 0.0) }}
            {% else %}
              invalid
            {% endif %}
          {% endif %}
        unit_of_measurement: "AQI"

  - trigger:
      - platform: state
        entity_id: sensor.purpleair
    sensor:
      - unique_id: "purpleair_temperature"
        name: "PurpleAir Temperature"
        device_class: temperature
        # Using documented offset (-8°F) from Purple Air.
        # Store the last 60 readings in an attribute.
        # Compute the value by discarding the ten largest and ten smallest values
        # and averaging the remaining.
        # The temperature sensor has noise that appears as drops in temperature,
        # this processing step seems to clean it up pretty well.
        state: >
          {% set data = state_attr('sensor.purpleair_temp', 'history') | default([], True) %}
          {% set current = state_attr('sensor.purpleair', 'current_temp_f') - 8 %}
          {% set middle_readings = ((data + [current]) | sort)[10:-10] %}
          {% if middle_readings | length %}
            {{ ((middle_readings | sum) / (middle_readings | length)) | round(1)}}
          {% else %}
            unknown
          {% endif %}
        unit_of_measurement: "°F"
        attributes:
          raw: "{{ state_attr('sensor.purpleair','current_temp_f') }}"
          # Cache about 15 minutes worth of readings for a max
          history: >
            {% set data = state_attr('sensor.purpleair_temp', 'history') | default([], True) %}
            {% set current = state_attr('sensor.purpleair', 'current_temp_f') - 8 %}
            {{ (data[-60:] + [current]) }}

  - sensor:
      # Includes offset, but no attempt to smooth the data.
      - unique_id: "purpleair_temperature_raw"
        name: "PurpleAir Temperature (raw)"
        device_class: temperature
        state: "{{ state_attr('sensor.purpleair', 'current_temp_f') - 8 }}"
        unit_of_measurement: "°F"

  - trigger:
      - platform: state
        entity_id: sensor.purpleair
    sensor:
      - unique_id: "purpleair_humidity"
        name: "PurpleAir Humidity"
        device_class: humidity
        # using documented offset from Purple Air
        state: >
          {% set data = state_attr('sensor.purpleair_humidity', 'history') | default([], True) %}
          {% set current = state_attr('sensor.purpleair', 'current_humidity') + 4 %}
          {{ ( (data | sum + current) / (data | length + 1) ) | round(1)}}
        unit_of_measurement: "%"
        attributes:
          raw: "{{ state_attr('sensor.purpleair','current_humidity') }}"
          # Cache about 5 minutes worth of readings for an average
          history: >
            {% set data = state_attr('sensor.purpleair_humidity', 'history') | default([], True) %}
            {% set current = state_attr('sensor.purpleair', 'current_humidity') + 4 %}
            {{ (data[-20:] + [current]) }}

  - sensor:
      # Includes offset, but no attempt to smooth the data.
      - unique_id: "purpleair_humidity_raw"
        name: "PurpleAir Humidity (raw)"
        device_class: humidity
        state: "{{ state_attr('sensor.purpleair', 'current_humidity') + 4 }}"
        unit_of_measurement: "%"

  - trigger:
      - platform: state
        entity_id: sensor.purpleair
    sensor:
      - unique_id: "purpleair_pressure"
        name: "PurpleAir Pressure"
        device_class: pressure
        # Store the last 60 readings in an attribute.
        # Compute the value by discarding the ten largest and ten smallest values
        # and averaging the remaining.
        # This method converts to a standard "sea level" pressure.
        # Set hm to your the altitude of your sensor in meters.
        # Sea level conversion from https://keisan.casio.com/keisan/image/Convertpressure.pdf
        state: >
          {% set data = state_attr('sensor.purpleair_pressure', 'history') | default([], True) %}
          {% set current = state_attr('sensor.purpleair','pressure') %}
          {% set tc = (states('sensor.purpleair_temp') | float - 32) * 5 / 9 %}
          {% set hm = 376 %}
          {% set middle_readings = ((data + [current]) | sort)[10:-10] %}
          {% if middle_readings | length %}
            {% set ps = ((middle_readings | sum) / (middle_readings | length)) | round(3) %}
            {{ (ps * (1 - (0.0065 * hm) / (tc + 0.0065 * hm + 273.15))**-5.257) | round(2) }}
          {% else %}
            unknown
          {% endif %}
        attributes:
          # Cache about 15 minutes worth of readings for a max
          history: >
            {% set data = state_attr('sensor.purpleair_pressure', 'history') | default([], True) %}
            {% set current = state_attr('sensor.purpleair', 'pressure') %}
            {{ (data[-60:] + [current]) }}
        unit_of_measurement: "mbar"

  - sensor:
      # Does not include sea level adjust or any attempt to smooth the data.
      - unique_id: "purpleair_pressure_raw"
        name: "PurpleAir Pressure (raw)"
        device_class: humidity
        state: "{{ state_attr('sensor.purpleair', 'pressure') + 4 }}"
        unit_of_measurement: "mbar"

  - sensor:
      - unique_id: "purpleair_dewpoint"
        name: "PurpleAir Dewpoint"
        device_class: temperature
        # There is a built-in dewpoint, but it appears to be computed from the unadjusted values, formula from https://en.wikipedia.org/wiki/Dew_point
        state: >
          {% if not is_number(states('sensor.purpleair_humidity')) or not is_number(states('sensor.purpleair_temp')) %}
            unknown
          {% else %}
            {% set rh = states('sensor.purpleair_humidity') | float %}
            {% set tc = (states('sensor.purpleair_temp') | float - 32) * 5 / 9 %}
            {% set b = 18.678 %}
            {% set c = 257.14 %}
            {% set lam = ((rh/100) | log) + ((b * tc) / (c + tc)) %}
            {% set dew_c = c * lam / (b - lam) %}
            {% set dew_f = dew_c * 9 / 5 + 32 %}
            {{ dew_f | round(1)}}
          {% endif %}
        unit_of_measurement: "°F"
        attributes:
          raw: "{{ state_attr('sensor.purpleair','current_dewpoint_f') }}"

  - sensor:
      # Does not include any attempt to smooth the data.
      - unique_id: "purpleair_dewpoint_raw"
        name: "PurpleAir Dewpoint (raw)"
        device_class: temperature
        state: "{{ state_attr('sensor.purpleair', 'current_dewpoint_f') }}"
        unit_of_measurement: "°F"

  - sensor:
      - unique_id: "purpleair_builtin_pm25_aqi"
        name: "PurpleAir PM2.5 AQI (built-in)"
        device_class: aqi
        state: "{{ ( (state_attr('sensor.purpleair','pm2.5_aqi') + state_attr('sensor.purpleair','pm2.5_aqi_b')) / 2 ) | round | int}}"
        unit_of_measurement: "AQI"

  - sensor:
      - unique_id: "purpleair_pm1_ugm3"
        name: "PurpleAir PM1.0 µg/m³"
        device_class: pm1
        state: "{{ (state_attr('sensor.purpleair','pm1_0_atm') + state_attr('sensor.purpleair','pm1_0_atm_b')) / 2 }}"
        unit_of_measurement: "µg/m³"

  - trigger:
      - platform: state
        entity_id: sensor.purpleair
    sensor:
      # There are some notes about the PurpleAir map using CF=1 (instead of CF=ATM) possibly due
      # to some old misunderstandings of the data. ATM was supposed to be adjusted for outdoor air
      # where CF=1 was for indoor. There are some notes about some sensors having the labels reversed
      # in firmware, I don't know if the firmware has been udpated or which values are actually being
      # pulled. Anyway, this is the one I've selected to use for the AQI value.
      # This code attempts to smooth the value by looking at the last ten minutes of readings,
      # throwing out the 5 highest and 5 lowest, and averaging the remaining.
      - unique_id: "purpleair_pm25_ugm3"
        name: "PurpleAir PM2.5 µg/m³"
        device_class: pm25
        state: >
          {% set data = state_attr('sensor.purpleair_pm25_ugm3', 'history') | default([], True) %}
          {% set current = (state_attr('sensor.purpleair','pm2_5_atm') + state_attr('sensor.purpleair','pm2_5_atm_b')) / 2 %}
          {% set middle_readings = ((data + [current]) | sort)[5:-5] %}
          {% if middle_readings | length %}
            {{ ((middle_readings | sum) / (middle_readings | length)) | round(3)}}
          {% else %}
            unknown
          {% endif %}
        unit_of_measurement: "µg/m³"
        attributes:
          raw: "{{ (state_attr('sensor.purpleair','pm2_5_atm') + state_attr('sensor.purpleair','pm2_5_atm_b')) / 2 }}"
          # Cache about 10 minutes worth of readings for a max
          history: >
            {% set data = state_attr('sensor.purpleair_pm25_ugm3', 'history') | default([], True) %}
            {% set current = (state_attr('sensor.purpleair','pm2_5_atm') + state_attr('sensor.purpleair','pm2_5_atm_b')) / 2 %}
            {{ (data[-40:] + [current]) }}

  - sensor:
      # Attempt at implementing: https://cfpub.epa.gov/si/si_public_record_report.cfm?dirEntryId=349513
      - unique_id: "purpleair_pm25_ugm3_epa_smoke"
        name: "PurpleAir PM2.5 µg/m³ (EPA)"
        icon: mdi:smoke
        device_class: pm25
        state: "{{ 0.52 * ((state_attr('sensor.purpleair','pm2_5_cf_1') + state_attr('sensor.purpleair','pm2_5_cf_1_b')) / 2) - (0.085 * state_attr('sensor.purpleair','current_humidity')) + 5.71 }}"
        unit_of_measurement: "µg/m³"

  - sensor:
      - unique_id: "purpleair_pm100_ugm3"
        name: "PurpleAir PM10.0 µg/m³"
        device_class: pm10
        state: "{{ (state_attr('sensor.purpleair','pm10_0_atm') + state_attr('sensor.purpleair','pm10_0_atm_b')) / 2 }}"
        unit_of_measurement: "µg/m³"