Merge pull request #80 from grimmpp/feature-branch

docs updated

README.md

@@ -53,14 +53,14 @@ Elatko devices are exemplarily mentioned. You can find [here](https://www.eltako
   * F6-02-01 (Rocker switch)
 * Cover
   * H5-3F-7F (Eltako cover, FSB14)
-* [Climate](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/heating-and-cooling/readme.md) (**Experimental** - Not properly test. Interaction and synchronization of temperature controllers may change.)
+* [Climate](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/heating-and-cooling/readme.md) (**Experimental** Feedback is welcome.)
   * A5-10-06 (Eltako FAE14, FHK14, F4HK14, F2L14, FHK61, FME14)
 
-[**Gateway**](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/gateways/readme.md) (See also [multiple gateway support](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/multiple-gateway-support/readme.md))
+[**Gateway**](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/gateways/readme.md) (See also [how to use gateways](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/gateway_usage/readme.md) and [multiple gateway support](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/multiple-gateway-support/readme.md))
   * **Eltako FAM14** and Eltako **FGW14-USB** (based on ESP2, rs485 bus and baud rate 57600, uses library [eltako14bus](https://github.com/grimmpp/eltako14bus)) 
   * **Eltako FAM-USB** (based on ESP2, baud rate 9600, uses library [eltako14bus](https://github.com/grimmpp/eltako14bus)) 
-  * **EnOcean USB300** (**NOT YET IMPLEMENTED**) (based on ESP3 and baud rate 57600, uses library [Python EnOcean](https://github.com/kipe/enocean))
-    * Library is integrated and USB300 can be configured. Message conversion from ESP3 to ESp2 and back is not yet implemented. This means this dongle is not yet working.
+  * **EnOcean USB300** (**experimental**) (based on ESP3 and baud rate 57600, uses library [Python EnOcean](https://github.com/kipe/enocean))
+    * ESP3 is not yet fully supported.
 
 
 # Installation and Configuration

changes.md

@@ -1,14 +1,17 @@
 # Changes and Feature List
 
-## Version 1.3.8
+## Version 1.3.9 
+* Docs about gateway usage added.
+
+## Version 1.3.8 Fixes and Smaller Imrovements
 * Fixed window handle F6-10-00 in binary sensor
 * Added better tests for binary sensors
 * Fixed covers which behaved differently after introducing recovery state feature.
 * Added additional values (battery voltage, illumination, temperature) for A5-08-01 as sensor
 * Occupancy Sensor of A5-08-01 added as binary sensor
-* Improved ESP3 adapter for USB300 support. Sending telegrams works now but actuators are not accepting commands for e.g. lights - EEP: A5-38-08
+* Improved ESP3 adapter for USB300 support. Sending telegrams works now but actuators are not accepting commands for e.g. lights - EEP: A5-38-08 😥
 * Teach-In buttons for lights, covers, and climate are available.
-* Static 'Event Id' of switches (EEP: F6-02-01 and F6-02-02) added.
+* Static 'Event Id' of switches (EEP: F6-02-01 and F6-02-02) is displayed on entity page.
 * Docs about how to use logging added.
 * Updated docs about how to trigger automations with wall-mounted switches.
 

custom_components/eltako/manifest.json

@@ -10,5 +10,5 @@
   "issue_tracker": "https://github.com/grimmpp/home-assistant-eltako/issues",
   "loggers": ["eltako"],
   "requirements": ["eltako14bus==0.0.47","enocean==0.60.1", "StrEnum"],
-  "version": "1.3.8" 
+  "version": "1.3.9" 
 }

docs/gateway_usage/readme.md

@@ -0,0 +1,63 @@
+# Usage of Gatways
+
+Hints: 
+* Have you checked out the different gatewys and their characteristics? [Supported Gateways](../gateways/readme.md)
+* Have you checked out the support for multiple gateways at the same time? [Multiple Gateway Support](../multiple-gateway-support/readme.md)
+
+## How to configure gateways
+
+In order to use a gateway you need to declare the gateway and all devices which shall interact with it in the Home Assistant Configuration (`/config/configuration.yaml`). The configuration can be e.g. edit with [File Editor](https://github.com/home-assistant/addons/tree/master/configurator).
+
+To get familiar with the Eltako Integration configuration check out [Update Home Assistant Configuration](../update_home_assistant_configuration.md).
+
+## Gateway Attributes
+| Attribute   | Type / Values   | Description |
+| :---        | :---        | :---        |
+| `id` | Number | Unique arbritary number to identify the gateway. |
+| `device_type` | fam14, fgw14usb, fam-usb, enocean-usb300 | The device type defines the gateway model. Base on this information other information is derived. Supported values can be found in [const.py](../../custom_components/eltako/const.py) Supported gateways are described [here](../gateways/readme.md). |
+| `base_id` | enocean address format | Gateways can obviously receive and send messages. To send messages they use a hardcoded range of 128 addresses. The base_id is the first address of this range. Base_ids are used to identify the source of a message and to validate the configuration. |
+| `devices` | configuration | Devices grouped by Home Assistant platform types. All devices which are listed here will be represented by this device. Device listed more than one in different devices will be recognized as two independent devices. |
+
+
+### Example Configuration
+```
+eltako:
+  general_settings:
+    fast_status_change: False
+    show_dev_id_in_dev_name: True
+
+  gateway:
+  - id: 1
+    device_type: fgw14usb
+    base_id: FF-AA-00-00
+    devices:
+      light:
+      - id: 00-00-00-01
+        eep: M5-38-08
+        name: "FSR14_4x - 1"
+        sender:
+          id: 00-00-B1-01
+          eep: A5-38-08
+```
+
+## Gateway Features
+
+* Gateways are a bridge between Home Assistant and the devices by receiving and sending messages.
+* Gateways are connected via USB to the Home Assistant box. They use the protocol ESP2 or ESP3 based on serial communication. This serial commuinication can automatically reconnected in case of hiccups.
+
+
+## Gateway Reprentation in Home Assistant
+
+The following information is mainly used for debugging purposes and statistics.
+
+| Entity   | Type | Description |
+| :---        | :---        | :---        |
+| `Reconnect Gateway` | Push Button | To trigger reconnection manually for testing. Reconnection actaully happens automatically  |
+| `ID` | Label | Shows the base id of the gateway. |
+| `Connected` | Binary State | Shows if the serial connection (USB) is established. |
+| `Last Message Received` | Timestamp | Shows time passed since last message received. |
+| `Received Messages per Session` | Counter | Counts messages for current connection. (Hint: There is a history for every sensor.) |
+| `Serial Path` | Label | Shows the USB port/path to which the gateway is connected. |
+| `USB Protocol` | Label | Shows the protocol for serial connection. |
+
+<img src="screenshot-gateway-representation.png" height="400" />

docs/update_home_assistant_configuration.md

@@ -1,9 +1,10 @@
 # Update Home Assistant Configuration
 
 Before you can start and see your devices and sensors in Home Assistant you need to enter them unfortunately manually into the Home Assistant Configuration ``/config/configuration.yaml``. 
-You can edit the configuration file e.g. with the add-on [File Editor](https://github.com/home-assistant/addons/tree/master/configurator). In this repository the is also a script which can read all devices mounted on the eltako bus.
+You can edit the configuration file e.g. with the add-on [File Editor](https://github.com/home-assistant/addons/tree/master/configurator). 
+In order to get supported by creating the configuration and managing your devices you can use [Enocean Device Manager (eo_man)](https://github.com/grimmpp/enocean-device-manager).
 
-After you have finished the configuration changes **don't forget to restart Home Assistant so that the changes will be applied.** You can trigger the restart in the menu of File Editor.
+After you have finished the configuration changes **don't forget to restart Home Assistant so that the changes will be applied.** Hint: You can trigger the restart in the menu of File Editor.
 
 ## Schema of the configuration file:
 If the documentation might be outdated and not complete you can always find the truth in [schema.py](../custom_components/eltako/schema.py).