Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

(WIP) Restructure usage documentation #196

Merged
merged 13 commits into from
Apr 30, 2021
Merged

(WIP) Restructure usage documentation #196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
417da90
Restructure usage documentation
michikrug Mar 7, 2021
0b8de52
Use line breaks for options
michikrug Mar 7, 2021
3f8a81b
Align members
michikrug Mar 7, 2021
e0d092b
Remove redundant information
michikrug Mar 8, 2021
dd7b086
Minor changes, use shell as code highlighting
michikrug Mar 8, 2021
3b6fcee
Minor consistency change
michikrug Mar 23, 2021
9fdc2e1
Add documentation for new AppSelector trait
michikrug Mar 24, 2021
3654e04
Add link to GitHub repo
michikrug Apr 13, 2021
2f99850
Adjust queryOnly and discreteOnly
michikrug Apr 25, 2021
1ea0731
Adjust language example
michikrug Apr 25, 2021
7c7c75e
Add thermostatTemperatureSetpointLow/High
michikrug Apr 25, 2021
a4a23a4
Add sensor
michikrug Apr 25, 2021
dc487a5
Fix missing equal sign
michikrug Apr 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 7 additions & 213 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand Down Expand Up @@ -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: "<CLIENT-ID>", clientSecret: "<CLIENT SECRET>"})
db.oauth2scopes.insert({ name: "any"})
Expand Down Expand Up @@ -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 <PROJECT ID>
```

Expand Down Expand Up @@ -184,223 +184,17 @@ 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" <light> (gKitchen) { ga="Switch" }
Dimmer BedroomLights "Bedroom Lights" <light> (gBedroom) { ga="Light" }
Color LivingroomLights "Livingroom Lights" <light> (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" }`
## Item Configuration, Example Voice Commands & Service Linkage

---

* `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
```
For details on how to configure your items and which voice commands you can use, please see the [USAGE documentation](docs/USAGE.md).

* 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 &nbsp;|&nbsp; 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

Here are some example voice commands:

* 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

To check your deployed openHAB Google Cloud function app logs and debugging use the following command:

```console
```shell
gcloud beta functions logs read openhabGoogleAssistant
```

Expand Down
Loading