Skip to content

Commit 51a95df

Browse files
cliniqueclinique
committed
Written documentation and reviewed channels descriptions
Signed-off-by: Gaël L'hopital <[email protected]>
1 parent b7c1a72 commit 51a95df

25 files changed

+339
-89
lines changed

‎bundles/org.openhab.binding.airparif/README.md

Lines changed: 145 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,168 @@
11
# AirParif Binding
22

3-
_Give some details about what this binding is meant for - a protocol, system, specific device._
4-
5-
_If possible, provide some resources like pictures (only PNG is supported currently), a video, etc. to give an impression of what can be done with this binding._
6-
_You can place such resources into a `doc` folder next to this README.md._
7-
8-
_Put each sentence in a separate line to improve readability of diffs._
3+
This binding uses the [AirParif service](https://www.airparif.fr/) for providing air quality information for Paris and departments of the Ile-de-France.
4+
To use it, you first need to [register and get your API key](https://www.airparif.fr/interface-de-programmation-applicative).
5+
You'll receive your API Key by mail.
96

107
## Supported Things
118

12-
_Please describe the different supported things / devices including their ThingTypeUID within this section._
13-
_Which different types are supported, which models were tested etc.?_
14-
_Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
9+
- `api`: bridge used to connect to the AirParif service. Provides some general informations for the whole area.
10+
- `location`: Presents the pollen and air quality information for a given location.
1511

16-
- `bridge`: Short description of the Bridge, if any
17-
- `sample`: Short description of the Thing with the ThingTypeUID `sample`
12+
Of course, you can add multiple `location`s, e.g. for gathering pollen or air quality data for different locations.
1813

1914
## Discovery
2015

21-
_Describe the available auto-discovery features here._
22-
_Mention for what it works and what needs to be kept in mind when using it._
23-
24-
## Binding Configuration
25-
26-
_If your binding requires or supports general configuration settings, please create a folder ```cfg``` and place the configuration file ```<bindingId>.cfg``` inside it._
27-
_In this section, you should link to this file and provide some information about the options._
28-
_The file could e.g. look like:_
29-
30-
```
31-
# Configuration for the AirParif Binding
32-
#
33-
# Default secret key for the pairing of the AirParif Thing.
34-
# It has to be between 10-40 (alphanumeric) characters.
35-
# This may be changed by the user for security reasons.
36-
secret=openHABSecret
37-
```
38-
39-
_Note that it is planned to generate some part of this based on the information that is available within ```src/main/resources/OH-INF/binding``` of your binding._
40-
41-
_If your binding does not offer any generic configurations, you can remove this section completely._
16+
Once your `api` bridge is created and configured with the API Key, a default `location` can be auto-discovered based on system location.
17+
It will be configured with the system location and detected department.
4218

4319
## Thing Configuration
4420

45-
_Describe what is needed to manually configure a thing, either through the UI or via a thing-file._
46-
_This should be mainly about its mandatory and optional configuration parameters._
47-
48-
_Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
49-
50-
### `sample` Thing Configuration
21+
### `api` Thing Configuration
5122

52-
| Name | Type | Description | Default | Required | Advanced |
53-
|-----------------|---------|---------------------------------------|---------|----------|----------|
54-
| hostname | text | Hostname or IP address of the device | N/A | yes | no |
55-
| password | text | Password to access the device | N/A | yes | no |
56-
| refreshInterval | integer | Interval the device is polled in sec. | 600 | no | yes |
23+
| Name | Type | Description | Default | Required | Advanced |
24+
|-----------------|---------|-----------------------------------|---------|----------|----------|
25+
| apikey | text | Token used to access the service | N/A | yes | no |
5726

58-
## Channels
59-
60-
_Here you should provide information about available channel types, what their meaning is and how they can be used._
61-
62-
_Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
27+
### `location` Thing Configuration
6328

64-
| Channel | Type | Read/Write | Description |
65-
|---------|--------|------------|-----------------------------|
66-
| control | Switch | RW | This is the control channel |
29+
| Name | Type | Description | Default | Required | Advanced |
30+
|-----------------|---------|--------------------------------------------------------------------------------|---------|----------|----------|
31+
| location | text | Geo coordinates to be considered (as <latitude>,<longitude>[,<altitude in m>]) | N/A | yes | no |
32+
| department | text | Code of the department (two digits) (*) | N/A | yes | no |
6733

68-
## Full Example
34+
(*) When auto-discovered, the department will be pre-filled based on the location and bounding limits defined in the internal department database.
35+
Please check that proposed value is correct according to the place.
6936

70-
_Provide a full usage example based on textual configuration files._
71-
_*.things, *.items examples are mandatory as textual configuration is well used by many users._
72-
_*.sitemap examples are optional._
73-
74-
### Thing Configuration
37+
## Channels
7538

76-
```java
77-
Example thing configuration goes here.
39+
### `api` Thing Channels
40+
41+
| Group | Channel | Type | Read/Write | Description |
42+
|----------------------|----------------|----------------|------------|----------------------------------------------|
43+
| pollens | comment | String | R | Current pollens situation |
44+
| pollens | begin-validity | DateTime | R | Bulletin validity start |
45+
| pollens | end-validity | DateTime | R | Bulletin validity end |
46+
| aq-bulletin | comment | String | R | General message for the air quality bulletin |
47+
| aq-bulletin | no2-min | Number:Density | R | Minimum level of NO2 concentration |
48+
| aq-bulletin | no2-max | Number:Density | R | Maximum level of NO2 concentration |
49+
| aq-bulletin | o3-min | Number:Density | R | Minimum level of O3 concentration |
50+
| aq-bulletin | o3-max | Number:Density | R | Maximum level of O3 concentration |
51+
| aq-bulletin | pm10-min | Number:Density | R | Minimum level of PM 10 concentration |
52+
| aq-bulletin | pm10-max | Number:Density | R | Maximum level of PM 10 concentration |
53+
| aq-bulletin | pm25-min | Number:Density | R | Minimum level of PM 2.5 concentration |
54+
| aq-bulletin | pm25-max | Number:Density | R | Maximum level of PM 2.5 concentration |
55+
| aq-bulletin-tomorrow | comment | String | R | General message for the air quality bulletin |
56+
| aq-bulletin-tomorrow | no2-min | Number:Density | R | Minimum level of NO2 concentration |
57+
| aq-bulletin-tomorrow | no2-max | Number:Density | R | Maximum level of NO2 concentration |
58+
| aq-bulletin-tomorrow | o3-min | Number:Density | R | Minimum level of O3 concentration |
59+
| aq-bulletin-tomorrow | o3-max | Number:Density | R | Maximum level of O3 concentration |
60+
| aq-bulletin-tomorrow | pm10-min | Number:Density | R | Minimum level of PM 10 concentration |
61+
| aq-bulletin-tomorrow | pm10-max | Number:Density | R | Maximum level of PM 10 concentration |
62+
| aq-bulletin-tomorrow | pm25-min | Number:Density | R | Minimum level of PM 2.5 concentration |
63+
| aq-bulletin-tomorrow | pm25-max | Number:Density | R | Maximum level of PM 2.5 concentration |
64+
| daily | message | String | R | Today's daily general information ||| daily | tomorrow | String | R | Tomorrow's daily general information |
65+
66+
### `location` Thing Channels
67+
68+
| Group | Channel | Type | Read/Write | Description |
69+
|---------|------------|----------------|------------|----------------------------------------------------------|
70+
| pollens | cypress | Number | R | Alert level associated to this taxon (*) |
71+
| pollens | hazel | Number | R | Alert level associated to this taxon (*) |
72+
| pollens | alder | Number | R | Alert level associated to this taxon (*) |
73+
| pollens | poplar | Number | R | Alert level associated to this taxon (*) |
74+
| pollens | willow | Number | R | Alert level associated to this taxon (*) |
75+
| pollens | ash | Number | R | Alert level associated to this taxon (*) |
76+
| pollens | hornbeam | Number | R | Alert level associated to this taxon (*) |
77+
| pollens | birch | Number | R | Alert level associated to this taxon (*) |
78+
| pollens | plane | Number | R | Alert level associated to this taxon (*) |
79+
| pollens | oak | Number | R | Alert level associated to this taxon (*) |
80+
| pollens | olive | Number | R | Alert level associated to this taxon (*) |
81+
| pollens | linden | Number | R | Alert level associated to this taxon (*) |
82+
| pollens | chestnut | Number | R | Alert level associated to this taxon (*) |
83+
| pollens | rumex | Number | R | Alert level associated to this taxon (*) |
84+
| pollens | grasses | Number | R | Alert level associated to this taxon (*) |
85+
| pollens | plantain | Number | R | Alert level associated to this taxon (*) |
86+
| pollens | urticaceae | Number | R | Alert level associated to this taxon (*) |
87+
| pollens | wormwood | Number | R | Alert level associated to this taxon (*) |
88+
| pollens | ragweed | Number | R | Alert level associated to this taxon (*) |
89+
| indice | message | String | R | Alert message associated to the value of the index |
90+
| indice | timestamp | DateTime | R | Timestamp of the evaluation |
91+
| indice | alert | Number | R | ATMO Index associated to highest pollutant concentration |
92+
| o3 | message | String | R | Polllutant concentration alert message |
93+
| o3 | value | Number:Density | R | Concentration of the given pollutant |
94+
| o3 | alert | Number | R | Alert Level associated to pollutant concentration (**) |
95+
| no2 | message | String | R | Polllutant concentration alert message |
96+
| no2 | value | Number:Density | R | Concentration of the given pollutant |
97+
| no2 | alert | Number | R | Alert Level associated to pollutant concentration (**) |
98+
| pm25 | message | String | R | Polllutant concentration alert message |
99+
| pm25 | value | Number:Density | R | Concentration of the given pollutant |
100+
| pm25 | alert | Number | R | Alert Level associated to pollutant concentration (**) |
101+
| pm10 | message | String | R | Polllutant concentration alert message |
102+
| pm10 | value | Number:Density | R | Concentration of the given pollutant |
103+
| pm10 | alert | Number | R | Alert Level associated to pollutant concentration (**) |
104+
105+
(*) Each pollen alert level has an associated color and description:
106+
107+
| Code | Color | Description |
108+
|------|--------|-----------------------|
109+
| 0 | Green | No allergic risk |
110+
| 1 | Yellow | Low allergic risk |
111+
| 2 | Orange | Average allergic risk |
112+
| 3 | Red | High allergic risk |
113+
114+
(*) Each pollutant concentration is associated to an alert level (and an icon) :
115+
116+
| Code | Description |
117+
|------|---------------|
118+
| 0 | Good |
119+
| 1 | Average |
120+
| 2 | Degrated |
121+
| 3 | Bad |
122+
| 4 | Very Bad |
123+
| 5 | Extremely Bad |
124+
125+
## Provided icon set
126+
127+
This binding has its own IconProvider and makes available the following list of icons
128+
129+
| Icon Name | Dynamic | Illustration |
130+
|------------------------|---------|--------------|
131+
| oh:airparif:aq | Yes | ![](doc/images/aq.svg) |
132+
| oh:airparif:alder | Yes | ![](doc/images/alder.svg) |
133+
| oh:airparif:ash | Yes | ![](doc/images/ash.svg) |
134+
| oh:airparif:birch | Yes | ![](doc/images/birch.svg) |
135+
| oh:airparif:chestnut | Yes | ![](doc/images/chestnut.svg) |
136+
| oh:airparif:cypress | Yes | ![](doc/images/cypress.svg) |
137+
| oh:airparif:grasses | Yes | ![](doc/images/grasses.svg) |
138+
| oh:airparif:hazel | Yes | ![](doc/images/hazel.svg) |
139+
| oh:airparif:hornbeam | Yes | ![](doc/images/hornbeam.svg) |
140+
| oh:airparif:linden | Yes | ![](doc/images/linden.svg) |
141+
| oh:airparif:oak | Yes | ![](doc/images/oak.svg) |
142+
| oh:airparif:olive | Yes | ![](doc/images/olive.svg) |
143+
| oh:airparif:plane | Yes | ![](doc/images/plane.svg) |
144+
| oh:airparif:plantain | Yes | ![](doc/images/plantain.svg) |
145+
| oh:airparif:pollen | Yes | ![](doc/images/pollen.svg) |
146+
| oh:airparif:poplar | Yes | ![](doc/images/poplar.svg) |
147+
| oh:airparif:ragweed | Yes | ![](doc/images/ragweed.svg) |
148+
| oh:airparif:rumex | Yes | ![](doc/images/rumex.svg) |
149+
| oh:airparif:urticaceae | Yes | ![](doc/images/urticaceae.svg) |
150+
| oh:airparif:willow | Yes | ![](doc/images/willow.svg) |
151+
| oh:airparif:wormwood | Yes | ![](doc/images/wormwood.svg) |
152+
153+
154+
## Full Examplee
155+
156+
### Thing Configurationn
157+
158+
```jav
159+
Bridge airparif:api:local "AirParif" [ apikey="xxxxx-dddd-cccc-4321-zzzzzzzzzzzzz" ] {
160+
location yvelines "Yvelines" [ department="78", location="52.639,1.8284" ]
161+
}a
78162
```
79-
### Item Configuration
163+
### Item Configurationn
80164

81165
```java
82166
Example item configuration goes here.
83-
```
84-
85-
### Sitemap Configuration
86-
87-
```perl
88-
Optional Sitemap configuration goes here.
89-
Remove this section, if not needed.
90-
```
91-
92-
## Any custom content here!
167+
``
93168

94-
_Feel free to add additional sections for whatever you think should also be mentioned about your binding!_

0 commit comments

Comments
 (0)