mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-10 23:22:02 +01:00
3b08217ff7
* #14195 Bridge and Device Discovery Bridge discovery is implemented via mDNS, local IP addresses are checked. If a GET returns the public SHC information, then this shcIpAddress is reported as a discovered bridge. Devices are always discovered after successful pairing, but a manual scan is also possible. Added unit tests for Bridge and Device Discovery. Signed-off-by: Gerd Zanker <gerd.zanker@web.de>
290 lines
17 KiB
Markdown
290 lines
17 KiB
Markdown
# Bosch Smart Home Binding
|
|
|
|
Binding for the Bosch Smart Home.
|
|
|
|
- [Bosch Smart Home Binding](#bosch-smart-home-binding)
|
|
- [Supported Things](#supported-things)
|
|
- [In-Wall Switch](#in-wall-switch)
|
|
- [Compact Smart Plug](#compact-smart-plug)
|
|
- [Twinguard Smoke Detector](#twinguard-smoke-detector)
|
|
- [Door/Window Contact](#doorwindow-contact)
|
|
- [Motion Detector](#motion-detector)
|
|
- [Shutter Control](#shutter-control)
|
|
- [Thermostat](#thermostat)
|
|
- [Climate Control](#climate-control)
|
|
- [Wall Thermostat](#wall-thermostat)
|
|
- [Security Camera 360](#security-camera-360)
|
|
- [Security Camera Eyes](#security-camera-eyes)
|
|
- [Intrusion Detection System](#intrusion-detection-system)
|
|
- [Smart Bulb](#smart-bulb)
|
|
- [Smoke Detector](#smoke-detector)
|
|
- [Limitations](#limitations)
|
|
- [Discovery](#discovery)
|
|
- [Bridge Configuration](#bridge-configuration)
|
|
- [Getting the device IDs](#getting-the-device-ids)
|
|
- [Thing Configuration](#thing-configuration)
|
|
- [Item Configuration](#item-configuration)
|
|
|
|
## Supported Things
|
|
|
|
### In-Wall Switch
|
|
|
|
A simple light control.
|
|
|
|
**Thing Type ID**: `in-wall-switch`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| ------------------ | ------------- | :------: | ------------------------------------------------ |
|
|
| power-switch | Switch | ☑ | Current state of the switch. |
|
|
| power-consumption | Number:Power | ☐ | Current power consumption (W) of the device. |
|
|
| energy-consumption | Number:Energy | ☐ | Cumulated energy consumption (Wh) of the device. |
|
|
|
|
### Compact Smart Plug
|
|
|
|
A compact smart plug with energy monitoring capabilities.
|
|
|
|
**Thing Type ID**: `smart-plug-compact`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| ------------------ | ------------- | :------: | ------------------------------------------------ |
|
|
| power-switch | Switch | ☑ | Current state of the switch. |
|
|
| power-consumption | Number:Power | ☐ | Current power consumption (W) of the device. |
|
|
| energy-consumption | Number:Energy | ☐ | Cumulated energy consumption (Wh) of the device. |
|
|
|
|
### Twinguard Smoke Detector
|
|
|
|
The Twinguard smoke detector warns you in case of fire and constantly monitors the air.
|
|
|
|
**Thing Type ID**: `twinguard`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| ------------------ | -------------------- | :------: | ------------------------------------------------------------------------------------------------- |
|
|
| temperature | Number:Temperature | ☐ | Current measured temperature. |
|
|
| temperature-rating | String | ☐ | Rating of the currently measured temperature. |
|
|
| humidity | Number:Dimensionless | ☐ | Current measured humidity (0 to 100). |
|
|
| humidity-rating | String | ☐ | Rating of current measured humidity. |
|
|
| purity | Number:Dimensionless | ☐ | Purity of the air (ppm). Range from 500 to 5500 ppm. A higher value indicates a higher pollution. |
|
|
| purity-rating | String | ☐ | Rating of current measured purity. |
|
|
| air-description | String | ☐ | Overall description of the air quality. |
|
|
| combined-rating | String | ☐ | Combined rating of the air quality. |
|
|
| battery-level | Number | ☐ | Current battery level percentage as integer number. Bosch-specific battery levels are mapped to numbers as follows: `OK`: 100, `LOW_BATTERY`: 10, `CRITICAL_LOW`: 1, `CRITICALLY_LOW_BATTERY`: 1, `NOT_AVAILABLE`: `UNDEF`. |
|
|
| low-battery | Switch | ☐ | Indicates whether the battery is low (`ON`) or OK (`OFF`). |
|
|
| smoke-check | String | ☑ | State of the smoke check. Also used to request a new smoke check. |
|
|
|
|
### Door/Window Contact
|
|
|
|
Detects open windows and doors.
|
|
|
|
**Thing Type ID**: `window-contact`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| --------------- | --------- | :------: | ---------------------------- |
|
|
| contact | Contact | ☐ | Contact state of the device. |
|
|
| battery-level | Number | ☐ | Current battery level percentage as integer number. Bosch-specific battery levels are mapped to numbers as follows: `OK`: 100, `LOW_BATTERY`: 10, `CRITICAL_LOW`: 1, `CRITICALLY_LOW_BATTERY`: 1, `NOT_AVAILABLE`: `UNDEF`. |
|
|
| low-battery | Switch | ☐ | Indicates whether the battery is low (`ON`) or OK (`OFF`). |
|
|
|
|
### Motion Detector
|
|
|
|
Detects every movement through an intelligent combination of passive infra-red technology and an additional temperature sensor.
|
|
|
|
**Thing Type ID**: `motion-detector`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| --------------- | --------- | :------: | ------------------------------ |
|
|
| latest-motion | DateTime | ☐ | The date of the latest motion. |
|
|
| battery-level | Number | ☐ | Current battery level percentage as integer number. Bosch-specific battery levels are mapped to numbers as follows: `OK`: 100, `LOW_BATTERY`: 10, `CRITICAL_LOW`: 1, `CRITICALLY_LOW_BATTERY`: 1, `NOT_AVAILABLE`: `UNDEF`. |
|
|
| low-battery | Switch | ☐ | Indicates whether the battery is low (`ON`) or OK (`OFF`). |
|
|
|
|
### Shutter Control
|
|
|
|
Control of your shutter to take any position you desire.
|
|
|
|
**Thing Type ID**: `shutter-control`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| --------------- | ------------- | :------: | ---------------------------------------- |
|
|
| level | Rollershutter | ☑ | Current open ratio (0 to 100, Step 0.5). |
|
|
|
|
### Thermostat
|
|
|
|
Radiator thermostat
|
|
|
|
**Thing Type ID**: `thermostat`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| --------------------- | -------------------- | :------: | ---------------------------------------------- |
|
|
| temperature | Number:Temperature | ☐ | Current measured temperature. |
|
|
| valve-tappet-position | Number:Dimensionless | ☐ | Current open ratio of valve tappet (0 to 100). |
|
|
| child-lock | Switch | ☑ | Indicates if child lock is active. |
|
|
| battery-level | Number | ☐ | Current battery level percentage as integer number. Bosch-specific battery levels are mapped to numbers as follows: `OK`: 100, `LOW_BATTERY`: 10, `CRITICAL_LOW`: 1, `CRITICALLY_LOW_BATTERY`: 1, `NOT_AVAILABLE`: `UNDEF`. |
|
|
| low-battery | Switch | ☐ | Indicates whether the battery is low (`ON`) or OK (`OFF`). |
|
|
|
|
### Climate Control
|
|
|
|
A virtual device which controls up to six Bosch Smart Home radiator thermostats in a room.
|
|
|
|
**Thing Type ID**: `climate-control`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| -------------------- | ------------------ | :------: | ----------------------------- |
|
|
| temperature | Number:Temperature | ☐ | Current measured temperature. |
|
|
| setpoint-temperature | Number:Temperature | ☑ | Desired temperature. |
|
|
|
|
### Wall Thermostat
|
|
|
|
Display of the current room temperature as well as the relative humidity in the room.
|
|
|
|
**Thing Type ID**: `wall-thermostat`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| --------------- | -------------------- | :------: | ------------------------------------- |
|
|
| temperature | Number:Temperature | ☐ | Current measured temperature. |
|
|
| humidity | Number:Dimensionless | ☐ | Current measured humidity (0 to 100). |
|
|
| battery-level | Number | ☐ | Current battery level percentage as integer number. Bosch-specific battery levels are mapped to numbers as follows: `OK`: 100, `LOW_BATTERY`: 10, `CRITICAL_LOW`: 1, `CRITICALLY_LOW_BATTERY`: 1, `NOT_AVAILABLE`: `UNDEF`. |
|
|
| low-battery | Switch | ☐ | Indicates whether the battery is low (`ON`) or OK (`OFF`). |
|
|
|
|
### Security Camera 360
|
|
|
|
Indoor security camera with 360° view and motion detection.
|
|
|
|
**Thing Type ID**: `security-camera-360`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| --------------------- | -------------------- | :------: | ------------------------------------------------------------------ |
|
|
| privacy-mode | Switch | ☑ | If privacy mode is enabled, the camera is disabled and vice versa. |
|
|
| camera-notification | Switch | ☑ | Enables or disables notifications for the camera. |
|
|
|
|
### Security Camera Eyes
|
|
|
|
Outdoor security camera with motion detection and light.
|
|
|
|
**Thing Type ID**: `security-camera-eyes`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| --------------------- | -------------------- | :------: | ------------------------------------------------------------------ |
|
|
| privacy-mode | Switch | ☑ | If privacy mode is enabled, the camera is disabled and vice versa. |
|
|
| camera-notification | Switch | ☑ | Enables or disables notifications for the camera. |
|
|
|
|
### Intrusion Detection System
|
|
|
|
Allows to retrieve notifications in case of intrusions. The system can be armed and disarmed and alarms can be muted.
|
|
|
|
**Thing Type ID**: `intrusion-detection-system`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| ---------------------------- | -------------------- | :------: | -------------------------------------------------------------- |
|
|
| system-availability | Switch | ☐ | Indicates whether the intrusion detection system is available. |
|
|
| arming-state | String | ☐ | Read-only channel to retrieve the current arming state. Possible values are `SYSTEM_ARMING`, `SYSTEM_ARMED` and `SYSTEM_DISARMED`. |
|
|
| alarm-state | String | ☐ | Read-only channel to retrieve the current alarm state. Possible values are `ALARM_OFF`, `PRE_ALARM`, `ALARM_ON`, `ALARM_MUTED` and `UNKNOWN`. |
|
|
| active-configuration-profile | String | ☐ | The name of the active configuration profile used for the intrusion detection system. |
|
|
| arm-action | String | ☑ | Arms the intrusion detection system using the given profile ID (default is "0"). |
|
|
| disarm-action | Switch | ☑ | Disarms the intrusion detection system when an ON command is received. |
|
|
| mute-action | Switch | ☑ | Mutes the alarm when an ON command is received. |
|
|
|
|
### Smart Bulb
|
|
|
|
A smart bulb connected to the bridge via Zigbee such as a Ledvance Smart+ bulb.
|
|
|
|
**Thing Type ID**: `smart-bulb`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| ----------------| --------- | :------: | -------------------------------------------------------------- |
|
|
| power-switch | Switch | ☑ | Switches the light on or off. |
|
|
| brightness | Dimmer | ☑ | Regulates the brightness on a percentage scale from 0 to 100%. |
|
|
| color | Color | ☑ | The color of the emitted light. |
|
|
|
|
### Smoke detector
|
|
|
|
The smoke detector warns you in case of fire.
|
|
|
|
**Thing Type ID**: `smoke-detector`
|
|
|
|
| Channel Type ID | Item Type | Writable | Description |
|
|
| ------------------ | -------------------- | :------: | ------------------------------------------------------------------------------------------------- |
|
|
| smoke-check | String | ☑ | State of the smoke check. Also used to request a new smoke check. |
|
|
|
|
|
|
## Limitations
|
|
|
|
No major limitation known.
|
|
Check list of [openhab issues with "boshshc"](https://github.com/openhab/openhab-addons/issues?q=is%3Aissue+boschshc+)
|
|
|
|
## Discovery
|
|
|
|
Bridge discovery is supported via mDNS.
|
|
Things discovery is started after successful pairing.
|
|
|
|
Configuration via configuration files or UI supported too (see below).
|
|
|
|
## Bridge Configuration
|
|
|
|
You need to provide the IP address and the system password of your Bosch Smart Home Controller.
|
|
The IP address of the controller is visible in the Bosch Smart Home Mobile App (More -> System -> Smart Home Controller) or in your network router UI.
|
|
The system password is set by you during your initial registration steps in the _Bosch Smart Home App_.
|
|
|
|
A keystore file with a self-signed certificate is created automatically.
|
|
This certificate is used for pairing between the Bridge and the Bosch Smart Home Controller.
|
|
|
|
_Press and hold the Bosch Smart Home Controller Bridge button until the LED starts blinking after you save your settings for pairing_.
|
|
|
|
## Getting the device IDs
|
|
|
|
Bosch IDs for found devices are displayed in the openHAB log on bootup (`OPENHAB_FOLDER/userdata/logs/openhab.log`)
|
|
|
|
The log can also be called using the following command.
|
|
|
|
```bash
|
|
tail -f /var/log/openhab/openhab.log /var/log/openhab/events.log
|
|
```
|
|
|
|
Alternatively, the log can be viewed using the OpenHab Log Viewer (frontail) via <http://openhab:9001>.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
2023-03-20 20:30:48.026 [INFO ] [g.discovery.internal.PersistentInbox] - Added new thing 'boschshc:security-camera-eyes:yourBridgeName:hdm_Cameras_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' to inbox.
|
|
2023-03-20 20:30:48.026 [INFO ] [g.discovery.internal.PersistentInbox] - Added new thing 'boschshc:smoke-detector:yourBridgeName:hdm_HomeMaticIP_XXXXXXXXXXXXXXXXXXXXXXXX' to inbox.
|
|
2023-03-20 20:30:48.027 [INFO ] [g.discovery.internal.PersistentInbox] - Added new thing 'boschshc:twinguard:yourBridgeName:hdm_ZigBee_XXXXXXXXXXXXXXXX' to inbox.
|
|
2023-03-20 20:30:48.028 [INFO ] [g.discovery.internal.PersistentInbox] - Added new thing 'boschshc:smart-bulb:yourBridgeName:hdm_PhilipsHueBridge_HueLight_XXXXXXXXXXXXXXXX-XX_XXXXXXXXXXXX' to inbox.
|
|
```
|
|
|
|
## Thing Configuration
|
|
|
|
You define your Bosch devices by adding them either to a `.things` file in your `$OPENHAB_CONF/things` folder like this:
|
|
|
|
```java
|
|
Bridge boschshc:shc:1 [ ipAddress="192.168.x.y", password="XXXXXXXXXX" ] {
|
|
Thing in-wall-switch bathroom "Bathroom" [ id="hdm:HomeMaticIP:3014F711A000XXXXXXXXXXXX" ]
|
|
Thing in-wall-switch bedroom "Bedroom" [ id="hdm:HomeMaticIP:3014F711A000XXXXXXXXXXXX" ]
|
|
Thing in-wall-switch kitchen "Kitchen" [ id="hdm:HomeMaticIP:3014F711A000XXXXXXXXXXXX" ]
|
|
Thing in-wall-switch corridor "Corridor" [ id="hdm:HomeMaticIP:3014F711A000XXXXXXXXXXXX" ]
|
|
Thing in-wall-switch livingroom "Living Room" [ id="hdm:HomeMaticIP:3014F711A000XXXXXXXXXXXX" ]
|
|
|
|
Thing in-wall-switch coffeemachine "Coffee Machine" [ id="hdm:HomeMaticIP:3014F711A0000XXXXXXXXXXXX" ]
|
|
|
|
Thing twinguard tg-corridor "Twinguard Smoke Detector" [ id="hdm:ZigBee:000d6f000XXXXXXX" ]
|
|
Thing window-contact window-kitchen "Window Kitchen" [ id="hdm:HomeMaticIP:3014F711A00000XXXXXXXXXX" ]
|
|
Thing window-contact entrance "Entrance door" [ id="hdm:HomeMaticIP:3014F711A00000XXXXXXXXXX" ]
|
|
|
|
Thing motion-detector motion-corridor "Bewegungsmelder" [ id="hdm:ZigBee:000d6f000XXXXXXX" ]
|
|
}
|
|
```
|
|
|
|
Or by adding them via UI: Settings -> Things -> "+" -> Bosch Smart Home Binding.
|
|
|
|
## Item Configuration
|
|
|
|
You define the items which should be linked to your Bosch devices via a `.items` file in your `$OPENHAB_CONF/items` folder like this:
|
|
|
|
```java
|
|
Switch Bosch_Bathroom "Bath Room" { channel="boschshc:in-wall-switch:1:bathroom:power-switch" }
|
|
Switch Bosch_Bedroom "Bed Room" { channel="boschshc:in-wall-switch:1:bedroom:power-switch" }
|
|
Switch Bosch_Kitchen "Kitchen" { channel="boschshc:in-wall-switch:1:kitchen:power-switch" }
|
|
Switch Bosch_Corridor "Corridor" { channel="boschshc:in-wall-switch:1:corridor:power-switch" }
|
|
Switch Bosch_Living_Room "Living Room" { channel="boschshc:in-wall-switch:1:livingroom:power-switch" }
|
|
|
|
Switch Bosch_Lelit "Lelit" { channel="boschshc:in-wall-switch:1:coffeemachine:power-switch" }
|
|
```
|
|
|
|
Or by adding them via UI: Settings -> Items -> "+".
|