Version 1.0

Upgraded to .NET 8 MQTT Managed Client Blind support
marcselis · Mar 3, 2024 · 31da6cb · 31da6cb
1 parent dfdd92d
commit 31da6cb
Show file tree

Hide file tree

Showing 75 changed files with 678 additions and 659 deletions.
diff --git a/README.md b/README.md
@@ -32,7 +32,9 @@ can be linked in 1- or 2-key mode:
 
 ### How to talk 'Easywave' using a computer?
 
-Eldat produces the [RX09 USB Transceiver](https://www.eldat.de/produkte/schnittstellen/rx09e_en.html). This USB stick emulates a serial port that a computer program can use to listen to Easywave traffic. By sending commands to the serial port, you can instruct the USB stick to send Easywave messages, but only using a limited number of addresses (0 to 64/128, depending on the stick model), requiring you to (also) link the transceiver to the receivers you want to control.
+Eldat produces the [RX09 USB Transceiver](https://www.eldat.de/produkte/schnittstellen/rx09e_en.html). This USB stick emulates a serial port that a computer program can use to listen to Easywave traffic. By sending commands to the serial port, you can instruct the USB stick to send Easywave messages, but only using a limited number of addresses (0 to 64/128, depending on the stick model), requiring you to (also) link the transceiver to the receivers you want to control.  This device is supported by the Linux kernel and Windows drivers are available as well.
+
+Niko sells the [USB RF interface for Niko Home Control](https://www.niko.eu/en/products/niko-home-control/products-on-bus-wiring/usb-rf-interface-for-niko-home-control-productmodel-niko-4f394869-c7ef-531b-ba63-5387f88d384a), but unfortunately that is not supported by the Linux kernel, nor are there any Windows drivers available.   The USB stick in that bundle seems an exact copy of the Eldat stick and I'm pretty sure it should be possible to get it to work in Linux by modifying the Eldat driver code to also recognize the USB device ID of the Niko stick.  If you really want to go that way [this StackExchange thread](https://raspberrypi.stackexchange.com/questions/78908/eldat-easywave-usbserial-device-not-detected-on-raspberrypi-3) might point you in the right direction, but don't look at me for help.
 
 ### Issues with the Easywave protocol & devices
 
@@ -43,18 +45,18 @@ In contrast to other protocols (like [Zigbee](https://en.wikipedia.org/wiki/Zigb
 - A typical Easywave wireless switch, like the [Niko 41-00001](https://www.niko.eu/en/products/wireless-controls/wireless-switch-with-two-buttons-productmodel-niko-fbacd5f6-94fc-5ce9-af7c-7394469b12c0) will send 2 to 4 repeated messages when a user presses a button.  This makes it difficult to predict in what state a receiver that is linked in 1-button mode will be after processing these messages, when looking at the messages being sent.  As a consequence, the current version does not support receivers in 1-button mode.
 - These repeated messages makes it also hard to detect a button being held and double- & tripple pressed. The addon tries to handle this with 2 settings.
   - **EasywaveRepeatTimeout**: any message received for the same button within this time (in milliseconds) is considered a repeated message and is ignored.  If the same message continues to be received after this timeout, the button is considered to be 'held'.
-  - **EasywaveActionTimeout**: number of milliseconds to wait until a button action is considered complete. 'Press' messages received within this time are considered to be repeated presses by the user.
+  - **EasywaveActionTimeout**: number of milliseconds to wait until a button action is considered complete. 'Press' messages received within this time are considered to be repeated presses by the user.  This gives this addon a nice feature: it can report double & triple presses on buttons, making it possible to trigger multiple types of actions in Home Assistant with one single button :smiley:.
 
 ## Architecture
 
 ![Easywave2MQTT Architecture](./Architecture.png)
 
 This program has 4 main parts:
 
-- A **Easyweave service** that takes care of the Easywave communication using the [RX09 USB Transceiver](https://www.eldat.de/produkte/schnittstellen/rx09e_en.html).
+- A **Easyweave service** that takes care of the Easywave communication using the serial port that the Easywave USB stick exposes.
 - A **Messaging service** that takes care of communication over MQTT.
 - Some **Worker service** that communicates with the other 2 services to detect what is happening in the Easywave world and 
-  communicating it with [Home Assistant](https://www.home-assistant.io/) and vice-versa.
+  communicating it to MQTT and vice-versa.
 - Communication between these services is done through a custom-built and very rudimentary in-memory [message bus](./src/Tools/Bus.cs).
 
 ## Getting started
@@ -83,7 +85,7 @@ So, for now, the only way to do it, is to manually alter the contents of the `ap
 ### Debugging
 
 - Check that you have the following tools available:
-  - [.NET 7.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/7.0)
+  - [.NET 8.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
   - A code editor, like [Visual Studio Code](https://code.visualstudio.com/) or [Visual Studio](https://visualstudio.microsoft.com/), if you want to make changes.
 - Attach the [RX09 USB Transceiver](https://www.eldat.de/produkte/schnittstellen/rx09e_en.html) to your developer PC and make sure you have the drivers installed (can be downloaded from the page in the link).
   - Update the contents of the `appsettings.json` file.  See the [Configuration Section](#configuration) for more information.
@@ -135,25 +137,27 @@ The `Devices` section is too complicated to configure through the Addon configur
                                  //A/B = on/off on left-hand side when using a normal light switch cover.
                                  //C/D = on/off on right-hand side when using a normal light switch cover.
                                  //Niko also has special covers with 4 independent buttons.
+                                 //There are also Easywave remotes available with 3 to 8 buttons.  If you have one of
+                                 //those, you can use these as well, but be sure to add a character for each of them.
   }
   ```
 
 - **Optional**: Declare the receivers and the transmitter buttons you have them linked to.  Doing so will allow these receivers and their current state to be synchronized to Home Assistant.  
   If you want to make it possible to control your receivers from Home Assistant, you'll need to manually link them to an RX09 message and add that message as a subscription with `CanSend: "true"`.
 
-  A receiver is the actual device that switches the light.  Its configuration looks as follows:
+  A receiver is the actual device that responds to transmitters.  This plug-in currently supports `Light` & `Blind` devices.  Its configuration looks as follows:
 
    ``` json
   {
     "Id": "ktchn1",              //the unique ID of the receivers.  You can choose this yourself.
-    "Type": "Light",             //fixed value
+    "Type": "Light",             //declare this receiver as a Light in Home Assistant.
     "Name": "Kitchen light",     //name that you want to see displayed in Home Assistant.
     "Area": "Kitchen",           //the Home Assistant area where the receiver is located
      "Subscriptions": [          
-        {                        //the transmitter buttons that you have manually linked to the receiver
+        {                        //the transmitter button that you have manually linked to the receiver
           "Address": "2274e4",   //this is needed to make Home Assistant reflect the state of the device
-          "KeyCode": "C"         //when one of these buttons is pressed
-        },
+          "KeyCode": "C"         //when one of these buttons is pressed.  You only need to mention the button you used
+        },                       //when linking the transmitter with the receiver.  The other buttons are infered.
         {
           "Address": "22a4c1",   //addresses mentioned here should be declared as Transmitter device first!
           "KeyCode": "A"

diff --git a/addon/Easywave2MQTT/CHANGELOG.md b/addon/Easywave2MQTT/CHANGELOG.md
@@ -2,13 +2,14 @@
 
 |Version|Changes|
 |-------|-------|
-| 0.1 alpha | First version.|
-| 0.2 alpha | First public version.|
-| 0.3 beta | Automatically add all serial devices to addon container.<br/>Added configuration options for serial device, mqtt & log level.<br/>Switched to SeriLog for logging.<br/>Switched to .NET 7.0.<br/>Added test project to simulate a local Eldat RX09 device. This project requires on the [com0com Null-modem emulator](https://files.akeo.ie/blog/com0com.7z) and an MQTT server where the Easywave2Mqtt process is connected to.|
-| 0.4 beta | Simplified addon building & startup: <br/>- addon binaries & config file are directly editable in app subfolder, making it easier for non-developers to alter the configuration and to deploy the addon in Home Assistant.<br/>- options are directly read from data subfolder (if available).<br/>Lowered logging level for a few `MessagingService` messages that were logged twice, but in a different way. |
-| 0.5 beta | Allow addon to start when no serial ports are found, or when a non-existing port was specified |
-| 0.5.2 beta | Fix crash when serialport is throwing IOException for a timeout, instead of a TimeoutException |
-| 0.5.3 beta | Fix bug in detection mechanism for button repeats |
-| 0.6 | Automatically reconnect to MQTT server when connection breaks<br/>Persist state of lights in MQTT|
-| 0.7.0 | First try to add support for blinds |
+| 1.0.0 | Upgrade to .NET 8.<br/>Log declaration of Lights & Blinds<br/>Switch to managed MQTT client that automatically reconnects. |
 | 0.7.1 | Fix blind states |
+| 0.7.0 | First try to add support for blinds |
+| 0.6 | Automatically reconnect to MQTT server when connection breaks<br/>Persist state of lights in MQTT|
+| 0.5.3 beta | Fix bug in detection mechanism for button repeats |
+| 0.5.2 beta | Fix crash when serialport is throwing IOException for a timeout, instead of a TimeoutException |
+| 0.5 beta | Allow addon to start when no serial ports are found, or when a non-existing port was specified |
+| 0.4 beta | Simplified addon building & startup: <br/>- addon binaries & config file are directly editable in app subfolder, making it easier for non-developers to alter the configuration and to deploy the addon in Home Assistant.<br/>- options are directly read from data subfolder (if available).<br/>Lowered logging level for a few `MessagingService` messages that were logged twice, but in a different way. |
+| 0.3 beta | Automatically add all serial devices to addon container.<br/>Added configuration options for serial device, mqtt & log level.<br/>Switched to SeriLog for logging.<br/>Switched to .NET 7.0.<br/>Added test project to simulate a local Eldat RX09 device. This project requires on the [com0com Null-modem emulator](https://files.akeo.ie/blog/com0com.7z) and an MQTT server where the Easywave2Mqtt process is connected to.|
+| 0.2 alpha | First public version.|
+| 0.1 alpha | First version.|
diff --git a/addon/Easywave2MQTT/Dockerfile b/addon/Easywave2MQTT/Dockerfile
@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/dotnet/runtime:7.0
+FROM mcr.microsoft.com/dotnet/runtime:8.0
 # Copy add-on binaries
 ADD app /app
 # Switch to app folder

diff --git a/addon/Easywave2MQTT/README.md b/addon/Easywave2MQTT/README.md
@@ -6,7 +6,7 @@
 
 You can use this add-on to add support for Easywave devices in Home Assistant.  Easywave is a proprietary protocol for wireless devices, developed by [Niko](https://niko.eu) & [Eldat](https://www.eldat.de/).
 
-This add-on requires the presence of an [RX09 USB Transceiver](https://www.eldat.de/produkte/schnittstellen/rx09e_en.html) in the machine.  Niko USB sticks could work too, **if they are recognized by the OS**.
+This add-on requires the presence of an [RX09 USB Transceiver](https://www.eldat.de/produkte/schnittstellen/rx09e_en.html) in the machine.  Niko USB sticks will probably work too, **provided they are recognized by the OS**.
 
 **This project is still in beta phase, but is usable after some manual tweaking.**