Provided documentation and added requirements.txt

README.md

@@ -1,2 +1,104 @@
-# dwd_pollen
-Home Assistant component to retrieve Pollen data from DWD (Germany)
+# DWD pollen sensor for Home Assistant
+
+[Home Assistant](https://www.home-assistant.io) component to retrieve Pollen data from the DWD (Deutscher Wetterdienst, 
+Germany)
+
+
+## Installation
+
+1. Either checkout this repository using `git clone [email protected]:marcschumacher/dwd_pollen.git` or download a specifc 
+   version from the [release page](https://github.com/marcschumacher/dwd_pollen/releases).
+2. Copy the created folder `dwd_pollen` to your configuration folder under `<config>/custom_components/`.
+3. Install the required dependencies using pip3. `cd` to the `dwd_pollen` folder and execute the following command:
+   ```
+   pip3 install -r requirements.txt
+   ```
+4. Now you are done. Proceed with configuring the component.
+
+
+## Configuration
+
+To be able to use this component, add the following configuration to your `configuration.yaml`:
+```
+sensor:
+  - platform: dwd_pollen
+    partregion_ids:
+      - 41
+      - 42
+    include_pollen:
+      - birke
+      - erle
+    include_days:
+      - today
+```
+
+Here is a description of the values possible:
+
+Parameter      | Default values | Possible values                                                                                                                                  | Description                                                | 
+---------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|
+partregion_ids | no default     | [API description](https://opendata.dwd.de/climate_environment/health/alerts/Beschreibung_pollen_s31fg.pdf) (search for partregion_id in the PDF) | Region for which the date shall be retrieved.              |
+include_pollen | all possible   | `birke`, `graeser`, `esche`, `erle`, `hasel`, `beifuss`, `ambrosia`, `roggen`                                                                    | List of pollens to retrieve and provide information about. |
+include_days   | all possible   | `today`, `tomorrow`, `dayafter_tomorrow`                                                                                                         | Days to include                                            |
+
+
+## Sensors
+
+Per default every 15 minutes new values are retrieved from the DWD.
+
+Two groups of sensors are created: value sensor that contain the actual values and statistical sensors which return the 
+average, maximum and minimum values calculated over all specified pollen types.
+
+### Value sensors
+
+The value sensors have the following format: `sensor.dwd_pollen_<partregion_id>_<day>_<pollen type>`, e.g. 
+`sensor.dwd_pollen_41_today_ambrosia`.
+
+The value of this sensor is an integer between `0-6`. Basically the values are normalized from the input values 
+delivered by DWD to make it easier to calculate with it. The following table describes which values are what:
+
+DWD | Sensor | Meaning (in German)
+----|--------|-------------------------------
+0   | 0      | keine Belastung
+0-1 | 1      | keine bis geringe Belastung
+1   | 2      | geringe Belastung
+1-2 | 3      | geringe bis mittlere Belastung
+2   | 4      | mittlere Belastung
+2-3 | 5      | mittlere bis hohe Belastung
+3   | 6      | hohe Belastung
+
+The following attributes are provided (default attributes excluded):
+
+Attribute           | Example                     | Description 
+--------------------|-----------------------------|-------------------------------------------------------------------------
+attribution         | Data provided by DWD        | Data provider (currently fixed value)
+last_updated        | 2019-05-16T11:00:00         | Time when the provided information was updated by the DWD
+region_name         | Nordrhein-Westfalen         | Region name
+partregion_name     | Rhein.-Westfäl. Tiefland    | Subregion name
+original_value      | 0-1                         | Original value retrieved from DWD (see table above)
+description         | keine bis geringe Belastung | Human readable text (in German) describing the severity of the pollution 
+
+### Statistical sensors
+
+Statistical sensors have the following format: `sensor.dwd_pollen_<partregion id>_<day>_<stat type>`, e.g. 
+`sensor.dwd_pollen_41_today_avg`.
+
+Statistics are always calculated using the values for a specific day for the specified pollen types. Following types 
+are supported:
+
+Type | Description
+-----|------------
+min  | Minimum
+max  | Maximum
+avg  | Average
+
+Be aware that the average value might not be an integer, but a floating value.
+
+The following attributes are provided (default attributes excluded):
+
+Attribute           | Example                     | Description 
+--------------------|-----------------------------|-------------------------------------------------------------------------
+attribution         | Data provided by DWD        | Data provider (currently fixed value)
+last_updated        | 2019-05-16T11:00:00         | Time when the provided information was updated by the DWD
+region_name         | Nordrhein-Westfalen         | Region name
+partregion_name     | Rhein.-Westfäl. Tiefland    | Subregion name
+description         | keine bis geringe Belastung | Human readable text (in German) describing the severity of the pollution 

__init__.py

@@ -0,0 +1 @@
+"""DWD Pollen sensor"""

requirements.txt

@@ -0,0 +1 @@
+voluptuous==0.11.5