2020-09-21 01:58:32 +02:00
# 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
2021-11-09 08:59:13 +01:00
Bridge: The binding supports a bridge to connect to the [AQIcn.org service ](https://aqicn.org ). A bridge uses the thing ID "api".
Station: Represents the air quality information for an observation location.
Of course, you can add multiple Stations, e.g. for measuring AQI for different locations.
2020-09-21 01:58:32 +02:00
## Discovery
Local Air Quality can be autodiscovered based on system location.
2021-11-09 08:59:13 +01:00
You will created a Bridge with your apiKey.
2020-09-21 01:58:32 +02:00
2021-11-09 08:59:13 +01:00
## Bridge Configuration
2022-12-07 21:09:32 +01:00
The bridge configuration only holds the api key :
2021-11-09 08:59:13 +01:00
| Parameter | Description |
|-----------|-------------------------------------------------------------------------|
| apiKey | Data-platform token to access the AQIcn.org service. Mandatory. |
2020-09-21 01:58:32 +02:00
## Thing Configuration
2021-11-09 08:59:13 +01:00
The 'Station' thing has a few configuration parameters:
2020-09-21 01:58:32 +02:00
| Parameter | Description |
|-----------|-------------------------------------------------------------------------|
| 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:
2022-12-07 21:09:32 +01:00
`https://api.waqi.info/search/?token=TOKEN&keyword=NAME` , replacing TOKEN by your apiKey and NAME by the station you are looking for.
2021-11-09 08:59:13 +01:00
### Thing properties
Once created, at first execution, the station's properties will be filled with informations gathered from the web service :
- Nearest measuring station location
- Measuring station ID
- Latitude/longitude of measuring station
2020-09-21 01:58:32 +02:00
## Channels
2021-11-09 08:59:13 +01:00
The AirQuality information that is retrieved for a given is available as these channels:
### AQI Channels Group - Global Results
| Channel ID | Item Type | Description |
|-----------------|----------------------|----------------------------------------------|
| alert-level | Number | Alert level (*) associated to AQI Index. |
| index | Number | Air Quality Index |
| timestamp | DateTime | Observation date and time |
| dominent | String | Dominent Pollutant |
| icon | Image | Pictogram associated to alert-level |
| color | Color | Color associated to alert level. |
### Weather Channels Group
2020-09-21 01:58:32 +02:00
| Channel ID | Item Type | Description |
|-----------------|----------------------|----------------------------------------------|
| temperature | Number:Temperature | Temperature in Celsius degrees |
| pressure | Number:Pressure | Pressure level |
| humidity | Number:Dimensionless | Humidity level |
2021-11-09 08:59:13 +01:00
| dew-point | Number:Temperature | Dew point temperature |
| wind-speed | Number:Speed | Wind speed |
### Pollutants Channels Group
For each pollutant (PM25, PM10, O3, NO2, CO, SO2) , depending upon availability of the station,
you will be provided with the following informations
| Channel ID | Item Type | Description |
|-----------------|----------------------|----------------------------------------------|
| value | Number:Density | Measured density of the pollutant |
| index | Number | AQI Index of the single pollutant |
| alert-level | Number | Alert level associate to the index |
2020-09-21 01:58:32 +02:00
2022-12-07 21:09:32 +01:00
(*) The alert level is described by a color :
2021-11-09 08:59:13 +01:00
| Code | Color | Description |
|------|--------|--------------------------------|
| 0 | Green | Good |
| 1 | Yellow | Moderate |
| 2 | Orange | Unhealthy for Sensitive Groups |
| 3 | Red | Unhealthy |
| 4 | Purple | Very Unhealthy |
| 5 | Maroon | Hazardous |
2020-09-21 01:58:32 +02:00
## Full Example
airquality.things:
```java
2021-11-09 08:59:13 +01:00
Bridge airquality:api:main "Bridge" [apiKey="xxxyyyzzz"] {
2022-01-20 15:19:15 +01:00
station home "Krakow"[location="50.06465,19.94498", refresh=60]
2021-11-09 08:59:13 +01:00
}
2020-09-21 01:58:32 +02:00
```
airquality.items:
```java
Group AirQuality < flow >
2022-01-20 15:19:15 +01:00
Number Aqi_Level "Air Quality Index" < flow > (AirQuality) { channel="airquality:station:main:home:aqi#index" }
Number Aqi_Pm25 "PM\u2082\u2085 Level" < line > (AirQuality) { channel="airquality:station:main:home:pm25#value" }
Number Aqi_Pm10 "PM\u2081\u2080 Level" < line > (AirQuality) { channel="airquality:station:main:home:pm10#value" }
Number Aqi_O3 "O\u2083 Level" < line > (AirQuality) { channel="airquality:station:main:home:o3#value" }
Number Aqi_No2 "NO\u2082 Level" < line > (AirQuality) { channel="airquality:station:main:home:no2#value" }
Number Aqi_Co "CO Level" < line > (AirQuality) { channel="airquality:station:main:home:co#value" }
Number Aqi_So2 "SO\u2082 Level" < line > (AirQuality) { channel="airquality:station:main:home:so2#value" }
2020-09-21 01:58:32 +02:00
2022-01-20 15:19:15 +01:00
DateTime Aqi_ObservationTime "Time of observation [%1$tH:%1$tM]" < clock > (AirQuality) { channel="airquality:station:main:home:aqi#timestamp" }
2020-09-21 01:58:32 +02:00
2022-01-20 15:19:15 +01:00
Number:Temperature Aqi_Temperature "Temperature" < temperature > (AirQuality) { channel="airquality:station:main:home:weather#temperature" }
Number:Pressure Aqi_Pressure "Pressure" < pressure > (AirQuality) { channel="airquality:station:main:home:weather#pressure" }
Number:Dimensionless Aqi_Humidity "Humidity" < humidity > (AirQuality) { channel="airquality:station:main:home:weather#humidity" }
2020-09-21 01:58:32 +02:00
```
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",
2021-11-09 08:59:13 +01:00
=="UNHEALTHY_FSG"="#ff9933",
2020-09-21 01:58:32 +02:00
=="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_ObservationTime
Text item=Aqi_Temperature
Text item=Aqi_Pressure
Text item=Aqi_Humidity
}
}
```
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"
2021-11-09 08:59:13 +01:00
case "UNHEALTHY_FSG":
2020-09-21 01:58:32 +02:00
hsb = "30,80,100"
case "MODERATE":
hsb = "50,80,100"
case "GOOD":
hsb = "160,100,60"
}
Lamp_Color.sendCommand(hsb)
end
```
