openhab-addons/bundles/org.openhab.binding.airquality/README.md

# Air Quality Binding

This binding uses the [AQIcn.org service](https://aqicn.org) for providing air quality information for any location worldwide.

The World Air Quality Index project is a social enterprise project started in 2007.
Its mission is to promote Air Pollution awareness and provide a unified Air Quality information for the whole world.

The project is proving a transparent Air Quality information for more than 70 countries, covering more than 9000 stations in 600 major cities, via those two websites: [aqicn.org](https://aqicn.org) and [waqi.info](https://waqi.info).

To use this binding, you first need to [register and get your API token](https://aqicn.org/data-platform/token/).

## Supported Things

There is exactly one supported thing type, which represents the air quality information for an observation location.
It has the `aqi` id.
Of course, you can add multiple Things, e.g. for measuring AQI for different locations.

## Discovery

Local Air Quality can be autodiscovered based on system location.
You will have complete default configuration with your apiKey.

## Binding Configuration

The binding has no configuration options, all configuration is done at Thing level.

## Thing Configuration

The thing has a few configuration parameters:

| Parameter | Description                                                             |
|-----------|-------------------------------------------------------------------------|
| apikey    | Data-platform token to access the AQIcn.org service. Mandatory.         |
| location  | Geo coordinates to be considered by the service.                        |
| stationId | Unique ID of the measuring station.                                     |
| refresh   | Refresh interval in minutes. Optional, the default value is 60 minutes. |

For the location parameter, the following syntax is allowed (comma separated latitude and longitude):

```java
37.8,-122.4
37.8255,-122.456
```

If you always want to receive data from specific station and you know its unique ID, you can enter it instead of the coordinates.

This `stationId` can be found by using the following link:
https://api.waqi.info/search/?token=TOKEN&keyword=NAME, replacing TOKEN by your apikey and NAME by the station you are looking for.

## Channels

The AirQuality information that is retrieved is available as these channels:

| Channel ID      | Item Type            | Description                                  |
|-----------------|----------------------|----------------------------------------------|
| aqiLevel        | Number               | Air Quality Index                            |
| aqiColor        | Color                | Color associated to given AQI Index.         |
| aqiDescription  | String               | AQI Description                              |
| locationName    | String               | Nearest measuring station location           |
| stationId       | Number               | Measuring station ID                         |
| stationLocation | Location             | Latitude/longitude of measuring station      |
| pm25            | Number               | Fine particles pollution level (PM2.5)       |
| pm10            | Number               | Coarse dust particles pollution level (PM10) |
| o3              | Number               | Ozone level (O3)                             |
| no2             | Number               | Nitrogen Dioxide level (NO2)                 |
| co              | Number               | Carbon monoxide level (CO)                   |
| so2             | Number               | Sulfur dioxide level (SO2)                   |
| observationTime | DateTime             | Observation date and time                    |
| temperature     | Number:Temperature   | Temperature in Celsius degrees               |
| pressure        | Number:Pressure      | Pressure level                               |
| humidity        | Number:Dimensionless | Humidity level                               |
| dominentpol     | String               | Dominent Polutor                             |

`AQI Description` item provides a human-readable output that can be interpreted e.g. by MAP transformation.

*Note that channels like* `pm25`, `pm10`, `o3`, `no2`, `co`, `so2` *can sometimes return* `UNDEF` *value due to the fact that some stations don't provide measurements for them.*

## Full Example

airquality.map:

```text
-=-
UNDEF=No data
NULL=No data
NO_DATA=No data
GOOD=Good
MODERATE=Moderate
UNHEALTHY_FOR_SENSITIVE=Unhealthy for sensitive groups
UNHEALTHY=Unhealthy
VERY_UNHEALTHY=Very unhealthy
HAZARDOUS=Hazardous
```

airquality.things:

```java
airquality:aqi:home "AirQuality" @ "Krakow" [ apikey="XXXXXXXXXXXX", location="50.06465,19.94498", refresh=60 ]
airquality:aqi:warsaw "AirQuality in Warsaw" [ apikey="XXXXXXXXXXXX", location="52.22,21.01", refresh=60 ]
airquality:aqi:brisbane "AirQuality in Brisbane" [ apikey="XXXXXXXXXXXX", stationId=5115 ]
```

airquality.items:

```java
Group AirQuality <flow>

Number   Aqi_Level           "Air Quality Index" <flow> (AirQuality) { channel="airquality:aqi:home:aqiLevel" }
String   Aqi_Description     "AQI Level [MAP(airquality.map):%s]" <flow> (AirQuality) { channel="airquality:aqi:home:aqiDescription" }

Number   Aqi_Pm25            "PM\u2082\u2085 Level" <line> (AirQuality) { channel="airquality:aqi:home:pm25" }
Number   Aqi_Pm10            "PM\u2081\u2080 Level" <line> (AirQuality) { channel="airquality:aqi:home:pm10" }
Number   Aqi_O3              "O\u2083 Level" <line> (AirQuality) { channel="airquality:aqi:home:o3" }
Number   Aqi_No2             "NO\u2082 Level" <line> (AirQuality) { channel="airquality:aqi:home:no2" }
Number   Aqi_Co              "CO Level" <line> (AirQuality) { channel="airquality:aqi:home:co" }
Number   Aqi_So2             "SO\u2082 Level" <line> (AirQuality) { channel="airquality:aqi:home:so2" }

String   Aqi_LocationName    "Measuring Location" <settings> (AirQuality) { channel="airquality:aqi:home:locationName" }
Location Aqi_StationGeo      "Station Location" <office> (AirQuality) { channel="airquality:aqi:home:stationLocation" }
Number   Aqi_StationId       "Station ID" <pie> (AirQuality) { channel="airquality:aqi:home:stationId" }
DateTime Aqi_ObservationTime "Time of observation [%1$tH:%1$tM]" <clock> (AirQuality) { channel="airquality:aqi:home:observationTime" }

Number:Temperature  Aqi_Temperature     "Temperature" <temperature> (AirQuality) { channel="airquality:aqi:home:temperature" }
Number:Pressure     Aqi_Pressure        "Pressure" <pressure> (AirQuality) { channel="airquality:aqi:home:pressure" }
Number:Dimensionless Aqi_Humidity        "Humidity" <humidity> (AirQuality) { channel="airquality:aqi:home:humidity" }
```

airquality.sitemap:

```perl
sitemap airquality label="Air Quality" {
    Frame {
        Text item=Aqi_Level valuecolor=[
                Aqi_Level=="-"="lightgray",
                Aqi_Level>=300="#7e0023",
                >=201="#660099",
                >=151="#cc0033",
                >=101="#ff9933",
                >=51="#ffde33",
                >=0="#009966"
            ]
        Text item=Aqi_Description valuecolor=[
                Aqi_Description=="HAZARDOUS"="#7e0023",
                =="VERY_UNHEALTHY"="#660099",
                =="UNHEALTHY"="#cc0033",
                =="UNHEALTHY_FOR_SENSITIVE"="#ff9933",
                =="MODERATE"="#ffde33",
                =="GOOD"="#009966"
            ]
    }

    Frame {
        Text item=Aqi_Pm25
        Text item=Aqi_Pm10
        Text item=Aqi_O3
        Text item=Aqi_No2
        Text item=Aqi_Co
        Text item=Aqi_So2
    }

    Frame {
        Text item=Aqi_LocationName
        Text item=Aqi_ObservationTime
        Text item=Aqi_Temperature
        Text item=Aqi_Pressure
        Text item=Aqi_Humidity
    }

    Frame label="Station Location" {
        Mapview item=Aqi_StationGeo height=10
    }
}

```

airquality.rules:

```java
rule "Change lamp color to reflect Air Quality"
when
    Item Aqi_Description changed
then
    var String hsb

    switch Aqi_Description.state {
        case "HAZARDOUS":
            hsb = "343,100,49"
        case "VERY_UNHEALTHY":
            hsb = "280,100,60"
        case "UNHEALTHY":
            hsb = "345,100,80"
        case "UNHEALTHY_FOR_SENSITIVE":
            hsb = "30,80,100"
        case "MODERATE":
            hsb = "50,80,100"
        case "GOOD":
            hsb = "160,100,60"
    }

    Lamp_Color.sendCommand(hsb)
end
```