mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-10 15:11:59 +01:00
211 lines
8.4 KiB
Markdown
211 lines
8.4 KiB
Markdown
# 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
|
|
|
|
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.
|
|
|
|
## Discovery
|
|
|
|
Local Air Quality can be autodiscovered based on system location.
|
|
You will created a Bridge with your apiKey.
|
|
|
|
## Bridge Configuration
|
|
|
|
The bridge configuration only holds the api key :
|
|
|
|
| Parameter | Description |
|
|
|-----------|-------------------------------------------------------------------------|
|
|
| apiKey | Data-platform token to access the AQIcn.org service. Mandatory. |
|
|
|
|
## Thing Configuration
|
|
|
|
The 'Station' thing has a few configuration parameters:
|
|
|
|
| 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:
|
|
`https://api.waqi.info/search/?token=TOKEN&keyword=NAME`, replacing TOKEN by your apiKey and NAME by the station you are looking for.
|
|
|
|
### 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
|
|
|
|
## Channels
|
|
|
|
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
|
|
|
|
| Channel ID | Item Type | Description |
|
|
|-----------------|----------------------|----------------------------------------------|
|
|
| temperature | Number:Temperature | Temperature in Celsius degrees |
|
|
| pressure | Number:Pressure | Pressure level |
|
|
| humidity | Number:Dimensionless | Humidity level |
|
|
| 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 |
|
|
|
|
(*) The alert level is described by a color :
|
|
|
|
| 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 |
|
|
|
|
## Full Example
|
|
|
|
airquality.things:
|
|
|
|
```java
|
|
Bridge airquality:api:main "Bridge" [apiKey="xxxyyyzzz"] {
|
|
station home "Krakow"[location="50.06465,19.94498", refresh=60]
|
|
}
|
|
```
|
|
|
|
airquality.items:
|
|
|
|
```java
|
|
Group AirQuality <flow>
|
|
|
|
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" }
|
|
|
|
DateTime Aqi_ObservationTime "Time of observation [%1$tH:%1$tM]" <clock> (AirQuality) { channel="airquality:station:main:home:aqi#timestamp" }
|
|
|
|
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" }
|
|
```
|
|
|
|
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_FSG"="#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_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"
|
|
case "UNHEALTHY_FSG":
|
|
hsb = "30,80,100"
|
|
case "MODERATE":
|
|
hsb = "50,80,100"
|
|
case "GOOD":
|
|
hsb = "160,100,60"
|
|
}
|
|
|
|
Lamp_Color.sendCommand(hsb)
|
|
end
|
|
```
|