light docs added

grimmpp · Mar 20, 2024 · 12d4442 · 12d4442
1 parent 704c7c3
commit 12d4442
Show file tree

Hide file tree

Showing 16 changed files with 82 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -38,7 +38,7 @@ Elatko devices are exemplarily mentioned. You can find [here](https://www.eltako
   * A5-12-03 (Automated meter reading - water, F3Z14D)
   * A5-13-01 (Weather station, FWG14)
   * F6-10-00 (Window handle, FTS14EM)
-* Light
+* [Light](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/lights-tutorial/readme.md)
   * A5-38-08 (Dimmable Light: Central command - gateway, FUD14)
   * M5-38-08 (Switchable Light: Eltako relay, FSR14)
 * Switch
@@ -48,16 +48,17 @@ Elatko devices are exemplarily mentioned. You can find [here](https://www.eltako
   * G5-3F-7F (Eltako cover, FSB14)
 
 **Supported sender EEPs**
-* Light
+* [Light](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/lights-tutorial/readme.md)
   * A5-38-08 (Central command - gateway, FUD14) PREFERRED!!!
   * F6-02-01 and F6-02-02 (Rocker switch - function 02 'direct  pushbutton top on' default left) / (only as switch not for dimmable lights.)
-* [Switch](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/rocker_switch/readme.md)
+* Switch
   * A5-38-08 (Central command) PREFERRED!!!
   * F6-02-01 and F6-02-02 (Rocker switch - function 02 'direct  pushbutton top on' default left)
 * Cover
   * H5-3F-7F (Eltako cover, FSB14)
 * [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)
+* [Teach-In Buttons](https://github.com/grimmpp/home-assistant-eltako/tree/main/docs/docs/teach_in_buttons/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)) 

diff --git a/changes.md b/changes.md
@@ -1,6 +1,6 @@
 # Changes and Feature List
 
-## Version 1.3.9 
+## Version 1.4.0 ESP3 Support (USB300)
 * Docs about gateway usage added.
 * Added EEPs F6-02-01 and F6-02-02 as sender EEP for lights so that regular switch commands can be sent from Home Assistant.
 * Change default behavior of switches and lights to 'direct pushbutton top on' and 'left rocker' for sender EEP F6-02-01/-02

diff --git a/custom_components/eltako/button.py b/custom_components/eltako/button.py
@@ -88,7 +88,7 @@ def __init__(self, platform: str, gateway: EnOceanGateway, dev_id: AddressExpres
             _dev_name = "teach-in-button"
         self.entity_description = ButtonEntityDescription(
             key="teach_in_button",
-            name="Teach-In Button"+sender_id.plain_address().hex(),
+            name="Teach-In Button",
             icon="mdi:button-pointer",
             device_class=ButtonDeviceClass.UPDATE,
         )

diff --git a/docs/gateway_usage/readme.md b/docs/gateway_usage/readme.md
@@ -36,7 +36,7 @@ eltako:
         eep: M5-38-08
         name: "FSR14_4x - 1"
         sender:
-          id: 00-00-B1-01
+          id: 00-00-B0-01
           eep: A5-38-08
 ```
 

diff --git a/docs/gateways/readme.md b/docs/gateways/readme.md
@@ -218,7 +218,7 @@ eltako:
         sender:
           id: FF-80-80-01       # baseId of USB300 (FF-80-80-00) + sender id (0-80 HEX/128 DEZ)
           eep: A5-38-08
-
+```
 
 ### 'FTD14 - RS485 bus telegram duplicator'
 Other possible gateway 
diff --git a/docs/lights-tutorial/fsr14x4.jpg b/docs/lights-tutorial/fsr14x4.jpg
diff --git a/docs/lights-tutorial/fsr61.jpg b/docs/lights-tutorial/fsr61.jpg
diff --git a/docs/lights-tutorial/fud14.jpg b/docs/lights-tutorial/fud14.jpg
diff --git a/docs/lights-tutorial/readme.md b/docs/lights-tutorial/readme.md
@@ -0,0 +1,52 @@
+# Lights in Home Assistant Eltako Integration
+
+This tutorial describes how to configure a light so that its status updates will be displayed in Home Assistant and so that you can control it out of Home Assistant.
+
+<img src="screenshot_HA_fud14.png" width="50%">
+
+## Configure Home Assistant (Eltako FSR14*, FUD14*, FSR61*, ...)
+
+Every Eltako devices which shall be represented in Home Assistant needs to be entered into the Home Assistant configuration (`/config/configuration.yaml`). Find details about how to configure Home Assistant for this integration manually [here](../update_home_assistant_configuration.md). You can also auto-generate the confuguration by using [EnOcean Device Manager (eo_man)](https://github.com/grimmpp/enocean-device-manager)
+
+For lights you need to create an entries in the light section. You need to specify the id/address of the device so that Home Assistant knows when a status update/change comes by that it needs to react on it. In addition we need to specify the address of the sender button in Home Assistant. A good pattern for the sender id/address is to use a base id + the same local id of the light. EEPs define the type of telegram. In case of light and series 14 devices I wouldn't change this behavior.
+
+
+The configuration could look like the following for USB300 as a gateway.
+```
+eltako:
+  gateway:
+  - id: 1
+    device_type: enocean-usb300
+    base_id: FF-80-80-00        # baseId of USB300 gateway
+    devices:
+      light:
+      - id: FF-AA-00-01         # baseId of FAM14 (FF-AA-00-00) + internal address
+        eep: M5-38-08
+        name: FSR14_4x - 1
+        sender:
+          id: FF-80-80-01       # baseId of USB300 (FF-80-80-00) + sender id (0-80 HEX/128 DEZ)
+          eep: A5-38-08
+```
+
+In case of being directly connected via cable the use a local address space (baseId = 00-00-00-00):
+```
+eltako:
+  gateway:
+  - id: 1
+    device_type: fgw14usb
+    base_id: FF-AA-00-00        # baseId of FAM14 (because this is the device connected to wireless network)
+    devices:
+      light:
+      - id: 00-00-00-01         # usage of local address (baseId = 00-00-00-00)
+        eep: M5-38-08
+        name: "FSR14_4x - 1"
+        sender:
+          id: 00-00-B0-01       # base address for Home Assistant (e.g. 00-00-B0-01) + sender id (0-80 HEX/128 DEZ)
+          eep: A5-38-08
+```
+
+
+## Register Home Assistant Address in Actuators 
+
+In the section before we made Home Assistant aware of what devices to be represented and on which telegram to react. Now, we need to tell the light to react on commands coming from Home Assistant. 
+How to program devices (teach-in switches) you can find in the tutorial [Teach-In Buttons](../teach_in_buttons/readme.md).
diff --git a/docs/lights-tutorial/screenshot_HA_fud14.png b/docs/lights-tutorial/screenshot_HA_fud14.png
diff --git a/docs/multiple-gateway-support/readme.md b/docs/multiple-gateway-support/readme.md
@@ -29,7 +29,7 @@ eltako:
         eep: M5-38-08
         name: "FSR14_4x - 1"
         sender:
-          id: 00-00-B1-01
+          id: 00-00-B0-01
           eep: A5-38-08
 
   - id: 2

diff --git a/docs/rocker_switch/readme.md b/docs/rocker_switch/readme.md
@@ -128,7 +128,7 @@ eltako:
         name: "Relay Test"
         eep: "M5-38-08"
         sender:
-          id: "00-00-B1-01"
+          id: "00-00-B0-01"
           eep: "A5-38-08"
       binary_sensor:
       - id: "FE-DB-DA-04"  # taster 1
@@ -142,7 +142,7 @@ logger:
     eltako: debug
 ```
 
-In this example the sender id ``00-00-B1-01`` for the light must be registered in the corresponding relay e.g. via [Eltako Software PCT14](https://www.eltako.com/en/software-pct14/). Don't forget to choose function type ``51`` for software controlled command.
+In this example the sender id ``00-00-B0-01`` for the light must be registered in the corresponding relay e.g. via [Eltako Software PCT14](https://www.eltako.com/en/software-pct14/). Don't forget to choose function type ``51`` for software controlled command.
 
 Code for detecting the switch and firing the event can be found in function ``value_changed`` in [binary_sensor.py](/eltako/binary_sensor.py).
 
diff --git a/docs/teach_in_buttons/readme.md b/docs/teach_in_buttons/readme.md
@@ -0,0 +1,17 @@
+# Teach-In Buttons
+
+<img src="screenshot_teach_in_button.png" width="25%" />
+
+Teach-In buttons are used to program the actuators so that they react on sensors or switches. 
+When we want to power on and off a light by using Home Assistant we need to tell the actuator that it needs to react on a specific button in Home Assistant. Every button in Home Assistant has its own id/address and sends telegrams either onto the bus or into wireless network. The actuators are listening for telegrams and if they corresponding address is programmed in / teached in for this button they react will on there telegrams.
+
+# Teach-In Progress
+1. Most of the time you need to turon on the rotary switch of a device and bring it into learning mode. Usually the devices start to blink. (You should check the specific behavior of the devices in their manual.)
+2. While the device is blinking you need to push the Teach-In Button in Home Assistant to program the device for this Home Assistant functionality. 
+3. The device stops with blinking and you can turn back the rotary switches, into a position which tells the device what function to perform. 
+
+# Better Alternative to Teach-In Bus Devices
+In case of teach-in/programming bus devices I recommend to use either [EnOcean Device Manager (eo_man)](https://github.com/grimmpp/enocean-device-manager) which can enter all address by just pushing one button or [PCT14 from Eltako](https://www.eltako.com/en/software-pct14/) which allows you to manage the memory entries of the devices via a nice application. 
+
+# Limitation
+If you are connected via wire to the bus e.g. with FAM14 or FGW14-USB you can only reach the devices directly mounted on the bus. If you want to teach-in other wireless devices or devices mounted on a different bus you need to use either a traceiver (e.g. FAM-USB or USB300) or you can use a telegram duplicater (e.g. FTD14). 
diff --git a/docs/teach_in_buttons/screenshot_teach_in_button.png b/docs/teach_in_buttons/screenshot_teach_in_button.png
diff --git a/tests/test_config.py b/tests/test_config.py
@@ -197,7 +197,7 @@ def test_device_config3_1(self):
         eep: M5-38-08
         name: "FSR14_4x - 1"
         sender:
-          id: 00-00-B1-01
+          id: 00-00-B0-01
           eep: A5-38-08
 
   - id: 2

diff --git a/tests/test_gateway.py b/tests/test_gateway.py
@@ -52,7 +52,7 @@ def test_gateway_creation(self):
         eep: M5-38-08
         name: "FSR14_4x - 1"
         sender:
-          id: 00-00-B1-01
+          id: 00-00-B0-01
           eep: A5-38-08
 
   - id: 2