From 417da90482e1ec8964182db705332fd46ffc853a Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Mon, 8 Mar 2021 00:23:20 +0100 Subject: [PATCH 01/13] Restructure usage documentation Signed-off-by: Michael Krug --- docs/USAGE.md | 375 ++++++++++++++++++++++++++++++++++---------------- 1 file changed, 256 insertions(+), 119 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index df95eb38..ac59f8b1 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -22,102 +22,285 @@ More information can be found in the corresponding [docs page](https://www.openh ### Requirements -* openHAB Cloud Connector configured using myopenHAB.org. (Items DO NOT need to be exposed to and will not show up on myopenHAB.org, this is only needed for the IFTTT service!) -* Google account. -* Google Home, Google Home mini, Google Nest or the Google Assistant on your phone. +* The openHAB Cloud Connector configured using myopenHAB.org (Items DO NOT need to be exposed to and will not show up on myopenHAB.org, this is only required for the IFTTT service!) +* A Google account +* A Google Home/Nest Voice Assistant Device or the Google Assistant on your phone ### Item configuration -In openHAB 2 items are exposed via [metadata](https://www.openhab.org/docs/configuration/items.html#item-definition-and-syntax). +To expose [items](https://www.openhab.org/docs/concepts/items.html) to Google Assistent you will need to add [metadata](https://www.openhab.org/docs/concepts/items.html#item-metadata) in the `ga` namespace. -Currently the following metadata values are supported (also depending on Googles API capabilities): +Currently the following devices are supported (also depending on Google's API capabilities): -* `Switch / Dimmer / Color { ga="Light" }` (Depending on the item type controlling power, brightness and color is supported) +_Hint: The value of `ga` is **not** case-sensitive._ ---- +#### `Switch` -* `Group { ga="Light" [ colorTemperatureRange="2000,9000", useKelvin=true ] }` (Light with separate brightness and color items) -* `Dimmer / Number { ga="lightBrightness" }` as part of Light group -* `Dimmer / Number { ga="lightColorTemperature" }` as part of Light group +| | | +|---|---| +| **Device Type** | [Switch](https://developers.google.com/assistant/smarthome/guides/switch) | +| **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff) | +| **Supported Items** | Switch | +| **Configuration** | (optional) `inverted (boolean)` | ---- +**Example:** -* `Switch { ga="Switch" [ inverted=true ] }` (all Switch items can use the inverted option) -* `Switch { ga="Outlet" }` -* `Switch { ga="Coffee_Maker" }` -* `Switch { ga="WaterHeater" }` -* `Switch { ga="Fireplace" }` -* `Switch { ga="Valve" }` -* `Switch { ga="Sprinkler" }` -* `Switch { ga="Vacuum" }` -* `Switch { ga="Scene" }` +```shell +Switch { ga="Switch" [ inverted=false ] } +``` ---- +#### `Light` -* `Switch / Contact { ga="Lock" [ ackNeeded=true ] }` -* `Switch { ga="SecuritySystem" [ pinNeeded="1234" ] }` -* `String { ga="Camera" [ protocols="hls,dash" ] }` -* `Dimmer { ga="Speaker" }` (Volume control) +| | | +|---|---| +| **Device Type** | [Light](https://developers.google.com/assistant/smarthome/guides/light) | +| **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [ColorSetting](https://developers.google.com/assistant/smarthome/traits/colorsetting), [Brightness](https://developers.google.com/assistant/smarthome/traits/brightness) (depending on used item type) | +| **Supported Items** | Switch, Dimmer, Color | +| **Configuration** | (optional) `inverted=true/false`, (optional) `colorTemperatureRange=minK,maxK` | ---- +```shell +Color { ga="Light" [ inverted=false, colorTemperatureRange="2000,9000" ] } +``` -* `Group { ga="TV" [ volumeDefaultPercentage="20", levelStepSize="10", volumeMaxLevel="100", transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME", availableInputs="hdmi1=xbox,hdmi2=settopbox", availableChannels="1=Channel1=NBC,2=Channel2=CBS" ] }` -* `Switch { ga="tvPower" }` as part of TV group (optional) -* `Switch { ga="tvMute" }` as part of TV group (optional) -* `Dimmer { ga="tvVolume" }` as part of TV group (optional) -* `String { ga="tvChannel" }` as part of TV group (optional) -* `String { ga="tvInput" }` as part of TV group (optional) -* `Player { ga="tvTransport" }` as part of TV group (optional) +#### `Light as Group with separate Color and Brightness` ---- +| | | +|---|---| +| **Device Type** | [Light](https://developers.google.com/assistant/smarthome/guides/light) | +| **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [ColorSetting](https://developers.google.com/assistant/smarthome/traits/colorsetting), [Brightness](https://developers.google.com/assistant/smarthome/traits/brightness) | +| **Supported Items** | Group as `light` with two Number or Dimmer members as `lightBrightness` & `lightColorTemperature` | +| **Configuration** | (optional) `useKelvin=true/false` , (optional) `colorTemperatureRange=minK,maxK`
_Hint: if you do not set `useKelvin=true` then `colorTemperatureRange` is required_ | -* `Switch / Dimmer { ga="Fan" [ speeds="0=away:zero,50=default:standard:one,100=high:two", lang="en", ordered=true ] }` (for Dimmer the options have to be set) -* `Switch / Dimmer { ga="Hood" }` -* `Switch / Dimmer { ga="AirPurifier" }` +```shell +Group groupItem { ga="Light" [ useKelvin=true, colorTemperatureRange="2000,9000" ] } +Dimmer brightnessItem (groupItem) { ga="lightBrightness" } +Dimmer colorItem (groupItem) { ga="lightColorTemperature" } +``` ---- +#### `Scene` -* `Rollershutter { ga="Awning" [ inverted=true ] }` (all Rollershutter items can use the inverted option) -* `Rollershutter { ga="Blinds" }` -* `Rollershutter { ga="Curtain" }` -* `Rollershutter { ga="Door" }` -* `Rollershutter { ga="Garage" }` -* `Rollershutter { ga="Gate" }` -* `Rollershutter { ga="Pergola" }` -* `Rollershutter { ga="Shutter" }` -* `Rollershutter { ga="Window" }` +| | | +|---|---| +| **Device Type** | [Scene](https://developers.google.com/assistant/smarthome/guides/scene) | +| **Supported Traits** | [Scene](https://developers.google.com/assistant/smarthome/traits/scene) | +| **Supported Items** | Switch | +| **Configuration** | (optional) `sceneReversible=true/false` | -_\* All Rollershutter devices can also be used with a Switch or Contact item with the limitation of only supporting open and close states._ +```shell +Switch { ga="Scene" [ sceneReversible=false ] } +``` ---- +#### `Outlet`, `Coffee_Maker`, `WaterHeater`, `Fireplace` -* `Group { ga="Thermostat" [ modes="...", thermostatTemperatureRange="10,30", useFahrenheit=true ] }` -* `Number { ga="thermostatTemperatureAmbient" }` as part of Thermostat group -* `Number { ga="thermostatHumidityAmbient" }` as part of Thermostat group -* `Number { ga="thermostatTemperatureSetpoint" }` as part of Thermostat group -* `Number / String { ga="thermostatMode" }` as part of Thermostat group +| | | +|---|---| +| **Device Type** | [Outlet](https://developers.google.com/assistant/smarthome/guides/outlet), [Coffee_Maker](https://developers.google.com/assistant/smarthome/guides/coffeemaker), [WaterHeater](https://developers.google.com/assistant/smarthome/guides/outlet), [Fireplace](https://developers.google.com/assistant/smarthome/guides/fireplace) | +| **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff) | +| **Supported Items** | Switch | +| **Configuration** | (optional) `inverted=true/false` | ---- +```shell +Switch { ga="Outlet" [ inverted=true ] } +Switch { ga="Coffee_Maker" [ inverted=true ] } +Switch { ga="WaterHeater" [ inverted=true ] } +Switch { ga="Fireplace" [ inverted=true ] } +``` -* `Number { ga="TemperatureSensor" } [ useFahrenheit=true ]` +#### `Valve` -Example item configuration: +| | | +|---|---| +| **Device Type** | [Valve](https://developers.google.com/assistant/smarthome/guides/valve) | +| **Supported Traits** | [OpenClose](https://developers.google.com/assistant/smarthome/traits/openclose) | +| **Supported Items** | Switch | +| **Configuration** | (optional) `inverted=true/false` | - ```js - Switch KitchenLights "Kitchen Lights" (gKitchen) { ga="Switch" } - Dimmer BedroomLights "Bedroom Lights" (gBedroom) { ga="Light" } - Color LivingroomLights "Livingroom Lights" (gLivingroom) { ga="Light" } - Switch SceneMovie "Livingroom Scene Movie" (gLivingroom) { synonyms="Movie Scene", ga="Scene" } - Switch CristmasTree "Cristmas Tree" (gLivingroom) { ga="Outlet" } - Switch DoorLock "Door Lock" { ga="Lock" } - - //Thermostat Setup (Google requires a mode, even if you manually set it up in openHAB) - Group g_HK_Basement_TSTAT "Basement Thermostat" { ga="Thermostat" [ useFahrenheit=true ] } - Number HK_Basement_Mode "Basement Heating/Cooling Mode" (g_HK_Basement_TSTAT) { ga="thermostatMode" } - Number HK_Basement_Setpoint "Basement Setpoint" (g_HK_Basement_TSTAT) { ga="thermostatTemperatureSetpoint" } - Number HK_Basement_Temp "Basement Temperature" (g_HK_Basement_TSTAT) { ga="thermostatTemperatureAmbient" } - Number HK_Basement_Humid "Basement Humidity" (g_HK_Basement_TSTAT) { ga="thermostatHumidityAmbient" } - ``` +```shell +Switch { ga="Valve" [ inverted=true ] } +``` + +#### `Sprinkler`, `Vacuum` + +| | | +|---|---| +| **Device Type** | [Sprinkler](https://developers.google.com/assistant/smarthome/guides/sprinkler), [Vacuum](https://developers.google.com/assistant/smarthome/guides/vacuum) | +| **Supported Traits** | [StartStop](https://developers.google.com/assistant/smarthome/traits/startstop) | +| **Supported Items** | Switch | +| **Configuration** | (optional) `inverted=true/false` | + +```shell +Switch { ga="Sprinkler" [ inverted=true ] } +Switch { ga="Vacuum" [ inverted=true ] } +``` + +#### `Lock` + +| | | +|---|---| +| **Device Type** | [Lock](https://developers.google.com/assistant/smarthome/guides/lock) | +| **Supported Traits** | [LockUnlock](https://developers.google.com/assistant/smarthome/traits/lockunlock) | +| **Supported Items** | Contact (no device control), Switch | +| **Configuration** | (optional) `ackNeeded=true/false`, (optional) `pinNeeded="1234"` | + +```shell +Switch { ga="Lock" [ ackNeeded=true ] } +Switch { ga="Lock" [ pinNeeded="1234" ] } +``` + +#### `SecuritySystem` + +| | | +|---|---| +| **Device Type** | [SecuritySystem](https://developers.google.com/assistant/smarthome/guides/securitysystem) | +| **Supported Traits** | [ArmDisarm](https://developers.google.com/assistant/smarthome/traits/armdisarm) | +| **Supported Items** | Switch | +| **Configuration** | (optional) `ackNeeded=true/false`, (optional) `pinNeeded="1234"` | + +```shell +Switch { ga="SecuritySystem" [ pinNeeded="1234" ] } +``` + +#### `Camera` + +| | | +|---|---| +| **Device Type** | [Camera](https://developers.google.com/assistant/smarthome/guides/camera) | +| **Supported Traits** | [CameraStream](https://developers.google.com/assistant/smarthome/traits/camerastream) | +| **Supported Items** | String | +| **Configuration** | (optional) `protocols="hls,dash,smooth_stream,progressive_mp4"` _(choose suitable)_ | + +```shell +String { ga="Camera" [ protocols="hls,dash" ] } +``` + +#### `Speaker` (volume control only) + +| | | +|---|---| +| **Device Type** | [Speaker](https://developers.google.com/assistant/smarthome/guides/speaker) | +| **Supported Traits** | [Volume](https://developers.google.com/assistant/smarthome/traits/volume) | +| **Supported Items** | Dimmer | +| **Configuration** | (optional) `volumeDefaultPercentage="20"`, (optional) `levelStepSize="5"`, (optional) `volumeMaxLevel="100"` | + +```shell +Dimmer { ga="Speaker" [ volumeDefaultPercentage="50", levelStepSize="10", volumeMaxLevel="90" ] } +``` + +#### `TV` + +| | | +|---|---| +| **Device Type** | [TV](https://developers.google.com/assistant/smarthome/guides/tv) | +| **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [Volume](https://developers.google.com/assistant/smarthome/traits/volume), [TransportControl](https://developers.google.com/assistant/smarthome/traits/transportcontrol), [InputSelector](https://developers.google.com/assistant/smarthome/traits/inputselector), [Channel](https://developers.google.com/assistant/smarthome/traits/channel) (depending on used members) | +| **Supported Items** | Group as `TV` with the following optional members: Switch as `tvPower`, Switch as `tvMute`, Dimmer as `tvVolume`, String as `tvChannel`, String as `tvInput`, Player as `tvTransport` | +| **Configuration** | (optional) `volumeDefaultPercentage="20"`, (optional) `levelStepSize="5"`, (optional) `volumeMaxLevel="100"`, (optional) `transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME"`, (optional) `availableInputs="hdmi1=xbox,hdmi2=settopbox"`, (optional) `availableChannels="1=Channel1=NBC,2=Channel2=CBS"` | + + +```shell +Group tvGroup { ga="TV" [ volumeDefaultPercentage="20", levelStepSize="10", volumeMaxLevel="100", transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME", availableInputs="hdmi1=xbox,hdmi2=settopbox", availableChannels="1=Channel1=NBC,2=Channel2=CBS" ] } +Switch powerItem (tvGroup) { ga="tvPower" } +Switch muteItem (tvGroup) { ga="tvMute" } +Dimmer volumeItem (tvGroup) { ga="tvVolume" } +String channelItem (tvGroup) { ga="tvChannel" } +String inputItem (tvGroup) { ga="tvInput" } +Player transportItem (tvGroup) { ga="tvTransport" } +``` + +#### `Fan`, `Hood`, `AirPurifier` + +| | | +|---|---| +| **Device Type** | [Fan](https://developers.google.com/assistant/smarthome/guides/fan), [Hood](https://developers.google.com/assistant/smarthome/guides/hood), [AirPurifier](https://developers.google.com/assistant/smarthome/guides/airpurifier) | +| **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/OnOff), [FanSpeed](https://developers.google.com/assistant/smarthome/traits/fanspeed) (depending on used item type) | +| **Supported Items** | Switch (no speed control), Dimmer | +| **Configuration** | `speeds="0=away:zero,50=default:standard:one,100=high:two"`, (optional) `lang="en"`, (optional) `ordered=true/false` | + +Fans (and similar device types, like AirPurifier or Hood) support the `FanSpeed` trait. +With that you will be able to set up and use human speakable modes, e.g. "fast" for 100% or "slow" for 25%. + +`speeds` will be a comma-separated list of modes with a percentage number followed by an equal sign and different aliases for that mode after a colon. +So here both "high" and "two" would set the speed to 100%. +You are also able to define the language of those aliases. +The option `ordered` will tell the system that your list is ordered and you will then be able to also say "faster" or "slower" and Google will use the next or previous speed. + +```shell +Dimmer { ga="Fan" [ speeds="0=away:zero,50=default:standard:one,100=high:two", lang="en", ordered=true ] } +Switch { ga="Hood" } +Dimmer { ga="AirPurifier" [ speeds="0=off,50=mid,100=high" ] } +``` + +#### `Awning`, `Blinds`, `Curtain`, `Door`, `Garage`, `Gate`, `Pergola`, `Shutter`, `Window` + +| | | +|---|---| +| **Device Type** | [Awning](https://developers.google.com/assistant/smarthome/guides/awning), [Blinds](https://developers.google.com/assistant/smarthome/guides/Blinds), [Curtain](https://developers.google.com/assistant/smarthome/guides/Curtain), [Door](https://developers.google.com/assistant/smarthome/guides/Door), [Garage](https://developers.google.com/assistant/smarthome/guides/Garage), [Gate](https://developers.google.com/assistant/smarthome/guides/Gate), [Pergola](https://developers.google.com/assistant/smarthome/guides/Pergola), [Shutter](https://developers.google.com/assistant/smarthome/guides/Shutter), [Window](https://developers.google.com/assistant/smarthome/guides/Window) | +| **Supported Traits** | [OpenClose](https://developers.google.com/assistant/smarthome/traits/openclose), [StartStop](https://developers.google.com/assistant/smarthome/traits/startstop) | +| **Supported Items** | Contact (no device control), Switch (no open percentage), Rollershutter | +| **Configuration** | (optional) `inverted=true/false` | + +Blinds and simiar devices should always use the `Rollershutter` item type for proper functionallity. +Since Google and openHAB use the oposite percentage value for "opened" and "closed", the action will tranlate this automatically. +If the values are still inverted in your case, you can state the `inverted=true` option for all `Rollershutter` items. + +Since Google only tells the open percentage (and not the verb "close" or "down"), it can not be differentiated between saying "set blind to 100%" or "open blind". +Therefore, it is not possible to "not invert" the verbs, if the user chooses to invert the numbers. + +```shell +Rollershutter { ga="Awning" } +Rollershutter { ga="Blinds" [ inverted=true ] } +Rollershutter { ga="Curtain" } +Switch { ga="Door" } +Rollershutter { ga="Garage" } +Contact { ga="Gate" } +Rollershutter { ga="Pergola" } +Rollershutter { ga="Shutter" } +Rollershutter { ga="Window" } +``` + +#### `TemperatureSensor` + +| | | +|---|---| +| **Device Type** | [Sensor](https://developers.google.com/assistant/smarthome/guides/sensor) | +| **Supported Traits** | [TemperatureControl](https://developers.google.com/assistant/smarthome/traits/temperaturecontrol) | +| **Supported Items** | Number | +| **Configuration** | (optional) `useFahrenheit=true/false` | + +```shell +Number { ga="TemperatureSensor" [ useFahrenheit=true ] } +``` + +#### `Thermostat` + +| | | +|---|---| +| **Device Type** | [Thermostat](https://developers.google.com/assistant/smarthome/guides/thermostat) | +| **Supported Traits** | [TemperatureSetting](https://developers.google.com/assistant/smarthome/traits/temperaturesetting) | +| **Supported Items** | Group as `Thermostat` with the following optional members: Number as `thermostatTemperatureAmbient`, Number as `thermostatTemperatureSetpoint`, Number as `thermostatHumidityAmbient`, String or Number as `thermostatMode` | +| **Configuration** | (optional) `useFahrenheit=true/false`, (optional) `thermostatTemperatureRange="10,30"`, (optional) `modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto"` | + +Thermostat requires a group of items to be properly configured to be used with Google Assistant. The default temperature unit is Celsius. +To change the temperature unit to Fahrenheit, add the config option `useFahrenheit=true` to the thermostat group. +To set the temperature range your thermostat supports, add the config option `thermostatTemperatureRange="10,30"` to the thermostat group. + +If your thermostat does not have a mode, you should create one and manually assign a value (e.g. heat, cool, on, etc.) to have proper functionality. + +To map the [default thermostat modes of Google](https://developers.google.com/assistant/smarthome/traits/temperaturesetting.html) (on, off, heat, cool, etc.) to custom ones for your specific setup, you can use the `modes` config option on the thermostat group. +E.g. `[ modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto" ]` will enable the following five modes in Google Home `"off, heat, eco, on, auto"` that will be translated to `"OFF, COMFORT, ECO, ON, auto"`. You can specify alternative conversions using the colon sign, so that in the former example "BOOST" in openHAB would also be translated to "heat" in Google. For the translation of Google modes to openHAB always the first option after the equal sign is used. +By default the integration will provide `"off,heat,cool,on,heatcool,auto,eco"`. + +You can also set up a Thermostat for using it as a temperature sensor. To do so, create a Thermostat group and only add one item member as "thermostatTemperatureAmbient". +However, it is recommended to prefer the `TemperatureSensor` type for simple temperature reports (but currently there is no UI support in Google Home). + +```shell +Group thermostatGroup { ga="Thermostat" [ modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto", thermostatTemperatureRange="10,30", useFahrenheit=false ] } +Number ambientItem (thermostatGroup) { ga="thermostatTemperatureAmbient" } +Number humidityItem (thermostatGroup) { ga="thermostatHumidityAmbient" } +Number setpointItem (thermostatGroup) { ga="thermostatTemperatureSetpoint" } +String modeItem (thermostatGroup) { ga="thermostatMode" } +``` + +### Addtional Information Item labels are not mandatory in openHAB, but for the Google Assistant Action they are absolutely necessary! @@ -171,57 +354,11 @@ _pinNeeded_: "A two-factor authentication that requires a personal identificatio Example: -```js +```shell Switch DoorLock "Front Door" { ga="Lock" [ ackNeeded=true ] } Switch HouseAlarm "House Alarm" { ga="SecuritySystem" [ pinNeeded="1234" ] } ``` -#### Thermostats - -Thermostat requires a group of items to be properly configured to be used with Google Assistant. The default temperature unit is Celsius. `{ ga="Thermostat" }` - -To change the temperature unit to Fahrenheit, add the config option `[ useFahrenheit=true ]` to the thermostat group. -To set the temperature range your thermostat supports, add the config option `[ thermostatTemperatureRange="10,30" ]` to the thermostat group. - -There must be at least three items as members of the group: - -* (Mandatory) Mode: Number or String (off, heat, cool, on, ...). `{ ga="thermostatMode" }` -* (Mandatory) Temperature Ambient: Number. `{ ga="thermostatTemperatureAmbient" }` -* (Mandatory) Temperature Setpoint: Number. `{ ga="thermostatTemperatureSetpoint" }` -* (Optional) Temperature Setpoint High: Number. `{ ga="thermostatTemperatureSetpointHigh" }` -* (Optional) Temperature Setpoint Low: Number. `{ ga="thermostatTemperatureSetpointLow" }` -* (Optional) Humidity Ambient: Number. `{ ga="thermostatHumidityAmbient" }` - -If your thermostat does not have a mode, you should create one and manually assign a value (e.g. heat, cool, on, etc.) to have proper functionality. - -To map the [default thermostat modes of Google](https://developers.google.com/assistant/smarthome/traits/temperaturesetting.html) (on, off, heat, cool, etc.) to custom ones for your specific setup, you can use the _modes_ config option on the thermostat group. -E.g. `[ modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto" ]` will enable the following five modes in Google Home `"off, heat, eco, on, auto"` that will be translated to `"OFF, COMFORT, ECO, ON, auto"`. You can specify alternative conversions using the colon sign, so that in the former example "BOOST" in openHAB would also be translated to "heat" in Google. For the translation of Google modes to openHAB always the first option after the equal sign is used. -By default the integration will provide `"off,heat,cool,on,heatcool,auto,eco"`. - -You can also set up a Thermostat for using it as a temperature sensor. To do so, create a Thermostat group and only add one item member as "thermostatTemperatureAmbient". -However, it is recommended to prefer the `TemperatureSensor` type for simple temperature reports (but currently no UI support in Google Assistant). - -#### Fans - -_Fans_ (and similar device types, like _AirPurifier_ or _Hood_) support the _FanSpeed_ trait. -With that you will be able to set up and use human speakable modes, e.g. "fast" for 100% or "slow" for 25%. - -To set up those modes use a _Dimmer_ item and the following metadata config: `[ speeds="0=away:zero,50=default:standard:one,100=high:two", lang="en", ordered=true ]`. - -_speeds_ will be a comma-separated list of modes with a percentage number followed by an equal sign and different aliases for that mode after a colon. -So here both "high" and "two" would set the speed to 100%. -You are also able to define the language of those aliases. -The option _ordered_ will tell the system that your list is ordered and you will then be able to also say "faster" or "slower" and Google will use the next or previous speed. - -#### Blinds and similar devices - -Blinds should always use the `Rollershutter` item type. -Since Google and openHAB use the oposite percentage value for "opened" or "closed", the action will tranlate this automatically. -If the values are still inverted in your case, you can state the `[ inverted=true ]` option for all `Rollershutter` items. - -Since Google only tells the open percentage (and not the verb "close" or "down"), it can not be differentiated between saying "set blind to 100%" or "open blind". -Therefore, it is not possible to "not invert" the verbs, if the user chooses to invert the numbers. - ## Setup & Usage on Google Assistant App * Make sure Google Play Services is up to date. From 0b8de52240a22fe650713cd55071422e54124ce1 Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Mon, 8 Mar 2021 00:40:16 +0100 Subject: [PATCH 02/13] Use line breaks for options Signed-off-by: Michael Krug --- docs/USAGE.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index ac59f8b1..d444bb0a 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -56,7 +56,7 @@ Switch { ga="Switch" [ inverted=false ] } | **Device Type** | [Light](https://developers.google.com/assistant/smarthome/guides/light) | | **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [ColorSetting](https://developers.google.com/assistant/smarthome/traits/colorsetting), [Brightness](https://developers.google.com/assistant/smarthome/traits/brightness) (depending on used item type) | | **Supported Items** | Switch, Dimmer, Color | -| **Configuration** | (optional) `inverted=true/false`, (optional) `colorTemperatureRange=minK,maxK` | +| **Configuration** | (optional) `inverted=true/false`
(optional) `colorTemperatureRange=minK,maxK` | ```shell Color { ga="Light" [ inverted=false, colorTemperatureRange="2000,9000" ] } @@ -69,7 +69,7 @@ Color { ga="Light" [ inverted=false, colorTemperatureRange="2000,9000" ] } | **Device Type** | [Light](https://developers.google.com/assistant/smarthome/guides/light) | | **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [ColorSetting](https://developers.google.com/assistant/smarthome/traits/colorsetting), [Brightness](https://developers.google.com/assistant/smarthome/traits/brightness) | | **Supported Items** | Group as `light` with two Number or Dimmer members as `lightBrightness` & `lightColorTemperature` | -| **Configuration** | (optional) `useKelvin=true/false` , (optional) `colorTemperatureRange=minK,maxK`
_Hint: if you do not set `useKelvin=true` then `colorTemperatureRange` is required_ | +| **Configuration** | (optional) `useKelvin=true/false`
(optional) `colorTemperatureRange=minK,maxK`
_Hint: if you do not set `useKelvin=true` then `colorTemperatureRange` is required_ | ```shell Group groupItem { ga="Light" [ useKelvin=true, colorTemperatureRange="2000,9000" ] } @@ -140,7 +140,7 @@ Switch { ga="Vacuum" [ inverted=true ] } | **Device Type** | [Lock](https://developers.google.com/assistant/smarthome/guides/lock) | | **Supported Traits** | [LockUnlock](https://developers.google.com/assistant/smarthome/traits/lockunlock) | | **Supported Items** | Contact (no device control), Switch | -| **Configuration** | (optional) `ackNeeded=true/false`, (optional) `pinNeeded="1234"` | +| **Configuration** | (optional) `ackNeeded=true/false`
(optional) `pinNeeded="1234"` | ```shell Switch { ga="Lock" [ ackNeeded=true ] } @@ -154,7 +154,7 @@ Switch { ga="Lock" [ pinNeeded="1234" ] } | **Device Type** | [SecuritySystem](https://developers.google.com/assistant/smarthome/guides/securitysystem) | | **Supported Traits** | [ArmDisarm](https://developers.google.com/assistant/smarthome/traits/armdisarm) | | **Supported Items** | Switch | -| **Configuration** | (optional) `ackNeeded=true/false`, (optional) `pinNeeded="1234"` | +| **Configuration** | (optional) `ackNeeded=true/false`
(optional) `pinNeeded="1234"` | ```shell Switch { ga="SecuritySystem" [ pinNeeded="1234" ] } @@ -180,7 +180,7 @@ String { ga="Camera" [ protocols="hls,dash" ] } | **Device Type** | [Speaker](https://developers.google.com/assistant/smarthome/guides/speaker) | | **Supported Traits** | [Volume](https://developers.google.com/assistant/smarthome/traits/volume) | | **Supported Items** | Dimmer | -| **Configuration** | (optional) `volumeDefaultPercentage="20"`, (optional) `levelStepSize="5"`, (optional) `volumeMaxLevel="100"` | +| **Configuration** | (optional) `volumeDefaultPercentage="20"`
(optional) `levelStepSize="5"`
(optional) `volumeMaxLevel="100"` | ```shell Dimmer { ga="Speaker" [ volumeDefaultPercentage="50", levelStepSize="10", volumeMaxLevel="90" ] } @@ -193,7 +193,7 @@ Dimmer { ga="Speaker" [ volumeDefaultPercentage="50", levelStepSize="10", volume | **Device Type** | [TV](https://developers.google.com/assistant/smarthome/guides/tv) | | **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [Volume](https://developers.google.com/assistant/smarthome/traits/volume), [TransportControl](https://developers.google.com/assistant/smarthome/traits/transportcontrol), [InputSelector](https://developers.google.com/assistant/smarthome/traits/inputselector), [Channel](https://developers.google.com/assistant/smarthome/traits/channel) (depending on used members) | | **Supported Items** | Group as `TV` with the following optional members: Switch as `tvPower`, Switch as `tvMute`, Dimmer as `tvVolume`, String as `tvChannel`, String as `tvInput`, Player as `tvTransport` | -| **Configuration** | (optional) `volumeDefaultPercentage="20"`, (optional) `levelStepSize="5"`, (optional) `volumeMaxLevel="100"`, (optional) `transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME"`, (optional) `availableInputs="hdmi1=xbox,hdmi2=settopbox"`, (optional) `availableChannels="1=Channel1=NBC,2=Channel2=CBS"` | +| **Configuration** | (optional) `volumeDefaultPercentage="20"`
(optional) `levelStepSize="5"`
(optional) `volumeMaxLevel="100"`
(optional) `transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME"`
(optional) `availableInputs="hdmi1=xbox,hdmi2=settopbox"`
(optional) `availableChannels="1=Channel1=NBC,2=Channel2=CBS"` | ```shell @@ -213,7 +213,7 @@ Player transportItem (tvGroup) { ga="tvTransport" } | **Device Type** | [Fan](https://developers.google.com/assistant/smarthome/guides/fan), [Hood](https://developers.google.com/assistant/smarthome/guides/hood), [AirPurifier](https://developers.google.com/assistant/smarthome/guides/airpurifier) | | **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/OnOff), [FanSpeed](https://developers.google.com/assistant/smarthome/traits/fanspeed) (depending on used item type) | | **Supported Items** | Switch (no speed control), Dimmer | -| **Configuration** | `speeds="0=away:zero,50=default:standard:one,100=high:two"`, (optional) `lang="en"`, (optional) `ordered=true/false` | +| **Configuration** | (optional) `speeds="0=away:zero,50=default:standard:one,100=high:two"`
(optional) `lang="en"`
(optional) `ordered=true/false`
_Hint: if you are using a Dimmer then `speeds` is required_ | Fans (and similar device types, like AirPurifier or Hood) support the `FanSpeed` trait. With that you will be able to set up and use human speakable modes, e.g. "fast" for 100% or "slow" for 25%. @@ -277,7 +277,7 @@ Number { ga="TemperatureSensor" [ useFahrenheit=true ] } | **Device Type** | [Thermostat](https://developers.google.com/assistant/smarthome/guides/thermostat) | | **Supported Traits** | [TemperatureSetting](https://developers.google.com/assistant/smarthome/traits/temperaturesetting) | | **Supported Items** | Group as `Thermostat` with the following optional members: Number as `thermostatTemperatureAmbient`, Number as `thermostatTemperatureSetpoint`, Number as `thermostatHumidityAmbient`, String or Number as `thermostatMode` | -| **Configuration** | (optional) `useFahrenheit=true/false`, (optional) `thermostatTemperatureRange="10,30"`, (optional) `modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto"` | +| **Configuration** | (optional) `useFahrenheit=true/false`
(optional) `thermostatTemperatureRange="10,30"`
(optional) `modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto"` | Thermostat requires a group of items to be properly configured to be used with Google Assistant. The default temperature unit is Celsius. To change the temperature unit to Fahrenheit, add the config option `useFahrenheit=true` to the thermostat group. @@ -340,8 +340,6 @@ NOTE: metadata is not available via paperUI in openHAB v2. Either you create you NOTE: Please be aware that for backward compatibilty also the former usage of tags (ref. [Google Assistant Action Documentation v2.5](https://www.openhab.org/v2.5/docs/ecosystem/google-assistant/)) to specify items to be exposed to Google Assistent is supported and may cause unexpected behavior. Items that contain tags that refer to a valid Google Assistent device will be exposed regardless of having metadata set. E.g.: `Switch MyBulb ["Lighting"]`. -### Special item configurations - #### Two-Factor-Authentication For some actions, Google recommends to use TFA (Two-Factor-Authentication) to prevent accidential or unauthorized triggers of sensitive actions. See [Two-factor authentication  |  Actions on Google Smart Home](https://developers.google.com/assistant/smarthome/develop/two-factor-authentication). From 3f8a81be30a48b78966298bd48ef8ba8f37fb944 Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Mon, 8 Mar 2021 00:47:47 +0100 Subject: [PATCH 03/13] Align members Signed-off-by: Michael Krug --- docs/USAGE.md | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index d444bb0a..03246932 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -59,7 +59,9 @@ Switch { ga="Switch" [ inverted=false ] } | **Configuration** | (optional) `inverted=true/false`
(optional) `colorTemperatureRange=minK,maxK` | ```shell -Color { ga="Light" [ inverted=false, colorTemperatureRange="2000,9000" ] } +Switch { ga="Light" [ inverted=true ] } +Dimmer { ga="Light" } +Color { ga="Light" [ colorTemperatureRange="2000,9000" ] } ``` #### `Light as Group with separate Color and Brightness` @@ -72,9 +74,9 @@ Color { ga="Light" [ inverted=false, colorTemperatureRange="2000,9000" ] } | **Configuration** | (optional) `useKelvin=true/false`
(optional) `colorTemperatureRange=minK,maxK`
_Hint: if you do not set `useKelvin=true` then `colorTemperatureRange` is required_ | ```shell -Group groupItem { ga="Light" [ useKelvin=true, colorTemperatureRange="2000,9000" ] } -Dimmer brightnessItem (groupItem) { ga="lightBrightness" } -Dimmer colorItem (groupItem) { ga="lightColorTemperature" } +Group lightGroup { ga="Light" [ useKelvin=true, colorTemperatureRange="2000,9000" ] } +Dimmer brightnessItem (lightGroup) { ga="lightBrightness" } +Number colorItem (lightGroup) { ga="lightColorTemperature" } ``` #### `Scene` @@ -102,8 +104,8 @@ Switch { ga="Scene" [ sceneReversible=false ] } ```shell Switch { ga="Outlet" [ inverted=true ] } Switch { ga="Coffee_Maker" [ inverted=true ] } -Switch { ga="WaterHeater" [ inverted=true ] } -Switch { ga="Fireplace" [ inverted=true ] } +Switch { ga="WaterHeater" [ inverted=false ] } +Switch { ga="Fireplace" } ``` #### `Valve` @@ -130,7 +132,7 @@ Switch { ga="Valve" [ inverted=true ] } ```shell Switch { ga="Sprinkler" [ inverted=true ] } -Switch { ga="Vacuum" [ inverted=true ] } +Switch { ga="Vacuum" [ inverted=false ] } ``` #### `Lock` @@ -195,14 +197,13 @@ Dimmer { ga="Speaker" [ volumeDefaultPercentage="50", levelStepSize="10", volume | **Supported Items** | Group as `TV` with the following optional members: Switch as `tvPower`, Switch as `tvMute`, Dimmer as `tvVolume`, String as `tvChannel`, String as `tvInput`, Player as `tvTransport` | | **Configuration** | (optional) `volumeDefaultPercentage="20"`
(optional) `levelStepSize="5"`
(optional) `volumeMaxLevel="100"`
(optional) `transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME"`
(optional) `availableInputs="hdmi1=xbox,hdmi2=settopbox"`
(optional) `availableChannels="1=Channel1=NBC,2=Channel2=CBS"` | - ```shell -Group tvGroup { ga="TV" [ volumeDefaultPercentage="20", levelStepSize="10", volumeMaxLevel="100", transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME", availableInputs="hdmi1=xbox,hdmi2=settopbox", availableChannels="1=Channel1=NBC,2=Channel2=CBS" ] } -Switch powerItem (tvGroup) { ga="tvPower" } -Switch muteItem (tvGroup) { ga="tvMute" } -Dimmer volumeItem (tvGroup) { ga="tvVolume" } -String channelItem (tvGroup) { ga="tvChannel" } -String inputItem (tvGroup) { ga="tvInput" } +Group tvGroup { ga="TV" [ volumeDefaultPercentage="20", levelStepSize="10", volumeMaxLevel="100", transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME", availableInputs="hdmi1=xbox,hdmi2=settopbox", availableChannels="1=Channel1=NBC,2=Channel2=CBS" ] } +Switch powerItem (tvGroup) { ga="tvPower" } +Switch muteItem (tvGroup) { ga="tvMute" } +Dimmer volumeItem (tvGroup) { ga="tvVolume" } +String channelItem (tvGroup) { ga="tvChannel" } +String inputItem (tvGroup) { ga="tvInput" } Player transportItem (tvGroup) { ga="tvTransport" } ``` @@ -249,9 +250,9 @@ Therefore, it is not possible to "not invert" the verbs, if the user chooses to Rollershutter { ga="Awning" } Rollershutter { ga="Blinds" [ inverted=true ] } Rollershutter { ga="Curtain" } -Switch { ga="Door" } +Switch { ga="Door" } Rollershutter { ga="Garage" } -Contact { ga="Gate" } +Contact { ga="Gate" } Rollershutter { ga="Pergola" } Rollershutter { ga="Shutter" } Rollershutter { ga="Window" } @@ -293,11 +294,11 @@ You can also set up a Thermostat for using it as a temperature sensor. To do so, However, it is recommended to prefer the `TemperatureSensor` type for simple temperature reports (but currently there is no UI support in Google Home). ```shell -Group thermostatGroup { ga="Thermostat" [ modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto", thermostatTemperatureRange="10,30", useFahrenheit=false ] } -Number ambientItem (thermostatGroup) { ga="thermostatTemperatureAmbient" } +Group thermostatGroup { ga="Thermostat" [ modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto", thermostatTemperatureRange="10,30", useFahrenheit=false ] } +Number ambientItem (thermostatGroup) { ga="thermostatTemperatureAmbient" } Number humidityItem (thermostatGroup) { ga="thermostatHumidityAmbient" } Number setpointItem (thermostatGroup) { ga="thermostatTemperatureSetpoint" } -String modeItem (thermostatGroup) { ga="thermostatMode" } +String modeItem (thermostatGroup) { ga="thermostatMode" } ``` ### Addtional Information From e0d092bd6c00cec4529a9bab4a0c9b180ecfb696 Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Mon, 8 Mar 2021 21:12:37 +0100 Subject: [PATCH 04/13] Remove redundant information Signed-off-by: Michael Krug --- README.md | 212 +----------------------------------------------------- 1 file changed, 3 insertions(+), 209 deletions(-) diff --git a/README.md b/README.md index db7d5150..e2ea0f06 100644 --- a/README.md +++ b/README.md @@ -184,217 +184,11 @@ To fix: Return back to the Google Home app and try to add the OpenHAB service again. You should now be able to see `[test] open hab` and add it successfully. -### Item configuration - -In openHAB items are exposed using metadata in the namespace `ga`: - -```js -Switch KitchenLights "Kitchen Lights" (gKitchen) { ga="Switch" } -Dimmer BedroomLights "Bedroom Lights" (gBedroom) { ga="Light" } -Color LivingroomLights "Livingroom Lights" (gLivingroom) { ga="Light" } -Switch SceneMovie "Livingroom Scene Movie" (gLivingroom) { synonyms="Movie Scene", ga="Scene" } -Switch CristmasTree "Cristmas Tree" (gLivingroom) { ga="Outlet" } -Switch DoorLock "Door Lock" { ga="Lock" } - -//Thermostat Setup (Google requires a mode, even if you manually set it up in openHAB) -Group g_HK_Basement_TSTAT "Basement Thermostat" { ga="Thermostat" [ useFahrenheit=true ] } -Number HK_Basement_Mode "Basement Heating/Cooling Mode" (g_HK_Basement_TSTAT) { ga="thermostatMode" } -Number HK_Basement_Setpoint "Basement Setpoint" (g_HK_Basement_TSTAT) { ga="thermostatTemperatureSetpoint" } -Number HK_Basement_Temp "Basement Temperature" (g_HK_Basement_TSTAT) { ga="thermostatTemperatureAmbient" } -Number HK_Basement_Humid "Basement Humidity" (g_HK_Basement_TSTAT) { ga="thermostatHumidityAmbient" } -``` - -Currently the following metadata values are supported (also depending on Googles API capabilities): - -* `Switch / Dimmer / Color { ga="Light" }` (Depending on the item type controlling power, brightness and color is supported) - ---- - -* `Group { ga="Light" [ colorTemperatureRange="2000,9000", useKelvin=true ] }` (Light with separate brightness and color items) -* `Dimmer / Number { ga="lightBrightness" }` as part of Light group -* `Dimmer / Number { ga="lightColorTemperature" }` as part of Light group - ---- - -* `Switch { ga="Switch" [ inverted=true ] }` (all Switch items can use the inverted option) -* `Switch { ga="Outlet" }` -* `Switch { ga="Coffee_Maker" }` -* `Switch { ga="WaterHeater" }` -* `Switch { ga="Fireplace" }` -* `Switch { ga="Valve" }` -* `Switch { ga="Sprinkler" }` -* `Switch { ga="Vacuum" }` -* `Switch { ga="Scene" }` - ---- - -* `Switch / Contact { ga="Lock" [ ackNeeded=true ] }` -* `Switch { ga="SecuritySystem" [ pinNeeded="1234" ] }` -* `String { ga="Camera" [ protocols="hls,dash" ] }` -* `Dimmer { ga="Speaker" }` (Volume control) - ---- - -* `Group { ga="TV" [ volumeDefaultPercentage="20", levelStepSize="10", volumeMaxLevel="100", transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME", availableInputs="hdmi1=xbox,hdmi2=settopbox", availableChannels="1=Channel1=NBC,2=Channel2=CBS" ] }` -* `Switch { ga="tvPower" }` as part of TV group (optional) -* `Switch { ga="tvMute" }` as part of TV group (optional) -* `Dimmer { ga="tvVolume" }` as part of TV group (optional) -* `String { ga="tvChannel" }` as part of TV group (optional) -* `String { ga="tvInput" }` as part of TV group (optional) -* `Player { ga="tvTransport" }` as part of TV group (optional) - ---- - -* `Switch / Dimmer { ga="Fan" [ speeds="0=away:zero,50=default:standard:one,100=high:two", lang="en", ordered=true ] }` (for Dimmer the options have to be set) -* `Switch / Dimmer { ga="Hood" }` -* `Switch / Dimmer { ga="AirPurifier" }` - ---- - -* `Rollershutter { ga="Awning" [ inverted=true ] }` (all Rollershutter items can use the inverted option) -* `Rollershutter { ga="Blinds" }` -* `Rollershutter { ga="Curtain" }` -* `Rollershutter { ga="Door" }` -* `Rollershutter { ga="Garage" }` -* `Rollershutter { ga="Gate" }` -* `Rollershutter { ga="Pergola" }` -* `Rollershutter { ga="Shutter" }` -* `Rollershutter { ga="Window" }` - -_\* All Rollershutter devices can also be used with a Switch or Contact item with the limitation of only supporting open and close states._ - ---- - -* `Group { ga="Thermostat" [ modes="...", thermostatTemperatureRange="10,30", useFahrenheit=true ] }` -* `Number { ga="thermostatTemperatureAmbient" }` as part of Thermostat group -* `Number { ga="thermostatHumidityAmbient" }` as part of Thermostat group -* `Number { ga="thermostatTemperatureSetpoint" }` as part of Thermostat group -* `Number / String { ga="thermostatMode" }` as part of Thermostat group - ---- - -* `Number { ga="TemperatureSensor" } [ useFahrenheit=true ]` - -Item labels are not mandatory in openHAB, but for the Google Assistant Action they are absolutely necessary! - -It is the "label text" (e.g. "Kitchen Lights" for example above) and not the item's name that will be available to you via voice commands or in the Google Home app, so make it unique and easy to say! - -If you do not want to adjust your labels to be human spellable, you can use the "name" config option in the metadata: `[ name="Kitchen Lights" ]`. This will overwrite the label as the device's name. - -Furthermore, you can state synonyms for the device name: `Switch KitchenLight "Kitchen Lights" { synonyms="Top Light", ga="Light" }`. - -To ease setting up new devices you can add a room hint: `[ roomHint="Living Room" ]`. - -For devices supporting the OpenClose trait, the attributes `[ discreteOnlyOpenClose=false, queryOnlyOpenClose=false ]` can be configured. - -* discreteOnlyOpenClose defaults to false. When set to true, this indicates that the device must either be fully open or fully closed (that is, it does not support values between 0% and 100%). An example of such a device may be a valve. -* queryOnlyOpenClose defaults to false. Is set to true for `Contact` items. Indicates if the device can only be queried for state information and cannot be controlled. Sensors that can only report open state should set this field to true. - ---- - -NOTE: metadata is not (yet?) available via paperUI. Either you create your items via ".items" files, or you can: - -* add metadata via console: - - ```console - smarthome:metadata add BedroomLights ga Light - ``` - -* add metadata using the REST API: - - ```js - PUT /rest/items/BedroomLights/metadata/ga - - { - "value": "Light" - } - ``` - -NOTE: Please be aware that for backward compatibilty also the former usage of tags (ref. [Google Assistant Action Documentation v2.5](https://www.openhab.org/v2.5/docs/ecosystem/google-assistant/)) to specify items to be exposed to Google Assistent is supported and may cause unexpected behavior. -Items that contain tags that refer to a valid Google Assistent device will be exposed regardless of having metadata set. E.g.: `Switch MyBulb ["Lighting"]`. - -### Special item configurations - -#### Two-Factor-Authentication - -For some actions, Google recommends to use TFA (Two-Factor-Authentication) to prevent accidential or unauthorized triggers of sensitive actions. See [Two-factor authentication  |  Actions on Google Smart Home](https://developers.google.com/assistant/smarthome/develop/two-factor-authentication). - -The openHAB Google Assistant integration supports both _ackNeeded_ and _pinNeeded_. You can use both types on all devices types and traits. - -_ackNeeded_: "A two-factor authentication that requires explicit acknowledgement (yes or no) and can also use trait states as response feedback. This challenge type is not recommended for security devices and traits." - -_pinNeeded_: "A two-factor authentication that requires a personal identification number (PIN), which is ideal for security devices and traits." - -Example: - -```js -Switch DoorLock "Front Door" { ga="Lock" [ ackNeeded=true ] } -Switch HouseAlarm "House Alarm" { ga="SecuritySystem" [ pinNeeded="1234" ] } -``` - -#### Thermostats - -Thermostat requires a group of items to be properly configured to be used with Google Assistant. The default temperature unit is Celsius. `{ ga="Thermostat" }` - -To change the temperature unit to Fahrenheit, add the config option `[ useFahrenheit=true ]` to the thermostat group. -To set the temperature range your thermostat supports, add the config option `[ thermostatTemperatureRange="10,30" ]` to the thermostat group. - -There must be at least three items as members of the group: - -* (Mandatory) Mode: Number (Zwave THERMOSTAT_MODE Format) or String (off, heat, cool, on, ...). `{ ga="thermostatMode" }` -* (Mandatory) Temperature Ambient: Number. `{ ga="thermostatTemperatureAmbient" }` -* (Mandatory) Temperature Setpoint: Number. `{ ga="thermostatTemperatureSetpoint" }` -* (Optional) Temperature Setpoint High: Number. `{ ga="thermostatTemperatureSetpointHigh" }` -* (Optional) Temperature Setpoint Low: Number. `{ ga="thermostatTemperatureSetpointLow" }` -* (Optional) Humidity Ambient: Number. `{ ga="thermostatHumidityAmbient" }` - -If your thermostat does not have a mode, you should create one and manually assign a value (e.g. heat, cool, on, etc.) to have proper functionality. - -To map the [default thermostat modes of Google](https://developers.google.com/assistant/smarthome/traits/temperaturesetting.html) (on, off, heat, cool, etc.) to custom ones for your specific setup, you can use the _modes_ config option on the thermostat group. -E.g. `[ modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto" ]` will enable the following five modes in Google Home `"off, heat, eco, on, auto"` that will be translated to `"OFF, COMFORT, ECO, ON, auto"`. You can specify alternative conversions using the colon sign, so that in the former example "BOOST" in openHAB would also be translated to "heat" in Google. For the translation of Google modes to openHAB always the first option after the equal sign is used. -By default the integration will provide `"off,heat,cool,on,heatcool,auto,eco"`. - -You can also set up a Thermostat for using it as a temperature sensor. To do so, create a Thermostat group and only add one item member as "thermostatTemperatureAmbient". -However, it is recommended to prefer the `TemperatureSensor` type for simple temperature reports (but currently no UI support in Google Assistant). - -#### Fans - -_Fans_ (and similar device types, like _AirPurifier_ or _Hood_) support the _FanSpeed_ trait. -With that you will be able to set up and use human speakable modes, e.g. "fast" for 100% or "slow" for 25%. - -To set up those modes use a _Dimmer_ item and the following metadata config: `[ speeds="0=away:zero,50=default:standard:one,100=high:two", lang="en", ordered=true ]`. - -_speeds_ will be a comma-separated list of modes with a percentage number followed by an equal sign and different aliases for that mode after a colon. -So here both "high" and "two" would set the speed to 100%. -You are also able to define the language of those aliases. -The option _ordered_ will tell the system that your list is ordered and you will then be able to also say "faster" or "slower" and Google will use the next or previous speed. - -#### Blinds and similar devices - -Blinds should always use the `Rollershutter` item type. -Since Google and openHAB use the oposite percentage value for "opened" or "closed", the action will tranlate this automatically. -If the values are still inverted in your case, you can state the `[ inverted=true ]` option for all `Rollershutter` items. - -Since Google only tells the open percentage (and not the verb "close" or "down"), it can not be differentiated between saying "set blind to 100%" or "open blind". -Therefore, it is not possible to "not invert" the verbs, if the user chooses to invert the numbers. - ---- - -More details about the setup and the service linkage (https://myopenhab.org) procedure within the Google App can be found in the [USAGE documentation](docs/USAGE.md). - -## Example Voice Commands +## Item Configuration, Example Voice Commands & Service Linkage -Here are some example voice commands: +For details on how to configure your items and which voice commands you can use, please see the [USAGE documentation](docs/USAGE.md). -* Turn on Office Lights -* Dim/Brighten Office Lights (increments 15%) -* Set Office Lights to 35% -* Open/Close the blinds -* Turn off Pool Waterfall -* Turn on House Fan -* Turn on Home Theater Scene -* Set Basement Thermostat to 15 degrees -* What is the current Basement Thermostat Temperature? +In addition, you can also find information there on how to set up service linking with https://myopenhab.org within the Google Home App. ## Logging & Debugging From dd7b086d880e771a1b3239032098988b95295401 Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Mon, 8 Mar 2021 21:19:20 +0100 Subject: [PATCH 05/13] Minor changes, use shell as code highlighting Signed-off-by: Michael Krug --- README.md | 8 ++++---- docs/USAGE.md | 26 +++++++++++++------------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index e2ea0f06..2452897e 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ The Google related parts of any Smart Home action rely on Google Home Graph, a d * Enable the Cloud Functions API and install the Google Cloud SDK by following this [quickstart](https://cloud.google.com/functions/docs/quickstart) * gactions CLI (https://developers.google.com/actions/tools/gactions-cli) -```console +```shell curl -O https://dl.google.com/gactions/updates/bin/linux/amd64/gactions/gactions chmod +x gactions ``` @@ -54,7 +54,7 @@ See [The Client ID and Secret - OAuth](https://www.oauth.com/oauth2-servers/clie * SSH into to your openHAB Cloud instance * Open the MongoDB client `mongo` and enter these commands -```console +```shell use openhab db.oauth2clients.insert({ clientId: "", clientSecret: ""}) db.oauth2scopes.insert({ name: "any"}) @@ -118,7 +118,7 @@ If you want to deploy your action in a foreign language, add locale parameter to * Afterwards deploy this action file using the following command: -```console +```shell gactions update --action_package action.json --project ``` @@ -194,7 +194,7 @@ In addition, you can also find information there on how to set up service linkin To check your deployed openHAB Google Cloud function app logs and debugging use the following command: -```console +```shell gcloud beta functions logs read openhabGoogleAssistant ``` diff --git a/docs/USAGE.md b/docs/USAGE.md index 03246932..7987d62e 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -324,7 +324,7 @@ NOTE: metadata is not available via paperUI in openHAB v2. Either you create you * add metadata via console: - ```console + ```shell smarthome:metadata add BedroomLights ga Light ``` @@ -354,7 +354,7 @@ _pinNeeded_: "A two-factor authentication that requires a personal identificatio Example: ```shell -Switch DoorLock "Front Door" { ga="Lock" [ ackNeeded=true ] } +Switch DoorLock "Front Door" { ga="Lock" [ ackNeeded=true ] } Switch HouseAlarm "House Alarm" { ga="SecuritySystem" [ pinNeeded="1234" ] } ``` @@ -426,23 +426,23 @@ I'm not able to connect openHAB to Google Home. * The items that you want to expose to Google Assistant should have the right metadata assigned. * The items that you want to expose to Google Assistant must have a item label! [Item Definition and Syntax](https://www.openhab.org/docs/configuration/items.html#item-definition-and-syntax) * If you expose thermostats make sure than you have: - * A group item with the metadata value { ga="Thermostat" } - * A number or string item with the metadata value { ga="thermostatMode" } as part of the thermostat group - * A number item with the metadata value { ga="thermostatTemperatureAmbient" } as part of the thermostat group - * A number item with the metadata value { ga="thermostatTemperatureSetpoint" } as part of the thermostat group - - ```js - Group g_HK_Basement_TSTAT "Basement Thermostat" { ga="Thermostat" [ useFahrenheit=true ] } - Number HK_Basement_Mode "Basement Heating/Cooling Mode" (g_HK_Basement_TSTAT) { ga="thermostatMode" } - Number HK_Basement_Setpoint "Basement Setpoint" (g_HK_Basement_TSTAT) { ga="thermostatTemperatureSetpoint" } - Number HK_Basement_Temp "Basement Temperature" (g_HK_Basement_TSTAT) { ga="thermostatTemperatureAmbient" } + * A Group item with the metadata value `{ ga="Thermostat" }` + * A Number or String item with the metadata value `{ ga="thermostatMode" }` as part of the thermostat group + * A Number item with the metadata value `{ ga="thermostatTemperatureAmbient" }` as part of the thermostat group + * A Number item with the metadata value `{ ga="thermostatTemperatureSetpoint" }` as part of the thermostat group + + ```shell + Group g_HK_Basement_TSTAT "Basement Thermostat" { ga="Thermostat" [ useFahrenheit=true ] } + Number HK_Basement_Mode "Basement Heating/Cooling Mode" (g_HK_Basement_TSTAT) { ga="thermostatMode" } + Number HK_Basement_Setpoint "Basement Setpoint" (g_HK_Basement_TSTAT) { ga="thermostatTemperatureSetpoint" } + Number HK_Basement_Temp "Basement Temperature" (g_HK_Basement_TSTAT) { ga="thermostatTemperatureAmbient" } ``` * If none of the above solutions works for you: * Remove all the metadata. * Make a new .item file with 1 item to expose. - ```js + ```shell Switch TestLight "Test Light" { ga="Switch" } ``` From 3b6fcee4062f1a6d2e5552a82f833547018e1dec Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Tue, 23 Mar 2021 19:22:40 +0100 Subject: [PATCH 06/13] Minor consistency change Signed-off-by: Michael Krug --- docs/USAGE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index 7987d62e..fba93c55 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -41,7 +41,7 @@ _Hint: The value of `ga` is **not** case-sensitive._ | **Device Type** | [Switch](https://developers.google.com/assistant/smarthome/guides/switch) | | **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff) | | **Supported Items** | Switch | -| **Configuration** | (optional) `inverted (boolean)` | +| **Configuration** | (optional) `inverted=true/false` | **Example:** @@ -56,7 +56,7 @@ Switch { ga="Switch" [ inverted=false ] } | **Device Type** | [Light](https://developers.google.com/assistant/smarthome/guides/light) | | **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [ColorSetting](https://developers.google.com/assistant/smarthome/traits/colorsetting), [Brightness](https://developers.google.com/assistant/smarthome/traits/brightness) (depending on used item type) | | **Supported Items** | Switch, Dimmer, Color | -| **Configuration** | (optional) `inverted=true/false`
(optional) `colorTemperatureRange=minK,maxK` | +| **Configuration** | (optional) `inverted=true/false`
(optional) `colorTemperatureRange="minK,maxK"` | ```shell Switch { ga="Light" [ inverted=true ] } @@ -71,7 +71,7 @@ Color { ga="Light" [ colorTemperatureRange="2000,9000" ] } | **Device Type** | [Light](https://developers.google.com/assistant/smarthome/guides/light) | | **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [ColorSetting](https://developers.google.com/assistant/smarthome/traits/colorsetting), [Brightness](https://developers.google.com/assistant/smarthome/traits/brightness) | | **Supported Items** | Group as `light` with two Number or Dimmer members as `lightBrightness` & `lightColorTemperature` | -| **Configuration** | (optional) `useKelvin=true/false`
(optional) `colorTemperatureRange=minK,maxK`
_Hint: if you do not set `useKelvin=true` then `colorTemperatureRange` is required_ | +| **Configuration** | (optional) `useKelvin=true/false`
(optional) `colorTemperatureRange="minK,maxK"`
_Hint: if you do not set `useKelvin=true` then `colorTemperatureRange` is required_ | ```shell Group lightGroup { ga="Light" [ useKelvin=true, colorTemperatureRange="2000,9000" ] } From 9fdc2e1d452911a19d17436a65d2210fe6777a04 Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Wed, 24 Mar 2021 21:43:37 +0100 Subject: [PATCH 07/13] Add documentation for new AppSelector trait Signed-off-by: Michael Krug --- docs/USAGE.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index fba93c55..f5e62405 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -193,18 +193,19 @@ Dimmer { ga="Speaker" [ volumeDefaultPercentage="50", levelStepSize="10", volume | | | |---|---| | **Device Type** | [TV](https://developers.google.com/assistant/smarthome/guides/tv) | -| **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [Volume](https://developers.google.com/assistant/smarthome/traits/volume), [TransportControl](https://developers.google.com/assistant/smarthome/traits/transportcontrol), [InputSelector](https://developers.google.com/assistant/smarthome/traits/inputselector), [Channel](https://developers.google.com/assistant/smarthome/traits/channel) (depending on used members) | -| **Supported Items** | Group as `TV` with the following optional members: Switch as `tvPower`, Switch as `tvMute`, Dimmer as `tvVolume`, String as `tvChannel`, String as `tvInput`, Player as `tvTransport` | -| **Configuration** | (optional) `volumeDefaultPercentage="20"`
(optional) `levelStepSize="5"`
(optional) `volumeMaxLevel="100"`
(optional) `transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME"`
(optional) `availableInputs="hdmi1=xbox,hdmi2=settopbox"`
(optional) `availableChannels="1=Channel1=NBC,2=Channel2=CBS"` | +| **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [Volume](https://developers.google.com/assistant/smarthome/traits/volume), [TransportControl](https://developers.google.com/assistant/smarthome/traits/transportcontrol), [InputSelector](https://developers.google.com/assistant/smarthome/traits/inputselector), [AppSelector](https://developers.google.com/assistant/smarthome/traits/appselector), [Channel](https://developers.google.com/assistant/smarthome/traits/channel) (depending on used members) | +| **Supported Items** | Group as `TV` with the following optional members: Switch as `tvPower`, Switch as `tvMute`, Dimmer as `tvVolume`, String as `tvChannel`, String as `tvInput`, String as `tvApplication`, Player as `tvTransport` | +| **Configuration** | (optional) `volumeDefaultPercentage="20"`
(optional) `levelStepSize="5"`
(optional) `volumeMaxLevel="100"`
(optional) `transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME"`
(optional) `availableChannels="channelNumber=channelId=channelName:channelSynonym:...,..."`
(optional) `availableInputs="inputKey=inputName:inputSynonym:...,..."`
(optional) `availableApplications="applicationKey=applicationName:applicationSynonym:...,..."`
(optional) `lang="en\|de\|..."` | ```shell -Group tvGroup { ga="TV" [ volumeDefaultPercentage="20", levelStepSize="10", volumeMaxLevel="100", transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME", availableInputs="hdmi1=xbox,hdmi2=settopbox", availableChannels="1=Channel1=NBC,2=Channel2=CBS" ] } -Switch powerItem (tvGroup) { ga="tvPower" } -Switch muteItem (tvGroup) { ga="tvMute" } -Dimmer volumeItem (tvGroup) { ga="tvVolume" } -String channelItem (tvGroup) { ga="tvChannel" } -String inputItem (tvGroup) { ga="tvInput" } -Player transportItem (tvGroup) { ga="tvTransport" } +Group tvGroup { ga="TV" [ volumeDefaultPercentage="20", levelStepSize="10", volumeMaxLevel="100", transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME", availableChannels="1=Channel1=NBC,2=Channel2=CBS", availableInputs="hdmi1=xbox:gaming,hdmi2=settopbox", availableApplications: "youtube=YouTube:Tube,netflix=Netflix:Chill" ] } +Switch powerItem (tvGroup) { ga="tvPower" } +Switch muteItem (tvGroup) { ga="tvMute" } +Dimmer volumeItem (tvGroup) { ga="tvVolume" } +String channelItem (tvGroup) { ga="tvChannel" } +String inputItem (tvGroup) { ga="tvInput" } +String applicationItem (tvGroup) { ga="tvApplication" } +Player transportItem (tvGroup) { ga="tvTransport" } ``` #### `Fan`, `Hood`, `AirPurifier` @@ -214,7 +215,7 @@ Player transportItem (tvGroup) { ga="tvTransport" } | **Device Type** | [Fan](https://developers.google.com/assistant/smarthome/guides/fan), [Hood](https://developers.google.com/assistant/smarthome/guides/hood), [AirPurifier](https://developers.google.com/assistant/smarthome/guides/airpurifier) | | **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/OnOff), [FanSpeed](https://developers.google.com/assistant/smarthome/traits/fanspeed) (depending on used item type) | | **Supported Items** | Switch (no speed control), Dimmer | -| **Configuration** | (optional) `speeds="0=away:zero,50=default:standard:one,100=high:two"`
(optional) `lang="en"`
(optional) `ordered=true/false`
_Hint: if you are using a Dimmer then `speeds` is required_ | +| **Configuration** | (optional) `speeds="0=away:zero,50=default:standard:one,100=high:two"`
(optional) `lang="en"`
(optional) `ordered=true/false`
(optional) `lang="en\|de\|..."`
_Hint: if you are using a Dimmer then `speeds` is required_ | Fans (and similar device types, like AirPurifier or Hood) support the `FanSpeed` trait. With that you will be able to set up and use human speakable modes, e.g. "fast" for 100% or "slow" for 25%. From 3654e0460b97be655189039890dfbd7e8ba26edd Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Tue, 13 Apr 2021 17:27:27 +0200 Subject: [PATCH 08/13] Add link to GitHub repo Signed-off-by: Michael Krug --- docs/USAGE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/USAGE.md b/docs/USAGE.md index f5e62405..7101ba9a 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -13,6 +13,8 @@ This guide describes step by step how to use the [openHAB Google Assistant Smart With the Action you can voice control your openHAB items and it supports lights, plugs, switches, thermostats and many more. The openHAB Action comes with multiple language support like English, German or French language. +If you have any issues, questions or an idea for additional features, please take a look at the [repository on GitHub](https://github.com/openhab/openhab-google-assistant). + ## General Configuration Instructions ::: tip From 2f99850ff57b48743af5258d83ad03adc14164ac Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Sun, 25 Apr 2021 20:00:42 +0200 Subject: [PATCH 09/13] Adjust queryOnly and discreteOnly Signed-off-by: Michael Krug --- docs/USAGE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index 7101ba9a..bc120471 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -316,10 +316,10 @@ Furthermore, you can state synonyms for the device name: `Switch KitchenLight "K To ease setting up new devices you can add a room hint: `[ roomHint="Living Room" ]`. -For devices supporting the OpenClose trait, the attributes `[ discreteOnlyOpenClose=false, queryOnlyOpenClose=false ]` can be configured. +For devices supporting the OpenClose trait, the attributes `[ discreteOnly=false, queryOnly=false ]` can be configured. -* discreteOnlyOpenClose defaults to false. When set to true, this indicates that the device must either be fully open or fully closed (that is, it does not support values between 0% and 100%). An example of such a device may be a valve. -* queryOnlyOpenClose defaults to false. Is set to true for `Contact` items. Indicates if the device can only be queried for state information and cannot be controlled. Sensors that can only report open state should set this field to true. +* `discreteOnly` defaults to false. When set to true, this indicates that the device must either be fully open or fully closed (that is, it does not support values between 0% and 100%). An example of such a device may be a valve. +* `queryOnly` defaults to false. Is set to true for `Contact` items. Indicates if the device can only be queried for state information and cannot be controlled. Sensors that can only report open state should set this field to true. --- From 1ea0731d58d165a8b5f342358838badc0e33d56f Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Sun, 25 Apr 2021 20:03:12 +0200 Subject: [PATCH 10/13] Adjust language example Signed-off-by: Michael Krug --- docs/USAGE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index bc120471..09c22f14 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -197,7 +197,7 @@ Dimmer { ga="Speaker" [ volumeDefaultPercentage="50", levelStepSize="10", volume | **Device Type** | [TV](https://developers.google.com/assistant/smarthome/guides/tv) | | **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/onoff), [Volume](https://developers.google.com/assistant/smarthome/traits/volume), [TransportControl](https://developers.google.com/assistant/smarthome/traits/transportcontrol), [InputSelector](https://developers.google.com/assistant/smarthome/traits/inputselector), [AppSelector](https://developers.google.com/assistant/smarthome/traits/appselector), [Channel](https://developers.google.com/assistant/smarthome/traits/channel) (depending on used members) | | **Supported Items** | Group as `TV` with the following optional members: Switch as `tvPower`, Switch as `tvMute`, Dimmer as `tvVolume`, String as `tvChannel`, String as `tvInput`, String as `tvApplication`, Player as `tvTransport` | -| **Configuration** | (optional) `volumeDefaultPercentage="20"`
(optional) `levelStepSize="5"`
(optional) `volumeMaxLevel="100"`
(optional) `transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME"`
(optional) `availableChannels="channelNumber=channelId=channelName:channelSynonym:...,..."`
(optional) `availableInputs="inputKey=inputName:inputSynonym:...,..."`
(optional) `availableApplications="applicationKey=applicationName:applicationSynonym:...,..."`
(optional) `lang="en\|de\|..."` | +| **Configuration** | (optional) `volumeDefaultPercentage="20"`
(optional) `levelStepSize="5"`
(optional) `volumeMaxLevel="100"`
(optional) `transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME"`
(optional) `availableChannels="channelNumber=channelId=channelName:channelSynonym:...,..."`
(optional) `availableInputs="inputKey=inputName:inputSynonym:...,..."`
(optional) `availableApplications="applicationKey=applicationName:applicationSynonym:...,..."`
(optional) `lang="en"` | ```shell Group tvGroup { ga="TV" [ volumeDefaultPercentage="20", levelStepSize="10", volumeMaxLevel="100", transportControlSupportedCommands="NEXT,PREVIOUS,PAUSE,RESUME", availableChannels="1=Channel1=NBC,2=Channel2=CBS", availableInputs="hdmi1=xbox:gaming,hdmi2=settopbox", availableApplications: "youtube=YouTube:Tube,netflix=Netflix:Chill" ] } @@ -217,7 +217,7 @@ Player transportItem (tvGroup) { ga="tvTransport" } | **Device Type** | [Fan](https://developers.google.com/assistant/smarthome/guides/fan), [Hood](https://developers.google.com/assistant/smarthome/guides/hood), [AirPurifier](https://developers.google.com/assistant/smarthome/guides/airpurifier) | | **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/OnOff), [FanSpeed](https://developers.google.com/assistant/smarthome/traits/fanspeed) (depending on used item type) | | **Supported Items** | Switch (no speed control), Dimmer | -| **Configuration** | (optional) `speeds="0=away:zero,50=default:standard:one,100=high:two"`
(optional) `lang="en"`
(optional) `ordered=true/false`
(optional) `lang="en\|de\|..."`
_Hint: if you are using a Dimmer then `speeds` is required_ | +| **Configuration** | (optional) `speeds="0=away:zero,50=default:standard:one,100=high:two"`
(optional) `lang="en"`
(optional) `ordered=true/false`
_Hint: if you are using a Dimmer then `speeds` is required_ | Fans (and similar device types, like AirPurifier or Hood) support the `FanSpeed` trait. With that you will be able to set up and use human speakable modes, e.g. "fast" for 100% or "slow" for 25%. From 7c7c75eb8bf0e891aaa3fc872e40899d485f0865 Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Sun, 25 Apr 2021 20:07:26 +0200 Subject: [PATCH 11/13] Add thermostatTemperatureSetpointLow/High Signed-off-by: Michael Krug --- docs/USAGE.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index 09c22f14..102c9573 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -280,12 +280,13 @@ Number { ga="TemperatureSensor" [ useFahrenheit=true ] } |---|---| | **Device Type** | [Thermostat](https://developers.google.com/assistant/smarthome/guides/thermostat) | | **Supported Traits** | [TemperatureSetting](https://developers.google.com/assistant/smarthome/traits/temperaturesetting) | -| **Supported Items** | Group as `Thermostat` with the following optional members: Number as `thermostatTemperatureAmbient`, Number as `thermostatTemperatureSetpoint`, Number as `thermostatHumidityAmbient`, String or Number as `thermostatMode` | +| **Supported Items** | Group as `Thermostat` with the following optional members: Number as `thermostatTemperatureAmbient`, Number as `thermostatTemperatureSetpoint`, Number as `thermostatTemperatureSetpointLow`, Number as `thermostatTemperatureSetpointHigh`, Number as `thermostatHumidityAmbient`, String or Number as `thermostatMode` | | **Configuration** | (optional) `useFahrenheit=true/false`
(optional) `thermostatTemperatureRange="10,30"`
(optional) `modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto"` | Thermostat requires a group of items to be properly configured to be used with Google Assistant. The default temperature unit is Celsius. To change the temperature unit to Fahrenheit, add the config option `useFahrenheit=true` to the thermostat group. To set the temperature range your thermostat supports, add the config option `thermostatTemperatureRange="10,30"` to the thermostat group. +If your thermostat supports a range for the setpoint you can use both `thermostatTemperatureSetpointLow` and `thermostatTemperatureSetpointHigh` instead of the single `thermostatTemperatureSetpoint` item. If your thermostat does not have a mode, you should create one and manually assign a value (e.g. heat, cool, on, etc.) to have proper functionality. @@ -298,10 +299,12 @@ However, it is recommended to prefer the `TemperatureSensor` type for simple tem ```shell Group thermostatGroup { ga="Thermostat" [ modes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto", thermostatTemperatureRange="10,30", useFahrenheit=false ] } -Number ambientItem (thermostatGroup) { ga="thermostatTemperatureAmbient" } -Number humidityItem (thermostatGroup) { ga="thermostatHumidityAmbient" } -Number setpointItem (thermostatGroup) { ga="thermostatTemperatureSetpoint" } -String modeItem (thermostatGroup) { ga="thermostatMode" } +Number ambientItem (thermostatGroup) { ga="thermostatTemperatureAmbient" } +Number humidityItem (thermostatGroup) { ga="thermostatHumidityAmbient" } +Number setpointItem (thermostatGroup) { ga="thermostatTemperatureSetpoint" } +Number setpointItemLow (thermostatGroup) { ga="thermostatTemperatureSetpointLow" } +Number setpointItemHigh (thermostatGroup) { ga="thermostatTemperatureSetpointHigh" } +String modeItem (thermostatGroup) { ga="thermostatMode" } ``` ### Addtional Information From a4a23a432b87c3c0c31a21999b74cc89c502a9ac Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Sun, 25 Apr 2021 20:21:38 +0200 Subject: [PATCH 12/13] Add sensor Signed-off-by: Michael Krug --- docs/USAGE.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/USAGE.md b/docs/USAGE.md index 102c9573..03fc170a 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -307,6 +307,22 @@ Number setpointItemHigh (thermostatGroup) { ga="thermostatTemperatureSetpointHig String modeItem (thermostatGroup) { ga="thermostatMode" } ``` +#### `Sensor` + +| | | +|---|---| +| **Device Type** | [Sensor](https://developers.google.com/assistant/smarthome/guides/sensor) | +| **Supported Traits** | [SensorState](https://developers.google.com/assistant/smarthome/traits/sensorstate) | +| **Supported Items** | Number, Dimmer | +| **Configuration** |`sensorName="SmokeLevel"`
`valueUnit="PARTS_PER_MILLION"`
`states="no smoke=10,smoke detected=50,high=90"` | + +Please see the [SensorState documentation](https://developers.google.com/assistant/smarthome/traits/sensorstate) for more details on configuration options. +For now only exact matches of the numeric value will report the descriptive state value. + +```shell +Number { ga="Sensor" [ sensorName="AirQuality", valueUnit="AQI", states"good=10,moderate=50,poor=90" ] } +``` + ### Addtional Information Item labels are not mandatory in openHAB, but for the Google Assistant Action they are absolutely necessary! From dc487a575dde3453b211e56c5e14a5ae32c96548 Mon Sep 17 00:00:00 2001 From: Michael Krug Date: Sun, 25 Apr 2021 22:29:50 +0200 Subject: [PATCH 13/13] Fix missing equal sign Signed-off-by: Michael Krug --- docs/USAGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index 03fc170a..bcd2df1a 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -320,7 +320,7 @@ Please see the [SensorState documentation](https://developers.google.com/assista For now only exact matches of the numeric value will report the descriptive state value. ```shell -Number { ga="Sensor" [ sensorName="AirQuality", valueUnit="AQI", states"good=10,moderate=50,poor=90" ] } +Number { ga="Sensor" [ sensorName="AirQuality", valueUnit="AQI", states="good=10,moderate=50,poor=90" ] } ``` ### Addtional Information