Add home assistant integration (#66)

* add home assistant integration * add remaining HA entities * update documentation & fix typos * typos * add conditional checks for `HOME_ASSISTANT_ENABLED` * add correct version to mqtt * fix a few typos in `install-software.md` * Update install-software.md
mwood77 · Oct 8, 2024 · 4422787 · 4422787
1 parent b2d59a8
commit 4422787
Show file tree

Hide file tree

Showing 7 changed files with 576 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -8,11 +8,10 @@
   </h2>
 </div>
 
-<div align="center">
-  <a href="https://www.youtube.com/watch?v=BJKpY6Zp8BI" target="_blank"><strong>👉 See Winderoo in action on youtube 👈</strong></a>
-  <br>
-  <br>
-  <img src="./docs/images/splash-image.jpg" alt="Winderoo - The Open Source Watch Winder" width="600">
+<div align="center"> 
+  <a href="https://www.youtube.com/watch?v=BJKpY6Zp8BI" target="_blank">
+    <img src="./docs/images/winderoo-splash.png" alt="Winderoo - The Open Source Watch Winder" width="600">
+  </a>
   <br>
   <br>
   <p>
@@ -36,7 +35,7 @@
 * Simple setup. Flash the firmware and File System with a few clicks, then connect your phone (or other device) to the winder's setup wifi network & add it to your home network.
 * There's no app required! You control it from a web browser.
 * Minimal electronics / programming experience required
-* Web UI is fully tranlated into 5 langauges (more are welcome!)
+* Web UI is fully translated into 5 languages (more are welcome!)
 
 
 ### Winderoo Requires a Different Microcontroller
@@ -52,7 +51,7 @@
 #### Download and install the following on your computer:
 1. [Visual Studio Code](https://code.visualstudio.com/)
 1. [PlatformIO](https://platformio.org/install/ide?install=vscode)
-    - Note: the "extensions" button has changed since Platformio has created their install guide. You can access the extions pane with the following key combinations:
+    - Note: the "extensions" button has changed since Platformio has created their install guide. You can access the extensions pane with the following key combinations:
         - Windows: Ctrl+Shift+X
         - macOS: Command+Shift+X
 1. You may or may not need these drivers, but some 'knock off' ESP32 dev boards require them.
@@ -70,12 +69,12 @@
 This project welcomes contributions. Please follow the regular git workflow; fork + PR to contribute.
 
 ### Translations / Localization
-Winderoo has multi-language support, and we welcome adding more langauges.
+Winderoo has multi-language support, and we welcome adding more languages.
 
 To add another language:
 1. Duplicate one of the current localizations, and translate the text:
     - `src/angular/osww-frontend/src/assets/i18n/` stores the current localizations.
-1. Add a new langauge menu item here to enable your langauge:
+1. Add a new language menu item here to enable your language:
     - `src/angular/osww-frontend/src/app/header/header.component.html`
 1. Open a Pull Request
 

diff --git a/docs/images/home-assistant-gui.png b/docs/images/home-assistant-gui.png
diff --git a/docs/images/winderoo-splash.png b/docs/images/winderoo-splash.png
diff --git a/docs/install-software.md b/docs/install-software.md
@@ -21,20 +21,32 @@
     - If you downloaded the repository as a zip, uzip it before proceeding to step 2.
     <div align="center"><img src="images/download_directory.png" alt="how to download"></div>
 1. Open the extracted folder (or cloned repository if using git) in Visual Studio Code
-1. **Build Options - IMPORTANT**
-    -  if you're building Winderoo with an OLED screen or you desire fine-grained motor control (pulse width modulation), you must enable one (or two) build flags to tell PlatformIO to include additional libraries.
+1. **Build Options - (PWM, OLED, Home Assistant)**
+    -  if you're building Winderoo with an OLED screen, intend to use Home Assistant, or you desire fine-grained motor control (pulse width modulation), you must enable some of the following build flags to tell PlatformIO to include additional libraries.
     - To toggle these build flags, navigate to the file called `platformio.ini`:
             <div align="center"><img src="images/platformio-ini.png" alt="how to download"></div>
         - In this file, you'll see the following block of code:
             ```yml
             build_flags =
                 -D OLED_ENABLED=false
                 -D PWM_MOTOR_CONTROL=false
+                -D HOME_ASSISTANT_ENABLED=false
             ```
+            - Change `-D HOME_ASSISTANT_ENABLED=false` to `-D HOME_ASSISTANT_ENABLED=true` to enable Winderoo's Home Assistant integration
+                - > 🚦 I'd strongly recommend you have a dedicated MQTT user; do not use your main account.
+
+                - If this feature is enabled, you must add your Home Assistant's IP, username, and password.
+                    - You can add them in [`main.cpp`](https://github.com/mwood77/winderoo/blob/main/src/platformio/osww-server/src/main.cpp#L51-L54) inside the configuration block:
+                    ```cpp
+                    // Home Assistant Configuration
+                    const char* HOME_ASSISTANT_BROKER_IP = "YOUR_HOME_ASSISTANT_IP";
+                    const char* HOME_ASSISTANT_USERNAME = "REPLACE_THIS_WITH_HOME_ASSISTANT_LOGIN_USERNAME";
+                    const char* HOME_ASSISTANT_PASSWORD = "REPLACE_THIS_WITH_HOME_ASSISTANT_LOGIN_PASSWORD";
+                    ```
             - Change `-D OLED_ENABLED=false` to `-D OLED_ENABLED=true` to enable OLED screen support
             - Change `-D PWM_MOTOR_CONTROL=false` to `-D PWM_MOTOR_CONTROL=true` to enable PWM motor control; at the time of writing, Winderoo with PWM only supports `MX1508` derived motor controllers.
-                - > PWM_MOTOR_CONTROL is an experimental flag. You will encounter incorrect cycle time estimation and other possible bugs unless you align the motor speed to **20 RPM** (see [Troubleshooting](#troubleshooting)). Use at your own risk.
-    - PlatformIO will now compile Winderoo with OLED screen and or PWM motor support
+                - > `PWM_MOTOR_CONTROL` is an experimental flag. You will encounter incorrect cycle time estimation and other possible bugs unless you align the motor speed to **20 RPM** (see [Troubleshooting](#troubleshooting)). Use at your own risk.
+    - PlatformIO will now compile Winderoo with OLED screen, Home Assistant, and or PWM motor support
 1. Select 'PlatformIO' (alien/insect looking button) on the workspace menu and wait for visual studio code to finish initializing the project
     <div align="center"><img src="images/platformIO.png" alt="platformIO button"></div>
 1. Expand the main heading: **"esp32doit-devkit-v1"**:
@@ -48,7 +60,7 @@
 1. If you have a different LED state, compare it with this table:
     - [Understanding Winderoo's LED Blink Status](user-manual.md#understanding-winderoos-led-blink-status)
 
-## Next steps:
+## Next steps
 
 Ok, you've got 2 LEDs illuminated on your board. Great! Let's make sure the code works.
 
@@ -64,6 +76,68 @@ Ok, you've got 2 LEDs illuminated on your board. Great! Let's make sure the code
 1. If you see Winderoo's user interface, you're all done!
     - [Here is an overview of Winderoo's user interface](./user-manual.md)
 
+### Home Assistant
+If you've enabled Winderoo's Home Assistant integration, Winderoo will stream a number of entities into Home Assistant over MQTT. If you're unsure what MQTT or need to set this up in Home Assistant, [please see this document](https://www.home-assistant.io/integrations/mqtt).
+
+Winderoo should be automatically discovered by Home Assistant within 60 seconds. The following entities are available to Home Assistant:
+```yml
+ -  button.winderoo_start
+ -  button.winderoo_stop
+
+ -  sensor.winderoo_status            : "Winding | Stopped"
+ -  sensor.winderoo_wifi_reception    : "Excellent | Good | Fair | Poor"
+
+ -  number.winderoo_rotations_per_day : 100 <-> 960 
+
+ -  select.winderoo_direction         : "CCW | BOTH | CW"
+ -  select.winderoo_hour              : 00 <-> 23
+ -  select.winderoo_minutes           : 00 <-> 50
+
+ -  switch.winderoo_timer_enabled     : "true | false"
+ -  switch.winderoo_oled              : "true | false"
+ -  switch.winderoo_power             : "true | false"
+```
+
+You can replicate Winderoo's GUI with a basic Home Assistant card:
+<table align="center">
+  <tr>
+    <th>Home Assistant GUI</th>
+    <th>Code</th>
+  </tr>
+  <tr>
+    <td>
+        <img src="./images/home-assistant-gui.png" alt="Winderoo - The Open Source Watch Winder" width="300">
+    </td>
+    <td>
+<pre><code>
+type: entities
+entities:
+- entity: sensor.winderoo_status
+- entity: number.winderoo_rotations_per_day
+    name: Rotations Per Day
+- entity: select.winderoo_direction
+    name: Direction
+- entity: button.winderoo_start
+    name: Start
+- entity: button.winderoo_stop
+    name: Stop
+- entity: switch.winderoo_timer_enabled
+    name: Timer Enabled
+- entity: select.winderoo_hour
+    name: Hour
+- entity: select.winderoo_minutes
+    name: Minutes
+- entity: switch.winderoo_oled
+    name: OLED
+- entity: switch.winderoo_power
+    name: Power
+title: Winderoo
+show_header_toggle: false
+</pre></code>
+    </td>
+  </tr>
+</table>
+
 ## Troubleshooting
 ### Motor Turns too fast when using PWM
 > [!WARNING]

diff --git a/docs/user-manual.md b/docs/user-manual.md
@@ -17,7 +17,7 @@
 ### Reset / Change WiFi Network
 | UI Element | Function |
 | :---: |:---: |
-|<img src="gui/reset.png" >  | This is will open a pop-up window, which will ask you to confirm reset, and walk you through the reset proceedure. Use this to change the WiFi network Winderoo connects to. |
+|<img src="gui/reset.png" >  | This is will open a pop-up window, which will ask you to confirm reset, and walk you through the reset procedure. Use this to change the WiFi network Winderoo connects to. |
 |<img src="gui/language.png" >  | This will open a pop-up menu where you can select which language you'd prefer. |
 
 ### Status Bar
@@ -57,7 +57,7 @@
 | UI Element | Function |
 | :---: |:---: |
 |<img src="gui/cycle-start-time-toggle.png" >  | This will enable or disable the winder's timer. When the switch is set to **ENABLED**, Winderoo will begin winding at a your desired 'Cycle Start Time.' If the switch is set to **DISABLED**, you must start the winder using the [control buttons](#control-buttons) |
-|<img src="gui/cycle-start-time.png" >  | Set which time you'd like Winderoo to begin winding at. **_Important!_** WInderoo will _always_ start at this time, even if you've already triggered a manual run with a [control button](#control-buttons). To stop this behaviour, see: [Enable / Disable Winding](#enable--disable-winding) |
+|<img src="gui/cycle-start-time.png" >  | Set which time you'd like Winderoo to begin winding at. **_Important!_** Winderoo will _always_ start at this time, even if you've already triggered a manual run with a [control button](#control-buttons). To stop this behavior, see: [Enable / Disable Winding](#enable--disable-winding) |
 
 ### OLED Screen
 
@@ -72,13 +72,13 @@
 ### Save / Update Settings
 | UI Element | Function |
 | :---: |:---: |
-|<img src="gui/save-button.png" >  | This will capture and save all settings (winding direction, rotations per day, cycle start time). If a winding routine is currenty running, it does not reset the current routine (it will update and finish accordingly). If you wish to make sure the routine is changed, manually stop, then start the routine. See [control buttons](#control-buttons). |
+|<img src="gui/save-button.png" >  | This will capture and save all settings (winding direction, rotations per day, cycle start time). If a winding routine is currently running, it does not reset the current routine (it will update and finish accordingly). If you wish to make sure the routine is changed, manually stop, then start the routine. See [control buttons](#control-buttons). |
 
 
 ## Understanding Winderoo's LED Blink Status
 
 - Most ESP32 dev boards have a primary RED LED that is always on. This cannot be shut off via firmware. 
-    - If you find it bothersome, you can cover it with electrical tape, de-solder it, or cut the trace with an exacto knife.
+    - If you find it bothersome, you can cover it with electrical tape, de-solder it, or cut the trace with an x-acto knife.
 
 - Most ESP32 dev boards have a secondary BLUE LED, however some may be a different colour. 
     - Please use the following table to understand what Winderoo is telling you.
@@ -90,4 +90,4 @@
 | <img src="images/led_states/blue_on.png" height="300">  | secondary LED is illuminated  | Winderoo is ready for setup. Connect to the WiFi network called "Winderoo Setup" and add Winderoo to your WiFi network. |
 | <img src="images/led_states/Winderoo_slow_blink.gif" height="300">   | slow blinking | Winderoo has successfully connected to your WiFi network. When the the **BLUE LED** stops blinking, you may access Winderoo's UI from your web browser. |
 | <img src="images/led_states/Winderoo_fast_blink.gif" height="300"> | fast blinking | Winderoo is resetting, wait until the **BLUE LED** turns solid to begin WiFi setup. |
-| <img src="images/led_states/Winderoo_snooze.gif" height="300">  | extremely slow blinking | Winderoo's winding capabilities have been turned 'OFF' via the software swtich, or an optional physical button. Winderoo will not wind until it has been turned to 'ON.' |
+| <img src="images/led_states/Winderoo_snooze.gif" height="300">  | extremely slow blinking | Winderoo's winding capabilities have been turned 'OFF' via the software switch, or an optional physical button. Winderoo will not wind until it has been turned to 'ON.' |
diff --git a/platformio.ini b/platformio.ini
@@ -23,6 +23,7 @@ check_tool = cppcheck, clangtidy
 build_flags = 
 	-D OLED_ENABLED=false
 	-D PWM_MOTOR_CONTROL=false
+	-D HOME_ASSISTANT_ENABLED=false
 check_flags = 
 	clangtidy: -fix-errors,--format-style=google
 lib_deps = 
@@ -34,3 +35,4 @@ lib_deps =
 	fbiego/ESP32Time@^2.0.0
 	adafruit/Adafruit SSD1306@^2.5.9
 	electromagus/ESPMX1508@^1.0.5
+	dawidchyrzynski/home-assistant-integration@^2.1.0