OpenHAB
/
openhab-docs
mirror of https://github.com/openhab/openhab-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated external content (Jenkins build 1185)

pull/1969/head
openHAB Build Server 2022-10-28 03:34:45 +00:00
parent 140efe7421
commit ee666a76e6
2 changed files with 33 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
_addons_bindings/groheondus/readme.md
View File

@ -20,7 +20,7 @@ The binding uses the REST API interface (the same as used by the Android App) to
## Supported Things
This binding should support all appliances from GROHE, however, only the GROHE Sense Guard is tested with it.
This binding should support all appliances from GROHE, however, only the GROHE Sense and Sense Guard is tested with it.
| Thing type | Name |
|--------------------------|--------------------------|
@ -44,18 +44,15 @@ There is only one thing and one bridge that needs to be configured together to g
### Account Bridge
The `groheondus:account` bridge is used to configure the API interface for a specific account, which is used to access the collected and saved data of your GROHE account.
You can either use your username and password combination for logging in into your GROHE account, in which case both parameters, `username` as well as `password`, are required arguments and refer to the same login credentials you used during setting up your GROHE account or while logging into the app.
Alternatively you can use a so called `refresh token` to grant openHAB access to your account without having to share your credentials with the system.
For that you need to obtain such `refresh token` from the GROHE ONDUS Api (see more on that below) and paste this string into the respective input field on the account management page you can reach from `http://<your-openHAB-domain-and-port>/groheondus`.
On this site you can also delete a previously saved `refresh token`.
The GROHE ONDUS binding also refreshes this refresh token in order to ensure that you stay logged in.
Use the same credentials as in the mobile app.
### Appliance
The `groheondus:sense` and `groheondus:senseguard` things are used to retrieve information of a specific appliance from GROHE.
This appliance needs to be connected with your GROHE ONDUS account as configured in the corresponding Account Bridge.
The appliance needs to be configured with the unique appliance ID (with the `applianceId` configuration) as well as the `roomId`
and the `locationId`. Once the account bridge is configured, the appliances in your account will be discovered as Appliance things.
The appliance needs to be configured with the unique appliance ID (with the `applianceId` configuration) as well as the `roomId` and the `locationId`.
Once the account bridge is configured, the appliances in your account will be discovered as Appliance things.
`pollingInterval` has a minimum value of 900 seconds to avoid service rate limiting.
| Configuration | Default value | Description |
|--------------------------|--------------------------|-------------------------------------------------------|
@ -63,19 +60,20 @@ and the `locationId`. Once the account bridge is configured, the appliances in y
| roomId | '' | ID of the room the appliance is in |
| locationId | '' | ID of the location (building) the appliance is in |
| pollingInterval | Retrieved from API, | Interval in seconds to get new data from the API |
| | usually 900 | The `sense` thing uses 900 by default |
| | usually 900 | The `sense` thing uses 900 by default. |
#### Channels
##### senseguard
| Channel | Type | Description |
|--------------------------|--------------------------|-------------------------------------------------------|
| name | String | The name of the appliance |
| pressure | Number:Pressure | The pressure of your water supply |
| temperature_guard | Number:Temperature | The ambient temperature of the appliance |
| valve_open | Switch | Valve switch |
| waterconsumption | Number | The amount of water used in a specific timeframe |
| Channel | Type | Description |
|---------------------------------|--------------------|--------------------------------------------------|
| name | String | The name of the appliance |
| pressure | Number:Pressure | The pressure of your water supply |
| temperature_guard | Number:Temperature | The ambient temperature of the appliance |
| valve_open | Switch | Valve switch |
| waterconsumption | Number:Volume | The amount of water used in a specific timeframe |
| waterconsumption_since_midnight | Number:Volume | The amount of water used since midnight |
##### sense
@ -86,6 +84,8 @@ and the `locationId`. Once the account bridge is configured, the appliances in y
| temperature | Number:Temperature | The ambient temperature of the appliance |
| battery | Number | The battery level of the appliance |
Note: Be aware that the Sense reports data once a day (at most), and that the value posted in the channel - however the latest - may be up to 48 hours old.
## Full Example
Things file:
@ -108,47 +108,9 @@ Items file:
String Name_Sense_Guard "Appliance Name" {channel="groheondus:senseguard:groheondus:appliance:550e8400-e29b-11d4-a716-446655440000:name"}
Number:Pressure Pressure_Sense_Guard "Pressure [%.1f %unit%]" {channel="groheondus:senseguard:groheondus:appliance:550e8400-e29b-11d4-a716-446655440000:pressure"}
Number:Temperature Temperature_Sense_Guard "Temperature [%.1f %unit%]" {channel="groheondus:senseguard:groheondus:appliance:550e8400-e29b-11d4-a716-446655440000:temperature_guard"}
Number:Volume Water_Usage_Since_Midnight_Sense_Guard "Water usage since midnight [%.1f %unit%]" {channel="groheondus:senseguard:groheondus:appliance:550e8400-e29b-11d4-a716-446655440000:waterconsumption_since_midnight"}
String Name_Sense "Temperature [%.1f %unit%]" {channel="groheondus:sense:groheondus:appliance:444e8400-e29b-11d4-a716-446655440000:name"}
Number:Temperature Temperature_Sense "Temperature [%.1f %unit%]" {channel="groheondus:sense:groheondus:appliance:444e8400-e29b-11d4-a716-446655440000:temperature"}
Number Humidity_Sense "Humidity [%.1f %unit%]" {channel="groheondus:sense:groheondus:appliance:444e8400-e29b-11d4-a716-446655440000:humidity"}
````
## Obtaining a `refresh token`
Actually obtaining a `refresh token` from the GROHE ONDUS Api requires some manual steps.
In order to more deeply understand what is happening during the process, you can read more information about the OAuth2/OIDC (OpenID Connect) login flow by searching for these terms in your favorite search engine.
Here is a short step-by-step guide on how to obtain a refresh token:
1. Open a new tab in your Internet browser
2. Open the developer console of your browser (mostly possible by pressing F12)
3. Select the network tab of the developer console (which shows you the network request done by the browser)
4. Open the following URL: https://idp2-apigw.cloud.grohe.com/v3/iot/oidc/login
5. You will automatically being redirected to the GROHE ONDUS login page, login there
6. After logging in successfully, nothing should happen, except a failed request to a page starting with `token?`
7. Click on this request (the URL in the request overview should start with `ondus://idp2-apigw.cloud.grohe.com/v3/iot/oidc/token?` or something like that
8. Copy the whole request URL (which should contain a lot of stuff, like a `state` parameter and so on)
9. Open a new tab in your Internet browser and paste the URL into the address bar (do not hit ENTER or start the navigation to this page, yet)
10. Replace the `ondus://` part of the URL with `https://` and hit ENTER
11. The response of the page should be plain text with a so called `JSON object`. Somewhere in the text should be a `refresh_token` string, select the string after this `refresh_token` text, which is encapsulated with `"`.
E.g.: If the response of the page looks like this:
````
{
"access_token": "the_access_token",
"expires_in":3600,
"refresh_expires_in":15552000,
"refresh_token":"the_refresh_token",
"token_type":"bearer",
"id_token":"the_id_token",
"not-before-policy":0,
"session_state":"a-state",
"scope":"",
"tandc_accepted":true,
"partialLogin":false
}
````
Then the `refresh_token` value you should copy would be: `the_refresh_token`.
This value is the `refresh token` you should save as described above.

23
_thing_types/org.openhab.binding.groheondus/src/main/resources/OH-INF/thing/thing-types.xml
View File

@ -7,7 +7,8 @@
<bridge-type id="account">
<label>GROHE ONDUS Account</label>
<description>This is an interface to the GROHE ONDUS Account as it is used by the app. If username and password are
not set, you can configure to use a `refreshToken` to login. Read the README to get more info.</description>
not set, you can configure to use a `refreshToken` to login. Read the README to get more info.
</description>
<config-description>
<parameter name="username" type="text" required="false">
@ -35,6 +36,7 @@
<channel id="pressure" typeId="pressure"/>
<channel id="temperature_guard" typeId="temperature_guard"/>
<channel id="waterconsumption" typeId="waterconsumption"/>
<channel id="waterconsumption_since_midnight" typeId="waterconsumption_since_midnight"/>
<channel id="valve_open" typeId="valve_open"/>
</channels>
@ -53,10 +55,11 @@
<label>Location ID</label>
<description>The ID of the location the room is in as retrieved from the GROHE ONDUS API.</description>
</parameter>
<parameter name="pollingInterval" type="integer" required="false">
<parameter name="pollingInterval" type="integer" required="false" min="900">
<label>Polling Interval</label>
<description>The interval in seconds used to poll the API for new data. Defaults to the configuration of the
appliance itself as retrieved from the API, usually 15 minutes.</description>
appliance itself as retrieved from the API, usually 15 minutes.
</description>
</parameter>
</config-description>
</thing-type>
@ -91,7 +94,7 @@
<label>Location ID</label>
<description>The ID of the location the room is in as retrieved from the GROHE ONDUS API.</description>
</parameter>
<parameter name="pollingInterval" type="integer" required="false">
<parameter name="pollingInterval" type="integer" required="false" min="900">
<label>Polling Interval</label>
<description>The interval in seconds used to poll the API for new data.</description>
</parameter>
@ -132,10 +135,10 @@
<state readOnly="true" pattern="%.1f %unit%"/>
</channel-type>
<channel-type id="waterconsumption">
<item-type>Number</item-type>
<item-type>Number:Volume</item-type>
<label>Water Consumption</label>
<description>The amount of water consumed in the given time period.</description>
<state readOnly="true"/>
<description>The amount of water consumed in the given time period in liters.</description>
<state readOnly="true" pattern="%.1f %unit%"/>
<config-description>
<parameter name="timeframe" type="integer" min="1" max="90" step="1" required="true">
<label>Timeframe</label>
@ -144,4 +147,10 @@
</parameter>
</config-description>
</channel-type>
<channel-type id="waterconsumption_since_midnight">
<item-type>Number:Volume</item-type>
<label>Water Consumption Since Midnight</label>
<description>The amount of water consumed since midnight in liters</description>
<state readOnly="true" pattern="%.1f %unit%"/>
</channel-type>
</thing:thing-descriptions>