Enables Thermostat type accessory to Turn Off and Turn On #605 (#608

) * Update TOC * Clean up gh-md-toc * Updates to #605, adds new setting thermostatTurnOn, and adds UI menu support * Update Dependencies --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: banboobee <[email protected]>
NorthernMan54 · Mar 21, 2024 · 9e6318d · 9e6318d
1 parent 87e3f8c
commit 9e6318d
Show file tree

Hide file tree

Showing 28 changed files with 14,646 additions and 4,533 deletions.
diff --git a/.github/workflows/Build and Publish.yml b/.github/workflows/Build and Publish.yml
@@ -52,7 +52,7 @@ jobs:
         persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal access token.
         fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
 
-    - uses: actions/setup-node@v3
+    - uses: actions/setup-node@v4
       with:
         node-version: lts/*
 
@@ -64,13 +64,14 @@ jobs:
     - name: Create Table of Contents
       run: |
         npm run-script document
+        rm gh-md-toc
 
     - name: Commit files
       run: |
         git config --local user.email "github-actions[bot]@users.noreply.github.com"
         git config --local user.name "github-actions[bot]"
         git add *
-        git commit -a -m "Update TOC"
+        git commit -a -m "Update TOC" || true
 
     - name: Push changes
       uses: ad-m/github-push-action@master
@@ -115,4 +116,4 @@ jobs:
         name: Release ${{ needs.publish_prod_release.outputs.NPM_VERSION }}
         generate_release_notes: true
         draft: false
-        prerelease: false
+        prerelease: false
diff --git a/.gitignore b/.gitignore
@@ -11,3 +11,5 @@ Troubleshooting.md.orig.*
 alexaDiscovery.json
 tools/after.json
 tools/output.txt
+
+gh-md-toc
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file. This project uses [Semantic Versioning](https://semver.org/).
 
+## 0.6.9 (2023-03-30)
+
+## [Version 0.6.9](https://github.com/northernman54/homebridge-alexa/compare/v0.6.8...v0.6.9)
+
+#### Changes
+
+- Enables Thermostat type accessory to `Turn Off` and `Turn On` #605 ( Tks @banboobee ).  To preserve existing functionality the inital / default behaviour for the `Turn on Thermostat` command is to return an error message `That command does not work on device` unless the new optional config setting `Thermostat Turn On Behaviour` is set.
+- Minor style updates to Config Menu
+- Updates to package dependencies
+
 ## 0.6.8 (2023-12-13)
 
 ## [Version 0.6.8](https://github.com/northernman54/homebridge-alexa/compare/v0.6.7...v0.6.8)

diff --git a/Installation.md b/Installation.md
@@ -27,6 +27,7 @@ Installation and Configuration of Homebridge Alexa
          * [refresh - Accessory Cache Refresh Interval](#refresh---accessory-cache-refresh-interval)
          * [filter - Homebridge Instance Filter](#filter---homebridge-instance-filter)
          * [mergeServiceName - Alternate device naming](#mergeservicename---alternate-device-naming)
+         * [thermostatTurnOn - Thermostat Turn On Behaviour](#thermostatturnon---thermostat-turn-on-behaviour)
          * [blind](#blind)
          * [door](#door)
       * [Speaker Settings](#speaker-settings)
@@ -39,10 +40,6 @@ Installation and Configuration of Homebridge Alexa
    * [Initial Testing and confirming configuration](#initial-testing-and-confirming-configuration)
    * [Enable Homebridge smarthome skill and link accounts](#enable-homebridge-smarthome-skill-and-link-accounts)
    * [Discover Devices](#discover-devices)
-
-<!-- Created by https://github.com/ekalinin/github-markdown-toc -->
-<!-- Added by: runner, at: Wed Dec 13 14:31:10 UTC 2023 -->
-
 <!--te-->
 
 # Setup Instructions
@@ -322,6 +319,25 @@ sudo npm install -g homebridge-alexa
 ],
 ```  
 
+#### thermostatTurnOn - Thermostat Turn On Behaviour
+  - Set Thermostat `Turn On` Behaviour to either Heat, Cool or Auto when Alexa is asked to turn on a Thermostat. Defaults to `That command does not work on device`.
+
+Heat - 1
+Cool - 2
+Auto - 3
+
+```
+"platforms": [
+  {
+    "platform": "Alexa",
+    "name": "Alexa",
+    "username": "....",
+    "password": "....",
+    "thermostatTurnOn": 2
+  }
+],
+```
+
 #### blind
   - Enables natural wording for opening and closing blinds, and window coverings.  Not supported in all countries.  Defaults to false
 

diff --git a/README.md b/README.md
@@ -2,11 +2,11 @@
 
 [![NPM Downloads](https://img.shields.io/npm/dm/homebridge-alexa.svg?style=flat)](https://npmjs.org/package/homebridge-alexa)
 
-<p align="center">
-    <img src="docs/homebridge.png" height="200">
-</p>
+<h1><p align="center">
+    <img src="docs/README_Image.001.jpeg" width="80%" style="vertical-align:middle">
+</p></h1>
 
-Enable Amazon Alexa to control your homebridge smart home devices and accessories.  Please note, that this does **NOT** bring Alexa enabled devices into homebridge, for this please try [homebridge-alexa-smarthome](https://github.com/joeyhage/homebridge-alexa-smarthome).  Full support for all Amazon Alexa devices, including the echo 2nd Generation and software based solutions.  Uses an Amazon smart home skill based approach for integration between HomeBridge and Amazon Alexa.
+Enable Amazon Alexa to control your homebridge smart home devices and accessories.  Please note, that this does **NOT** bring Alexa enabled devices into homebridge, for this please try [homebridge-alexa-smarthome](https://github.com/joeyhage/homebridge-alexa-smarthome).
 
 # Note to users of the service
 
@@ -60,6 +60,7 @@ Country availability - The plugin is available in these countries, English (AU),
       * [Garage Door With blind = true ( Not supported in all countries )](#garage-door-with-blind--true--not-supported-in-all-countries-)
       * [Window coverings / blinds With blind = true ( Not supported in all countries )](#window-coverings--blinds-with-blind--true--not-supported-in-all-countries-)
    * [Thermostat's and Heater / Cooler's](#thermostats-and-heater--coolers)
+      * [For Thermostat's only](#for-thermostats-only)
    * [Lock / Unlock Doors](#lock--unlock-doors)
    * [Temperature sensors](#temperature-sensors)
    * [AppleTV ( homebridge-apple-tv or homebridge-apple-tv-remote )](#appletv--homebridge-apple-tv-or-homebridge-apple-tv-remote-)
@@ -82,10 +83,6 @@ Country availability - The plugin is available in these countries, English (AU),
       * [Homebridge Accessory Dump](#homebridge-accessory-dump)
 * [Roadmap](#roadmap)
 * [Credits](#credits)
-
-<!-- Created by https://github.com/ekalinin/github-markdown-toc -->
-<!-- Added by: runner, at: Wed Dec 13 14:31:09 UTC 2023 -->
-
 <!--te-->
 
 # Supported devices
@@ -217,6 +214,13 @@ See [example](https://github.com/NorthernMan54/homebridge-alexa/wiki/Garage-Door
 * Alexa, set thermostat to 20
 * Alexa, set thermostat to heat/cool/automatic/off
 
+### For Thermostat's only
+
+* Alexa, turn off thermostat
+* Alexa, turn on thermostat
+
+The `Turn On` thermostat behaviour is configured in the Optional Setting config menu under `Thermostat Turn On Behaviour`, and unless this is configured `Turn On` is disabled, and alexa will respond with `That command does not work on device`.
+
 Adamo Maisano provided a deeper [comparison](https://github.com/NorthernMan54/homebridge-alexa/wiki/Thermostat-Voice-Control-Comparison) of Thermostat Voice Control [here](https://github.com/NorthernMan54/homebridge-alexa/wiki/Thermostat-Voice-Control-Comparison).
 
 ## Lock / Unlock Doors

diff --git a/Troubleshooting.md b/Troubleshooting.md
@@ -3,7 +3,7 @@
 <!--ts-->
 * [Initial Setup](#initial-setup)
    * [[Alexa] ERROR: ( homebridge-alexa) Login to homebridge.ca failed, please validate your credentials in config.json and restart homebridge.](#alexa-error--homebridge-alexa-login-to-homebridgeca-failed-please-validate-your-credentials-in-configjson-and-restart-homebridge)
-      * [- Bad login or password in your config.json for <a href="https://www.homebridge.ca" rel="nofollow">https://www.homebridge.ca</a>](#--bad-login-or-password-in-your-configjson-for-httpswwwhomebridgeca)
+      * [- Bad login or password in your config.json for <a href="https://www.homebridge.ca" rel="nofollow">https://www.homebridge.ca</a>](https://www.homebridge.ca)
    * [[Alexa] ERROR: ( homebridge-alexa) You have an issue with your installation, please review the README.](#alexa-error--homebridge-alexa-you-have-an-issue-with-your-installation-please-review-the-readme)
       * [- Cloud Server DDOS Protection has blocked your IP address](#--cloud-server-ddos-protection-has-blocked-your-ip-address)
       * [- Multiple copies of homebridge-alexa on your network](#--multiple-copies-of-homebridge-alexa-on-your-network)
@@ -32,14 +32,11 @@
       * [Unsuccessful event message ( No event gateway token )](#unsuccessful-event-message--no-event-gateway-token-)
       * [Successful event message being sent to Alexa](#successful-event-message-being-sent-to-alexa)
    * [[Alexa] ERROR:  Event gateway token refresh error: 400](#alexa-error--event-gateway-token-refresh-error-400)
-
-<!-- Created by https://github.com/ekalinin/github-markdown-toc -->
-<!-- Added by: runner, at: Wed Dec 13 14:31:10 UTC 2023 -->
-
 <!--te-->
 
 # Initial Setup
 
+
 ## [Alexa] ERROR: ( homebridge-alexa) Login to homebridge.ca failed, please validate your credentials in config.json and restart homebridge.
 
 ### - Bad login or password in your config.json for https://www.homebridge.ca

diff --git a/config.schema.json b/config.schema.json
@@ -2,66 +2,76 @@
   "pluginAlias": "Alexa",
   "pluginType": "platform",
   "singular": true,
-  "headerDisplay": "<h1><p align='center'>Allow your Amazon Alexa to control your homebridge devices</H1></p><h1><p align='center'> <img width='18%' src='https://user-images.githubusercontent.com/19808920/210089307-7622bb91-49d0-4d90-b2c3-31118e1a76c0.png'><b> => </b><img width='20%' src='https://user-images.githubusercontent.com/19808920/210090318-9e8ddc2a-a025-40ac-9718-7b5a2aa9a518.png'></p></h1> <br>To setup the service:<br>1 - First <b>create</b> an account on <a href='https://www.homebridge.ca/'>https://www.homebridge.ca/</a>.  <br>2 - Then <b>enter</b> the username and password for your account <b>below</b>.  <br>3 - <b>Save</b> the settings and <b>restart</b> homebridge.  <br>4 - In the Amazon Alexa Application on your smart phone, <b>search</b> for the Homebridge Skill and enable it.  When you enable the skill, it will take you to the <b>https://www.homebridge.ca/</b> website to <b>enable</b> and link the skill to the plugin.  <br>5 - You can now ask Alexa to <b>`discover devices`</b> and it should discover your homebridge devices.<br><br>Detailed setup instructions are available <a href='https://github.com/NorthernMan54/homebridge-alexa/blob/master/Installation.md#setup-instructions'>here</a>.",
+  "headerDisplay": "<h1><p align='center'>Allow your Amazon Alexa to control your homebridge devices</H1></p><h1><p align='center'><img src='https://raw.githubusercontent.com/NorthernMan54/homebridge-alexa/main/docs/README_Image.001.jpeg' width='80%' style='vertical-align:middle'></p></h1> <br><b>To setup the service:</b><br><br>1 - First <b>create</b> an account on <a href='https://www.homebridge.ca/'>https://www.homebridge.ca/</a>.  <br>2 - Then <b>enter</b> the username and password for your account <b>below</b>.  <br>3 - <b>Save</b> the settings and <b>restart</b> homebridge.  <br>4 - In the Amazon Alexa Application on your smart phone, <b>search</b> for the Homebridge Skill and enable it.  When you enable the skill, it will take you to the <b>https://www.homebridge.ca/</b> website to <b>enable</b> and link the skill to the plugin.  <br>5 - You can now ask Alexa to <b>`discover devices`</b> and it should discover your homebridge devices.<br><br>Detailed setup instructions are available <a href='https://github.com/NorthernMan54/homebridge-alexa/blob/master/Installation.md#setup-instructions'>here</a>.<br>",
   "footerDisplay": "Homebridge Alexa Skill: https://www.amazon.com/Northern-Man-54-Homebridge/dp/B07B9QMTFQ",
   "schema": {
     "type": "object",
     "properties": {
       "name": {
-        "title": "Name",
+        "title": "<b>Name</b>",
         "type": "string",
         "required": true,
         "default": "Alexa",
         "description": "Plugin name as displayed in the Homebridge log"
       },
       "username": {
-        "title": "Username",
+        "title": "<b>Username</b>",
         "type": "string",
         "required": true,
         "description": "Username for https://www.homebridge.ca/"
       },
       "password": {
-        "title": "Password",
+        "title": "<b>Password</b>",
         "type": "string",
         "required": true,
         "description": "Password for https://www.homebridge.ca/"
       },
       "pin": {
-        "title": "Homebridge Pin",
+        "title": "<b>Homebridge Pin</b>",
         "type": "string",
         "placeholder": "031-45-154",
         "description": "This needs to match the Homebridge pin set in your config.json file"
       },
       "routines": {
-        "title": " Routines - enables passing of Motion and Contact sensor events to Alexa. For use in the Alexa app to create Routines triggered by these sensors.",
+        "title": "<b>Routines</b>",
         "type": "boolean",
-        "placeholder": false
+        "placeholder": false,
+        "description": "Enables passing of Motion and Contact sensor events to Alexa. For use in the Alexa app to create Routines triggered by these sensors."
       },
       "blind": {
-        "title": "Enables natural wording for opening and closing blinds, and window coverings.  Not supported in all countries.  Defaults to false",
+        "title": "<b>Blind</b>",
         "type": "boolean",
-        "placeholder": false
+        "placeholder": false,
+        "description": "Enables natural wording for opening and closing blinds, and window coverings.  Not supported in all countries.  Defaults to false"
       },
       "door": {
-        "title": "Enables natural wording for opening and closing garage doors.  Not supported in all countries.  Please note that opening a garage door requires setting a voice pin within the Alexa app.  Defaults to false",
+        "title": "<b>Door</b>",
         "type": "boolean",
-        "placeholder": false
+        "placeholder": false,
+        "description": "Enables natural wording for opening and closing garage doors.  Not supported in all countries.  Please note that opening a garage door requires setting a voice pin within the Alexa app.  Defaults to false"
       },
       "debug": {
-        "title": "Enable debug level logging to assist in problem investigation",
+        "title": "<b>Debug</b>",
         "type": "boolean",
-        "placeholder": false
+        "placeholder": false,
+        "description": "Enable debug level logging to assist in problem investigation."
+      },
+      "beta": {
+        "title": "<b>beta</b>",
+        "type": "boolean",
+        "placeholder": false,
+        "description": "Enable beta test environment.  Only available by invitation."
       },
       "refresh": {
-        "title": "Accessory Cache Refresh Interval",
+        "title": "<b>Accessory Cache Refresh Interval</b>",
         "type": "integer",
         "default": 900,
         "description": "Frequency of refreshes of the homebridge accessory cache, in seconds. Defaults to 900 Seconds ( 15 minutes ). This is the interval before new devices/homebridge instances are discovered.  This should never require changing, unless you are frequently changing your homebridge configuration without restarting the plugin.",
         "minimum": 120,
         "maximum": 86400
       },
       "keepalive": {
-        "title": "Cloud Server Connection Keepalive",
+        "title": "<b>Cloud Server Connection Keepalive</b>",
         "type": "integer",
         "default": "5",
         "description": "Frequency of keepalive messages to cloud server, in minutes. Defaults to 5 minutes.  Do not change from default unless requested as part of problem investigation.",
@@ -72,13 +82,38 @@
         }
       },
       "mergeServiceName": {
-        "title": "Alternate device naming approach",
+        "title": "<b>Alternate device naming approach</b>",
         "type": "boolean",
         "description": "This is an alternate device naming approach, which combines the internal HomeKit names for a device.  It may resolve duplicate device name issues. Do not enable on an existing implementation, as you will lose control of your existing devices.",
         "placeholder": false
       },
+      "thermostatTurnOn": {
+        "title": "<b>Thermostat Turn On Behaviour</b>",
+        "description": "Set Thermostat `Turn On` Behaviour to either Heat, Cool or Auto when Alexa is asked to turn on a Thermostat. Defaults to doing nothing and saying `That command does not work on device ...`.",
+        "type": "integer",
+        "oneOf": [
+          {
+            "title": "Heat",
+            "enum": [
+              1
+            ]
+          },
+          {
+            "title": "Cool",
+            "enum": [
+              2
+            ]
+          },
+          {
+            "title": "Auto",
+            "enum": [
+              3
+            ]
+          }
+        ]
+      },
       "CloudTransport": {
-        "title": "Cloud Server Connection Transport",
+        "title": "<b>Cloud Server Connection Transport</b>",
         "description": "Transport options for cloud server connection. MQTTS - this is the recommended setting. MQTT - this is the original/legacy option. WSS - this is the an alternative transport option.",
         "type": "string",
         "default": "mqtts",
@@ -105,15 +140,16 @@
         ]
       },
       "filter": {
-        "title": "Homebridge Instance Filter",
+        "title": "<b>Homebridge Instance Filter</b>",
         "type": "string",
         "placeholder": "eg. 192.168.1.122:51826",
-        "description": "Limits accessories shared with Alexa to a single homebridge instance.",
+        "description": "Limits accessories shared with Alexa to a single homebridge instance. Uses ip address and port of homebridge instance.",
         "pattern": "^[^{}/ :\\\\]+(?::\\d+)?$"
       },
       "deviceListHandling": {
-        "title": "<b>Filtering of devices by name, either allow or ignore.</b>",
+        "title": "<b>Device List</b>",
         "type": "string",
+        "description": "Allows filtering of devices by name. You can either allow or ignore a list of device names.",
         "default": "none",
         "required": true,
         "oneOf": [
@@ -144,7 +180,7 @@
           "type": "string"
         },
         "condition": {
-          "functionBody": "return model.deviceListHandling !== 'null';"
+          "functionBody": "if (model.deviceListHandling === 'allow' || model.deviceListHandling === 'deny') { return true } else { return false };"
         }
       },
       "combine": {
@@ -214,6 +250,7 @@
         "pin",
         "routines",
         "debug",
+        "thermostatTurnOn",
         "deviceListHandling",
         {
           "key": "deviceList",
@@ -239,7 +276,9 @@
         "keepalive",
         "refresh",
         "filter",
-        "mergeServiceName"
+        "mergeServiceName",
+        "blind",
+        "door"
       ]
     },
     {

diff --git a/docs/Alexa_Logo_RGB_BLUE.png b/docs/Alexa_Logo_RGB_BLUE.png
diff --git a/docs/README_Image.key b/docs/README_Image.key
diff --git a/docs/echo_1st.jpg b/docs/echo_1st.jpg
diff --git a/docs/echo_2nd.jpeg b/docs/echo_2nd.jpeg
diff --git a/docs/echo_5th.jpg b/docs/echo_5th.jpg