diff --git a/_ecosystem/google-assistant/readme.md b/_ecosystem/google-assistant/readme.md index aa95dbb34..67630e69e 100644 --- a/_ecosystem/google-assistant/readme.md +++ b/_ecosystem/google-assistant/readme.md @@ -24,9 +24,15 @@ If you have any issues, questions or an idea for additional features, please tak ## Latest Changes ::: tip State of this document -This documentation refers to release [v5.0.2](https://github.com/openhab/openhab-google-assistant/releases/tag/v5.0.2) of [openHAB Google Assistant](https://github.com/openhab/openhab-google-assistant) published on 2025-12-21 +This documentation refers to release [v5.1.0](https://github.com/openhab/openhab-google-assistant/releases/tag/v5.1.0) of [openHAB Google Assistant](https://github.com/openhab/openhab-google-assistant) published on 2026-03-21 ::: +### v5.1.0 + +- Added [`Washer`](#washer-and-dishwasher-as-group-with-cycle-information) support, including advanced group configuration with cycle information +- Improved command validation and state checks (including humidity, rotation and thermostat flows) +- Standardized Google error propagation with `GoogleAssistantError` across command handling + ### v5.0.1 - Added [`Humidifier`](#humidifier) device type with humidity control and fan speed support @@ -185,6 +191,33 @@ Color colorItem2 (colorItems) ... ``` +### Light with Modes support + +| | | +|---|---| +| **Device Type** | [Light](https://developers.home.google.com/cloud-to-cloud/guides/light) | +| **Supported Traits** | [Modes](https://developers.home.google.com/cloud-to-cloud/traits/modes) | +| **Supported Items** | Switch, Dimmer, Number, String, Color, Rollershutter, Player (static modes)
Group with `modesCurrentMode` and `modesSettings` members (dynamic modes) | +| **Configuration** | (required) `mode="ModeName,ModeAlias"`
(required) `settings="value1=Name1:Synonym1,value2=Name2"` _(static)_ or `modesSettings` member _(dynamic)_
(optional) `lang="en"`
(optional) `ordered=true/false` | + +Any item with `ga="Light"` extended with `mode` and `settings` configuration options will present a Light device with the [Modes](https://developers.home.google.com/cloud-to-cloud/traits/modes) trait. +The item's state value is used directly as the mode setting key when executing a command. + +`mode` is a comma-separated list of names for the mode — the first entry is the mode key used internally, any additional entries are treated as synonyms. +`settings` is a comma-separated list of `value=Name:Synonym` pairs, where `value` is the raw state value sent to/read from the openHAB item. + +For Group-based lights with dynamic mode settings (where available modes are read from an openHAB item at runtime), use a Group with a `modesSettings` string member encoding the available settings, and a `modesCurrentMode` member holding the current setting. + +```shell +# Static modes: item state maps directly to a mode setting value +String lightModeItem { ga="Light" [ mode="LightEffect,Effect", settings="1=Relax:Warm,2=Focus:Cool,3=Party:RGB", lang="en" ] } + +# Dynamic modes: settings are read from a group member at runtime +Group lightGroup { ga="Light" [ mode="LightEffect,Effect", lang="en" ] } +String currentModeItem (lightGroup) { ga="modesCurrentMode" } +String settingsItem (lightGroup) { ga="modesSettings" } # state e.g. "1=Relax:Warm,2=Focus:Cool" +``` + ### Scene | | | @@ -261,6 +294,24 @@ Number vacuumBatteryItem (vacuumRobot) { ga="vacuumBattery" } String vacuumCycleItem (vacuumRobot) { ga="vacuumCurrentCycle" } ``` +### Washer and Dishwasher as Group with cycle information + +| | | +|---|---| +| **Device Type** | [Washer](https://developers.home.google.com/cloud-to-cloud/guides/washer), [Dishwasher](https://developers.home.google.com/cloud-to-cloud/guides/dishwasher) | +| **Supported Traits** | [StartStop](https://developers.home.google.com/cloud-to-cloud/traits/startstop), [RunCycle](https://developers.home.google.com/cloud-to-cloud/traits/runcycle) | +| **Supported Items** | Group as `Washer` or `Dishwasher` with at least one of the following members:
(optional) Switch as `washerPower`
(optional) Number as `washerTimerRemaining`
(optional) String as `washerCurrentCycle` | +| **Configuration** | (optional) `inverted=true/false`
(optional) `checkState=true/false` | + +```shell +Group washerDevice { ga="Washer" [ checkState=true ] } +Switch washerPowerItem (washerDevice) { ga="washerPower" } +Number washerTimerRemainingItem (washerDevice) { ga="washerTimerRemaining" } +String washerCurrentCycleItem (washerDevice) { ga="washerCurrentCycle" } +``` + +You can configure a dishwasher the same way; just change the group metadata to `ga="Dishwasher"` while keeping the same member tags (`washerPower`, `washerTimerRemaining`, `washerCurrentCycle`). + ### Lock | | | @@ -301,7 +352,7 @@ Switch houseAlarm "House Alarm" { ga="SecuritySystem", pinNeeded="1234" } | **Device Type** | [SecuritySystem](https://developers.home.google.com/cloud-to-cloud/guides/securitysystem) | | **Supported Traits** | [ArmDisarm](https://developers.home.google.com/cloud-to-cloud/traits/armdisarm)
[StatusReport](https://developers.home.google.com/cloud-to-cloud/traits/statusreport) | | **Supported Items** | Group as `SecuritySystem` with the following members:
Switch as `securitySystemArmed`
(optional) String as `securitySystemArmLevel`
(optional) Switch as `securitySystemTrouble`
(optional) String as `securitySystemTroubleCode`
(optional) Contact as `securitySystemZone` | -| **Configuration** | (optional) `inverted=true/false`
(optional) `checkState=true/false`
(optional) `ackNeeded=true/false`
(optional) `pinNeeded="1234"`
(optional) `pinOnDisarmOnly=true/false`
(optional) `waitForStateChange="2"`
(optional) `armLevels="L1=Level 1,L2=Level 2"`

Specifically on Zone Contacts:
(required) `zoneType="OpenClose/Motion"`
(optional) `blocking=true/false`| +| **Configuration** | (optional) `inverted=true/false`
(optional) `checkState=true/false`
(optional) `ackNeeded=true/false`
(optional) `pinNeeded="1234"`
(optional) `pinOnDisarmOnly=true/false`
(optional) `waitForStateChange="2"`
(optional) `armLevels="L1=Level 1,L2=Level 2"`
(optional) `ordered=true/false`

Specifically on Zone Contacts:
(required) `zoneType="OpenClose/Motion"`
(optional) `blocking=true/false` | Configuring the `SecuritySystem` as a Group will enable a lot of advanced functionality. @@ -316,6 +367,7 @@ The `Switch` and the `Group` configuration support the following configuration p When configured as a group, you can add arm levels as well as report errors and get details of zones causing the system to not arm. `armLevels="Key=Label"` - The label is used for commanding Google Assistant, the key is the matching value sent to openHAB. +`ordered=true` - When set together with `armLevels`, marks the arm levels as ordered, so Google understands their relative ranking. Google Command: "_Hey Google, set House Alarm to Level 1_" (L1 sent to item). @@ -367,7 +419,7 @@ Dimmer { ga="Speaker" [ volumeDefaultPercentage="50", levelStepSize="10", volume | | | |---|---| | **Device Type** | [TV](https://developers.home.google.com/cloud-to-cloud/guides/tv) | -| **Supported Traits** | [OnOff](https://developers.home.google.com/cloud-to-cloud/traits/onoff), [Volume](https://developers.home.google.com/cloud-to-cloud/traits/volume), [TransportControl](https://developers.home.google.com/cloud-to-cloud/traits/transportcontrol), [InputSelector](https://developers.home.google.com/cloud-to-cloud/traits/inputselector), [AppSelector](https://developers.home.google.com/cloud-to-cloud/traits/appselector), [Channel](https://developers.home.google.com/cloud-to-cloud/traits/channel) (depending on used members) | +| **Supported Traits** | [OnOff](https://developers.home.google.com/cloud-to-cloud/traits/onoff), [Volume](https://developers.home.google.com/cloud-to-cloud/traits/volume), [TransportControl](https://developers.home.google.com/cloud-to-cloud/traits/transportcontrol), [InputSelector](https://developers.home.google.com/cloud-to-cloud/traits/inputselector), [AppSelector](https://developers.home.google.com/cloud-to-cloud/traits/appselector), [MediaState](https://developers.home.google.com/cloud-to-cloud/traits/mediastate), [Channel](https://developers.home.google.com/cloud-to-cloud/traits/channel) (when `tvChannel` member is present) | | **Supported Items** | Group as `TV` with the following members:
(optional) Switch as `tvPower`
(optional) Switch as `tvMute`
(optional) Dimmer or Number as `tvVolume`
(optional) String or Number as `tvChannel`
(optional) String or Number as `tvInput`
(optional) String or Number as `tvApplication`
(optional) Player as `tvTransport` | | **Configuration** | (optional) `checkState=true/false`
(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"` | @@ -413,8 +465,8 @@ Switch { ga="AirPurifier" } # No speed control - only on/off | | | |---|---| -| **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), [Modes](https://developers.google.com/assistant/smarthome/traits/modes), [SensorState](https://developers.google.com/assistant/smarthome/traits/sensorstate) | +| **Device Type** | [Fan](https://developers.home.google.com/cloud-to-cloud/guides/fan), [Hood](https://developers.home.google.com/cloud-to-cloud/guides/hood), [AirPurifier](https://developers.home.google.com/cloud-to-cloud/guides/airpurifier) | +| **Supported Traits** | [OnOff](https://developers.home.google.com/cloud-to-cloud/traits/onoff), [FanSpeed](https://developers.home.google.com/cloud-to-cloud/traits/fanspeed), [Modes](https://developers.home.google.com/cloud-to-cloud/traits/modes), [SensorState](https://developers.home.google.com/cloud-to-cloud/traits/sensorstate) | | **Supported Items** | Group as `Fan`, `Hood` or `AirPurifier` with the following members:
(optional) Switch as `fanPower`
(optional) Dimmer or Number as `fanSpeed`
(optional) Number or String as `fanMode`
(optional) Number as `fanFilterLifeTime`
(optional) Number as `fanPM25` | | **Configuration** | (optional) `checkState=true/false`
(optional) `fanSpeeds="0=away:zero,50=default:standard:one,100=high:two"`
(optional) `fanModeName="OperationMode,Modus"`
(optional) `fanModeSettings="1=Low:Silent,2=Normal,3=High:Night"`
(optional) `lang="en"`
(optional) `ordered=true/false` | @@ -440,8 +492,8 @@ Number pm25Item (fanGroup) { ga="fanPM25" } | | | |---|---| -| **Device Type** | [AC_Unit](https://developers.google.com/assistant/smarthome/guides/acunit) | -| **Supported Traits** | [OnOff](https://developers.google.com/assistant/smarthome/traits/OnOff), [FanSpeed](https://developers.google.com/assistant/smarthome/traits/fanspeed), [TemperatureSetting](https://developers.google.com/assistant/smarthome/traits/temperaturesetting), [Modes](https://developers.google.com/assistant/smarthome/traits/modes), [SensorState](https://developers.google.com/assistant/smarthome/traits/sensorstate) | +| **Device Type** | [AC_Unit](https://developers.home.google.com/cloud-to-cloud/guides/acunit) | +| **Supported Traits** | [OnOff](https://developers.home.google.com/cloud-to-cloud/traits/onoff), [FanSpeed](https://developers.home.google.com/cloud-to-cloud/traits/fanspeed), [TemperatureSetting](https://developers.home.google.com/cloud-to-cloud/traits/temperaturesetting), [Modes](https://developers.home.google.com/cloud-to-cloud/traits/modes), [SensorState](https://developers.home.google.com/cloud-to-cloud/traits/sensorstate) | | **Supported Items** | Group as `AC_Unit` with the following members:
(optional) Switch as `fanPower`
(optional) Dimmer or Number as `fanSpeed`
(optional) Number or String as `fanMode`
(optional) Number as `fanFilterLifeTime`
(optional) Number as `fanPM25`
(optional) Number as `thermostatTemperatureAmbient`
(optional) Number as `thermostatTemperatureSetpoint`
(optional) Number as `thermostatTemperatureSetpointLow`
(optional) Number as `thermostatTemperatureSetpointHigh`
(optional) Number as `thermostatHumidityAmbient`
(optional) String or Number or Switch as `thermostatMode` | | **Configuration** | (optional) `checkState=true/false`
(optional) `fanSpeeds="0=away:zero,50=default:standard:one,100=high:two"`
(optional) `fanModeName="OperationMode,Modus"`
(optional) `fanModeSettings="1=Low:Silent,2=Normal,3=High:Night"`
(optional) `useFahrenheit=true/false`
(optional) `maxHumidity=1-100`
(optional) `thermostatTemperatureRange="10,30"`
(optional) `thermostatModes="off=OFF:WINDOW_OPEN,heat=COMFORT:BOOST,eco=ECO,on=ON,auto"`
(optional) `lang="en"`
(optional) `ordered=true/false` | @@ -703,7 +755,7 @@ String modeItem (thermostatGroup) { ga="thermostatMode" } |---|---| | **Device Type** | [Sensor](https://developers.home.google.com/cloud-to-cloud/guides/sensor) | | **Supported Traits** | [SensorState](https://developers.home.google.com/cloud-to-cloud/traits/sensorstate) | -| **Supported Items** | Number, Dimmer | +| **Supported Items** | Number, String, Dimmer, Switch, Rollershutter, Contact | | **Configuration** |`sensorName="SmokeLevel"`
`valueUnit="PARTS_PER_MILLION"`
`states="no smoke=10,smoke detected=50,high=90"` | Please see the [SensorState documentation](https://developers.home.google.com/cloud-to-cloud/traits/sensorstate) for more details on configuration options. @@ -723,7 +775,7 @@ If you do not want to adjust your labels to be human spellable, you can use the 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" ]`. +To ease setting up new devices you can add a room hint: `[ roomHint="Living Room" ]` or a structure hint: `[ structureHint="My Home" ]`. For devices supporting the `OnOff` trait, the attribute `[ queryOnly=true ]` can be configured. For devices supporting the `OpenClose` trait, the attributes `[ queryOnly=true, discreteOnly=true ]` can be configured.