These weather stations are white labeled products which are re-branded by many distribution companies around the world.
Some of these brands are e.g.:
-* Aercus
-* Ambient Weather
-* Ecowitt
-* ELV
-* Froggit
-* Misol
-* Pantech
-* Sainlogic
-* Steinberg Systems
-* Waldbeck Halley
+- Aercus
+- Ambient Weather
+- Ecowitt
+- ELV
+- Froggit
+- Misol
+- Pantech
+- Sainlogic
+- Steinberg Systems
+- Waldbeck Halley
Here is a product picture of how this Weather Station looks like:
## Discussion
-If you have any issues or feedback, please feel free to [get in touch via the community forum](https://community.openhab.org/t/fine-offset-weather-station-binding-discussion/134167)
+If you have any issues or feedback, please feel free to [get in touch via the community forum](https://community.openhab.org/t/fine-offset-weather-station-binding-discussion/134167)
## Supported Things
- `weatherstation`: A Fine Offset gateway device with the ThingTypeUID `fineoffsetweatherstation:weatherstation` which supports the [wire protocol](https://osswww.ecowitt.net/uploads/20220407/WN1900%20GW1000,1100%20WH2680,2650%20telenet%20v1.6.4.pdf) e.g.:
- - HP2550
- - HP3500
- - GW1000
- - GW1001
- - GW1002
- - GW1003
- - GW1100
- - GW2001
- - WN1900
- - WN1910
- - WH2350
- - WH2600
- - WH2610
- - WH2620
- - WH2650 (tested)
- - WH2680
- - WH2900
- - WH2950
- - WS980 ELV (tested)
- - WittBoy (tested)
+ - HP2550
+ - HP3500
+ - GW1000
+ - GW1001
+ - GW1002
+ - GW1003
+ - GW1100
+ - GW2001
+ - WN1900
+ - WN1910
+ - WH2350
+ - WH2600
+ - WH2610
+ - WH2620
+ - WH2650 (tested)
+ - WH2680
+ - WH2900
+ - WH2950
+ - WS980 ELV (tested)
+ - WittBoy (tested)
- `sensor`: A Fine Offset sensor which is connected to the bridge with the ThingTypeUID `fineoffsetweatherstation:sensor`.
Since the gateway collects all the sensor data and harmonizes them, the sensor thing itself will only hold information about the signal and battery status.
This is a list of sensors supported by the protocol:
Please try if here the [IPObserver binding](https://www.openhab.org/addons/bindings/ipobserver/) offers an alternative.
Known weather stations not compatible with this binding:
- - [WH3000](https://community.openhab.org/t/fine-offset-weather-station-binding-beta-and-discussion/134167/52?u=andy2003)
+- [WH3000](https://community.openhab.org/t/fine-offset-weather-station-binding-beta-and-discussion/134167/52?u=andy2003)
## Discovery
| sensor-co2-co2 | Number:Dimensionless | R | CO2 |
| sensor-co2-co2-24-hour-average | Number:Dimensionless | R | CO2 24 Hour Average |
| leaf-wetness-channel-1 | Number:Dimensionless | R | Leaf Moisture Channel 1 |
-| leaf-wetness-channel-2 | Number:Dimensionless | R | Leaf Moisture Channel 2 |
-| leaf-wetness-channel-3 | Number:Dimensionless | R | Leaf Moisture Channel 3 |
-| leaf-wetness-channel-4 | Number:Dimensionless | R | Leaf Moisture Channel 4 |
-| leaf-wetness-channel-5 | Number:Dimensionless | R | Leaf Moisture Channel 5 |
-| leaf-wetness-channel-6 | Number:Dimensionless | R | Leaf Moisture Channel 6 |
-| leaf-wetness-channel-7 | Number:Dimensionless | R | Leaf Moisture Channel 7 |
-| leaf-wetness-channel-8 | Number:Dimensionless | R | Leaf Moisture Channel 8 |
+| leaf-wetness-channel-2 | Number:Dimensionless | R | Leaf Moisture Channel 2 |
+| leaf-wetness-channel-3 | Number:Dimensionless | R | Leaf Moisture Channel 3 |
+| leaf-wetness-channel-4 | Number:Dimensionless | R | Leaf Moisture Channel 4 |
+| leaf-wetness-channel-5 | Number:Dimensionless | R | Leaf Moisture Channel 5 |
+| leaf-wetness-channel-6 | Number:Dimensionless | R | Leaf Moisture Channel 6 |
+| leaf-wetness-channel-7 | Number:Dimensionless | R | Leaf Moisture Channel 7 |
+| leaf-wetness-channel-8 | Number:Dimensionless | R | Leaf Moisture Channel 8 |
| piezo-rain-rate | Number:VolumetricFlowRate | R | Piezo - Rainfall Rate |
| piezo-rain-event | Number:Length | R | Piezo - Amount of Rainfall At the last Rain |
| piezo-rain-hour | Number:Length | R | Piezo - Rainfall Current Hour |
_weatherstation.things_:
-```xtend
+```java
Bridge fineoffsetweatherstation:gateway:3906700515 "Weather station" [
ip="192.168.1.42",
port="45000",
pollingInterval="16",
protocol="DEFAULT"
] {
- Thing sensor WH25 "WH25" [sensor="WH25"]
- Thing sensor WH65 "WH65" [sensor="WH65"]
+ Thing sensor WH25 "WH25" [sensor="WH25"]
+ Thing sensor WH65 "WH65" [sensor="WH65"]
}
```
_weatherstation.items_:
-```xtend
+```java
Group WH25 "WH25" <Sensor> ["Sensor"]
Number SignalWH25 "Signal WH25" <QualityOfService> (WH25) ["Measurement", "Level"] { channel="fineoffsetweatherstation:sensor:3906700515:WH25:signal" }
Switch BatteryStatusWH25 "Low Battery WH25" <LowBattery> (WH25) ["Energy", "LowBattery"] { channel="fineoffsetweatherstation:sensor:3906700515:WH25:lowBattery" }
-# Flic Button Binding
+# Flic Button Binding
openHAB binding for using [Flic Buttons](https://flic.io/)
with a [fliclib-linux-hci](https://github.com/50ButtonsEach/fliclib-linux-hci) bridge.
## Discovery
-* There is no automatic discovery for flicd-bridge available.
-* After flicd-bridge is (manually) configured, buttons will be automatically discovered via background discovery as soon
+- There is no automatic discovery for flicd-bridge available.
+- After flicd-bridge is (manually) configured, buttons will be automatically discovered via background discovery as soon
as they're added with [simpleclient](https://github.com/50ButtonsEach/fliclib-linux-hci).
If they're already attached to the flicd-bridge before configuring this binding, they can be discovered by triggering an
Example for textual configuration:
-```
+```java
Bridge flicbutton:flicd-bridge:mybridge
```
The default host is localhost:5551 (this should be sufficient if flicd is running with default settings on the same server as openHAB).
If your flicd service is running somewhere else, specify it like this:
-```
+```java
Bridge flicbutton:flicd-bridge:mybridge [ hostname="<YOUR_HOSTNAME>", port=<YOUR_PORT>]
```
Normally, no textual configuration is necessary as buttons are auto discovered as soon as the bridge is configured.
If you want to use textual configuration anyway, you can do it like this:
-```
+```java
Bridge flicbutton:flicd-bridge:mybridge [ hostname="<YOUR_HOSTNAME>", port=<YOUR_PORT>] {
Thing button myflic1 "<YOUR_LABEL>" [address ="<MAC_ADDRESS>"]
Thing button myflic2 "<YOUR_LABEL>" [address ="<MAC_ADDRESS>"]
| rawbutton | [System Trigger Channel](https://www.openhab.org/docs/developer/bindings/thing-xml.html#system-trigger-channel-types) `system.rawbutton` | Depends on the [Trigger Profile](https://www.openhab.org/docs/configuration/items.html#profiles) used | Raw Button channel that triggers `PRESSED` and `RELEASED` events, allows to use openHAB profiles or own implementations via rules to detect e.g. double clicks, long presses etc. |
| button | [System Trigger Channel](https://www.openhab.org/docs/developer/bindings/thing-xml.html#system-trigger-channel-types) `system.button` | Depends on the [Trigger Profile](https://www.openhab.org/docs/configuration/items.html#profiles) used | Button channel that is using Flic's implementation for detecting long, short or double clicks. Triggers `SHORT_PRESSED`,`DOUBLE_PRESSED` and `LONG_PRESSED` events. |
| battery-level | [System State Channel](https://www.openhab.org/docs/developer/bindings/thing-xml.html#system-state-channel-types) `system.battery-level` | Number | Represents the battery level as a percentage (0-100%).
+
## Example
### Initial setup
-1. Setup and run flicd as described in [fliclib-linux-hci](https://github.com/50ButtonsEach/fliclib-linux-hci).
+1. Setup and run flicd as described in [fliclib-linux-hci](https://github.com/50ButtonsEach/fliclib-linux-hci).
Please consider that you need a separate Bluetooth adapter. Shared usage with other Bluetooth services (e.g. Bluez)
is not possible.
1. Connect your buttons to flicd using the simpleclient as described in
demo.things:
-```
+```java
Bridge flicbutton:flicd-bridge:local-flicd {
- Thing button flic_livingroom "Yellow Button Living Room" [address = "60:13:B3:02:18:BD"]
- Thing button flic_kitchen "Black Button Kitchen" [address = "B5:7E:59:78:86:9F"]
+ Thing button flic_livingroom "Yellow Button Living Room" [address = "60:13:B3:02:18:BD"]
+ Thing button flic_kitchen "Black Button Kitchen" [address = "B5:7E:59:78:86:9F"]
}
```
demo.items:
-```
+```java
Dimmer Light_LivingRoom { channel="milight:rgbLed:milight2:4:ledbrightness", channel="flicbutton:button:local-flicd:flic_livingroom:rawbutton" [profile="rawbutton-toggle-switch"], channel="flicbutton:button:local-flicd:flic_kitchen:rawbutton" [profile="rawbutton-toggle-switch"] } // We have a combined kitchen / livingroom, so we control the living room lights with switches from the living room and from the kitchen
Switch Light_Kitchen { channel="hue:group:1:kitchen-bulbs:switch", channel="flicbutton:button:local-flicd:flic_kitchen:rawbutton" [profile="rawbutton-toggle-switch"] }
```
It's also possible to setup [Rules](https://www.openhab.org/docs/configuration/rules-dsl.html).
The following rules help to initially test your setup as they'll trigger log messages on incoming events.
-```
+```java
rule "Button rule using the button channel"
when
# FMI Weather Binding
-This binding integrates to [the Finnish Meteorological Institute (FMI) Open Data API](https://en.ilmatieteenlaitos.fi/open-data).
+This binding integrates to [the Finnish Meteorological Institute (FMI) Open Data API](https://en.ilmatieteenlaitos.fi/open-data).
Binding provides access to weather observations from FMI weather stations and [HIRLAM weather forecast model](https://en.ilmatieteenlaitos.fi/weather-forecast-models) forecasts.
Forecast covers all of Europe, see previous link for more information.
| --------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `fmisid` | text | ✓ | FMI Station ID. You can FMISID of see all weathers stations at [FMI web site](https://en.ilmatieteenlaitos.fi/observation-stations?p_p_id=stationlistingportlet_WAR_fmiwwwweatherportlets&p_p_lifecycle=0&p_p_state=normal&p_p_mode=view&p_p_col_id=column-4&p_p_col_count=1&_stationlistingportlet_WAR_fmiwwwweatherportlets_stationGroup=WEATHER#station-listing) | `"852678"` for Espoo Nuuksio station |
-
### `forecast` thing configuration
| Parameter | Type | Required | Description | Example |
`fmi.things`:
-```
+```java
Thing fmiweather:observation:station_Helsinki_Kumpula "Helsinki Kumpula Observation" [fmisid="101004"]
Thing fmiweather:forecast:forecast_Paris "Paris Forecast" [location="48.864716, 2.349014"]
```
'"{label} [{unit}]" {{ channel="{channel_id}" }}').format(**locals()))
-->
-```
+```java
DateTime HelsinkiObservationTime "Observation Time [%1$tY-%1$tm-%1$tdT%1$tH:%1$tM:%1$tS]" <time> { channel="fmiweather:observation:station_Helsinki_Kumpula:current#time" }
Number:Temperature HelsinkiTemperature "Temperature [%.1f %unit%]" <temperature> { channel="fmiweather:observation:station_Helsinki_Kumpula:current#temperature" }
Number:Dimensionless HelsinkiHumidity "Humidity [%.1f %unit%]" <humidity> { channel="fmiweather:observation:station_Helsinki_Kumpula:current#humidity" }
'"{label} [{unit}]" {icon} {{ channel="{channel_id}" }}').format(**locals()))
-->
-```
+```java
DateTime ParisForecastNowTime "Forecast Time Now [%1$tY-%1$tm-%1$tdT%1$tH:%1$tM:%1$tS]" <time> { channel="fmiweather:forecast:forecast_Paris:forecastNow#time" }
Number:Temperature ParisForecastNowTemperature "Temperature Now [%.1f %unit%]" <temperature> { channel="fmiweather:forecast:forecast_Paris:forecastNow#temperature" }
Number:Dimensionless ParisForecastNowHumidity "Humidity Now [%.1f %unit%]" <humidity> { channel="fmiweather:forecast:forecast_Paris:forecastNow#humidity" }
`fmi_weather.sitemap`:
-```
+```perl
sitemap fmi_weather label="FMI Weather" {
Frame label="Observation Helsinki" {
Text item=HelsinkiObservationTime
Currently the binding support two types of things: `ftpfolder` and `localfolder`.
-
## Thing Configuration
The `ftpfolder` thing has the following configuration options:
| newftpfile | String | A new file name discovered on FTP |
| newlocalfile | String | A new file name discovered on in local folder |
-
## Full Example
Thing configuration:
| Parameter | Description | Required
|------------------|-------------------------------------------------------|----------
-| apikey | API Key from https://api.foobot.io/apidoc/index.html | Mandatory
+| apikey | API Key from <https://api.foobot.io/apidoc/index.html> | Mandatory
| username | The e-mail address used to log into the Foobot App | Mandatory
| refreshInterval | Refresh interval in minutes, minimal 5 minutes | Optional, the default value is 8 minutes.
|----------------------|-----------|-----------------------------------------------
| apiKeyLimitRemaining | Number | The remaining number of API requests for today
-
The AirQuality sensors information that is retrieved is available as these channels:
| Channel ID | Item Type | Description
demo.things:
-```
+```java
// Bridge configuration:
Bridge foobot:account:myfoobotaccount "Foobot Account" [apiKey="XXXXXX", username="XXXXXX", refreshInterval=8] {
Things:
demo.items:
-```
+```java
Number:Temperature Temperature "Temperature" <temperature> { channel="foobot:myfoobotaccount:device:myfoobot:temperature" }
```
### Server
-The *server* bridge thing requires the following configuration parameters:
+The _server_ bridge thing requires the following configuration parameters:
| Parameter Label | Parameter ID | Description | Required | Default |
|------------------------------------|-------------------------|-----------------------------------------------------------------------------|----------|----------------------|
| Enable Network Interface Discovery | discoverNetInterface | Enable the discovery of network interface things. | false | true |
| Enable AirPlay Receiver Discovery | discoverAirPlayReceiver | Enable the discovery of AirPlay receiver things. | false | true |
-If the parameter *fqdn* is not set, the binding will use the default address used by Free to access your Freebox Server (mafreebox.freebox.fr).
-The bridge thing will initialize only if a valid application token (parameter *appToken*) is filled.
+If the parameter _fqdn_ is not set, the binding will use the default address used by Free to access your Freebox Server (mafreebox.freebox.fr).
+The bridge thing will initialize only if a valid application token (parameter _appToken_) is filled.
### Phone
-The *phone* thing requires the following configuration parameters:
+The _phone_ thing requires the following configuration parameters:
| Parameter Label | Parameter ID | Description | Required | Default |
|------------------------------|---------------------------|---------------------------------------------------------------------------------------------|----------|---------|
### Network device
-The *net_device* thing requires the following configuration parameters:
+The _net_device_ thing requires the following configuration parameters:
| Parameter Label | Parameter ID | Description | Required |
|-----------------|--------------|----------------------------------------|----------|
### Network interface
-The *net_interface* thing requires the following configuration parameters:
+The _net_interface_ thing requires the following configuration parameters:
| Parameter Label | Parameter ID | Description | Required |
|-----------------|--------------|-----------------------------------------------------|----------|
### AirPlay device
-The *airplay* thing requires the following configuration parameters:
+The _airplay_ thing requires the following configuration parameters:
| Parameter Label | Parameter ID | Description | Required |
|-----------------|--------------|-----------------------------|----------|
This binding uses the [Fronius Solar API V1](https://www.fronius.com/en/photovoltaics/products/all-products/system-monitoring/open-interfaces/fronius-solar-api-json-) to obtain data from Fronius devices.
-It supports Fronius inverters and Fronius Smart Meter. Supports:
-* Fronius Symo
-* Fronius Symo Gen24
-* Fronius Smart Meter 63A
-* Fronius Smart Meter TS 65A-3
-* Fronius Ohmpilot
+It supports Fronius inverters and Fronius Smart Meter.
+Supports:
+
+- Fronius Symo
+- Fronius Symo Gen24
+- Fronius Smart Meter 63A
+- Fronius Smart Meter TS 65A-3
+- Fronius Ohmpilot
## Supported Things
| `energyrealsumconsumed` | Number:Energy | Real Energy consumed |
| `energyrealsumproduced` | Number:Energy | Real Energy produced |
-
### Channels for `ohmpilot` Thing
| Channel ID | Item Type | Description |
| `errorcode` | Number | Device error code |
| `statecode` | Number | Device state code<br />`0` up and running <br />`1` keep minimum temperature <br />`2` legionella protection <br />`3` critical fault<br />`4` fault<br />`5` boost mode |
-
## Properties
### The `meter` thing has the following properties:
demo.things:
-```
+```java
Bridge fronius:bridge:mybridge [hostname="192.168.66.148", refreshInterval=5] {
Thing powerinverter myinverter [deviceId=1]
Thing meter mymeter [deviceId=0]
demo.items:
-```
+```java
Number:Power AC_Power { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachannelpac" }
Number:Energy Day_Energy { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachanneldayenergy" }
Number:Energy Total_Energy { channel="fronius:powerinverter:mybridge:myinverter:inverterdatachanneltotal" }
Successfully tested are internet radios:
- * [Hama IR100, IR110](https://de.hama.com/00054823/hama-internetradio-ir110)
- * [Hama DIR3100](https://www.conrad.com/p/hama-dir3100-internet-desk-radio-dab-fm-aux-internet-radio-usb-spotify-black-1233624)
- * [Medion MD87180, MD86988, MD86955, MD87528](http://internetradio.medion.com/)
- * [Silvercrest SMRS18A1, SMRS30A1, SMRS35A1, SIRD 14 C2, SIRD 14 D1](https://www.silvercrest-multiroom.de/en/products/stereo-internet-radio/)
- * [Roberts Stream 83i and 93i](https://www.robertsradio.com/uk/products/radio/smart-radio/)
- * [Auna Connect 150, Auna KR200, Auna Connect CD](https://www.auna.de/Radios/Internetradios/)
- * [TechniSat DIGITRADIO 350 IR and 850](https://www.technisat.com/en_XX/DAB+-Radios-with-Internetradio/352-10996/)
- * [TTMicro AS Pinell Supersound](https://www.ttmicro.no/radio)
- * [Revo SuperConnect](https://revo.co.uk/products/)
- * [Sangean WFR-28C](https://sg.sangean.com.tw/products/product_category.asp?cid=2)
- * [Roku SoundBridge M1001](https://soundbridge.roku.com/soundbridge/index.php)
- * [Dual IR 3a](https://www.dual.de/produkte/digitalradio/radio-station-ir-3a/)
- * [Teufel 3sixty](https://www.teufel.de/stereo/radio-3sixty-p16568.html)
- * [Ruark R5](https://www.ruarkaudio.com/products/r5-high-fidelity-music-system)
+- [Hama IR100, IR110](https://de.hama.com/00054823/hama-internetradio-ir110)
+- [Hama DIR3100](https://www.conrad.com/p/hama-dir3100-internet-desk-radio-dab-fm-aux-internet-radio-usb-spotify-black-1233624)
+- [Medion MD87180, MD86988, MD86955, MD87528](http://internetradio.medion.com/)
+- [Silvercrest SMRS18A1, SMRS30A1, SMRS35A1, SIRD 14 C2, SIRD 14 D1](https://www.silvercrest-multiroom.de/en/products/stereo-internet-radio/)
+- [Roberts Stream 83i and 93i](https://www.robertsradio.com/uk/products/radio/smart-radio/)
+- [Auna Connect 150, Auna KR200, Auna Connect CD](https://www.auna.de/Radios/Internetradios/)
+- [TechniSat DIGITRADIO 350 IR and 850](https://www.technisat.com/en_XX/DAB+-Radios-with-Internetradio/352-10996/)
+- [TTMicro AS Pinell Supersound](https://www.ttmicro.no/radio)
+- [Revo SuperConnect](https://revo.co.uk/products/)
+- [Sangean WFR-28C](https://sg.sangean.com.tw/products/product_category.asp?cid=2)
+- [Roku SoundBridge M1001](https://soundbridge.roku.com/soundbridge/index.php)
+- [Dual IR 3a](https://www.dual.de/produkte/digitalradio/radio-station-ir-3a/)
+- [Teufel 3sixty](https://www.teufel.de/stereo/radio-3sixty-p16568.html)
+- [Ruark R5](https://www.ruarkaudio.com/products/r5-high-fidelity-music-system)
But in principle, all internet radios based on the [Frontier Silicon chipset](https://www.frontier-silicon.com/) should be supported because they share the same API.
So it is very likely that other internet radio models of the same manufacturers do also work.
Each radio must be configured via its ip address, port, pin, and a refresh rate.
-* If the ip address is not discovered automatically, it must be manually set.
-* The default port is `80` which should work for most radios.
-* The default pin is `1234` for most radios, but if it does not work or if it was changed, look it up in the on-screen menu of the radio.
-* The default refresh rate for the radio items is `60` seconds; `0` disables periodic refresh.
+- If the ip address is not discovered automatically, it must be manually set.
+- The default port is `80` which should work for most radios.
+- The default pin is `1234` for most radios, but if it does not work or if it was changed, look it up in the on-screen menu of the radio.
+- The default refresh rate for the radio items is `60` seconds; `0` disables periodic refresh.
## Channels
| Teufel 3sixty | Internet Radio | Spotify | - | USB/Network | DAB Radio | FM Radio | Bluetooth | AUX in | - | - | - | - | - | - |
| Ruark R5 | Internet Radio | TIDAL | Deezer | Amazon Music | Spotify | Local Music | Music Player | DAB Radio | FM Radio | Bluetooth | AUX in | Phono | Optical | CD |
-
## Full Example
demo.things:
-```
+```java
fsinternetradio:radio:radioInKitchen [ ip="192.168.0.42" ]
```
demo.items:
-```
+```java
Switch RadioPower "Radio Power" { channel="fsinternetradio:radio:radioInKitchen:power" }
Switch RadioMute "Radio Mute" { channel="fsinternetradio:radio:radioInKitchen:mute" }
Dimmer RadioVolume "Radio Volume" { channel="fsinternetradio:radio:radioInKitchen:volume-percent" }
demo.sitemap:
-```
+```perl
sitemap demo label="Main Menu"
{
- Frame {
- Switch item=RadioPower
- Slider visibility=[RadioPower==ON] item=RadioVolume
- Switch visibility=[RadioPower==ON] item=RadioMute
- Selection visibility=[RadioPower==ON] item=RadioPreset mappings=[0="Favourit 1", 1="Favourit 2", 2="Favourit 3", 3="Favourit 4"]
- Selection visibility=[RadioPower==ON] item=RadioMode mappings=[0="Internet Radio", 1="Musik Player", 2="DAB", 3="FM", 4="AUX"]
- Text visibility=[RadioPower==ON] item=RadioInfo1
- Text visibility=[RadioPower==ON] item=RadioInfo2
- }
+ Frame {
+ Switch item=RadioPower
+ Slider visibility=[RadioPower==ON] item=RadioVolume
+ Switch visibility=[RadioPower==ON] item=RadioMute
+ Selection visibility=[RadioPower==ON] item=RadioPreset mappings=[0="Favourit 1", 1="Favourit 2", 2="Favourit 3", 3="Favourit 4"]
+ Selection visibility=[RadioPower==ON] item=RadioMode mappings=[0="Internet Radio", 1="Musik Player", 2="DAB", 3="FM", 4="AUX"]
+ Text visibility=[RadioPower==ON] item=RadioInfo1
+ Text visibility=[RadioPower==ON] item=RadioInfo2
+ }
}
```
| userName | User name to login to the FTP server. User name is used to identify the Thing, so it should be unique per Thing. | yes | |
| password | Password to login to the FTP server. | yes | |
-
## Channels
This binding currently supports the following channels:
|-------------|--------------|--------------------------------------------------------------------------|----------|---------------|
| filename | Filename | Filename to match received files. Supports regular expression patterns. | yes | .* |
-
### Trigger Channels
| Channel Type ID | Options | Description |
When an image file is uploaded to FTP server, the binding tries to find the trigger channel whose filename matches the upload image filename.
If no match is found, no channel is updated.
The filename parameter supports regular expression patterns.
-See more details in the Things example.
+See more details in the Things example.
Trigger channels supports following options:
Things:
-```
+```java
Thing ftpupload:imagereceiver:images1 [ userName="test1", password="12345" ] {
Thing ftpupload:imagereceiver:images2 [ userName="test2", password="12345" ] {
Items:
-```
+```java
Image Image1 { channel="ftpupload:imagereceiver:images1:image" }
Image Image2 { channel="ftpupload:imagereceiver:images2:my_image1" }
```
Rules:
-```
+```java
rule "example trigger rule 1"
when
Channel 'ftpupload:imagereceiver:images1:image-received' triggered IMAGE_RECEIVED
Sitemap:
-```
+```perl
Frame label="FTP images" {
Image item=Image1
Image item=Image2
Things:
-```
+```java
Thing ftpupload:imagereceiver:garagecamera [ userName="garage", password="12345" ]
```
Items:
-```
+```java
Image Garage_NetworkCamera_Motion_Image { channel="ftpupload:imagereceiver:garagecamera:image" }
```
Rules:
-```
+```java
rule "example trigger rule"
when
Channel 'ftpupload:imagereceiver:garagecamera:image-received' triggered IMAGE_RECEIVED
Sitemap:
-```
+```perl
Frame label="Garage network camera" icon="camera" {
Image item=Garage_NetworkCamera_Motion_Image
}
For problem solving, if binding logging is not enough, Apache FTP server logging can also be enabled by the following command in the Karaf console:
-```
+```shell
log:set DEBUG org.apache.ftpserver
```
and set back to default level:
-```
+```shell
log:set DEFAULT org.apache.ftpserver
```
### Obtaining your API Key
-1. Goto https://developer.husqvarnagroup.cloud/, sign in using your GARDENA smart system account and accept the terms of use
-2. Create and save a new application via the 'Create application' button. The Redirect URLs do not matter, you can enter what you want (e.g. http://localhost:8080)
-3. Connect both _Authentication API_ and _GARDENA smart system API_ to your application via the 'Connect new API' button
-4. Copy the application key to use with this binding as _apiKey_
+1. Goto <https://developer.husqvarnagroup.cloud/>, sign in using your GARDENA smart system account and accept the terms of use
+1. Create and save a new application via the 'Create application' button. The Redirect URLs do not matter, you can enter what you want (e.g. <http://localhost:8080>)
+1. Connect both _Authentication API_ and _GARDENA smart system API_ to your application via the 'Connect new API' button
+1. Copy the application key to use with this binding as _apiKey_
## Examples
### Example configuration
-```
+```java
// smart Water Control
String WC_Valve_Activity "Valve Activity" { channel="gardena:water_control:home:myWateringComputer:valve#activity" }
Number WC_Valve_Duration "Last Watering Duration [%d min]" { channel="gardena:water_control:home:myWateringComputer:valve#duration" }
All channels are read-only, except the command group and the lastUpdate timestamp
-```
+```shell
openhab:send WC_Valve_cmd_Duration.sendCommand(10) // set the duration for the command to 10min
openhab:send WC_Valve_cmd_OpenWithDuration.sendCommand(ON) // start watering
openhab:send WC_Valve_cmd_CloseValve.sendCommand(ON) // stop any active watering
If you send a REFRESH command to the last update timestamp (no matter which thing), **ALL** items from **ALL** things are updated
-```
+```java
DateTime LastUpdate "LastUpdate [%1$td.%1$tm.%1$tY %1$tH:%1$tM]" { channel="gardena:water_control:home:myWateringComputer:common#lastUpdate_timestamp" }
+```
+```shell
// refresh ALL items
openhab:send LastUpdate REFRESH
```
If you want to see what's going on in the binding, switch the loglevel to TRACE in the Karaf console
-```
+```shell
log:set TRACE org.openhab.binding.gardena
```
Set the logging back to normal
-```
+```shell
log:set INFO org.openhab.binding.gardena
```
-**Notes and known limitations:**
+**Notes and known limitations:**
When the binding sends a command to a device, it communicates only with the Gardena smart system integration API.
It has no control over whether the command is sent from the online service via your gateway to the device.
It is the same as if you send the command in the Gardena App.
Schedules, sensor-refresh commands, irrigation control master valve configuration etc. are not supported.
This binding relies on the GARDENA smart system integration API.
-Further API documentation: https://developer.1689.cloud/apis/GARDENA+smart+system+API
+Further API documentation: <https://developer.1689.cloud/apis/GARDENA+smart+system+API>
+
+### Troubleshooting
-###Troubleshooting
Occasionally it can happen that the API key is no longer valid.
-```
+```text
HTTP protocol violation: Authentication challenge without WWW-Authenticate header
```
If this error message appears in the log file, simply renew or delete/create a new API key as described in 'Obtaining your API Key' and restart openHAB.
-
This binding aims to handle various GCE Electronics equipments.
IPX800 is a 8 relay webserver from gce-electronics with a lot of possibilities:
-* 8 Digital Input
-* 8 Relay (250V / 10A / channel)
-* 4 Analog Input
-* 8 Counters
-* Ability to cascade up to 3 extensions for a total of 32 inputs / 32 relay
+- 8 Digital Input
+- 8 Relay (250V / 10A / channel)
+- 4 Analog Input
+- 8 Counters
+- Ability to cascade up to 3 extensions for a total of 32 inputs / 32 relay
Each IPX800 connected to openHAB must be configured with the setting 'Send data on status changed' on the website in M2M > TCP client.
-To make it simple, IPX800 is a simple device that drives output and retrieves input.
+To make it simple, IPX800 is a simple device that drives output and retrieves input.
On input we generally connect push buttons (for instance house switchs), on ouputs we can connect light bulbs for instance.
Features of the binding:
- * Multi ipx support
- * Direct TCP connection
- * Auto reconnect
- * Simple clic/Long press
- * Pulse mode support
+- Multi ipx support
+- Direct TCP connection
+- Auto reconnect
+- Simple clic/Long press
+- Pulse mode support
## Binding Configuration
There is no configuration at binding level.
-
## Thing Configuration
The IPX800v3 (ID : 'ipx800v3') accepts the following configuration parameters :
### Digital Inputs
-This represents the inputs of the PLC. Each can be open or closed.
+This represents the inputs of the PLC. Each can be open or closed.
They are usually commuted by physical devices like pushbuttons, magnets...
#### Digital Input Channels (contacts)
| pulsePeriod | 0(*) | ms | Period of pulse event triggering while the entry is closed. Ignored if '0'. |
| pulseTimeout | 0(*) | ms | Period of time after pulsing will be stopped. None if '0'. |
-* Values below 100ms should be avoided as the JVM could skip them and proceed in the same time slice.
-
+- Values below 100ms should be avoided as the JVM could skip them and proceed in the same time slice.
### Digital Outputs Channels (relays)
|------------|---------|-------------------------------------------------------------------------------------|
| hysteresis | 0 | If set, the channel will ignore status if change (+ or -) is less than hysteresis/2 |
-
## Rule Actions
Multiple actions are supported by this binding. In classic rules these are accessible as shown in the example below:
Getting ipxActions variable in scripts
-```
+```java
val ipxActions = getActions("gce","gce:ipx800v3:43cc8d07")
if(null === ipxActions) {
logInfo("actions", "ipxActions not found, check thing ID")
Resets the value of the given counter to 0.
-* `counterId` (Integer) - id of the counter.
-
+- `counterId` (Integer) - id of the counter.
### reset(placeholder)
Restarts the PLC.
-* `placeholder` (Integer) - This parameter is not used (can be null).
+- `placeholder` (Integer) - This parameter is not used (can be null).
## Example
## Supported Things
-
### MobileLink Account
A MobileLink account bridge thing represents a user's MobileLink account and is responsible for authentication and polling for updates.
| password | The password used to login to the MobileLink service |
| refreshInterval | The frequency to poll for generator updates, minimum duration is 30 seconds |
-
## Channels
### Generator Channels
-All channels are read-only.
+All channels are read-only.
| channel | type | description |
|-------------------------|----------------------|-------------------------------------------|
| batteryVoltage | String | Battery voltage status |
| serviceStatus | Switch | Service status |
-
## Full Example
### Things
-```xtend
+```java
Bridge generacmobilelink:account:main "MobileLink Account" [ userName="foo@bar.com", password="secret",refreshInterval=60 ] {
Thing generator 123456 "MobileLink Generator" [ generatorId="123456" ]
}
### Items
-```xtend
+```java
Switch GeneratorConnected "Connected [%s]" {channel="generacmobilelink:generator:main:123456:connected"}
Switch GeneratorGreenLight "Green Light [%s]" {channel="generacmobilelink:generator:main:123456:greenLight"}
Switch GeneratorYellowLight "Yellow Light [%s]" {channel="generacmobilelink:generator:main:123456:yellowLight"}
### Sitemap
-```xtend
+```perl
sitemap MobileLink label="Demo Sitemap" {
Frame label="Generator" {
Switch item=GeneratorConnected
### Manual Thing Creation
-Devices can be created in the *UI*, or by placing a *.things* file in the *conf/things* directory.
+Devices can be created in the _UI_, or by placing a _.things_ file in the _conf/things_ directory.
See example below.
### Binding Dependencies
The GlobalCache binding will automatically detect those devices, then add them to the inbox.
Background discovery is **enabled** by default.
-To disable background discovery, add the following line to the *conf/services/runtime.cfg* file:
+To disable background discovery, add the following line to the _conf/services/runtime.cfg_ file:
```text
discovery.globalcache:background=false
```
Note that automatic device discovery **will not work** with GC-100's running firmware earlier than v3.0 as those versions do not emit announcement beacons on the multicast address.
-GC-100's running firmware earlier than v3.0 must be configured manually, either through the *UI* or using a *.things* file.
+GC-100's running firmware earlier than v3.0 must be configured manually, either through the _UI_ or using a _.things_ file.
See below.
## Channels and Channel Types
-There are four *channel types* used across the GC-100 and iTach family of devices.
+There are four _channel types_ used across the GC-100 and iTach family of devices.
- Contact Closure (CC)
- Infrared (IR)
- Serial (SL)
- Serial Direct (SL)
-*Channels* follow a naming convention that relates to the physical configuration of the Global Cache device -- specifically the **module** and **connector** numbers.
+_Channels_ follow a naming convention that relates to the physical configuration of the Global Cache device -- specifically the **module** and **connector** numbers.
For example, the channel name **m2c3** refers to connector 3 on module 2.
For iTach Flex devices, since they can be configured to support infrared, serial, or contact closure, channels are prefixed with ir-, sl-, and cc-, respectively.
## Infrared (IR) Channel
-The *Infrared channel* sends IR codes out the IR connector on the device.
+The _Infrared channel_ sends IR codes out the IR connector on the device.
For example, the following item links to the module 1 / connector 2 channel on an iTach IR device.
```java
#### Unsupported Features
-Currently, only the *IR Out* and *IR Blaster* connector configurations are supported.
-Other settings, such as *Sensor In*, *Sensor Notify*, and *LED Lighting*, may be supported in the future.
+Currently, only the _IR Out_ and _IR Blaster_ connector configurations are supported.
+Other settings, such as _Sensor In_, _Sensor Notify_, and _LED Lighting_, may be supported in the future.
## Contact Closure (CC) Channel
-A *Contact Closure channel* activates the contact closure (relay) on the iTach or GC-100 device.
+A _Contact Closure channel_ activates the contact closure (relay) on the iTach or GC-100 device.
For example, the following item links to the module 1, connector 1 channel on an iTach CC device.
-```
+```java
Switch MyRelay "My Relay [%s]" (gRelays) { channel="globalcache:itachCC:000C1E039BCF:cc-m1#c1" }
```
The item definition for an iTach Flex WiFi device would look like this.
-```
+```java
String MyRelay "My Relay [%s]" (gRelays) { channel="globalcache:itachFlex:000C01AF4990:cc-m1#c1" }
```
## Serial (SL) Channel
-An *SL channel* sends serial command strings out the serial connector on the device.
+An _SL channel_ sends serial command strings out the serial connector on the device.
For example, the following item links to the module 1 connector 1 channel on a GC-100-6 device.
-```
+```java
String RS232ME "My RS232-controlled Device" { channel="globalcache:gc100_6:000C459A120A:sl-m1#c1" }
```
This is useful in rules where the serial command might be constructed "on the fly" in the body of the rule.
For example, the following item links to the module 1 connector 1 channel on an iTach Flex device.
-```
+```java
String RUSSCAA66 "Russound CAA66" { channel="globalcache:itachFlex:000C45D530B9:sl-m1#c1-direct" }
```
For example, the following item links to the receive channel on module 1 connector 1 on a GC-100.
A rule that looks for updates on this item will be able to process messages sent from the device connected to the GlobalCache's serial port.
-```
+```java
String RUSSCAA66_Receive "Russound CAA66 Receive" { channel="globalcache:gc100_06:000C1EFFF039:sl-m1#c1-receive" }
```
%F7 Russound RNET message terminator
```
-**Example**
+### Example
-### MAP File
+#### MAP File
```text
# Harmon Kardon AVR-245 Home Theater Receiver
RS232ME_VOLUME_DOWN = VOLUME%20DOWN%0D%0A
```
-### Items File
+#### Items File
-```
+```java
Switch ContactClosure1 "Relay on Connector 1" { channel="globalcache:itachCC:000C1E017BCF:cc-m1#c1" }
Switch ContactClosure2 "Relay on Connector 2" { channel="globalcache:itachCC:000C1E017BCF:cc-m1#c2" }
Switch ContactClosure3 "Relay on Connector 3" { channel="globalcache:itachCC:000C1E017BCF:cc-m1#c3" }
String ZSAMSUNGHLS "Samsung HL-S DLP TV" { channel="globalcache:zmote:CI00073306:ir-m1-c1#c1" }
```
-### Sitemap File
+#### Sitemap File
This is an example of how to use contact closure, infrared, and serial devices in a sitemap.
-```
+```perl
Frame label="Contact Closure" {
Switch item=ContactClosure1 label="Open/Close Garage Door"
Switch item=ContactClosure2 label="Light on Garage Door Opener"
}
```
-### Rule file
+#### Rule file
This is an example of how to use a Contact Closure channel within a rule to implement a momentary contact switch, which could be used to trigger a garage door opener.
-```
+```java
var boolean isRunning = false
rule "Example Garage Door Opener"
This is an example of how to send IR and/or serial commands from within a rule.
-```
+```java
rule "AV Power On/Off"
when
Item AVPowerOn received command
This is an example of how to send a serial command directly from within a rule.
-```
+```java
rule "Russound Set Zone 1 Volume to 20"
when
Item RussoundSetVolume received command
### Manual Thing Creation
-Place a file named *globalcache.things* in the *conf/things* directory.
+Place a file named _globalcache.things_ in the _conf/things_ directory.
The file should contain lines formatted like this.
-```
+```java
globalcache:itachCC:000CFF17B106 [ ipAddress="192.168.12.62" ]
globalcache:itachIR:000C0B1E54A0 [ ipAddress="192.168.12.63", mapFilename="ir-codes.map" ]
globalcache:itachSL:000CF886B107 [ ipAddress="192.168.12.64", mapFilename="serial-codes.map" ]
## Channels
-Currently available channels are
+Currently available channels are
| Channel ID | Item Type | Description | API version |
|--------------------------|--------------------------|---------------------------------------------------------------|-------------------|
| maxCurrent | Number:ElectricCurrent | Maximum current allowed to use for charging | 1 (r/w), 2 (r/w) |
demo.things
-```
+```java
Thing goecharger:goe:garage [ip="192.168.1.36",refreshInterval=5]
```
demo.items
-```
+```java
Number:ElectricCurrent GoEChargerMaxCurrent "Maximum current" {channel="goecharger:goe:garage:maxCurrent"}
Number:ElectricCurrent GoEChargerMaxCurrentTemp "Maximum current temporary" {channel="goecharger:goe:garage:maxCurrentTemp"}
Number GoEChargerForceState "Force state" {channel="goecharger:goe:garage:forceState"}
You can easily define rules to charge with PV power alone.
Here is a simple sample how such a rule could look like:
-```
+```java
rule "Set max amps for PV charging"
when
Item availablePVCurrent received update
Advanced example:
-```
+```java
rule "Set charging limit for go-eCharger"
when
Time cron "*/10 * * ? * *" // Trigger every 10 seconds
# GPIO Binding
This binding adds GPIO support via the pigpio daemon to openhab.
-It requires the pigpio (http://abyz.me.uk/rpi/pigpio/) to be running on the pi that should be controlled.
+It requires the pigpio (<http://abyz.me.uk/rpi/pigpio/>) to be running on the pi that should be controlled.
## Supported Things
On a raspberry (or a compatible device) you have to install pigpio:
-```
+```shell
sudo apt-get install pigpiod
sudo raspi-config
```
Note: if you are setting this up on a Raspberry Pi without `raspi-config` you can create the service config file manually:
-```
+```shell
sudo mkdir -p /etc/systemd/system/pigpiod.service.d/
sudo nano /etc/systemd/system/pigpiod.service.d/public.conf
```
- [Service]
- ExecStart=
- ExecStart=/usr/bin/pigpiod
-
+```text
+[Service]
+ExecStart=
+ExecStart=/usr/bin/pigpiod
```
+
+```shell
sudo systemctl daemon-reload
```
Now that Remote GPIO is enabled, get the daemon going (even if installed with apt-get):
-```
+```shell
sudo systemctl enable pigpiod
sudo systemctl start pigpiod
```
## Full Example
-
demo.things:
-```
+```java
Thing gpio:pigpio-remote:sample-pi-1 "Sample-Pi 1" [host="192.168.2.36", port=8888] {
Channels:
Type pigpio-digital-input : sample-input-1 [ gpioId=10]
demo.items:
-```
+```java
Switch SampleInput1 {channel="gpio:pigpio-remote:sample-pi-1:sample-input-1"}
Switch SampleOutput1 {channel="gpio:pigpio-remote:sample-pi-1:sample-output-1"}
```
demo.sitemap:
-```
+```perl
sitemap demo label="Main Menu"
{
Switch item=SampleInput1
Currently two applications are supported:
-* [OwnTracks](https://owntracks.org/booklet/) - iOS, Android
-* [GPSLogger](https://gpslogger.app/) - Android
+- [OwnTracks](https://owntracks.org/booklet/) - iOS, Android
+- [GPSLogger](https://gpslogger.app/) - Android
GPS location reports are sent to openHAB using HTTP.
Please be aware that this communication uses the public network so make sure your openHAB installation is [secured](https://www.openhab.org/docs/installation/security.html#encrypted-communication) (but accessible from public internet through myopenhab.org or using a reverse proxy) and you configured HTTP**S** access in tracking applications.
The binding can process two message types received from trackers:
-* **Location** - This is a simple location report with coordinates extended with some extra information about the tracker (e.g. tracker device battery level). [OwnTracks, GPSLogger]
-* **Transition** - This report is based on regions defined in tracker application only. A message is sent every time the tracker enters or leaves a region. [OwnTracks only] See "Distance Channel and Presence Switch" how this behavior can be achieved with openHAB's on-board tools.
+- **Location** - This is a simple location report with coordinates extended with some extra information about the tracker (e.g. tracker device battery level). [OwnTracks, GPSLogger]
+- **Transition** - This report is based on regions defined in tracker application only. A message is sent every time the tracker enters or leaves a region. [OwnTracks only] See "Distance Channel and Presence Switch" how this behavior can be achieved with openHAB's on-board tools.
## Configuration
Go to Preferences/Connection and set:
-* **Mode** - select Private HTTP
-* **Host**
- * https://<your.ip.address>/gpstracker/owntracks or
- * https://home.myopenhab.org/gpstracker/owntracks
-* **Identification**
- * Turn Authentication ON
- * Set username and password to be able to reach your openHAB server (myopenhab.org credential, if choosen as host)
- * Device ID is not important. Set it to e.g. phone
- * Tracker ID - This id identifies the tracker as a thing. This must be unique for each tracker connected to the same openHAB instance (e.g. family members).
+- **Mode** - select Private HTTP
+- **Host**
+ - `https://<your.ip.address>/gpstracker/owntracks` or
+ - `https://home.myopenhab.org/gpstracker/owntracks`
+- **Identification**
+ - Turn Authentication ON
+ - Set username and password to be able to reach your openHAB server (myopenhab.org credential, if choosen as host)
+ - Device ID is not important. Set it to e.g. phone
+ - Tracker ID - This id identifies the tracker as a thing. This must be unique for each tracker connected to the same openHAB instance (e.g. family members).
### GPSLogger
After the launch, go to General Options.
Enable **Start on boot-up** and **Start on app launch**.
-Go to *Logging details* and enable **Log to custom URL**.
-If you only want to use GPSLogger for this binding, you can disable all other "*Log to*" entries.
-Right after enabling, the app takes you to the *Log to custom URL* settings:
+Go to _Logging details_ and enable **Log to custom URL**.
+If you only want to use GPSLogger for this binding, you can disable all other "_Log to_" entries.
+Right after enabling, the app takes you to the _Log to custom URL_ settings:
-* **URL**
- * https://<your.ip.address>/gpstracker/gpslogger or
- * https://home.myopenhab.org/gpstracker/gpslogger
-* **HTTP Body** - type in: { "_type":"location", "lat":%LAT, "lon":%LON, "tid":"XY", "acc":%ACC, "batt":%BATT, "tst":%TIMESTAMP }
- * Note: "*tid*" is the tracker id that identifies the tracker as a thing. This must be unique for each tracker connected to the same openHAB instance (e.g. family members).
-* **HTTP Headers** - type in: *Content-Type: application/json*
-* **HTTP Method** - type in: *POST*
-* **Basic Authentication** - Set username and password to be able to reach your openHAB server (myopenhab.org credential, if choosen as URL)
-* Check if everything is ok by clicking on **Validate SSL Certificate**.
+- **URL**
+ - `https://<your.ip.address>/gpstracker/gpslogger` or
+ - `https://home.myopenhab.org/gpstracker/gpslogger`
+- **HTTP Body** - type in: { "_type":"location", "lat":%LAT, "lon":%LON, "tid":"XY", "acc":%ACC, "batt":%BATT, "tst":%TIMESTAMP }
+ - Note: "_tid_" is the tracker id that identifies the tracker as a thing. This must be unique for each tracker connected to the same openHAB instance (e.g. family members).
+- **HTTP Headers** - type in: _Content-Type: application/json_
+- **HTTP Method** - type in: _POST_
+- **Basic Authentication** - Set username and password to be able to reach your openHAB server (myopenhab.org credential, if choosen as URL)
+- Check if everything is ok by clicking on **Validate SSL Certificate**.
### Things
Basic channels provided by the tracker things:
-* **Location** - Current location of the tracker
-* **Accuracy** - GPS accuracy
-* **Last Report** - Timestamp of the last location report
-* **Battery Level** - Battery level of the device running the tracker application
-* **Region trigger channel** - Used by regions defined in tracker application. Event is fired with payload of the region name when the binding receives a **transition** log record or a distance calculation for a **location** record indicates that the tracker is outside of the region circle. Payload is suffixed with `/enter` for entering and with `/leave` for leaving events.
+- **Location** - Current location of the tracker
+- **Accuracy** - GPS accuracy
+- **Last Report** - Timestamp of the last location report
+- **Battery Level** - Battery level of the device running the tracker application
+- **Region trigger channel** - Used by regions defined in tracker application. Event is fired with payload of the region name when the binding receives a **transition** log record or a distance calculation for a **location** record indicates that the tracker is outside of the region circle. Payload is suffixed with `/enter` for entering and with `/leave` for leaving events.
#### Distance Calculation
When this calculated distance is less than the defined geofence radius the binding also fires event on Region Trigger channel.
-* When the tracker is approaching (the new calculated distance is less then the previous one) the payload is <<region_name>>/enter.
-* If the tracker is distancing (the new calculated distance is greater then the previous one) payload is <<region_name>>/leave.
+- When the tracker is approaching (the new calculated distance is less then the previous one) the payload is <<region_name>>/enter.
+- If the tracker is distancing (the new calculated distance is greater then the previous one) payload is <<region_name>>/leave.
If the tracker is moving inside/outside the region (both the previous and the current calculated distance value is less/greater than the radius) no events are fired.
This means that the region events are triggered **ONLY IN CASE THE REGION BORDER IS CROSSED**.
In order to have this state available in stateful switch items (e.g. for rule logic) switch type items can be linked to **regionTrigger** channel.
There is a special profile (gpstracker:trigger-geofence) that transforms trigger enter/leave events to switch states:
-* **<<region_name>>/enter** will update the switch state to **ON**
-* **<<region_name>>/leave** will update the switch state to **OFF**
+- **<<region_name>>/enter** will update the switch state to **ON**
+- **<<region_name>>/leave** will update the switch state to **OFF**
To link a switch item to regionTrigger channel the following parameters are required by the item link:
### Things
-```
+```java
//tracker definition
Thing gpstracker:tracker:1 "XY tracker" [trackerId="XY"]
### Items
-```
+```java
//items for basic channels
-Location locationEX "Location" {channel="gpstracker:tracker:1:lastLocation"}
-DateTime lastSeenEX "Last seen" {channel="gpstracker:tracker:1:lastReport"}
-Number batteryEX "Battery level" {channel="gpstracker:tracker:1:batteryLevel"}
-Number:Length accuracyEX "GPS Accuracy [%d m]" {channel="gpstracker:tracker:1:gpsAccuracy"}
+Location locationEX "Location" {channel="gpstracker:tracker:1:lastLocation"}
+DateTime lastSeenEX "Last seen" {channel="gpstracker:tracker:1:lastReport"}
+Number batteryEX "Battery level" {channel="gpstracker:tracker:1:batteryLevel"}
+Number:Length accuracyEX "GPS Accuracy [%d m]" {channel="gpstracker:tracker:1:gpsAccuracy"}
//linking switch item to regionTrigger channel. assuming the Home distance channel is defined in the binding config (see above)
Switch atHomeEX "Home presence" {channel="gpstracker:tracker:EX:regionTrigger" [profile="gpstracker:trigger-geofence", regionName="Home"]}
### Sitemaps
-```
+```perl
sitemap gpstracker label="GPSTracker Binding" {
Text item=distanceEX
Text item=atWorkEX
### Binding Start
-```
+```text
2018-10-03 18:12:38.950 [DEBUG] [org.openhab.binding.gpstracker ] - ServiceEvent REGISTERED - {org.openhab.core.config.discovery.DiscoveryService, org.openhab.binding.gpstracker.internal.discovery.TrackerDiscoveryService}={service.id=425, service.bundleid=183, service.scope=bundle, component.name=org.openhab.binding.gpstracker.internal.discovery.TrackerDiscoveryService, component.id=268} - org.openhab.binding.gpstracker
2018-10-03 18:12:38.965 [DEBUG] [org.openhab.binding.gpstracker ] - ServiceEvent REGISTERED - {org.openhab.core.thing.binding.ThingHandlerFactory, org.openhab.core.config.core.ConfigOptionProvider}={location=47.536178,19.169812, service.id=426, service.bundleid=183, service.scope=bundle, radius=100, name=Home, component.name=org.openhab.binding.gpstracker.internal.GPSTrackerHandlerFactory, component.id=267, additionalRegionsJSON=[
], triggerEvent=false, service.pid=binding.gpstracker} - org.openhab.binding.gpstracker
Please note the lines about started servlets:
-```
+```text
Started GPSTracker Callback servlet on /gpstracker/owntracks
Started GPSTracker Callback servlet on /gpstracker/gpslogger
```
In case the discovery is used the first message from a tracker registers it in the inbox:
-```
+```text
2018-10-05 08:36:14.283 [DEBUG] [nal.provider.AbstractCallbackServlet] - Post message received from OwnTracks tracker: {"_type":"location","tid":"XX","acc":10.0,"lat":41.53,"lon":16.16,"tst":1527966973,"wtst":1524244195,"batt":96}
2018-10-05 08:36:14.286 [DEBUG] [nal.provider.AbstractCallbackServlet] - There is no handler for tracker XX. Check the inbox for the new tracker.
```
The next location message already calculates the distance for System location:
-```
+```text
2018-10-05 08:38:33.916 [DEBUG] [nal.provider.AbstractCallbackServlet] - Post message received from OwnTracks tracker: {"_type":"location","tid":"XX","acc":10.0,"lat":41.53,"lon":16.16,"tst":1527966973,"wtst":1524244195,"batt":96}
2018-10-05 08:38:33.917 [DEBUG] [cker.internal.handler.TrackerHandler] - Update base channels for tracker XX from message: org.openhab.binding.gpstracker.internal.message.LocationMessage@31dfed63
2018-10-05 08:38:33.941 [TRACE] [cker.internal.handler.TrackerHandler] - batteryLevel -> 96
Assumptions:
-* A Home distance channel is added to the tracker with parameters:
- * Channel ID: distanceHome
- * Region Name: Home
- * Region Radius: 100
- * Region Center: 42.53,16.16
-* Presence switch is linked to the regionTrigger channel with parameters:
- * Profile: Geofence(gpstracker:trigger-geofence)
- * Region Name: Home
+- A Home distance channel is added to the tracker with parameters:
+ - Channel ID: distanceHome
+ - Region Name: Home
+ - Region Radius: 100
+ - Region Center: 42.53,16.16
+- Presence switch is linked to the regionTrigger channel with parameters:
+ - Profile: Geofence(gpstracker:trigger-geofence)
+ - Region Name: Home
After a location message received from the tracker the log should contain these lines:
-```
+```text
2018-10-05 09:27:58.768 [DEBUG] [nal.provider.AbstractCallbackServlet] - Post message received from OwnTracks tracker: {"_type":"location","tid":"XX","acc":10.0,"lat":42.53,"lon":17.16,"tst":1527966973,"wtst":1524244195,"batt":96}
2018-10-05 09:27:58.769 [DEBUG] [cker.internal.handler.TrackerHandler] - Update base channels for tracker XX from message: org.openhab.binding.gpstracker.internal.message.LocationMessage@67e5d438
2018-10-05 09:27:58.770 [TRACE] [cker.internal.handler.TrackerHandler] - batteryLevel -> 96
Assumptions:
-* A **shared** region is defined in OwnTracks application. Lets call it Work.
-* Presence switch is linked to the regionTrigger channel with parameters:
- * Profile: Geofence(gpstracker:trigger-geofence)
- * Region Name: Work
+- A **shared** region is defined in OwnTracks application. Lets call it Work.
+- Presence switch is linked to the regionTrigger channel with parameters:
+ - Profile: Geofence(gpstracker:trigger-geofence)
+ - Region Name: Work
-```
+```text
2018-10-05 09:35:27.203 [DEBUG] [nal.provider.AbstractCallbackServlet] - Post message received from OwnTracks tracker: {"_type":"transition","tid":"XX","acc":10.0,"desc":"Work","event":"enter","lat":42.53,"lon":18.22,"tst":1527966973,"wtst":1524244195,"t":"c"}
2018-10-05 09:35:27.204 [DEBUG] [cker.internal.handler.TrackerHandler] - ConfigHelper transition event received: Work
2018-10-05 09:35:27.204 [DEBUG] [cker.internal.handler.TrackerHandler] - Update base channels for tracker XX from message: org.openhab.binding.gpstracker.internal.message.TransitionMessage@5e5b0d59
**Note**:
-* If the binding was restarted only the second transition update will trigger event as the binding has to know the previous state.
-* The distance is not calculated for Work as the binding doesn't know the Work region center.
+- If the binding was restarted only the second transition update will trigger event as the binding has to know the previous state.
+- The distance is not calculated for Work as the binding doesn't know the Work region center.
This binding integrates Air Conditioners that use the GREE protocol (GREE, Sinclair and others).
-Note: The Air Conditioner must already be set-up on the WiFi network and must have a fixed IP Address.
+Note: The Air Conditioner must already be set-up on the WiFi network and must have a fixed IP Address.
## Supported Things
## Discovery
Once the Air Conditioner is on the network (WiFi active) it could be discovered automatically.
-An IP broadcast message is sent and every responding unit gets added to the Inbox.
+An IP broadcast message is sent and every responding unit gets added to the Inbox.
## Binding Configuration
| refresh | Integer | Refresh interval in seconds for polling the device status. |
| currentTemperatureOffset | Decimal | Offset in Celsius for the current temperature value received from the device. |
-The Air Conditioner's IP address is mandatory, all other parameters are optional.
+The Air Conditioner's IP address is mandatory, all other parameters are optional.
If the broadcast is not set (default) it will be derived from openHAB's network setting (Check Network Settings in the openHAB UI).
Only change this if you have a good reason to.
| light | Switch | Enable/disable the front display on the Air Conditioner if applicable to the Air Conditioner model|
| | | Full Swing: 1, Up: 2, MidUp: 3, Mid: 4, Mid Down: 5, Down : 6 |
-
When changing mode, the air conditioner will be turned on unless "off" is selected.
## Full Example
-**Things**
+### Things
-```
+```java
Thing gree:airconditioner:a1234561 [ ipAddress="192.168.1.111", refresh=2 ]
```
-**Items**
+### Items
-```
+```java
Switch AirconPower { channel="gree:airconditioner:a1234561:power" }
String AirconMode { channel="gree:airconditioner:a1234561:mode" }
Switch AirconTurbo { channel="gree:airconditioner:a1234561:turbo" }
Switch AirconPowerSaving { channel="gree:airconditioner:a1234561:powersave" }
```
-**Sitemap**
+### Sitemap
This is an example of how to set up your sitemap.
-```
+```perl
Frame label="Controls"
{
Switch item=AirconMode label="Mode" mappings=["auto"="Auto", "cool"="Cool", "eco"="Eco", "dry"="Dry", "fan"="Fan", "turbo"="Turbo", "heat"="Heat", "on"="ON", "off"="OFF"]
}
```
-**Example**
+## Example
This example shows how to make a GREE Air Conditioner controllable by Google HA (A/C mode + temperature)
-**Items**
+### Items
-```
+```java
Group Gree_Modechannel "Gree" { ga="Thermostat" } // allows mapping for Google Home Assistent
Switch GreeAirConditioner_Power "Aircon" {channel="gree:airconditioner:a1234561:power", ga="Switch"}
String GreeAirConditioner_Mode "Aircon Mode" {channel="gree:airconditioner:a1234561:mode", ga="thermostatMode"}
Switch GreeAirConditioner_Light "Light" {channel="gree:airconditioner:a1234561:light"}
```
-**Rules**
+### Rules
-```
+```java
rule "Mode changed"
when
Item GreeAirConditioner_Mode changed
Things file:
-````
+```java
Bridge groheondus:account:account1 [ username="user@example.com", password="YourStrongPasswordHere!" ] {
groheondus:senseguard:550e8400-e29b-11d4-a716-446655440000 [ applianceId="550e8400-e29b-11d4-a716-446655440000", roomId=456, locationId=123 ] {
Channels:
}
groheondus:sense:550e8400-e29b-11d4-a716-446655440000 [ applianceId="444e8400-e29b-11d4-a716-446655440000", roomId=456, locationId=123 ]
}
-````
+```
Items file:
-````
+```java
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"}
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"}
-````
+```
You need to select a brand and enter the user name and password.
The Polling Interval (in minutes) determines how often the API will be polled for new cars.
The Client ID and Client Secret should not need to be updated.
-(However you can register your own app via https://developer.groupe-psa.com/inc/ and use this client information if you wish.)
+(However you can register your own app via <https://developer.groupe-psa.com/inc/> and use this client information if you wish.)
### parameters
| userName | None | Yes | The user name for the mypeugot/mycitroen/myds/myopel/myvauxhall website or app. |
| password | None | Yes | The password for the given user. |
| pollingInterval | 60 | No | The Polling Interval (in minutes) determines how often the available vehicles are queried. |
-| clientId | | Yes | The Client ID for API access: can normally left at the default value. (see: https://developer.groupe-psa.io/webapi/b2c/quickstart/connect/#article) |
-| clientSecret | | Yes | The Client Secret for API access: can normally left at the default value. (see: https://developer.groupe-psa.io/webapi/b2c/quickstart/connect/#article) |
+| clientId | | Yes | The Client ID for API access: can normally left at the default value. (see: <https://developer.groupe-psa.io/webapi/b2c/quickstart/connect/#article>) |
+| clientSecret | | Yes | The Client Secret for API access: can normally left at the default value. (see: <https://developer.groupe-psa.io/webapi/b2c/quickstart/connect/#article>) |
## Vehicle Configuration
| chargingRemainingTime | Number:Time | Time remaining till charged |
| chargingNextDelayedTime | Number:Time | Time till the next charging starts |
-Further documentation can be found at: https://developer.groupe-psa.io/webapi/b2c/api-reference/specification/#article
+Further documentation can be found at: <https://developer.groupe-psa.io/webapi/b2c/api-reference/specification/#article>
## Full Example
### Things file
-```
+```java
Bridge groupepsa:bridge:opel "Auto Interface" [
pollingInterval=60,
userName="anonymous@anonymous.email",
### Items file
-```
+```java
Group Auto
Number:ElectricCurrent Auto_Aux_Current "Auxillliary Battery Current [%.1f %unit%]" (Auto) ["Measurement","Current"] {channel="groupepsa:vehicle:opel:zafira:battery#current"}
Guntamatic Heating Systems supported as Thing Types:
-| Name | Thing Type ID | Heating System Type | Binding Development Status |
-|---------------|---------------|----------------------|--------------------------------------------------|
-| Biostar | `biostar` | Pellets | tested via 15kW, firmware 3.2d, German & English |
-| Biosmart | `biosmart` | Logs | tested via 22kW, firmware 3.2f, German |
-| Powerchip | `powerchip` | WoodChips | tested via 100kW, firmware 3.2d, French |
-| Powercorn | `powercorn` | EnergyGrain | untested |
-| Biocom | `biocom` | Pellets | untested |
-| Pro | `pro` | Pellets or WoodChips | untested |
-| Therm | `therm` | Pellets | untested |
-| Generic | `generic` | - | use, if none from above |
+| Name | Thing Type ID | Heating System Type | Binding Development Status |
+| --------- | ------------- | -------------------- | ------------------------------------------------ |
+| Biostar | `biostar` | Pellets | tested via 15kW, firmware 3.2d, German & English |
+| Biosmart | `biosmart` | Logs | tested via 22kW, firmware 3.2f, German |
+| Powerchip | `powerchip` | WoodChips | tested via 100kW, firmware 3.2d, French |
+| Powercorn | `powercorn` | EnergyGrain | untested |
+| Biocom | `biocom` | Pellets | untested |
+| Pro | `pro` | Pellets or WoodChips | untested |
+| Therm | `therm` | Pellets | untested |
+| Generic | `generic` | - | use, if none from above |
### Thing Configuration
-| Parameter | Description | Default |
-|--------------------|-----------------------------------------------------------------------------|-----------------|
-| `hostname` | Hostname or IP address of the Guntamatic Heating System | |
-| `key` | Optional, but required to read protected parameters and to control the Guntamatic Heating System.<br/>The key needs to be requested from Guntamatic support, e.g. via https://www.guntamatic.com/en/contact/. | |
-| `refreshInterval` | Interval the Guntamatic Heating System is polled in seconds | `60` |
-| `encoding` | Code page used by the Guntamatic Heating System | `windows-1252` |
+| Parameter | Description | Default |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `hostname` | Hostname or IP address of the Guntamatic Heating System | |
+| `key` | Optional, but required to read protected parameters and to control the Guntamatic Heating System.<br/>The key needs to be requested from Guntamatic support, e.g. via <https://www.guntamatic.com/en/contact/>. | |
+| `refreshInterval` | Interval the Guntamatic Heating System is polled in seconds | `60` |
+| `encoding` | Code page used by the Guntamatic Heating System | `windows-1252` |
### Properties
-| Property | Description | Supported |
-|---------------------|---------------------------------------------------------------|---------------------------------------------------|
-| `extraWwHeat` | Parameter used by `controlExtraWwHeat` channels | all |
-| `boilerApproval` | Parameter used by `controlBoilerApproval` channel | Biostar, Powerchip, Powercorn, Biocom, Pro, Therm |
-| `heatCircProgram` | Parameter used by `controlHeatCircProgram` channels | all |
-| `program` | Parameter used by `controlProgram` channel | all |
-| `wwHeat` | Parameter used by `controlWwHeat` channels | all |
+| Property | Description | Supported |
+| ----------------- | --------------------------------------------------- | ------------------------------------------------- |
+| `extraWwHeat` | Parameter used by `controlExtraWwHeat` channels | all |
+| `boilerApproval` | Parameter used by `controlBoilerApproval` channel | Biostar, Powerchip, Powercorn, Biocom, Pro, Therm |
+| `heatCircProgram` | Parameter used by `controlHeatCircProgram` channels | all |
+| `program` | Parameter used by `controlProgram` channel | all |
+| `wwHeat` | Parameter used by `controlWwHeat` channels | all |
## Channels
The Guntamatic Heating System can be controlled using the following channels:
-| Channel | Description | Type | Unit | Security Access Level | ReadOnly | Advanced |
-|-----------------------|---------------------------------------------------------------------------|-------|:---------:|:-------------------------:|:--------:|:--------:|
-| `controlBoilerApproval` | Set Boiler Approval (`AUTO`, `OFF`, `ON`) | `String` | | 🔐 W1 | R/W | true |
-| `controlProgram` | Set Program (`OFF`, `NORMAL`, `WARMWATER`, `MANUAL`<sup id="a1">[1](#f1)</sup>) | `String` | | 🔐 W1 | R/W | false |
-| `controlHeatCircProgram0` | Set Heat Circle 0 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
-| `controlHeatCircProgram1` | Set Heat Circle 1 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
-| `controlHeatCircProgram2` | Set Heat Circle 2 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
-| `controlHeatCircProgram3` | Set Heat Circle 3 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
-| `controlHeatCircProgram4` | Set Heat Circle 4 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
-| `controlHeatCircProgram5` | Set Heat Circle 5 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
-| `controlHeatCircProgram6` | Set Heat Circle 6 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
-| `controlHeatCircProgram7` | Set Heat Circle 7 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
-| `controlHeatCircProgram8` | Set Heat Circle 8 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
-| `controlWwHeat0` | Trigger Warm Water Circle 0 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
-| `controlWwHeat1` | Trigger Warm Water Circle 1 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
-| `controlWwHeat2` | Trigger Warm Water Circle 2 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
-| `controlExtraWwHeat0` | Trigger Extra Warm Water Circle 0 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
-| `controlExtraWwHeat1` | Trigger Extra Warm Water Circle 1 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
-| `controlExtraWwHeat2` | Trigger Extra Warm Water Circle 2 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
+| Channel | Description | Type | Unit | Security Access Level | ReadOnly | Advanced |
+| ------------------------- | ------------------------------------------------------------------------------- | -------- | :--: | :-------------------: | :------: | :------: |
+| `controlBoilerApproval` | Set Boiler Approval (`AUTO`, `OFF`, `ON`) | `String` | | 🔐 W1 | R/W | true |
+| `controlProgram` | Set Program (`OFF`, `NORMAL`, `WARMWATER`, `MANUAL`<sup id="a1">[1](#f1)</sup>) | `String` | | 🔐 W1 | R/W | false |
+| `controlHeatCircProgram0` | Set Heat Circle 0 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
+| `controlHeatCircProgram1` | Set Heat Circle 1 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
+| `controlHeatCircProgram2` | Set Heat Circle 2 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
+| `controlHeatCircProgram3` | Set Heat Circle 3 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
+| `controlHeatCircProgram4` | Set Heat Circle 4 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
+| `controlHeatCircProgram5` | Set Heat Circle 5 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
+| `controlHeatCircProgram6` | Set Heat Circle 6 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
+| `controlHeatCircProgram7` | Set Heat Circle 7 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
+| `controlHeatCircProgram8` | Set Heat Circle 8 Program (`OFF`, `NORMAL`, `HEAT`, `LOWER`) | `String` | | 🔐 W1 | R/W | true |
+| `controlWwHeat0` | Trigger Warm Water Circle 0 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
+| `controlWwHeat1` | Trigger Warm Water Circle 1 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
+| `controlWwHeat2` | Trigger Warm Water Circle 2 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
+| `controlExtraWwHeat0` | Trigger Extra Warm Water Circle 0 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
+| `controlExtraWwHeat1` | Trigger Extra Warm Water Circle 1 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
+| `controlExtraWwHeat2` | Trigger Extra Warm Water Circle 2 (`RECHARGE`) | `String` | | 🔐 W1 | R/W | true |
- <b id="f1">1)</b> ... `MANUAL` is supported by Biostar, Powerchip, Powercorn, Biocom, Pro as well as Therm only [↩](#a1)
Example list of Channels using a Guntamatic Biostar 15kW Pellets Heating System running firmware 3.2d and Guntamatic System Language configured to English:
-| Channel | Description | Type | Unit | Security Access Level | ReadOnly | Advanced |
-|-----------------------|-----------------------------------------------------------|-------|:---------:|:-------------------------:|:--------:|:--------:|
-| `running` | Running | `String` | | 🔓 W0 | R/O | false |
-| `outsideTemp` | Outside Temp. | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `blrTargetTemp` | Blr.Target Temp | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `boilerTemperature` | Boiler Temperature | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `flueGasUtilisation` | Flue gas utilisation | `Number:Dimensionless` | `%` | 🔐 W1 | R/O | false |
-| `output` | Output | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
-| `returnTemp` | Return temp | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `co2Target` | CO2 Target | `Number:Dimensionless` | `%` | 🔐 W1 | R/O | false |
-| `co2Content` | CO2 Content | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
-| `returnTempTarget` | Return temp target | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `statusCode` | Status code | `Number` | | 🔐 W1 | R/O | false |
-| `efficiency` | Efficiency | `Number:Dimensionless` | `%` | 🔐 W1 | R/O | false |
-| `extractorSystem` | Extractor System | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
-| `feedTurbine` | Feed Turbine | `String` | | 🔐 W1 | R/O | false |
-| `dischargeMotor` | Discharge motor | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
-| `g1Target` | G1 Target | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
-| `bufferTop` | Buffer Top | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `bufferMid` | Buffer Mid | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `bufferBtm` | Buffer Btm | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `pumpHp0` | Pump HP0 | `Switch` | | 🔓 W0 | R/O | false |
-| `dhw0` | DHW 0 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `bDhw0` | B DHW 0 | `Switch` | | 🔓 W0 | R/O | false |
-| `dhw1` | DHW 1 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `bDhw1` | B DHW 1 | `Switch` | | 🔓 W0 | R/O | false |
-| `dhw2` | DHW 2 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `bDhw2` | B DHW 2 | `Switch` | | 🔓 W0 | R/O | false |
-| `roomTempHc0` | Room Temp:HC 0 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `heatCirc0` | Heat Circ. 0 | `Switch` | | 🔓 W0 | R/O | false |
-| `roomTempHc1` | Room Temp:HC 1 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `flowTarget1` | Flow Target 1 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `flowIs1` | Flow is 1 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `mixer1` | Mixer 1 | `String` | | 🔐 W1 | R/O | false |
-| `heatCirc1` | Heat Circ. 1 | `Switch` | | 🔐 W1 | R/O | false |
-| `roomTempHc2` | Room Temp:HC 2 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `flowTarget2` | Flow Target 2 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `flowIs2` | Flow is 2 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `mixer2` | Mixer 2 | `String` | | 🔐 W1 | R/O | false |
-| `heatCirc2` | Heat Circ. 2 | `Switch` | | 🔓 W0 | R/O | false |
-| `roomTempHc3` | Room Temp:HC 3 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `heatCirc3` | Heat Circ. 3 | `Switch` | | 🔓 W0 | R/O | false |
-| `roomTempHc4` | Room Temp:HC 4 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `flowTarget4` | Flow Target 4 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `flowIs4` | Flow is 4 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `mixer4` | Mixer 4 | `String` | | 🔐 W1 | R/O | false |
-| `heatCirc4` | Heat Circ. 4 | `Switch` | | 🔓 W0 | R/O | false |
-| `roomTempHc5` | Room Temp:HC 5 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `flowTarget5` | Flow Target 5 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `flowIs5` | Flow is 5 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `mixer5` | Mixer 5 | `String` | | 🔐 W1 | R/O | false |
-| `heatCirc5` | Heat Circ. 5 | `Switch` | | 🔓 W0 | R/O | false |
-| `roomTempHc6` | Room Temp:HC 6 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `heatCirc6` | Heat Circ. 6 | `Switch` | | 🔓 W0 | R/O | false |
-| `roomTempHc7` | Room Temp:HC 7 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `flowTarget7` | Flow Target 7 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `flowIs7` | Flow is 7 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `mixer7` | Mixer 7 | `String` | | 🔐 W1 | R/O | false |
-| `heatCirc7` | Heat Circ. 7 | `Switch` | | 🔓 W0 | R/O | false |
-| `roomTempHc8` | Room Temp:HC 8 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `flowTarget8` | Flow Target 8 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `flowIs8` | Flow is 8 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `mixer8` | Mixer 8 | `String` | | 🔐 W1 | R/O | false |
-| `heatCirc8` | Heat Circ. 8 | `Switch` | | 🔓 W0 | R/O | false |
-| `fuelLevel` | Fuel Level | `String` | | 🔐 W1 | R/O | false |
-| `stb` | STB | `String` | | 🔐 W1 | R/O | false |
-| `tks` | TKS | `String` | | 🔐 W1 | R/O | false |
-| `boilerApproval` | Boiler approval | `Switch` | | 🔐 W1 | R/O | false |
-| `programme` | Programme | `String` | | 🔓 W0 | R/O | false |
-| `programHc0` | Program HC0 | `String` | | 🔓 W0 | R/O | false |
-| `programHc1` | Program HC1 | `String` | | 🔓 W0 | R/O | false |
-| `programHc2` | Program HC2 | `String` | | 🔓 W0 | R/O | false |
-| `programHc3` | Program HC3 | `String` | | 🔓 W0 | R/O | false |
-| `programHc4` | Program HC4 | `String` | | 🔓 W0 | R/O | false |
-| `programHc5` | Program HC5 | `String` | | 🔓 W0 | R/O | false |
-| `programHc6` | Program HC6 | `String` | | 🔓 W0 | R/O | false |
-| `programHc7` | Program HC7 | `String` | | 🔓 W0 | R/O | false |
-| `programHc8` | Program HC8 | `String` | | 🔓 W0 | R/O | false |
-| `interuption0` | Interuption 0 | `String` | | 🔓 W0 | R/O | false |
-| `interuption1` | Interuption 1 | `String` | | 🔓 W0 | R/O | false |
-| `serial` | Serial | `Number` | | 🔓 W0 | R/O | false |
-| `version` | Version | `String` | | 🔓 W0 | R/O | false |
-| `runningTime` | Running Time | `Number:Time` | `h` | 🔓 W0 | R/O | false |
-| `serviceHrs` | Service Hrs | `Number:Time` | `d` | 🔓 W0 | R/O | false |
-| `emptyAshIn` | Empty ash in | `Number:Time` | `h` | 🔓 W0 | R/O | false |
-| `flowIs0` | Flow is 0 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `flowIs3` | Flow is 3 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `flowIs6` | Flow is 6 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `fuelCounter` | Fuel counter | `Number:Volume` | `m³` | 🔐 W1 | R/O | false |
-| `bufferLoad` | Buffer load. | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
-| `bufferTop0` | Buffer Top 0 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `bufferBtm0` | Buffer Btm 0 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `bufferTop1` | Buffer Top 1 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `bufferBtm1` | Buffer Btm 1 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `bufferTop2` | Buffer Top 2 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `bufferBtm2` | Buffer Btm 2 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
-| `bExtraWw0` | B extra-WW. 0 | `Switch` | | 🔐 W1 | R/O | false |
-| `bExtraWw1` | B extra-WW. 1 | `Switch` | | 🔐 W1 | R/O | false |
-| `bExtraWw2` | B extra-WW. 2 | `Switch` | | 🔐 W1 | R/O | false |
-| `auxiliaryPump0` | Auxiliary pump 0 | `Switch` | | 🔐 W1 | R/O | false |
-| `auxiliaryPump1` | Auxiliary pump 1 | `Switch` | | 🔐 W1 | R/O | false |
-| `auxiliaryPump2` | Auxiliary pump 2 | `Switch` | | 🔐 W1 | R/O | false |
-| `boilersConditionNo` | Boiler´s condition no. | `String` | | 🔐 W1 | R/O | false |
-| `bufferT5` | Buffer T5 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `bufferT6` | Buffer T6 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `bufferT7` | Buffer T7 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `extraWw0` | Extra-WW. 0 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `extraWw1` | Extra-WW. 1 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `extraWw2` | Extra-WW. 2 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
-| `grate` | Grate | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
+| Channel | Description | Type | Unit | Security Access Level | ReadOnly | Advanced |
+| -------------------- | ---------------------- | ---------------------- | :--: | :-------------------: | :------: | :------: |
+| `running` | Running | `String` | | 🔓 W0 | R/O | false |
+| `outsideTemp` | Outside Temp. | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `blrTargetTemp` | Blr.Target Temp | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `boilerTemperature` | Boiler Temperature | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `flueGasUtilisation` | Flue gas utilisation | `Number:Dimensionless` | `%` | 🔐 W1 | R/O | false |
+| `output` | Output | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
+| `returnTemp` | Return temp | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `co2Target` | CO2 Target | `Number:Dimensionless` | `%` | 🔐 W1 | R/O | false |
+| `co2Content` | CO2 Content | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
+| `returnTempTarget` | Return temp target | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `statusCode` | Status code | `Number` | | 🔐 W1 | R/O | false |
+| `efficiency` | Efficiency | `Number:Dimensionless` | `%` | 🔐 W1 | R/O | false |
+| `extractorSystem` | Extractor System | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
+| `feedTurbine` | Feed Turbine | `String` | | 🔐 W1 | R/O | false |
+| `dischargeMotor` | Discharge motor | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
+| `g1Target` | G1 Target | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
+| `bufferTop` | Buffer Top | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `bufferMid` | Buffer Mid | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `bufferBtm` | Buffer Btm | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `pumpHp0` | Pump HP0 | `Switch` | | 🔓 W0 | R/O | false |
+| `dhw0` | DHW 0 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `bDhw0` | B DHW 0 | `Switch` | | 🔓 W0 | R/O | false |
+| `dhw1` | DHW 1 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `bDhw1` | B DHW 1 | `Switch` | | 🔓 W0 | R/O | false |
+| `dhw2` | DHW 2 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `bDhw2` | B DHW 2 | `Switch` | | 🔓 W0 | R/O | false |
+| `roomTempHc0` | Room Temp:HC 0 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `heatCirc0` | Heat Circ. 0 | `Switch` | | 🔓 W0 | R/O | false |
+| `roomTempHc1` | Room Temp:HC 1 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `flowTarget1` | Flow Target 1 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `flowIs1` | Flow is 1 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `mixer1` | Mixer 1 | `String` | | 🔐 W1 | R/O | false |
+| `heatCirc1` | Heat Circ. 1 | `Switch` | | 🔐 W1 | R/O | false |
+| `roomTempHc2` | Room Temp:HC 2 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `flowTarget2` | Flow Target 2 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `flowIs2` | Flow is 2 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `mixer2` | Mixer 2 | `String` | | 🔐 W1 | R/O | false |
+| `heatCirc2` | Heat Circ. 2 | `Switch` | | 🔓 W0 | R/O | false |
+| `roomTempHc3` | Room Temp:HC 3 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `heatCirc3` | Heat Circ. 3 | `Switch` | | 🔓 W0 | R/O | false |
+| `roomTempHc4` | Room Temp:HC 4 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `flowTarget4` | Flow Target 4 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `flowIs4` | Flow is 4 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `mixer4` | Mixer 4 | `String` | | 🔐 W1 | R/O | false |
+| `heatCirc4` | Heat Circ. 4 | `Switch` | | 🔓 W0 | R/O | false |
+| `roomTempHc5` | Room Temp:HC 5 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `flowTarget5` | Flow Target 5 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `flowIs5` | Flow is 5 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `mixer5` | Mixer 5 | `String` | | 🔐 W1 | R/O | false |
+| `heatCirc5` | Heat Circ. 5 | `Switch` | | 🔓 W0 | R/O | false |
+| `roomTempHc6` | Room Temp:HC 6 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `heatCirc6` | Heat Circ. 6 | `Switch` | | 🔓 W0 | R/O | false |
+| `roomTempHc7` | Room Temp:HC 7 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `flowTarget7` | Flow Target 7 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `flowIs7` | Flow is 7 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `mixer7` | Mixer 7 | `String` | | 🔐 W1 | R/O | false |
+| `heatCirc7` | Heat Circ. 7 | `Switch` | | 🔓 W0 | R/O | false |
+| `roomTempHc8` | Room Temp:HC 8 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `flowTarget8` | Flow Target 8 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `flowIs8` | Flow is 8 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `mixer8` | Mixer 8 | `String` | | 🔐 W1 | R/O | false |
+| `heatCirc8` | Heat Circ. 8 | `Switch` | | 🔓 W0 | R/O | false |
+| `fuelLevel` | Fuel Level | `String` | | 🔐 W1 | R/O | false |
+| `stb` | STB | `String` | | 🔐 W1 | R/O | false |
+| `tks` | TKS | `String` | | 🔐 W1 | R/O | false |
+| `boilerApproval` | Boiler approval | `Switch` | | 🔐 W1 | R/O | false |
+| `programme` | Programme | `String` | | 🔓 W0 | R/O | false |
+| `programHc0` | Program HC0 | `String` | | 🔓 W0 | R/O | false |
+| `programHc1` | Program HC1 | `String` | | 🔓 W0 | R/O | false |
+| `programHc2` | Program HC2 | `String` | | 🔓 W0 | R/O | false |
+| `programHc3` | Program HC3 | `String` | | 🔓 W0 | R/O | false |
+| `programHc4` | Program HC4 | `String` | | 🔓 W0 | R/O | false |
+| `programHc5` | Program HC5 | `String` | | 🔓 W0 | R/O | false |
+| `programHc6` | Program HC6 | `String` | | 🔓 W0 | R/O | false |
+| `programHc7` | Program HC7 | `String` | | 🔓 W0 | R/O | false |
+| `programHc8` | Program HC8 | `String` | | 🔓 W0 | R/O | false |
+| `interuption0` | Interuption 0 | `String` | | 🔓 W0 | R/O | false |
+| `interuption1` | Interuption 1 | `String` | | 🔓 W0 | R/O | false |
+| `serial` | Serial | `Number` | | 🔓 W0 | R/O | false |
+| `version` | Version | `String` | | 🔓 W0 | R/O | false |
+| `runningTime` | Running Time | `Number:Time` | `h` | 🔓 W0 | R/O | false |
+| `serviceHrs` | Service Hrs | `Number:Time` | `d` | 🔓 W0 | R/O | false |
+| `emptyAshIn` | Empty ash in | `Number:Time` | `h` | 🔓 W0 | R/O | false |
+| `flowIs0` | Flow is 0 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `flowIs3` | Flow is 3 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `flowIs6` | Flow is 6 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `fuelCounter` | Fuel counter | `Number:Volume` | `m³` | 🔐 W1 | R/O | false |
+| `bufferLoad` | Buffer load. | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
+| `bufferTop0` | Buffer Top 0 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `bufferBtm0` | Buffer Btm 0 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `bufferTop1` | Buffer Top 1 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `bufferBtm1` | Buffer Btm 1 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `bufferTop2` | Buffer Top 2 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `bufferBtm2` | Buffer Btm 2 | `Number:Temperature` | `°C` | 🔐 W1 | R/O | false |
+| `bExtraWw0` | B extra-WW. 0 | `Switch` | | 🔐 W1 | R/O | false |
+| `bExtraWw1` | B extra-WW. 1 | `Switch` | | 🔐 W1 | R/O | false |
+| `bExtraWw2` | B extra-WW. 2 | `Switch` | | 🔐 W1 | R/O | false |
+| `auxiliaryPump0` | Auxiliary pump 0 | `Switch` | | 🔐 W1 | R/O | false |
+| `auxiliaryPump1` | Auxiliary pump 1 | `Switch` | | 🔐 W1 | R/O | false |
+| `auxiliaryPump2` | Auxiliary pump 2 | `Switch` | | 🔐 W1 | R/O | false |
+| `boilersConditionNo` | Boiler´s condition no. | `String` | | 🔐 W1 | R/O | false |
+| `bufferT5` | Buffer T5 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `bufferT6` | Buffer T6 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `bufferT7` | Buffer T7 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `extraWw0` | Extra-WW. 0 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `extraWw1` | Extra-WW. 1 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `extraWw2` | Extra-WW. 2 | `Number:Temperature` | `°C` | 🔓 W0 | R/O | false |
+| `grate` | Grate | `Number:Dimensionless` | `%` | 🔓 W0 | R/O | false |
#### Security Access Levels
## Full Example
-**Thing File**
+### Thing File
```java
Thing guntamatic:biostar:mybiostar "Guntamatic Biostar" [ hostname="192.168.1.100", key="0123456789ABCDEF0123456789ABCDEF0123", refreshInterval=60, encoding="windows-1252" ]
```
-**Item File**
+### Item File
```java
-String Biostar_ControlBoilerApproval "Set Boiler Approval" { channel="guntamatic:biostar:mybiostar:controlBoilerApproval" }
-String Biostar_ControlProgram "Set Program" { channel="guntamatic:biostar:mybiostar:controlProgram" }
-String Biostar_ControlHeatCircProgram0 "Set Heat Circle 0 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram0" }
-String Biostar_ControlHeatCircProgram1 "Set Heat Circle 1 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram1" }
-String Biostar_ControlHeatCircProgram2 "Set Heat Circle 2 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram2" }
-String Biostar_ControlHeatCircProgram3 "Set Heat Circle 3 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram3" }
-String Biostar_ControlHeatCircProgram4 "Set Heat Circle 4 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram4" }
-String Biostar_ControlHeatCircProgram5 "Set Heat Circle 5 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram5" }
-String Biostar_ControlHeatCircProgram6 "Set Heat Circle 6 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram6" }
-String Biostar_ControlHeatCircProgram7 "Set Heat Circle 7 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram7" }
-String Biostar_ControlHeatCircProgram8 "Set Heat Circle 8 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram8" }
-String Biostar_ControlWwHeat0 "Trigger Warm Water Circle 0" { channel="guntamatic:biostar:mybiostar:controlWwHeat0" }
-String Biostar_ControlWwHeat1 "Trigger Warm Water Circle 1" { channel="guntamatic:biostar:mybiostar:controlWwHeat1" }
-String Biostar_ControlWwHeat2 "Trigger Warm Water Circle 2" { channel="guntamatic:biostar:mybiostar:controlWwHeat2" }
-String Biostar_ControlExtraWwHeat0 "Trigger Extra Warm Water Circle 0" { channel="guntamatic:biostar:mybiostar:controlExtraWwHeat0" }
-String Biostar_ControlExtraWwHeat1 "Trigger Extra Warm Water Circle 1" { channel="guntamatic:biostar:mybiostar:controlExtraWwHeat1" }
-String Biostar_ControlExtraWwHeat2 "Trigger Extra Warm Water Circle 2" { channel="guntamatic:biostar:mybiostar:controlExtraWwHeat2" }
-String Biostar_Running "Running" { channel="guntamatic:biostar:mybiostar:running" }
-Number:Temperature Biostar_OutsideTemp "Outside Temp." { channel="guntamatic:biostar:mybiostar:outsideTemp" }
-Number:Temperature Biostar_BlrTargetTemp "Blr.Target Temp" { channel="guntamatic:biostar:mybiostar:blrTargetTemp" }
-Number:Temperature Biostar_BoilerTemperature "Boiler Temperature" { channel="guntamatic:biostar:mybiostar:boilerTemperature" }
-Number:Dimensionless Biostar_FlueGasUtilisation "Flue gas utilisation" { channel="guntamatic:biostar:mybiostar:flueGasUtilisation" }
-Number:Dimensionless Biostar_Output "Output" { channel="guntamatic:biostar:mybiostar:output" }
-Number:Temperature Biostar_ReturnTemp "Return temp" { channel="guntamatic:biostar:mybiostar:returnTemp" }
-Number:Dimensionless Biostar_Co2Target "CO2 Target" { channel="guntamatic:biostar:mybiostar:co2Target" }
-Number:Dimensionless Biostar_Co2Content "CO2 Content" { channel="guntamatic:biostar:mybiostar:co2Content" }
-Number:Temperature Biostar_ReturnTempTarget "Return temp target" { channel="guntamatic:biostar:mybiostar:returnTempTarget" }
-Number Biostar_StatusCode "Status code" { channel="guntamatic:biostar:mybiostar:statusCode" }
-Number:Dimensionless Biostar_Efficiency "Efficiency" { channel="guntamatic:biostar:mybiostar:efficiency" }
-Number:Dimensionless Biostar_ExtractorSystem "Extractor System" { channel="guntamatic:biostar:mybiostar:extractorSystem" }
-String Biostar_FeedTurbine "Feed Turbine" { channel="guntamatic:biostar:mybiostar:feedTurbine" }
-Number:Dimensionless Biostar_DischargeMotor "Discharge motor" { channel="guntamatic:biostar:mybiostar:dischargeMotor" }
-Number:Dimensionless Biostar_G1Target "G1 Target" { channel="guntamatic:biostar:mybiostar:g1Target" }
-Number:Temperature Biostar_BufferTop "Buffer Top" { channel="guntamatic:biostar:mybiostar:bufferTop" }
-Number:Temperature Biostar_BufferMid "Buffer Mid" { channel="guntamatic:biostar:mybiostar:bufferMid" }
-Number:Temperature Biostar_BufferBtm "Buffer Btm" { channel="guntamatic:biostar:mybiostar:bufferBtm" }
-Switch Biostar_PumpHp0 "Pump HP0" { channel="guntamatic:biostar:mybiostar:pumpHp0" }
-Number:Temperature Biostar_Dhw0 "DHW 0" { channel="guntamatic:biostar:mybiostar:dhw0" }
-Switch Biostar_BDhw0 "B DHW 0" { channel="guntamatic:biostar:mybiostar:bDhw0" }
-Number:Temperature Biostar_Dhw1 "DHW 1" { channel="guntamatic:biostar:mybiostar:dhw1" }
-Switch Biostar_BDhw1 "B DHW 1" { channel="guntamatic:biostar:mybiostar:bDhw1" }
-Number:Temperature Biostar_Dhw2 "DHW 2" { channel="guntamatic:biostar:mybiostar:dhw2" }
-Switch Biostar_BDhw2 "B DHW 2" { channel="guntamatic:biostar:mybiostar:bDhw2" }
-Number:Temperature Biostar_RoomTempHc0 "Room Temp:HC 0" { channel="guntamatic:biostar:mybiostar:roomTempHc0" }
-Switch Biostar_HeatCirc0 "Heat Circ. 0" { channel="guntamatic:biostar:mybiostar:heatCirc0" }
-Number:Temperature Biostar_RoomTempHc1 "Room Temp:HC 1" { channel="guntamatic:biostar:mybiostar:roomTempHc1" }
-Number:Temperature Biostar_FlowTarget1 "Flow Target 1" { channel="guntamatic:biostar:mybiostar:flowTarget1" }
-Number:Temperature Biostar_FlowIs1 "Flow is 1" { channel="guntamatic:biostar:mybiostar:flowIs1" }
-String Biostar_Mixer1 "Mixer 1" { channel="guntamatic:biostar:mybiostar:mixer1" }
-Switch Biostar_HeatCirc1 "Heat Circ. 1" { channel="guntamatic:biostar:mybiostar:heatCirc1" }
-Number:Temperature Biostar_RoomTempHc2 "Room Temp:HC 2" { channel="guntamatic:biostar:mybiostar:roomTempHc2" }
-Number:Temperature Biostar_FlowTarget2 "Flow Target 2" { channel="guntamatic:biostar:mybiostar:flowTarget2" }
-Number:Temperature Biostar_FlowIs2 "Flow is 2" { channel="guntamatic:biostar:mybiostar:flowIs2" }
-String Biostar_Mixer2 "Mixer 2" { channel="guntamatic:biostar:mybiostar:mixer2" }
-Switch Biostar_HeatCirc2 "Heat Circ. 2" { channel="guntamatic:biostar:mybiostar:heatCirc2" }
-Number:Temperature Biostar_RoomTempHc3 "Room Temp:HC 3" { channel="guntamatic:biostar:mybiostar:roomTempHc3" }
-Switch Biostar_HeatCirc3 "Heat Circ. 3" { channel="guntamatic:biostar:mybiostar:heatCirc3" }
-Number:Temperature Biostar_RoomTempHc4 "Room Temp:HC 4" { channel="guntamatic:biostar:mybiostar:roomTempHc4" }
-Number:Temperature Biostar_FlowTarget4 "Flow Target 4" { channel="guntamatic:biostar:mybiostar:flowTarget4" }
-Number:Temperature Biostar_FlowIs4 "Flow is 4" { channel="guntamatic:biostar:mybiostar:flowIs4" }
-String Biostar_Mixer4 "Mixer 4" { channel="guntamatic:biostar:mybiostar:mixer4" }
-Switch Biostar_HeatCirc4 "Heat Circ. 4" { channel="guntamatic:biostar:mybiostar:heatCirc4" }
-Number:Temperature Biostar_RoomTempHc5 "Room Temp:HC 5" { channel="guntamatic:biostar:mybiostar:roomTempHc5" }
-Number:Temperature Biostar_FlowTarget5 "Flow Target 5" { channel="guntamatic:biostar:mybiostar:flowTarget5" }
-Number:Temperature Biostar_FlowIs5 "Flow is 5" { channel="guntamatic:biostar:mybiostar:flowIs5" }
-String Biostar_Mixer5 "Mixer 5" { channel="guntamatic:biostar:mybiostar:mixer5" }
-Switch Biostar_HeatCirc5 "Heat Circ. 5" { channel="guntamatic:biostar:mybiostar:heatCirc5" }
-Number:Temperature Biostar_RoomTempHc6 "Room Temp:HC 6" { channel="guntamatic:biostar:mybiostar:roomTempHc6" }
-Switch Biostar_HeatCirc6 "Heat Circ. 6" { channel="guntamatic:biostar:mybiostar:heatCirc6" }
-Number:Temperature Biostar_RoomTempHc7 "Room Temp:HC 7" { channel="guntamatic:biostar:mybiostar:roomTempHc7" }
-Number:Temperature Biostar_FlowTarget7 "Flow Target 7" { channel="guntamatic:biostar:mybiostar:flowTarget7" }
-Number:Temperature Biostar_FlowIs7 "Flow is 7" { channel="guntamatic:biostar:mybiostar:flowIs7" }
-String Biostar_Mixer7 "Mixer 7" { channel="guntamatic:biostar:mybiostar:mixer7" }
-Switch Biostar_HeatCirc7 "Heat Circ. 7" { channel="guntamatic:biostar:mybiostar:heatCirc7" }
-Number:Temperature Biostar_RoomTempHc8 "Room Temp:HC 8" { channel="guntamatic:biostar:mybiostar:roomTempHc8" }
-Number:Temperature Biostar_FlowTarget8 "Flow Target 8" { channel="guntamatic:biostar:mybiostar:flowTarget8" }
-Number:Temperature Biostar_FlowIs8 "Flow is 8" { channel="guntamatic:biostar:mybiostar:flowIs8" }
-String Biostar_Mixer8 "Mixer 8" { channel="guntamatic:biostar:mybiostar:mixer8" }
-Switch Biostar_HeatCirc8 "Heat Circ. 8" { channel="guntamatic:biostar:mybiostar:heatCirc8" }
-String Biostar_FuelLevel "Fuel Level" { channel="guntamatic:biostar:mybiostar:fuelLevel" }
-String Biostar_Stb "STB" { channel="guntamatic:biostar:mybiostar:stb" }
-String Biostar_Tks "TKS" { channel="guntamatic:biostar:mybiostar:tks" }
-Switch Biostar_BoilerApproval "Boiler approval" { channel="guntamatic:biostar:mybiostar:boilerApproval" }
-String Biostar_Programme "Programme" { channel="guntamatic:biostar:mybiostar:programme" }
-String Biostar_ProgramHc0 "Program HC0" { channel="guntamatic:biostar:mybiostar:programHc0" }
-String Biostar_ProgramHc1 "Program HC1" { channel="guntamatic:biostar:mybiostar:programHc1" }
-String Biostar_ProgramHc2 "Program HC2" { channel="guntamatic:biostar:mybiostar:programHc2" }
-String Biostar_ProgramHc3 "Program HC3" { channel="guntamatic:biostar:mybiostar:programHc3" }
-String Biostar_ProgramHc4 "Program HC4" { channel="guntamatic:biostar:mybiostar:programHc4" }
-String Biostar_ProgramHc5 "Program HC5" { channel="guntamatic:biostar:mybiostar:programHc5" }
-String Biostar_ProgramHc6 "Program HC6" { channel="guntamatic:biostar:mybiostar:programHc6" }
-String Biostar_ProgramHc7 "Program HC7" { channel="guntamatic:biostar:mybiostar:programHc7" }
-String Biostar_ProgramHc8 "Program HC8" { channel="guntamatic:biostar:mybiostar:programHc8" }
-String Biostar_Interuption0 "Interuption 0" { channel="guntamatic:biostar:mybiostar:interuption0" }
-String Biostar_Interuption1 "Interuption 1" { channel="guntamatic:biostar:mybiostar:interuption1" }
-Number Biostar_Serial "Serial" { channel="guntamatic:biostar:mybiostar:serial" }
-String Biostar_Version "Version" { channel="guntamatic:biostar:mybiostar:version" }
-Number:Time Biostar_RunningTime "Running Time" { channel="guntamatic:biostar:mybiostar:runningTime" }
-Number:Time Biostar_ServiceHrs "Service Hrs" { channel="guntamatic:biostar:mybiostar:serviceHrs" }
-Number:Time Biostar_EmptyAshIn "Empty ash in" { channel="guntamatic:biostar:mybiostar:emptyAshIn" }
-Number:Temperature Biostar_FlowIs0 "Flow is 0" { channel="guntamatic:biostar:mybiostar:flowIs0" }
-Number:Temperature Biostar_FlowIs3 "Flow is 3" { channel="guntamatic:biostar:mybiostar:flowIs3" }
-Number:Temperature Biostar_FlowIs6 "Flow is 6" { channel="guntamatic:biostar:mybiostar:flowIs6" }
-Number:Volume Biostar_FuelCounter "Fuel counter" { channel="guntamatic:biostar:mybiostar:fuelCounter" }
-Number:Dimensionless Biostar_BufferLoad "Buffer load." { channel="guntamatic:biostar:mybiostar:bufferLoad" }
-Number:Temperature Biostar_BufferTop0 "Buffer Top 0" { channel="guntamatic:biostar:mybiostar:bufferTop0" }
-Number:Temperature Biostar_BufferBtm0 "Buffer Btm 0" { channel="guntamatic:biostar:mybiostar:bufferBtm0" }
-Number:Temperature Biostar_BufferTop1 "Buffer Top 1" { channel="guntamatic:biostar:mybiostar:bufferTop1" }
-Number:Temperature Biostar_BufferBtm1 "Buffer Btm 1" { channel="guntamatic:biostar:mybiostar:bufferBtm1" }
-Number:Temperature Biostar_BufferTop2 "Buffer Top 2" { channel="guntamatic:biostar:mybiostar:bufferTop2" }
-Number:Temperature Biostar_BufferBtm2 "Buffer Btm 2" { channel="guntamatic:biostar:mybiostar:bufferBtm2" }
-Switch Biostar_BExtraWw0 "B extra-WW. 0" { channel="guntamatic:biostar:mybiostar:bExtraWw0" }
-Switch Biostar_BExtraWw1 "B extra-WW. 1" { channel="guntamatic:biostar:mybiostar:bExtraWw1" }
-Switch Biostar_BExtraWw2 "B extra-WW. 2" { channel="guntamatic:biostar:mybiostar:bExtraWw2" }
-Switch Biostar_AuxiliaryPump0 "Auxiliary pump 0" { channel="guntamatic:biostar:mybiostar:auxiliaryPump0" }
-Switch Biostar_AuxiliaryPump1 "Auxiliary pump 1" { channel="guntamatic:biostar:mybiostar:auxiliaryPump1" }
-Switch Biostar_AuxiliaryPump2 "Auxiliary pump 2" { channel="guntamatic:biostar:mybiostar:auxiliaryPump2" }
-String Biostar_BoilersConditionNo "Boiler´s condition no." { channel="guntamatic:biostar:mybiostar:boilersConditionNo" }
-Number:Temperature Biostar_BufferT5 "Buffer T5" { channel="guntamatic:biostar:mybiostar:bufferT5" }
-Number:Temperature Biostar_BufferT6 "Buffer T6" { channel="guntamatic:biostar:mybiostar:bufferT6" }
-Number:Temperature Biostar_BufferT7 "Buffer T7" { channel="guntamatic:biostar:mybiostar:bufferT7" }
-Number:Temperature Biostar_ExtraWw0 "Extra-WW. 0" { channel="guntamatic:biostar:mybiostar:extraWw0" }
-Number:Temperature Biostar_ExtraWw1 "Extra-WW. 1" { channel="guntamatic:biostar:mybiostar:extraWw1" }
-Number:Temperature Biostar_ExtraWw2 "Extra-WW. 2" { channel="guntamatic:biostar:mybiostar:extraWw2" }
-Number:Dimensionless Biostar_Grate "Grate" { channel="guntamatic:biostar:mybiostar:grate" }
+String Biostar_ControlBoilerApproval "Set Boiler Approval" { channel="guntamatic:biostar:mybiostar:controlBoilerApproval" }
+String Biostar_ControlProgram "Set Program" { channel="guntamatic:biostar:mybiostar:controlProgram" }
+String Biostar_ControlHeatCircProgram0 "Set Heat Circle 0 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram0" }
+String Biostar_ControlHeatCircProgram1 "Set Heat Circle 1 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram1" }
+String Biostar_ControlHeatCircProgram2 "Set Heat Circle 2 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram2" }
+String Biostar_ControlHeatCircProgram3 "Set Heat Circle 3 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram3" }
+String Biostar_ControlHeatCircProgram4 "Set Heat Circle 4 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram4" }
+String Biostar_ControlHeatCircProgram5 "Set Heat Circle 5 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram5" }
+String Biostar_ControlHeatCircProgram6 "Set Heat Circle 6 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram6" }
+String Biostar_ControlHeatCircProgram7 "Set Heat Circle 7 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram7" }
+String Biostar_ControlHeatCircProgram8 "Set Heat Circle 8 Program" { channel="guntamatic:biostar:mybiostar:controlHeatCircProgram8" }
+String Biostar_ControlWwHeat0 "Trigger Warm Water Circle 0" { channel="guntamatic:biostar:mybiostar:controlWwHeat0" }
+String Biostar_ControlWwHeat1 "Trigger Warm Water Circle 1" { channel="guntamatic:biostar:mybiostar:controlWwHeat1" }
+String Biostar_ControlWwHeat2 "Trigger Warm Water Circle 2" { channel="guntamatic:biostar:mybiostar:controlWwHeat2" }
+String Biostar_ControlExtraWwHeat0 "Trigger Extra Warm Water Circle 0" { channel="guntamatic:biostar:mybiostar:controlExtraWwHeat0" }
+String Biostar_ControlExtraWwHeat1 "Trigger Extra Warm Water Circle 1" { channel="guntamatic:biostar:mybiostar:controlExtraWwHeat1" }
+String Biostar_ControlExtraWwHeat2 "Trigger Extra Warm Water Circle 2" { channel="guntamatic:biostar:mybiostar:controlExtraWwHeat2" }
+String Biostar_Running "Running" { channel="guntamatic:biostar:mybiostar:running" }
+Number:Temperature Biostar_OutsideTemp "Outside Temp." { channel="guntamatic:biostar:mybiostar:outsideTemp" }
+Number:Temperature Biostar_BlrTargetTemp "Blr.Target Temp" { channel="guntamatic:biostar:mybiostar:blrTargetTemp" }
+Number:Temperature Biostar_BoilerTemperature "Boiler Temperature" { channel="guntamatic:biostar:mybiostar:boilerTemperature" }
+Number:Dimensionless Biostar_FlueGasUtilisation "Flue gas utilisation" { channel="guntamatic:biostar:mybiostar:flueGasUtilisation" }
+Number:Dimensionless Biostar_Output "Output" { channel="guntamatic:biostar:mybiostar:output" }
+Number:Temperature Biostar_ReturnTemp "Return temp" { channel="guntamatic:biostar:mybiostar:returnTemp" }
+Number:Dimensionless Biostar_Co2Target "CO2 Target" { channel="guntamatic:biostar:mybiostar:co2Target" }
+Number:Dimensionless Biostar_Co2Content "CO2 Content" { channel="guntamatic:biostar:mybiostar:co2Content" }
+Number:Temperature Biostar_ReturnTempTarget "Return temp target" { channel="guntamatic:biostar:mybiostar:returnTempTarget" }
+Number Biostar_StatusCode "Status code" { channel="guntamatic:biostar:mybiostar:statusCode" }
+Number:Dimensionless Biostar_Efficiency "Efficiency" { channel="guntamatic:biostar:mybiostar:efficiency" }
+Number:Dimensionless Biostar_ExtractorSystem "Extractor System" { channel="guntamatic:biostar:mybiostar:extractorSystem" }
+String Biostar_FeedTurbine "Feed Turbine" { channel="guntamatic:biostar:mybiostar:feedTurbine" }
+Number:Dimensionless Biostar_DischargeMotor "Discharge motor" { channel="guntamatic:biostar:mybiostar:dischargeMotor" }
+Number:Dimensionless Biostar_G1Target "G1 Target" { channel="guntamatic:biostar:mybiostar:g1Target" }
+Number:Temperature Biostar_BufferTop "Buffer Top" { channel="guntamatic:biostar:mybiostar:bufferTop" }
+Number:Temperature Biostar_BufferMid "Buffer Mid" { channel="guntamatic:biostar:mybiostar:bufferMid" }
+Number:Temperature Biostar_BufferBtm "Buffer Btm" { channel="guntamatic:biostar:mybiostar:bufferBtm" }
+Switch Biostar_PumpHp0 "Pump HP0" { channel="guntamatic:biostar:mybiostar:pumpHp0" }
+Number:Temperature Biostar_Dhw0 "DHW 0" { channel="guntamatic:biostar:mybiostar:dhw0" }
+Switch Biostar_BDhw0 "B DHW 0" { channel="guntamatic:biostar:mybiostar:bDhw0" }
+Number:Temperature Biostar_Dhw1 "DHW 1" { channel="guntamatic:biostar:mybiostar:dhw1" }
+Switch Biostar_BDhw1 "B DHW 1" { channel="guntamatic:biostar:mybiostar:bDhw1" }
+Number:Temperature Biostar_Dhw2 "DHW 2" { channel="guntamatic:biostar:mybiostar:dhw2" }
+Switch Biostar_BDhw2 "B DHW 2" { channel="guntamatic:biostar:mybiostar:bDhw2" }
+Number:Temperature Biostar_RoomTempHc0 "Room Temp:HC 0" { channel="guntamatic:biostar:mybiostar:roomTempHc0" }
+Switch Biostar_HeatCirc0 "Heat Circ. 0" { channel="guntamatic:biostar:mybiostar:heatCirc0" }
+Number:Temperature Biostar_RoomTempHc1 "Room Temp:HC 1" { channel="guntamatic:biostar:mybiostar:roomTempHc1" }
+Number:Temperature Biostar_FlowTarget1 "Flow Target 1" { channel="guntamatic:biostar:mybiostar:flowTarget1" }
+Number:Temperature Biostar_FlowIs1 "Flow is 1" { channel="guntamatic:biostar:mybiostar:flowIs1" }
+String Biostar_Mixer1 "Mixer 1" { channel="guntamatic:biostar:mybiostar:mixer1" }
+Switch Biostar_HeatCirc1 "Heat Circ. 1" { channel="guntamatic:biostar:mybiostar:heatCirc1" }
+Number:Temperature Biostar_RoomTempHc2 "Room Temp:HC 2" { channel="guntamatic:biostar:mybiostar:roomTempHc2" }
+Number:Temperature Biostar_FlowTarget2 "Flow Target 2" { channel="guntamatic:biostar:mybiostar:flowTarget2" }
+Number:Temperature Biostar_FlowIs2 "Flow is 2" { channel="guntamatic:biostar:mybiostar:flowIs2" }
+String Biostar_Mixer2 "Mixer 2" { channel="guntamatic:biostar:mybiostar:mixer2" }
+Switch Biostar_HeatCirc2 "Heat Circ. 2" { channel="guntamatic:biostar:mybiostar:heatCirc2" }
+Number:Temperature Biostar_RoomTempHc3 "Room Temp:HC 3" { channel="guntamatic:biostar:mybiostar:roomTempHc3" }
+Switch Biostar_HeatCirc3 "Heat Circ. 3" { channel="guntamatic:biostar:mybiostar:heatCirc3" }
+Number:Temperature Biostar_RoomTempHc4 "Room Temp:HC 4" { channel="guntamatic:biostar:mybiostar:roomTempHc4" }
+Number:Temperature Biostar_FlowTarget4 "Flow Target 4" { channel="guntamatic:biostar:mybiostar:flowTarget4" }
+Number:Temperature Biostar_FlowIs4 "Flow is 4" { channel="guntamatic:biostar:mybiostar:flowIs4" }
+String Biostar_Mixer4 "Mixer 4" { channel="guntamatic:biostar:mybiostar:mixer4" }
+Switch Biostar_HeatCirc4 "Heat Circ. 4" { channel="guntamatic:biostar:mybiostar:heatCirc4" }
+Number:Temperature Biostar_RoomTempHc5 "Room Temp:HC 5" { channel="guntamatic:biostar:mybiostar:roomTempHc5" }
+Number:Temperature Biostar_FlowTarget5 "Flow Target 5" { channel="guntamatic:biostar:mybiostar:flowTarget5" }
+Number:Temperature Biostar_FlowIs5 "Flow is 5" { channel="guntamatic:biostar:mybiostar:flowIs5" }
+String Biostar_Mixer5 "Mixer 5" { channel="guntamatic:biostar:mybiostar:mixer5" }
+Switch Biostar_HeatCirc5 "Heat Circ. 5" { channel="guntamatic:biostar:mybiostar:heatCirc5" }
+Number:Temperature Biostar_RoomTempHc6 "Room Temp:HC 6" { channel="guntamatic:biostar:mybiostar:roomTempHc6" }
+Switch Biostar_HeatCirc6 "Heat Circ. 6" { channel="guntamatic:biostar:mybiostar:heatCirc6" }
+Number:Temperature Biostar_RoomTempHc7 "Room Temp:HC 7" { channel="guntamatic:biostar:mybiostar:roomTempHc7" }
+Number:Temperature Biostar_FlowTarget7 "Flow Target 7" { channel="guntamatic:biostar:mybiostar:flowTarget7" }
+Number:Temperature Biostar_FlowIs7 "Flow is 7" { channel="guntamatic:biostar:mybiostar:flowIs7" }
+String Biostar_Mixer7 "Mixer 7" { channel="guntamatic:biostar:mybiostar:mixer7" }
+Switch Biostar_HeatCirc7 "Heat Circ. 7" { channel="guntamatic:biostar:mybiostar:heatCirc7" }
+Number:Temperature Biostar_RoomTempHc8 "Room Temp:HC 8" { channel="guntamatic:biostar:mybiostar:roomTempHc8" }
+Number:Temperature Biostar_FlowTarget8 "Flow Target 8" { channel="guntamatic:biostar:mybiostar:flowTarget8" }
+Number:Temperature Biostar_FlowIs8 "Flow is 8" { channel="guntamatic:biostar:mybiostar:flowIs8" }
+String Biostar_Mixer8 "Mixer 8" { channel="guntamatic:biostar:mybiostar:mixer8" }
+Switch Biostar_HeatCirc8 "Heat Circ. 8" { channel="guntamatic:biostar:mybiostar:heatCirc8" }
+String Biostar_FuelLevel "Fuel Level" { channel="guntamatic:biostar:mybiostar:fuelLevel" }
+String Biostar_Stb "STB" { channel="guntamatic:biostar:mybiostar:stb" }
+String Biostar_Tks "TKS" { channel="guntamatic:biostar:mybiostar:tks" }
+Switch Biostar_BoilerApproval "Boiler approval" { channel="guntamatic:biostar:mybiostar:boilerApproval" }
+String Biostar_Programme "Programme" { channel="guntamatic:biostar:mybiostar:programme" }
+String Biostar_ProgramHc0 "Program HC0" { channel="guntamatic:biostar:mybiostar:programHc0" }
+String Biostar_ProgramHc1 "Program HC1" { channel="guntamatic:biostar:mybiostar:programHc1" }
+String Biostar_ProgramHc2 "Program HC2" { channel="guntamatic:biostar:mybiostar:programHc2" }
+String Biostar_ProgramHc3 "Program HC3" { channel="guntamatic:biostar:mybiostar:programHc3" }
+String Biostar_ProgramHc4 "Program HC4" { channel="guntamatic:biostar:mybiostar:programHc4" }
+String Biostar_ProgramHc5 "Program HC5" { channel="guntamatic:biostar:mybiostar:programHc5" }
+String Biostar_ProgramHc6 "Program HC6" { channel="guntamatic:biostar:mybiostar:programHc6" }
+String Biostar_ProgramHc7 "Program HC7" { channel="guntamatic:biostar:mybiostar:programHc7" }
+String Biostar_ProgramHc8 "Program HC8" { channel="guntamatic:biostar:mybiostar:programHc8" }
+String Biostar_Interuption0 "Interuption 0" { channel="guntamatic:biostar:mybiostar:interuption0" }
+String Biostar_Interuption1 "Interuption 1" { channel="guntamatic:biostar:mybiostar:interuption1" }
+Number Biostar_Serial "Serial" { channel="guntamatic:biostar:mybiostar:serial" }
+String Biostar_Version "Version" { channel="guntamatic:biostar:mybiostar:version" }
+Number:Time Biostar_RunningTime "Running Time" { channel="guntamatic:biostar:mybiostar:runningTime" }
+Number:Time Biostar_ServiceHrs "Service Hrs" { channel="guntamatic:biostar:mybiostar:serviceHrs" }
+Number:Time Biostar_EmptyAshIn "Empty ash in" { channel="guntamatic:biostar:mybiostar:emptyAshIn" }
+Number:Temperature Biostar_FlowIs0 "Flow is 0" { channel="guntamatic:biostar:mybiostar:flowIs0" }
+Number:Temperature Biostar_FlowIs3 "Flow is 3" { channel="guntamatic:biostar:mybiostar:flowIs3" }
+Number:Temperature Biostar_FlowIs6 "Flow is 6" { channel="guntamatic:biostar:mybiostar:flowIs6" }
+Number:Volume Biostar_FuelCounter "Fuel counter" { channel="guntamatic:biostar:mybiostar:fuelCounter" }
+Number:Dimensionless Biostar_BufferLoad "Buffer load." { channel="guntamatic:biostar:mybiostar:bufferLoad" }
+Number:Temperature Biostar_BufferTop0 "Buffer Top 0" { channel="guntamatic:biostar:mybiostar:bufferTop0" }
+Number:Temperature Biostar_BufferBtm0 "Buffer Btm 0" { channel="guntamatic:biostar:mybiostar:bufferBtm0" }
+Number:Temperature Biostar_BufferTop1 "Buffer Top 1" { channel="guntamatic:biostar:mybiostar:bufferTop1" }
+Number:Temperature Biostar_BufferBtm1 "Buffer Btm 1" { channel="guntamatic:biostar:mybiostar:bufferBtm1" }
+Number:Temperature Biostar_BufferTop2 "Buffer Top 2" { channel="guntamatic:biostar:mybiostar:bufferTop2" }
+Number:Temperature Biostar_BufferBtm2 "Buffer Btm 2" { channel="guntamatic:biostar:mybiostar:bufferBtm2" }
+Switch Biostar_BExtraWw0 "B extra-WW. 0" { channel="guntamatic:biostar:mybiostar:bExtraWw0" }
+Switch Biostar_BExtraWw1 "B extra-WW. 1" { channel="guntamatic:biostar:mybiostar:bExtraWw1" }
+Switch Biostar_BExtraWw2 "B extra-WW. 2" { channel="guntamatic:biostar:mybiostar:bExtraWw2" }
+Switch Biostar_AuxiliaryPump0 "Auxiliary pump 0" { channel="guntamatic:biostar:mybiostar:auxiliaryPump0" }
+Switch Biostar_AuxiliaryPump1 "Auxiliary pump 1" { channel="guntamatic:biostar:mybiostar:auxiliaryPump1" }
+Switch Biostar_AuxiliaryPump2 "Auxiliary pump 2" { channel="guntamatic:biostar:mybiostar:auxiliaryPump2" }
+String Biostar_BoilersConditionNo "Boiler´s condition no." { channel="guntamatic:biostar:mybiostar:boilersConditionNo" }
+Number:Temperature Biostar_BufferT5 "Buffer T5" { channel="guntamatic:biostar:mybiostar:bufferT5" }
+Number:Temperature Biostar_BufferT6 "Buffer T6" { channel="guntamatic:biostar:mybiostar:bufferT6" }
+Number:Temperature Biostar_BufferT7 "Buffer T7" { channel="guntamatic:biostar:mybiostar:bufferT7" }
+Number:Temperature Biostar_ExtraWw0 "Extra-WW. 0" { channel="guntamatic:biostar:mybiostar:extraWw0" }
+Number:Temperature Biostar_ExtraWw1 "Extra-WW. 1" { channel="guntamatic:biostar:mybiostar:extraWw1" }
+Number:Temperature Biostar_ExtraWw2 "Extra-WW. 2" { channel="guntamatic:biostar:mybiostar:extraWw2" }
+Number:Dimensionless Biostar_Grate "Grate" { channel="guntamatic:biostar:mybiostar:grate" }
```
-**Rule**
+### Rule
-```javascript
+```java
rule "Example Guntamatic Rule"
when
Item Season changed
Forum topic for feedback:
- - [openHAB community #128451](https://community.openhab.org/t/guntamatic-new-binding-for-guntamatic-heating-systems-biostar-powerchip-powercorn-biocom-pro-therm/128451 "openHAB community #128451")
+- [openHAB community #128451](https://community.openhab.org/t/guntamatic-new-binding-for-guntamatic-heating-systems-biostar-powerchip-powercorn-biocom-pro-therm/128451 "openHAB community #128451")
# Haas Sohn Pellet Stove Binding
The binding for Haassohnpelletstove communicates with a Haas and Sohn Pelletstove through the optional
-WIFI module. More information about the WIFI module can be found here: https://www.haassohn.com/de/ihr-plus/WLAN-Funktion
+WIFI module. More information about the WIFI module can be found here: <https://www.haassohn.com/de/ihr-plus/WLAN-Funktion>
## Supported Things
|--------|--------------|------------|
| haassohnpelletstove | Control of a Haas & Sohn Pellet Stove| oven|
-
## Thing Configuration
In general two parameters are required. The IP-Address of the WIFI-Modul of the Stove in the local Network and the Access PIN of the Stove.
The PIN can be found directly at the stove under the Menue/Network/WLAN-PIN
-```
+```java
Thing haassohnpelletstove:oven:myOven "Pelletstove" [ hostIP="192.168.0.23", hostPIN="1234"]
```
The following channels are yet supported:
-
| Channel | Type | Access| Description|
|---------|-------|-------|------------|
| power| Switch | read/write|Turn the stove on/off|
demo.items:
-```
+```java
Number:Temperature isTemp { channel="oven:channelIsTemp" }
Number:Temperature spTemp { channel="oven:channelSpTemp" }
String mode { channel="oven:channelMode" }
## Google Assistant configuration
-See also: https://www.openhab.org/docs/ecosystem/google-assistant/
+See also: <https://www.openhab.org/docs/ecosystem/google-assistant/>
googleassistantdemo.items
-```
+```java
Group g_FeuerThermostat "FeuerThermostat" {ga="Thermostat" }
Number StatusFeuer "Status Feuer" (g_FeuerThermostat) { ga="thermostatMode" }
Number ZieltemperaturFeuer "ZieltemperaturFeuer" (g_FeuerThermostat) {ga="thermostatTemperatureSetpoint"}
```
Hubs can also send a button press to a device associated with the current activity.
-A String item can be used to send any button name/label or a Player item can be used to send Play/Pause/FastForward/Rewind/SkipForward/SkipBackward.
+A String item can be used to send any button name/label or a Player item can be used to send Play/Pause/FastForward/Rewind/SkipForward/SkipBackward.
This mimics the physical remote where buttons are mapped differently depending on which activity is running.
-For example the play button may be sent to a DVD player when running a "Watch DVD" activity, or it may be sent to an Apple TV when running a "Watch Movie" activity.
-
+For example the play button may be sent to a DVD player when running a "Watch DVD" activity, or it may be sent to an Apple TV when running a "Watch Movie" activity.
```java
String HarmonyHubGreatButton { channel="harmonyhub:hub:GreatRoom:buttonPress" }
## ButtonPress values
-Example subset of values for the current activity "buttonPress" channels
+Example subset of values for the current activity "buttonPress" channels
-```
+```text
Mute,VolumeDown,VolumeUp,DirectionDown,DirectionLeft,DirectionRight,DirectionUp,Select,Stop,Play,Rewind,Pause,FastForward,SkipBackward,SkipForward,Menu,Back,Home,SelectGame,PageDown,PageUp,Aspect,Display,Search,Cross,Circle,Square,Triangle,PS,Info,NumberEnter,Hyphen,Number0,Number1,Number2,Number3,Number4,Number5,Number6,Number7,Number8,Number9,PrevChannel,ChannelDown,ChannelUp,Record,FrameAdvance,C,B,D,A,Live,ThumbsDown,ThumbsUp,TiVo,WiiA,WiiB,Guide,Clear,Green,Red,Blue,Yellow,Dot,Return,Favorite,Exit,Sleep
```
A complete list of names for device buttons values can be determined via the REST API for channel-types. The easiest way to do this is through the API explorer:
1. Go to the main UI page for your installation
- * This is usually at <http://your-openhab-ip:8080> or, in the case of openhabian, <http://openhabian:8080>
-2. Login if you are not already logged in
-3. Using the left panel (or three bars on the upper left corner) go to Developer Tools -> API Explorer -> channel-types
-4. Click `GET` next to `/channel-types`
-5. Click `Try it out`
-6. Click `Execute`
-7. Search the `Response Body` "harmonyhub:device" and find your device in the JSON output
+ - This is usually at <http://your-openhab-ip:8080> or, in the case of openhabian, <http://openhabian:8080>
+1. Login if you are not already logged in
+1. Using the left panel (or three bars on the upper left corner) go to Developer Tools -> API Explorer -> channel-types
+1. Click `GET` next to `/channel-types`
+1. Click `Try it out`
+1. Click `Execute`
+1. Search the `Response Body` "harmonyhub:device" and find your device in the JSON output
The valid commands (read: values) will be listed with the device. For example, the response body might show that for `harmonyhub:device:HarmonyHub:lasko_fan` the valid commands are `PowerToggle, Speed, Timer`
- {
- "parameters": [],
- "parameterGroups": [],
- "description": "Send a button press to device Harmony Device",
- "label": "Send Button Press",
- "itemType": "String",
- "kind": "STATE",
- "stateDescription": {
- "readOnly": false,
- "options": [
- {
- "value": "PowerToggle",
- "label": "Power Toggle"
- },
- {
- "value": "Speed",
- "label": "Speed"
- },
- {
- "value": "Timer",
- "label": "Timer"
- }
- ]
- },
- "tags": [],
- "UID": "harmonyhub:device:GreatRoom:lasko_fan:buttonPress",
- "advanced": false
+```json
+{
+ "parameters": [],
+ "parameterGroups": [],
+ "description": "Send a button press to device Harmony Device",
+ "label": "Send Button Press",
+ "itemType": "String",
+ "kind": "STATE",
+ "stateDescription": {
+ "readOnly": false,
+ "options": [
+ {
+ "value": "PowerToggle",
+ "label": "Power Toggle"
+ },
+ {
+ "value": "Speed",
+ "label": "Speed"
+ },
+ {
+ "value": "Timer",
+ "label": "Timer"
}
+ ]
+ },
+ "tags": [],
+ "UID": "harmonyhub:device:GreatRoom:lasko_fan:buttonPress",
+ "advanced": false
+}
+```
| Property | Default | Required | Description |
|----------------------|----------------------------------------------------------------|----------|----------------------------------------------|
-| Host Name | https://app1.haywardomnilogic.com/HAAPI/HomeAutomation/API.ash | Yes | Host name of the Hayward API server |
+| Host Name | <https://app1.haywardomnilogic.com/HAAPI/HomeAutomation/API.ash> | Yes | Host name of the Hayward API server |
| User Name | None | Yes | Your Hayward User Name (not email address) |
| Password | None | Yes | Your Hayward User Password |
| Telemetry Poll Delay | 12 | Yes | Telemetry Poll Delay (10-60 seconds) |
## Thing Configuration
The thing supports one setting labelled `address` which is your street number and name as it appears on Google.
-*For Example:
-1 Victoria Street*
+_For Example:
+1 Victoria Street_
> Note: The above address example is not valid as it is a business address.
-*__If the address is not valid or rubbish collection service does not apply (for example, a business address) then a `CONFIGURATION_ERROR` will occur.__*
+_If the address is not valid or rubbish collection service does not apply (for example, a business address) then a `CONFIGURATION_ERROR` will occur._
## Channels
#### Configuration
-You can set an `offset` in minutes.
+You can set an `offset` in minutes.
This can then trigger the collection event before or after the normal time of 12:00am on the day of the collection.
-*For Example:
-If you want the event to trigger at 7pm the day before, to remind you to take out the bins, then set the `offset` to `-300` (5 hours x 60 minutes).*
+_For Example:
+If you want the event to trigger at 7pm the day before, to remind you to take out the bins, then set the `offset` to `-300` (5 hours x 60 minutes)._
This binding currently supports the following thing types:
-- *multiroomplus* : Multiroom+ V3 (**Note:** This product is no longer sold by HDanywhere)
-- *mhub4k431* : MHUB 4K (4X3+1)
+- _multiroomplus_ : Multiroom+ V3 (**Note:** This product is no longer sold by HDanywhere)
+- _mhub4k431_ : MHUB 4K (4X3+1)
## Discovery
## Thing Configuration
Each thing requires the IP address of the matrix, and the interval in between status updates that are fetched from the matrix.
-Additionally, the *multiroomplus* has an additional required parameter 'ports' to specify the number of physical ports (e.g. 4x4, 8x8,...) of the matrix.
+Additionally, the _multiroomplus_ has an additional required parameter 'ports' to specify the number of physical ports (e.g. 4x4, 8x8,...) of the matrix.
```java
Thing hdanywhere:mhub4k431:m1 [ipAddress="192.168.0.89",interval=15]
The discovery process can be started by pressing the refresh button in the Main Configuration UI Inbox.
However you can also manually create a (bridge) thing for the hub, and enter the required configuration parameters (see Thing Configuration below).
If the configuration parameters are all valid, the binding will then automatically attempt to connect to the hub.
-If the connection succeeds, the hub will indicate its status as Online, otherwise it will show an error status.
+If the connection succeeds, the hub will indicate its status as Online, otherwise it will show an error status.
Once the hub thing has been created and successfully connected, the binding will automatically discover all shades and scenes that are in it.
|-------------------------|---------------|
| host | The host name or IP address of the hub on your network. |
| refresh | The number of milli-seconds between fetches of the PowerView hub's shade state (default 60'000 one minute). |
-| hardRefresh | The number of minutes between hard refreshes of the PowerView hub's shade state (default 180 three hours). See [Refreshing the PowerView Hub Cache](#Refreshing-the-PowerView-Hub-Cache). |
-| hardRefreshBatteryLevel | The number of hours between hard refreshes of battery levels from the PowerView Hub (or 0 to disable, defaulting to weekly). See [Refreshing the PowerView Hub Cache](#Refreshing-the-PowerView-Hub-Cache). |
+| hardRefresh | The number of minutes between hard refreshes of the PowerView hub's shade state (default 180 three hours). See [Refreshing the PowerView Hub Cache](#refreshing-the-powerview-hub-cache). |
+| hardRefreshBatteryLevel | The number of hours between hard refreshes of battery levels from the PowerView Hub (or 0 to disable, defaulting to weekly). See [Refreshing the PowerView Hub Cache](#refreshing-the-powerview-hub-cache). |
### Thing Configuration for PowerView Shades and Accessories
| Channel | Item Type | Description |
|----------------|--------------------------|-------------|
-| position | Rollershutter | The vertical position of the shade's rail (if any). -- See [next chapter](#Roller-Shutter-Up/Down-Position-vs.-Open/Close-State). Up/Down commands will move the rail completely up or completely down. Percentage commands will move the rail to an intermediate position. Stop commands will halt any current movement of the rail. |
-| secondary | Rollershutter | The vertical position of the secondary rail (if any). Its function is similar to the `position` channel above. -- But see [next chapter](#Roller-Shutter-Up/Down-Position-vs.-Open/Close-State). |
-| vane | Dimmer | The degree of opening of the slats or vanes (if any). On some shade types, setting this to a non-zero value might first move the shade `position` fully down, since the slats or vanes can only have a defined state if the shade is in its down position. See [Interdependency between Channel positions](#Interdependency-between-Channel-positions). |
+| position | Rollershutter | The vertical position of the shade's rail (if any). -- See [next chapter](#roller-shutter-updown-position-vs-openclose-state). Up/Down commands will move the rail completely up or completely down. Percentage commands will move the rail to an intermediate position. Stop commands will halt any current movement of the rail. |
+| secondary | Rollershutter | The vertical position of the secondary rail (if any). Its function is similar to the `position` channel above. -- But see [next chapter](#roller-shutter-updown-position-vs-openclose-state). |
+| vane | Dimmer | The degree of opening of the slats or vanes (if any). On some shade types, setting this to a non-zero value might first move the shade `position` fully down, since the slats or vanes can only have a defined state if the shade is in its down position. See [Interdependency between Channel positions](#interdependency-between-channel-positions). |
| command | String | Send a command to the shade. Valid values are: `CALIBRATE`, `IDENTIFY` |
| lowBattery | Switch | Indicates ON when the battery level of the shade is low, as determined by the hub's internal rules. |
| batteryLevel | Number | Battery level (10% = low, 50% = medium, 100% = high) |
|-----------------------------|-------------------|-----------------------|------------------|----------------|-------------------|----------------------|
| Single action<br>bottom-up | `position` | ▲ | Up | `OPEN` | 0% | ▲ |
| | | ▼ | Down | `CLOSED` | 100% | ▼ |
-| Single action<br>top-down | `position` | ▲ | Up | ***`CLOSED`*** | 0% | ▲ |
-| | | ▼ | Down | ***`OPEN`*** | 100% | ▼ |
-| Single action<br>right-left | `position` | ▲ | ***Left*** | `OPEN` | 0% | ▲ |
-| | | ▼ | ***Right*** | `CLOSED` | 100% | ▼ |
-| Single action<br>left-right | `position` | ▲ | ***Right*** | `OPEN` | 0% | ▲ |
-| | | ▼ | ***Left*** | `CLOSED` | 100% | ▼ |
+| Single action<br>top-down | `position` | ▲ | Up | **`CLOSED`** | 0% | ▲ |
+| | | ▼ | Down | **`OPEN`** | 100% | ▼ |
+| Single action<br>right-left | `position` | ▲ | _**Left**_ | `OPEN` | 0% | ▲ |
+| | | ▼ | _**Right**_ | `CLOSED` | 100% | ▼ |
+| Single action<br>left-right | `position` | ▲ | _**Right**_ | `OPEN` | 0% | ▲ |
+| | | ▼ | _**Left**_ | `CLOSED` | 100% | ▼ |
| Dual action<br>(lower rail) | `position` | ▲ | Up | `OPEN` | 0% | ▲ |
| | | ▼ | Down | `CLOSED` | 100% | ▼ |
-| Dual action<br>(upper rail) | ***`secondary`*** | ▲ | Up | ***`CLOSED`*** | 0%<sup>1)</sup> |  |
-| | | ▼ | Down | ***`OPEN`*** | 100%<sup>1)</sup> |  |
-| Blackout panel ('DuoLite') | ***`secondary`*** | ▲ | Up | `OPEN` | 0% | ▲ |
+| Dual action<br>(upper rail) | _**`secondary`**_ | ▲ | Up | **`CLOSED`** | 0%<sup>1)</sup> |  |
+| | | ▼ | Down | **`OPEN`** | 100%<sup>1)</sup> |  |
+| Blackout panel ('DuoLite') | _**`secondary`**_ | ▲ | Up | `OPEN` | 0% | ▲ |
| | | ▼ | Down | `CLOSED` | 100% | ▼ |
-***<sup>1)</sup> BUG NOTE***: In openHAB versions v3.1.x and earlier, there was a bug in the handling of the position percent value of the `secondary` shade.
+_**<sup>1)</sup> BUG NOTE**_: In openHAB versions v3.1.x and earlier, there was a bug in the handling of the position percent value of the `secondary` shade.
Although the RollerShutter Up/Down commands functioned properly as described in the table above, the percent state values (e.g. displayed on a slider control), did not.
After moving the shade, the percent value would initially display the correct value, but on the next refresh it would 'flip' to the **inverse** of the correct value.
The details are shown in the following table.
This bug has been fixed from openHAB v3.2.x (or later) —
-***so if you have rules that depend on the percent value, and you update from an earlier openHAB version to v3.2.x (or later), you will need to modify them!***
+_so if you have rules that depend on the percent value, and you update from an earlier openHAB version to v3.2.x (or later), you will need to modify them!_
| Channel | UI Control Element | UI Control Command | Immediate Action<br>on Shade State | Dimmer Percent Display<br>(Initial => Final) |
|-------------|--------------------|---------------------|------------------------------------|----------------------------------------------|
Note: You can also force the hub to refresh itself by sending a `REFRESH` command in a rule to an item that is connected to a channel in the hub as follows:
-```
+```java
rule "Hub Refresh (every 20 minutes)"
when
Time cron "0 1/20 0 ? * * *"
### `demo.things` File
-```
+```java
Bridge hdpowerview:hub:home "Luxaflex Hub" @ "Living Room" [host="192.168.1.123"] {
Thing shade s50150 "Living Room Shade" @ "Living Room" [id="50150"]
Thing repeater r16384 "Bedroom Repeater" @ "Bedroom" [id="16384"]
Shade items:
-```
+```java
Rollershutter Living_Room_Shade_Position "Living Room Shade Position [%.0f %%]" {channel="hdpowerview:shade:home:s50150:position"}
Rollershutter Living_Room_Shade_Secondary "Living Room Shade Secondary Position [%.0f %%]" {channel="hdpowerview:shade:home:s50150:secondary"}
Dimmer Living_Room_Shade_Vane "Living Room Shade Vane [%.0f %%]" {channel="hdpowerview:shade:home:s50150:vane"}
Repeater items:
-```
+```java
Color Bedroom_Repeater_Color "Bedroom Repeater Color" {channel="hdpowerview:repeater:home:r16384:color"}
Dimmer Bedroom_Repeater_Brightness "Bedroom Repeater Brightness" {channel="hdpowerview:repeater:home:r16384:brightness"}
String Bedroom_Repeater_Identify "Bedroom Repeater Identify" {channel="hdpowerview:repeater:home:r16384:identify"}
Scene items:
-```
+```java
Switch Living_Room_Shades_Scene_Heart "Living Room Shades Scene Heart" <blinds> (g_Shades_Scene_Trigger) {channel="hdpowerview:hub:home:scenes#22663"}
```
Scene Group items:
-```
+```java
Switch Children_Rooms_Shades_Up "Good Morning Children" {channel="hdpowerview:hub:home:sceneGroups#27119"}
```
Automation items:
-```
+```java
Switch Automation_Children_Up_Sun "Children Up At Sunrise" {channel="hdpowerview:hub:home:automations#1262"}
Switch Automation_Children_Up_Time "Children Up At 6:30" {channel="hdpowerview:hub:home:automations#49023"}
```
### `demo.sitemap` File
-```
+```perl
Frame label="Living Room" {
Switch item=Living_Room_Shades_Scene_Open
Slider item=Living_Room_Shade_Position
# Helios Binding
-This binding integrates the Heliop door/videophone system (https://www.2n.cz).
+This binding integrates the Heliop door/videophone system (<https://www.2n.cz>).
## Supported Things
Currently, the Helios IP Vario is supported by this binding, running the 2.21 version of the firmware
-
## Binding Configuration
There is no specific binding configuration
-
## Thing Configuration
The ipvario221 Thing requires the IP address of the videophone, and the username and password as a configuration value in order for the binding to log into the videophone.
In the thing file, this looks e.g. like
-```
+```java
Thing helios:ipvario213:gate [ipAddress="192.168.0.14", username="admin", password="mypassword"]
```
demo.Things:
-```
+```java
Thing helios:ipvario221:gate [ipAddress="192.168.0.14", username="admin", password="mypassword"]
```
demo.items:
-```
+```java
String GateKeyStamp "[%s]" (helios) {channel="helios:ipvario221:gate:keypressedstamp"}
String GateCardSwiped "[%s]" (helios) {channel="helios:ipvario221:gate:card"}
String GateCardStamp "[%s]" (helios) {channel="helios:ipvario221:gate:cardstamp"}
demo.rules:
-```
+```java
rule SomeRule
when
Channel "helios:ipvario221:gate:keypressed" triggered
It requires a connection to the RS485 bus used by the original remote controls KWL-FB (9417) and does not use the Modbus/TCP interface of the newer EasyControl devices.
For electrical connection it is recommended to use an USB-RS485 interface, but any RS485 interface that shows up as a serial port will do.
-Setup the device as described in https://www.openhab.org/docs/administration/serial.html.
+Setup the device as described in <https://www.openhab.org/docs/administration/serial.html>.
The binding will use the remote control address 15 for communication, so make sure that this is not assigned to a physically present remote control.
## Binding Configuration
-The binding requires access to the serial device connecting to the RS485 bus as described in https://www.openhab.org/docs/administration/serial.html.
+The binding requires access to the serial device connecting to the RS485 bus as described in <https://www.openhab.org/docs/administration/serial.html>.
Otherwise only thing configuration is needed.
## Thing Configuration
Things:
-```
+```java
heliosventilation:ventilation:MyKWL [ serialPort="/dev/ttyUSB0" ]
```
Items:
-```
+```java
Switch KWLOnOff { channel="heliosventilation:ventilation:MyKWL:powerState" }
Switch KWLWinter { channel="heliosventilation:ventilation:MyKWL:winterMode" }
Sitemap:
-```
+```perl
sitemap helios_kwl label="Helios Ventilation" {
Frame label="Temperatures" {
Text item=Outside_Temperature
The binding supports a bridge to connect to the HEOS-Network.
A bridge uses the thing ID "bridge".
-
Player:
A generic player is supported via this binding.
Currently no differences are made between the players.
The binding supports HEOS groups.
A group uses the Thing ID "group"
-
## Discovery
This binding supports full automatic discovery of available players to be used as a bridge, players and groups.
You need to add a Bridge device first (which is also auto-discovered by the binding) which can be any HEOS device in your network (preferably which has wired connection).
-__Important!__
+**Important!**
Please note that only one bridge is required to establish a connection.
Adding a second bridge can cause trouble with the connection.
This is required to load the favorites, playlists and so on from personal settings.
If no login information is provided these features can't be used.
-````
+```java
Bridge heos:bridge:main "name" [ipAddress="192.168.0.1", unsername="xxx", password="123456"]
-````
+```
### Player Configuration
For manual configuration a player can be defined as followed:
-````
+```java
Thing heos:player:player1 "name" [pid="123456789"]
-````
+```
PID behind the heos:player:--- should be changed as required.
It is recommended to use the Player PID.
Groups will automatically appear in the Inbox if that Group is active.
To do this, build your Group from the HEOS app, then the group will appear in the Inbox.
-```
+```java
Thing heos:group:group1 "name" [members="45345634;35534567"]
```
Defining Player and Bridge together.
To ensure that the players and groups are attached to the bridge the definition can be like:
-```
+```java
Bridge heos:bridge:main "Bridge" [ipAddress="192.168.0.1", username="userName", password="123456"] {
- player Kitchen "Kitchen"[pid="434523813"]
- player LivingRoom "Living Room"[pid="918797451"]
- group 813793755 "Ground Level"[members="434523813;918797451"]
+ player Kitchen "Kitchen"[pid="434523813"]
+ player LivingRoom "Living Room"[pid="918797451"]
+ group 813793755 "Ground Level"[members="434523813;918797451"]
}
```
#### Example
-```
+```java
Player LivingRoom_Control "Control" {channel="heos:player:main:LivingRoom:Control"}
Selection item=LivingRoom_Playlists label="Playlist" icon="music"
```
For a list of the commands please refer to the [HEOS CLI protocol](https://rn.dmglobal.com/euheos/HEOS_CLI_ProtocolSpecification_2021.pdf).
-## *Dynamic Channels*
+## _Dynamic Channels_
Also the bridge supports dynamic channels which represent the players of the network.
They are added dynamically if a player is found. The player and group channels are only shown on the bridge.
Example
- ```
+ ```java
Switch Player_1 "Player [%s]" {channel="heos:bridge:main:P123456789"}
```
### demo.things:
-```
+```java
Bridge heos:bridge:main "Bridge" [ipAddress="192.168.0.1", username="userName", password="123456"] {
player Kitchen "Kitchen"[pid="434523813"]
player LivingRoom "Living Room"[pid="918797451"]
### demo.items:
-```
+```java
Player LivingRoom_Control "Control" {channel="heos:player:main:LivingRoom:Control"}
Switch LivingRoom_Mute "Mute"{channel="heos:player:main:LivingRoom:Mute"}
Dimmer LivingRoom_Volume "Volume" {channel="heos:player:main:LivingRoom:Volume"}
### demo.sitemap
-```
+```perl
Frame label="LivingRoom" {
- Default item=LivingRoom_Control
- Default item=LivingRoom_Mute
- Default item=LivingRoom_Volume
- Default item=LivingRoom_Title
- Default item=LivingRoom_Interpret
- Default item=LivingRoom_Album
+ Default item=LivingRoom_Control
+ Default item=LivingRoom_Mute
+ Default item=LivingRoom_Volume
+ Default item=LivingRoom_Title
+ Default item=LivingRoom_Interpret
+ Default item=LivingRoom_Album
Selection item=LivingRoom_Favorites label="Favorite" icon="music"
Selection item=LivingRoom_Playlists label="Playlist" icon="music"
}
Items:
-```
-Switch HeosBridge_Play_Living "Living Room" (gHeos) {channel="heos:bridge:ed0ac1ff-0193-65c6-c1b8-506137456a50:P918797451"}
-String HeosKitchen_Input (gHeos) {channel="heos:player:918797451:Inputs"}
-String HeosKitchen_InputSelect "Input" (gHeos)
+```java
+Switch HeosBridge_Play_Living "Living Room" (gHeos) {channel="heos:bridge:ed0ac1ff-0193-65c6-c1b8-506137456a50:P918797451"}
+String HeosKitchen_Input (gHeos) {channel="heos:player:918797451:Inputs"}
+String HeosKitchen_InputSelect "Input" (gHeos)
```
Rule for kitchen:
-```
+```java
rule "Play AuxIn from Living Room"
- when
- Item HeosKitchen_InputSelect received command
- then
- if (receivedCommand.toString == "aux_in_1") {
- sendCommand(HeosKitchen_Input, "aux_in_1")
-
- } if (receivedCommand.toString == "LivingRoom") {
- sendCommand(HeosBridge_Play_Living, ON)
- sendCommand(HeosKitchen_Input, "aux_in_1")
- sendCommand(HeosBridge_Play_Living, OFF) //Switch player channel off again to be sure that it is OFF
- }
+ when
+ Item HeosKitchen_InputSelect received command
+ then
+ if (receivedCommand.toString == "aux_in_1") {
+ sendCommand(HeosKitchen_Input, "aux_in_1")
+
+ } if (receivedCommand.toString == "LivingRoom") {
+ sendCommand(HeosBridge_Play_Living, ON)
+ sendCommand(HeosKitchen_Input, "aux_in_1")
+ sendCommand(HeosBridge_Play_Living, OFF) //Switch player channel off again to be sure that it is OFF
+ }
```
Sitemap:
-```
-Switch item=HeosKitchen_InputSelect mappings=[aux_in_1 = "Aux In" , LivingRoom = "Living Room"]
+```java
+Switch item=HeosKitchen_InputSelect mappings=[aux_in_1 = "Aux In" , LivingRoom = "Living Room"]
```
### The Online status of Groups and Players
Items:
-```
+```java
String HeosGroup_Status
-
```
Then we need a rule which triggers the state if an Item goes Online or Offline.
Rules:
-```
+```java
rule "Online State Heos Group"
when
Sitemap:
-```
+```perl
Frame label="Heos Group" visibility=[HeosGroup_Status==ONLINE] {
- Default item=HeosGroup1_Player
- Default item=HeosGroup1_Volume
- Default item=HeosGroup1_Mute
- Default item=HeosGroup1_Favorites
- Default item=HeosGroup1_Playlist
-
- Text item=HeosGroup1_Song {
- Default item=HeosGroup1_Song
- Default item=HeosGroup1_Artist
- Default item=HeosGroup1_Album
- Image item=HeosGroup1_Cover url=""
- }
+ Default item=HeosGroup1_Player
+ Default item=HeosGroup1_Volume
+ Default item=HeosGroup1_Mute
+ Default item=HeosGroup1_Favorites
+ Default item=HeosGroup1_Playlist
+
+ Text item=HeosGroup1_Song {
+ Default item=HeosGroup1_Song
+ Default item=HeosGroup1_Artist
+ Default item=HeosGroup1_Album
+ Image item=HeosGroup1_Cover url=""
+ }
}
```
Multiple actions are supported by this binding. In classic rules these are accessible as shown in the example below:
-```
+```java
val actions = getActions("heos","heos:bridge:bridgeId")
if(null === actions) {
logInfo("actions", "Actions not found, check thing ID")
### playInputFromPlayer(sourcePlayer, sourceInput, destination)
-Allows to play a source from a player to another player.
+Allows to play a source from a player to another player.
# Herzborg Binding
-This binding supports smart curtain motors by Herzborg (http://www.herzborg.com/pro_list.aspx?TypeID=1)
+This binding supports smart curtain motors by Herzborg (<http://www.herzborg.com/pro_list.aspx?TypeID=1>)
## Supported Things
herzborg.things:
-```
+```java
Bridge herzborg:serial_bus:my_herzborg_bus [ port="/dev/ttyAMA1" ]
{
Thing herzborg:curtain:livingroom [ address=1234, poll_interval=1 ]
herzborg.items:
-```
+```java
Rollershutter LivingRoom_Window {channel="herzborg:curtain:livingroom:position"}
```
herzborg.sitemap:
-```
+```perl
Frame label="Living room curtain"
{
Switch item=LivingRoom_Window label="Control" mappings=["DOWN"="Close", "STOP"="Stop", "UP"="Open"]
# Home Connect Binding
The binding integrates the [Home Connect](https://www.home-connect.com/) system into openHAB.
-By using the Home Connect API it connects to household devices from brands like Bosch and Siemens.
+By using the Home Connect API it connects to household devices from brands like Bosch and Siemens.
Because all status updates and commands have to go through the API, a permanent internet connection is required.
### Bridge
-The __Home Connect API__ (Bridge Type ID: api_bridge) is responsible for the communication with the Home Connect API. All devices use a bridge to execute commands and listen for updates. Without a working bridge the devices cannot communicate.
+The **Home Connect API** (Bridge Type ID: api_bridge) is responsible for the communication with the Home Connect API. All devices use a bridge to execute commands and listen for updates. Without a working bridge the devices cannot communicate.
### Devices
Supported devices: dishwasher, washer, washer / dryer combination, dryer, oven, refrigerator freezer, coffee machine, hood, cooktop*
-*\* experimental support*
+#### experimental support
-| Home appliance | Thing Type ID |
+| Home appliance | Thing Type ID |
| --------------- | ------------ |
-| Dishwasher | dishwasher |
-| Washer | washer |
-| Washer / Dryer combination | washerdryer |
-| Dryer | dryer |
-| Oven | oven |
-| Hood | hood |
-| Cooktop | hob |
-| Refrigerator Freezer | fridgefreezer |
-| Coffee Machine | coffeemaker |
-
-> **INFO**: Currently the Home Connect API does not support all appliance programs. Please check if your desired program is available (e.g. https://developer.home-connect.com/docs/washing-machine/supported_programs_and_options).
-
+| Dishwasher | dishwasher |
+| Washer | washer |
+| Washer / Dryer combination | washerdryer |
+| Dryer | dryer |
+| Oven | oven |
+| Hood | hood |
+| Cooktop | hob |
+| Refrigerator Freezer | fridgefreezer |
+| Coffee Machine | coffeemaker |
+
+> **INFO:** Currently the Home Connect API does not support all appliance programs. Please check if your desired program is available (e.g. <https://developer.home-connect.com/docs/washing-machine/supported_programs_and_options>).
## Discovery
After the bridge has been added and authorized, devices are discovered automatically.
-
## Channels
| Channel Type ID | Item Type | Read only | Description | Available on thing |
| --------------- | --------- | --------- | ----------- | ------------------ |
-| power_state | Switch | false | This setting describes the current power state of the home appliance. | dishwasher, oven, coffeemaker, hood, hob |
-| door_state | Contact | true | This status describes the door state of a home appliance. A status change is either triggered by the user operating the home appliance locally (i.e. opening/closing door) or automatically by the home appliance (i.e. locking the door). | dishwasher, washer, washerdryer, dryer, oven, fridgefreezer |
-| operation_state | String | true | This status describes the operation state of the home appliance. | dishwasher, washer, washerdryer, dryer, oven, hood, hob, coffeemaker |
-| remote_start_allowance_state | Switch | true | This status indicates whether the remote program start is enabled. This can happen due to a programmatic change (only disabling), or manually by the user changing the flag locally on the home appliance, or automatically after a certain duration - usually in 24 hours. | dishwasher, washer, washerdryer, dryer, oven, hood, coffeemaker |
-| remote_control_active_state | Switch | true | This status indicates whether the allowance for remote controlling is enabled. | dishwasher, washer, washerdryer, dryer, oven, hood, hob |
-| active_program_state | String | true | This status describes the active program of the home appliance. | dishwasher, washer, washerdryer, dryer, oven, hood, hob, coffeemaker |
-| selected_program_state | String | false | This state describes the selected program of the home appliance. | dishwasher, washer, washerdryer, dryer, oven, hob, coffeemaker |
-| remaining_program_time_state | Number:Time | true | This status indicates the remaining program time of the home appliance. | dishwasher, washer, washerdryer, dryer, oven |
-| elapsed_program_time | Number:Time | true | This status indicates the elapsed program time of the home appliance. | oven |
-| program_progress_state | Number:Dimensionless | true | This status describes the program progress of the home appliance in percent. | dishwasher, washer, washerdryer, dryer, oven, coffeemaker |
-| duration | Number:Time | true | This status describes the duration of the program of the home appliance. | oven |
-| oven_current_cavity_temperature | Number:Temperature | true | This status describes the current cavity temperature of the home appliance. | oven |
-| setpoint_temperature | Number:Temperature | false | This status describes the setpoint/target temperature of the home appliance. | oven |
-| laundry_care_washer_temperature | String | false | This status describes the temperature of the washing program of the home appliance. | washer, washerdryer |
-| laundry_care_washer_spin_speed | String | false | This status defines the spin speed of a washer program of the home appliance. | washer, washerdryer |
-| laundry_care_washer_idos1_level | String | false | This status defines the i-Dos 1 dosing level of a washer program of the home appliance (if appliance supports i-Dos). | washer |
-| laundry_care_washer_idos2_level | String | false | This status defines the i-Dos 2 dosing level of a washer program of the home appliance (if appliance supports i-Dos). | washer |
-| laundry_care_washer_idos1 | Switch | true | This status indicates whether i-Dos 1 is activated for a washer program of the home appliance. (If appliance supports i-Dos) | washer |
-| laundry_care_washer_idos2 | Switch | true | This status indicates whether i-Dos 2 is activated for a washer program of the home appliance. (If appliance supports i-Dos) | washer |
-| laundry_care_washer_vario_perfect | String | true | This status defines the vario perfect mode of a washer program of the home appliance. | washer, washerdryer |
-| laundry_care_washer_less_ironing | Switch | true | This status indicates whether less ironing is activated for a washer program of the home appliance. | washer, washerdryer |
-| laundry_care_washer_pre_wash | Switch | true | This status indicates whether the pre-wash is activated for a washer program of the home appliance. | washer, washerdryer |
-| laundry_care_washer_rinse_plus | String | true | This status defines the number of additional rinses of a washer program of the home appliance. | washer, washerdryer |
-| laundry_care_washer_rinse_hold | Switch | true | This status indicates whether the spin function is deactivated for a washer program of the home appliance (washing will remain in the water after the last rinse cycle). | washer, washerdryer |
-| laundry_care_washer_soak | Switch | true | This status indicates whether the soaking is activated for a washer program of the home appliance. | washer, washerdryer |
-| laundry_care_washer_load_recommendation | Number:Mass | true | This channel indicates the maximum laundry load recommended for a program of the home appliance. | washer, washerdryer |
-| program_energy | Number:Dimensionless | true | This channel provides the estimated energy required in percentage for a program of the home appliance. | washer, washerdryer |
-| program_water | Number:Dimensionless | true | This channel provides the estimated water required in percentage for a program of the home appliance. | washer, washerdryer |
-| dryer_drying_target | String | false | This status defines the desired dryness of a program of the home appliance. | dryer, washerdryer |
-| setpoint_temperature_refrigerator | Number:Temperature | false | Target temperature of the refrigerator compartment (range depends on appliance - common range 2 to 8°C). | fridgefreezer |
-| setpoint_temperature_freezer | Number:Temperature | false | Target temperature of the freezer compartment (range depends on appliance - common range -16 to -24°C). | fridgefreezer |
-| super_mode_refrigerator | Switch | false | The setting has no impact on setpoint temperatures but will make the fridge compartment cool to the lowest possible temperature until it is disabled manually by the customer or by the HA because of a timeout. | fridgefreezer |
-| super_mode_freezer | Switch | false | This setting has no impact on setpoint temperatures but will make the freezer compartment cool to the lowest possible temperature until it is disabled manually by the customer or by the home appliance because of a timeout. | fridgefreezer |
-| coffeemaker_drip_tray_full_state | Switch | true | Is coffee maker drip tray full? | coffeemaker |
-| coffeemaker_water_tank_empty_state | Switch | true | Is coffee maker water tank empty? | coffeemaker |
-| coffeemaker_bean_container_empty_state | Switch | true | Is coffee maker bean container empty? | coffeemaker |
-| hood_venting_level | String | true | This option defines the required fan setting of the hood. | hood |
-| hood_intensive_level | String | true | This option defines the intensive setting of the hood. | hood |
-| hood_program_state | String | false | Adds hood controller actions to the appliance. The following commands are supported: `stop`, `venting1`, `venting2`, `venting3`, `venting4`, `venting5`, `ventingIntensive1`, `ventingIntensive1`, `automatic` and `delayed`. Furthermore it is possible to send raw (Home Connect JSON payload) to the home appliance. | hood |
-| basic_actions_state | String | false | Adds basic controller actions to the appliance. The following basic commands are supported: `start` (start current selected program), `stop` (stop current program) and `selected` (show current program information). Furthermore it is possible to send raw (Home Connect JSON payload) to the home appliance. | dishwasher, oven, washer, washerdryer, dryer, coffeemaker |
-| functional_light_state | Switch | false | This setting describes the current functional light state of the home appliance. | hood |
-| functional_light_brightness_state | Dimmer | false | This setting describes the brightness state of the functional light. | hood |
-| ambient_light_state | Switch | false | This setting describes the current ambient light state of the home appliance. | dishwasher, hood |
-| ambient_light_brightness_state | Dimmer | false | This setting describes the brightness state of the ambient light. *INFO: Please note that the brightness can't be set if the ambient light color is set to `CustomColor`.* | dishwasher, hood |
-| ambient_light_color_state | String | false | This setting describes the current ambient light color state of the home appliance. | dishwasher, hood |
-| ambient_light_custom_color_state | Color | false | This setting describes the custom color state of the ambient light. HSB color commands are supported as well as hex color string e.g. `#11ff00`. *INFO: Please note that the brightness can't be set.* | dishwasher, hood |
-
-
-## Thing Configuration
+| power_state | Switch | false | This setting describes the current power state of the home appliance. | dishwasher, oven, coffeemaker, hood, hob |
+| door_state | Contact | true | This status describes the door state of a home appliance. A status change is either triggered by the user operating the home appliance locally (i.e. opening/closing door) or automatically by the home appliance (i.e. locking the door). | dishwasher, washer, washerdryer, dryer, oven, fridgefreezer |
+| operation_state | String | true | This status describes the operation state of the home appliance. | dishwasher, washer, washerdryer, dryer, oven, hood, hob, coffeemaker |
+| remote_start_allowance_state | Switch | true | This status indicates whether the remote program start is enabled. This can happen due to a programmatic change (only disabling), or manually by the user changing the flag locally on the home appliance, or automatically after a certain duration - usually in 24 hours. | dishwasher, washer, washerdryer, dryer, oven, hood, coffeemaker |
+| remote_control_active_state | Switch | true | This status indicates whether the allowance for remote controlling is enabled. | dishwasher, washer, washerdryer, dryer, oven, hood, hob |
+| active_program_state | String | true | This status describes the active program of the home appliance. | dishwasher, washer, washerdryer, dryer, oven, hood, hob, coffeemaker |
+| selected_program_state | String | false | This state describes the selected program of the home appliance. | dishwasher, washer, washerdryer, dryer, oven, hob, coffeemaker |
+| remaining_program_time_state | Number:Time | true | This status indicates the remaining program time of the home appliance. | dishwasher, washer, washerdryer, dryer, oven |
+| elapsed_program_time | Number:Time | true | This status indicates the elapsed program time of the home appliance. | oven |
+| program_progress_state | Number:Dimensionless | true | This status describes the program progress of the home appliance in percent. | dishwasher, washer, washerdryer, dryer, oven, coffeemaker |
+| duration | Number:Time | true | This status describes the duration of the program of the home appliance. | oven |
+| oven_current_cavity_temperature | Number:Temperature | true | This status describes the current cavity temperature of the home appliance. | oven |
+| setpoint_temperature | Number:Temperature | false | This status describes the setpoint/target temperature of the home appliance. | oven |
+| laundry_care_washer_temperature | String | false | This status describes the temperature of the washing program of the home appliance. | washer, washerdryer |
+| laundry_care_washer_spin_speed | String | false | This status defines the spin speed of a washer program of the home appliance. | washer, washerdryer |
+| laundry_care_washer_idos1_level | String | false | This status defines the i-Dos 1 dosing level of a washer program of the home appliance (if appliance supports i-Dos). | washer |
+| laundry_care_washer_idos2_level | String | false | This status defines the i-Dos 2 dosing level of a washer program of the home appliance (if appliance supports i-Dos). | washer |
+| laundry_care_washer_idos1 | Switch | true | This status indicates whether i-Dos 1 is activated for a washer program of the home appliance. (If appliance supports i-Dos) | washer |
+| laundry_care_washer_idos2 | Switch | true | This status indicates whether i-Dos 2 is activated for a washer program of the home appliance. (If appliance supports i-Dos) | washer |
+| laundry_care_washer_vario_perfect | String | true | This status defines the vario perfect mode of a washer program of the home appliance. | washer, washerdryer |
+| laundry_care_washer_less_ironing | Switch | true | This status indicates whether less ironing is activated for a washer program of the home appliance. | washer, washerdryer |
+| laundry_care_washer_pre_wash | Switch | true | This status indicates whether the pre-wash is activated for a washer program of the home appliance. | washer, washerdryer |
+| laundry_care_washer_rinse_plus | String | true | This status defines the number of additional rinses of a washer program of the home appliance. | washer, washerdryer |
+| laundry_care_washer_rinse_hold | Switch | true | This status indicates whether the spin function is deactivated for a washer program of the home appliance (washing will remain in the water after the last rinse cycle). | washer, washerdryer |
+| laundry_care_washer_soak | Switch | true | This status indicates whether the soaking is activated for a washer program of the home appliance. | washer, washerdryer |
+| laundry_care_washer_load_recommendation | Number:Mass | true | This channel indicates the maximum laundry load recommended for a program of the home appliance. | washer, washerdryer |
+| program_energy | Number:Dimensionless | true | This channel provides the estimated energy required in percentage for a program of the home appliance. | washer, washerdryer |
+| program_water | Number:Dimensionless | true | This channel provides the estimated water required in percentage for a program of the home appliance. | washer, washerdryer |
+| dryer_drying_target | String | false | This status defines the desired dryness of a program of the home appliance. | dryer, washerdryer |
+| setpoint_temperature_refrigerator | Number:Temperature | false | Target temperature of the refrigerator compartment (range depends on appliance - common range 2 to 8°C). | fridgefreezer |
+| setpoint_temperature_freezer | Number:Temperature | false | Target temperature of the freezer compartment (range depends on appliance - common range -16 to -24°C). | fridgefreezer |
+| super_mode_refrigerator | Switch | false | The setting has no impact on setpoint temperatures but will make the fridge compartment cool to the lowest possible temperature until it is disabled manually by the customer or by the HA because of a timeout. | fridgefreezer |
+| super_mode_freezer | Switch | false | This setting has no impact on setpoint temperatures but will make the freezer compartment cool to the lowest possible temperature until it is disabled manually by the customer or by the home appliance because of a timeout. | fridgefreezer |
+| coffeemaker_drip_tray_full_state | Switch | true | Is coffee maker drip tray full? | coffeemaker |
+| coffeemaker_water_tank_empty_state | Switch | true | Is coffee maker water tank empty? | coffeemaker |
+| coffeemaker_bean_container_empty_state | Switch | true | Is coffee maker bean container empty? | coffeemaker |
+| hood_venting_level | String | true | This option defines the required fan setting of the hood. | hood |
+| hood_intensive_level | String | true | This option defines the intensive setting of the hood. | hood |
+| hood_program_state | String | false | Adds hood controller actions to the appliance. The following commands are supported: `stop`, `venting1`, `venting2`, `venting3`, `venting4`, `venting5`, `ventingIntensive1`, `ventingIntensive1`, `automatic` and `delayed`. Furthermore it is possible to send raw (Home Connect JSON payload) to the home appliance. | hood |
+| basic_actions_state | String | false | Adds basic controller actions to the appliance. The following basic commands are supported: `start` (start current selected program), `stop` (stop current program) and `selected` (show current program information). Furthermore it is possible to send raw (Home Connect JSON payload) to the home appliance. | dishwasher, oven, washer, washerdryer, dryer, coffeemaker |
+| functional_light_state | Switch | false | This setting describes the current functional light state of the home appliance. | hood |
+| functional_light_brightness_state | Dimmer | false | This setting describes the brightness state of the functional light. | hood |
+| ambient_light_state | Switch | false | This setting describes the current ambient light state of the home appliance. | dishwasher, hood |
+| ambient_light_brightness_state | Dimmer | false | This setting describes the brightness state of the ambient light. _INFO: Please note that the brightness can't be set if the ambient light color is set to `CustomColor`._ | dishwasher, hood |
+| ambient_light_color_state | String | false | This setting describes the current ambient light color state of the home appliance. | dishwasher, hood |
+| ambient_light_custom_color_state | Color | false | This setting describes the custom color state of the ambient light. HSB color commands are supported as well as hex color string e.g. `#11ff00`. _INFO: Please note that the brightness can't be set._ | dishwasher, hood |
-### Configuring the __Home Connect API__ Bridge
+## Thing Configuration
+### Configuring the **Home Connect API** Bridge
#### 1. Preconditions
1. Please create an account at [Home Connect](https://www.home-connect.com/) and add your physical appliance to your account.
-2. Test the connection to your physical appliance via mobile app ([Apple App Store (iOS)](https://itunes.apple.com/de/app/home-connect-app/id901397789?mt=8) or [Google Play Store (Android)](https://play.google.com/store/apps/details?id=com.bshg.homeconnect.android.release)).
+1. Test the connection to your physical appliance via mobile app ([Apple App Store (iOS)](https://itunes.apple.com/de/app/home-connect-app/id901397789?mt=8) or [Google Play Store (Android)](https://play.google.com/store/apps/details?id=com.bshg.homeconnect.android.release)).
#### 2. Create Home Connect developer account
1. Create an account at [https://developer.home-connect.com](https://developer.home-connect.com) and login.
-2. Please make sure you've added your associated Home Connect account email at <https://developer.home-connect.com/user/me/edit>. You should fill in your email address, which you use for the official Android or iOS app, at `Default Home Connect User Account for Testing`.
+1. Please make sure you've added your associated Home Connect account email at <https://developer.home-connect.com/user/me/edit>. You should fill in your email address, which you use for the official Android or iOS app, at `Default Home Connect User Account for Testing`.
-
-3. Register / Create an application at [https://developer.home-connect.com/applications](https://developer.home-connect.com/applications)
- * _Application ID_: e.g. `openhab-binding`
- * _OAuth Flow_: Authorization Code Grant Flow
- * _Home Connect User Account for Testing_: the associated user account email from [Home Connect](https://www.home-connect.com/)
+1. Register / Create an application at [https://developer.home-connect.com/applications](https://developer.home-connect.com/applications)
+ - _Application ID_: e.g. `openhab-binding`
+ - _OAuth Flow_: Authorization Code Grant Flow
+ - _Home Connect User Account for Testing_: the associated user account email from [Home Connect](https://www.home-connect.com/)
> **WARNING**: Please don't use your developer account username
**_Please don't use your developer account username_**
- * _Redirect URIs_: add your openHAB URL followed by `/homeconnect`
+ - _Redirect URIs_: add your openHAB URL followed by `/homeconnect`
for example: `http://192.168.178.34:8080/homeconnect` or `https://myhome.domain.com/homeconnect`
- * _One Time Token Mode_: keep unchecked
- * _Proof Key for Code Exchange_: keep unchecked
-4. After your application has been created, you should see the _Client ID_ and _Client Secret_ of the application. Please save these for later.
+ - _One Time Token Mode_: keep unchecked
+ - _Proof Key for Code Exchange_: keep unchecked
+1. After your application has been created, you should see the _Client ID_ and _Client Secret_ of the application. Please save these for later.
-
-
#### 3. Setup bridge (openHAB UI)
The Home Connect bridge can be configured in the openHAB UI as follows:
1. Go to the Inbox and press the add button
-2. Choose `Home Connect Binding`
-3. Select `Home Connect API`
-4. Setup and save thing
- * __client id:__ your application client id
- * __client secret:__ your application client secret
- * __simulator:__ false
-5. Now navigate to the URL (`Redirct URI`) you've added to your Home Connect application in the previous step (2.3). For example `http://192.168.178.80:8080/homeconnect`.
-6. Please follow the steps shown to authenticate your binding. You can redo this step every time. For example if you have authentication problems, just start wizard again.
+1. Choose `Home Connect Binding`
+1. Select `Home Connect API`
+1. Setup and save thing
+ - **client id:** your application client id
+ - **client secret:** your application client secret
+ - **simulator:** false
+1. Now navigate to the URL (`Redirct URI`) you've added to your Home Connect application in the previous step (2.3). For example `http://192.168.178.80:8080/homeconnect`.
+1. Please follow the steps shown to authenticate your binding. You can redo this step every time. For example if you have authentication problems, just start wizard again.
-
-7. That's it! Now you can use autodiscovery to add devices. Your devices should show up if you start a device scan in the openHAB UI.
-
-
+1. That's it! Now you can use autodiscovery to add devices. Your devices should show up if you start a device scan in the openHAB UI.
## Examples: File based configuration
### things/homeconnect.things
-```
+```java
Bridge homeconnect:api_bridge:api_bridge_at_home "Home Connect API" [ clientId="1234", clientSecret="1234", simulator=false] {
// Thing configurations
Thing dishwasher dishwasher1 "Dishwasher" [ haId="SIEMENS-HCS02DWH1-6F2FC400C1EA4A" ]
The channel parameter uses the following syntax: `homeconnect:<thing type id>:<bridge id>:<thing id>:<channel type id>`. For example: `homeconnect:dishwasher:api_bridge_at_home:dishwasher1:power_state`
-```
+```java
// dishwasher
Switch Dishwasher_PowerState "Power State" {channel="homeconnect:dishwasher:api_bridge_at_home:dishwasher1:power_state"}
Contact Dishwasher_DoorState "Door State" {channel="homeconnect:dishwasher:api_bridge_at_home:dishwasher1:door_state"}
## Home Connect Console
-The binding comes with a separate user interface, which is reachable through the web browser http(s)://[YOUROPENHAB]:[YOURPORT]/homeconnect (e.g. http://192.168.178.100:8080/homeconnect).
+The binding comes with a separate user interface, which is reachable through the web browser http(s)://[YOUROPENHAB]:[YOURPORT]/homeconnect (e.g. `http://192.168.178.100:8080/homeconnect`).
Features:
-* overview of your bridges and appliances
-* send commands to your appliances
-* see latest API requests
-* see received events from the Home Connect backend
-* API request counts
+- overview of your bridges and appliances
+- send commands to your appliances
+- see latest API requests
+- see received events from the Home Connect backend
+- API request counts
> **INFO**: If you have a problems with your installation, please always provide request and event exports. 
### Notification on credential error
-To get notified when your Home Connect credentials have been revoked or expired you can use the following rule to get notified.
+To get notified when your Home Connect credentials have been revoked or expired you can use the following rule to get notified.
-This can happen if
+This can happen if
-* your openHAB instance was offline for a longer period or
-* new terms weren't accepted or
-* a technical problem occurred.
+- your openHAB instance was offline for a longer period or
+- new terms weren't accepted or
+- a technical problem occurred.
```java
rule "Offline check - Home Connect bridge"
#### 1. Retrieve "special command" payload
-You have a couple options to get the program settings payload.
+You have a couple options to get the program settings payload.
-a) You could have a look at the Home Connect developer documentation (https://developer.home-connect.com/docs/) and create the payload on your own.
+a) You could have a look at the Home Connect developer documentation (<https://developer.home-connect.com/docs/>) and create the payload on your own.
-b) You could have a look at the request logs and extract the payload from there.
+b) You could have a look at the request logs and extract the payload from there.
1. On the physical device, select your desired program with the appropriate options.
-2. Open the appliance section of the binding UI (http(s)://[YOUROPENHAB]:[YOURPORT]/appliances) and click the 'Selected Program' button.
+1. Open the appliance section of the binding UI (http(s)://[YOUROPENHAB]:[YOURPORT]/appliances) and click the 'Selected Program' button.
-3.  Copy the JSON payload. In a further step, this payload will be used to start the program.
-
+1.  Copy the JSON payload. In a further step, this payload will be used to start the program.
#### 2. Start program
##### in rule
-*Example rule:*
+_Example rule:_
```java
rule "trigger program"
##### via curl
-*Example command:*
+_Example command:_
-```bash
+```shell
curl -X POST --header "Content-Type: text/plain" --header "Accept: application/json" -d '{"data":{"key":"ConsumerProducts.CoffeeMaker.Program.Beverage.EspressoMacchiato","options":[{"key":"ConsumerProducts.CoffeeMaker.Option.CoffeeTemperature","value":"ConsumerProducts.CoffeeMaker.EnumType.CoffeeTemperature.94C","unit":"enum"},{"key":"ConsumerProducts.CoffeeMaker.Option.BeanAmount","value":"ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.Mild","unit":"enum"},{"key":"ConsumerProducts.CoffeeMaker.Option.FillQuantity","value":60,"unit":"ml"}]}}' "http://localhost:8080/rest/items/homeconnect_CoffeeMaker_BOSCH_HCS06COM1_B95E5103934D_basic_actions_state"
```
The Home Connect API enforces rate [limits](https://developer.home-connect.com/docs/general/ratelimiting). If you have a lot of `429` response codes in your request log section (http(s)://[YOUROPENHAB]:[YOURPORT]/log/requests), please check the error response.
-
### Error message 'Program not supported', 'Unsupported operation' or 'SDK.Error.UnsupportedOption'
Not all appliance programs and program options are supported by the Home Connect API. Unfortunately you can't use them. You will see error messages like the following in the binding UI (request log):
You have two options to find the right HaID of your device.
1. You can use the openHAB UI and start a scan. 
-2. You can use Home Connect binding UI. Please have a look at the first API request. 
+1. You can use Home Connect binding UI. Please have a look at the first API request. 
Also the "Remote Homematic-Script API" has to be set to "Full Access" or "Restricted access".
When the option "Restricted access" is used, some ports have to be added to the "Port opening" list.
-```
+```text
2000;
2001;
2010;
If this is not done the binding will not be able to connect to the CCU and the CCU Thing will stay uninitialized and sets a timeout exception:
-```
+```text
xxx-xx-xx xx:xx:xx.xxx [hingStatusInfoChangedEvent] - - 'homematic:bridge:xxx' changed from INITIALIZING to OFFLINE (COMMUNICATION_ERROR): java.net.SocketTimeoutException: Connect Timeout
```
If set to true, devices are automatically factory reset when their corresponding things are removed.
Due to the factory reset, the device will also be unpaired from the gateway, even if "unpairOnDeletion" is set to false! (default = false)
-- **bufferSize**
-If a large number of devices are connected to the gateway, the default buffersize of 2048 kB may be too small for communication with the gateway.
-In this case, e.g. the discovery fails.
+- **bufferSize**
+If a large number of devices are connected to the gateway, the default buffersize of 2048 kB may be too small for communication with the gateway.
+In this case, e.g. the discovery fails.
With this setting the buffer size can be adjusted. The value is specified in kB.
The syntax for a bridge is:
### Example
-**Minimum configuration**
+#### Minimum configuration
```java
Bridge homematic:bridge:ccu [ gatewayAddress="..."]
```
-**With callback settings**
+#### With callback settings
```java
Bridge homematic:bridge:ccu [ gatewayAddress="...", callbackHost="...", callbackPort=... ]
```
-**Multiple bridges**
+#### Multiple bridges
```java
Bridge homematic:bridge:lxccu [ gatewayAddress="..."]
You have several additional options to control the display.
-- BEEP *(TONE1, TONE2, TONE3)* - let the remote control beep
-- BACKLIGHT *(BACKLIGHT_ON, BLINK_SLOW, BLINK_FAST)* - control the display backlight
-- UNIT *(PERCENT, WATT, CELSIUS, FAHRENHEIT)* - display one of these units
-- SYMBOL *(BULB, SWITCH, WINDOW, DOOR, BLIND, SCENE, PHONE, BELL, CLOCK, ARROW_UP, ARROW_DOWN)* - display symbols, multiple symbols possible
+- BEEP _(TONE1, TONE2, TONE3)_ - let the remote control beep
+- BACKLIGHT _(BACKLIGHT_ON, BLINK_SLOW, BLINK_FAST)_ - control the display backlight
+- UNIT _(PERCENT, WATT, CELSIUS, FAHRENHEIT)_ - display one of these units
+- SYMBOL _(BULB, SWITCH, WINDOW, DOOR, BLIND, SCENE, PHONE, BELL, CLOCK, ARROW_UP, ARROW_DOWN)_ - display symbols, multiple symbols possible
You can combine any option, they must be separated by a comma.
If you specify more than one option for BEEP, BACKLIGHT and UNIT, only the first one is taken into account and all others are ignored. For SYMBOL you can specify multiple options.
**Note:** The HM-Dis-EP-WM55 has only a black and white display and therefore does not support datapoints for colored lines. In addition, only lines 1-3 can be set.
-#### Example ####
+#### Example
Display text at line 1,3 and 5 when the bottom button on the display is pressed
-**Items**
+##### Items
```java
String Display_line_1 "Line 1" { channel="homematic:HM-Dis-WM55:ccu:NEQ0123456:1#DISPLAY_LINE_1" }
Switch Display_submit "Submit" { channel="homematic:HM-Dis-WM55:ccu:NEQ0123456:1#DISPLAY_SUBMIT" }
```
-**Rule**
+##### Rule
```javascript
rule "Display Test"
```
**Available icons:**
+
- NONE
- OFF
- ON
- SIGNAL_RED
**Available colors (only HM-Dis-WM55):**
+
- NONE(=WHITE)
- WHITE
- RED
```java
String Display_CombinedParam "Combined Parameter" {channel="homematic:HmIP-WRCD:ccu:123456:3#COMBINED_PARAMETER"}
```
+
#### Set Display Lines
The combined parameter can be used in a rule file like this:
```
**Key translation:**
-- DDBC: Background color of this line. (*WHITE*, *BLACK*)
-- DDTC: Text color of this line. (*WHITE*, *BLACK*)
+
+- DDBC: Background color of this line. (_WHITE_, _BLACK_)
+- DDTC: Text color of this line. (_WHITE_, _BLACK_)
- DDI: Icon to be shown after text. (see icon listing below)
-- DDA: Alignment of this line. (*LEFT*, *CENTER*, *RIGHT*)
+- DDA: Alignment of this line. (_LEFT_, _CENTER_, _RIGHT_)
- DDS: Text of this line. (String, but see special character listing below)
-- DDID: Line number. (*1-5*)
-- DDC: Commit, should be set in the last line, otherwise leave unset. (*true*)
+- DDID: Line number. (_1-5_)
+- DDC: Commit, should be set in the last line, otherwise leave unset. (_true_)
Each line can be updated separately without changing the other lines.
-Multiple lines can be updated within one command, use comma to separate each line.
+Multiple lines can be updated within one command, use comma to separate each line.
Here an example for a rule file:
```java
```
**Special Characters:**
+
- [ -> Ä
- \# -> Ö
- $ -> Ü
- @ -> Arrow Down Right
**Icons:**
+
- 0 - No Icon
- 1 - Light off
- 2 - Light on
```java
Display_CombinedParam.sendCommand("{R=0,IN=10,ANS=0}")
```
-Note, that a commit (`DDC`) is not necessary for sounds.
+
+Note, that a commit (`DDC`) is not necessary for sounds.
As with line configuration, this can be combined with other line updates, separated with a comma.
-**Key translations**
-- R: Repetitions (*0 to 15*, 15=infinite)
-- IN: Interval (*5 to 80* in steps of five)
-- ANS: Beep sound (*-1 to 7*, see beep table)
+##### Key translations
+
+- R: Repetitions (_0 to 15_, 15=infinite)
+- IN: Interval (_5 to 80_ in steps of five)
+- ANS: Beep sound (_-1 to 7_, see beep table)
+
+##### Beep Sounds
-**Beep Sounds**
This is the official mapping for the beep sounds
+
- -1 - No Sound
- 0 - Empty Battery
- 1 - Alarm Off
## Troubleshooting
-**SHORT & LONG_PRESS events of push buttons do not occur on the event bus**
+### SHORT & LONG_PRESS events of push buttons do not occur on the event bus
It seems buttons like the HM-PB-2-WM55 do just send these kind of events to the CCU if they are mentioned in a CCU program.
A simple workaround to make them send these events is, to create a program (rule inside the CCU) that does just have a "When" part and no "Then" part, in this "When" part each channel needs to be mentioned at least once.
The LONG_PRESS events will work automatically as they are part of the same channels.
After the creation of this program, the button device will receive configuration data from the CCU which have to be accepted by pressing the config-button at the back of the device.
-**INSTALL_TEST**
+### INSTALL_TEST
If a button is still not working and you do not see any PRESS_LONG / SHORT in your log file (log level DEBUG), it could be because of enabled security.
Try to disable security of your buttons in the HomeMatic Web GUI and try again.
If you can't disable security try to use key INSTALL_TEST which gets updated to ON for each key press
-**-1 Failure**
+### -1 Failure
A device may return this failure while fetching the datapoint values.
I have tested pretty much but I did not find the reason.
I hope this will be fixed in one of the next CCU firmwares.
With [Homegear](https://www.homegear.eu) everything works as expected.
-**No variables and scripts in GATEWAY-EXTRAS**
+### No variables and scripts in GATEWAY-EXTRAS
The gateway autodetection of the binding can not clearly identify the gateway and falls back to the default implementation.
Use the ```gatewayType=ccu``` config to force the binding to use the CCU implementation.
-**Variables out of sync**
+### Variables out of sync
The CCU only sends an event if a datapoint of a device has changed.
There is (currently) no way to receive an event automatically when a variable has changed.
:::: tabs
::: tab JavaScript
-
+
``` javascript
import org.openhab.core.types.RefreshType
...
``` php
Var_1.sendCommand(REFRESH)
```
+
:::
::::
In case of problems in the discovery or if above mentioned error message appears in `openhab.log`, the size for the transmission buffer for the communication with the gateway is too small.
The problem can be solved by increasing the `bufferSize` value in the bridge configuration.
-**Rollershutters are inverted**
+### Rollershutters are inverted
openHAB and the CCU are using different values for the same state of a rollershutter.
Examples: HmIP-BROLL, HmIP-FROLL, HmIP-BBL, HmIP-FBL and HmIP-DRBLI4
| openHAB | 0% | 100% |
| CCU | 100% | 0% |
-** The binding does not receive any status changes from the Homematic gateway**
+### The binding does not receive any status changes from the Homematic gateway
First of all, make sure that none of the ports needed to receive status changes from the gateway are blocked by firewall settings.
# HomeWizard Binding
The HomeWizard binding retrieves measurements from the HomeWizard Wi-Fi P1 meter.
-The meter itself is attached to a DSMR Smart Meter and reads out the telegrams, which it will forward to cloud storage.
+The meter itself is attached to a DSMR Smart Meter and reads out the telegrams, which it will forward to cloud storage.
However, recently HomeWizard also added an interface that can be queried locally.
This binding uses that local interface to make the measurements available.
Example of configuration through a .thing file:
-```
+```java
Thing homewizard:p1_wifi_meter:my_meter [ ipAddress="192.178.1.67", refreshDelay=5 ]
```
| total_gas | Number:Volume | The most recently reported total imported gas in m^3. |
| gas_timestamp | DateTime | The time stamp of the total_gas measurement. |
-
Example of configuration through a .items file:
-```
+```java
Number:Energy Energy_Import_T1 "Imported Energy T1 [%.0f kWh]" {channel="homewizard:p1_wifi_meter:my_meter:total_energy_import_t1" }
Number:Power Active_Power_L1 "Active Power Phase 1 [%.1f W]" {channel="homewizard:p1_wifi_meter:my_meter:active_power_l1" }
DateTime Gas_Update "Gas Update Time [%1$tH:%1$tM]" {channel="homewizard:p1_wifi_meter:my_meter:gas_timestamp" }
## Discovery
-This binding uses mDNS for discovering HP Printers on the local network.
+This binding uses mDNS for discovering HP Printers on the local network.
## Thing Configuration
Notes:
-* All channels are dynamically added at runtime.
-* The word color in channel names follows American spelling ("color").
-* The `colorLevel`, `colorMarkingUsed` and `colorPagesRemaining` channels are used on printers that have only a single color cartridge instead of separate Ccyan, magenta and yellow cartridges.
-* The `scanner` group is for the scanning engine which consists of scan, copy and other operations; the `scan` group is for scanner operations only.
-* If no `status` group channels are selected, then those relevant data endpoints on the *Embedded Web Server* are not polled for status information.
+- All channels are dynamically added at runtime.
+- The word color in channel names follows American spelling ("color").
+- The `colorLevel`, `colorMarkingUsed` and `colorPagesRemaining` channels are used on printers that have only a single color cartridge instead of separate Ccyan, magenta and yellow cartridges.
+- The `scanner` group is for the scanning engine which consists of scan, copy and other operations; the `scan` group is for scanner operations only.
+- If no `status` group channels are selected, then those relevant data endpoints on the _Embedded Web Server_ are not polled for status information.
## Full Textual Example
### Thing File
-```
+```java
Thing hpprinter:printer:djprinter "Printer" @ "Office" [ ipAddress="192.168.1.1", usageInterval="30", statusInterval="4" ]
```
### Item File
-```
+```java
String PrinterStatus "Status" { channel="hpprinter:printer:djprinter:status#status" }
Number:Dimensionless PrinterBlackLevel "Black Level" { channel="hpprinter:printer:djprinter:ink#blackLevel" }
Black Ink displayed as a whole percentage - `60 %`
-```
+```perl
Text item=hpprinter_printer_djprinter_ink_blackLevel label="Black [%.0f %unit%]"
```
Black Marker displayed in millilitres - `21 ml`
-*Default*
+_Default_
-```
+```perl
Text item=hpprinter_printer_djprinter_usage_blackMarker label="Black Marker [%.0f %unit%]"
```
Black Marker displayed in litres - `0.021 l`
-```
+```perl
Text item=hpprinter_printer_djprinter_usage_blackMarker label="Black Marker [%.3f l]"
```
Black Marker displayed in microlitres - `21000 µl`
-```
+```perl
Text item=hpprinter_printer_djprinter_usage_blackMarker label="Black Marker [%.0f µl]"
```
Scanner Document Feeder loaded with text status display - `ON` or `OFF`
-```
+```perl
Text item=hpprinter_printer_djprinter_status_scannerAdfLoaded label="ADF Loaded [%s]"
```
| `headers` | yes | - | Additional headers that are sent along with the request. Format is "header=value". Multiple values can be stored as `headers="key1=value1", "key2=value2", "key3=value3",`. When using text based configuration include at minimum 2 headers to avoid parsing errors.|
| `ignoreSSLErrors` | no | false | If set to true ignores invalid SSL certificate errors. This is potentially dangerous.|
-*Note:* Optional "no" means that you have to configure a value unless a default is provided and you are ok with that setting.
+_Note:_ Optional "no" means that you have to configure a value unless a default is provided and you are ok with that setting.
-*Note:* The `BASIC_PREEMPTIVE` mode adds basic authentication headers even if the server did not request authentication.
+_Note:_ The `BASIC_PREEMPTIVE` mode adds basic authentication headers even if the server did not request authentication.
This is dangerous and might be misused.
The option exists to be able to authenticate when the server is not sending the proper 401/Unauthorized code.
Authentication might fail if redirections are involved as headers are stripper prior to redirection.
-*Note:* If you rate-limit requests by using the `delay` parameter you have to make sure that the time between two refreshes is larger than the time needed for one refresh cycle.
+_Note:_ If you rate-limit requests by using the `delay` parameter you have to make sure that the time between two refreshes is larger than the time needed for one refresh cycle.
**Attention:** `baseUrl` (and `stateExtension`/`commandExtension`) should not normally use escaping (e.g. `%22` instead of `"` or `%2c` instead of `,`).
URLs are properly escaped by the binding itself before the request is sent.
|-------------------------|----------|-------------|-------------|
| `stateExtension` | yes | - | Appended to the `baseURL` for requesting states. |
| `commandExtension` | yes | - | Appended to the `baseURL` for sending commands. If empty, same as `stateExtension`. |
-| `stateTransformation ` | yes | - | One or more transformation applied to received values before updating channel. |
+| `stateTransformation` | yes | - | One or more transformation applied to received values before updating channel. |
| `commandTransformation` | yes | - | One or more transformation applied to channel value before sending to a remote. |
| `escapedUrl` | yes | - | This specifies whether the URL is already escaped. |
| `stateContent` | yes | - | Content for state requests (if method is `PUT` or `POST`) |
See the link above for more information about the available format parameters (e.g. to use the string representation, you need to append `s` to the reference, for a timestamp `t`).
When sending an OFF command on 2020-07-06, the URL
-```
+```text
http://www.domain.org/home/lights/23871/?status=%2$s&date=%1$tY-%1$tm-%1$td
```
is transformed to
-```
+```text
http://www.domain.org/home/lights/23871/?status=OFF&date=2020-07-06
```
### `demo.things`
-```
+```java
Thing http:url:foo "Foo" [
- baseURL="https://example.com/api/v1/metadata-api/web/metadata",
- headers="key1=value1", "key2=value2", "key3=value3",
- refresh=15] {
- Channels:
- Type string : text "Text" [ stateTransformation="JSONPATH:$.metadata.data" ]
+ baseURL="https://example.com/api/v1/metadata-api/web/metadata",
+ headers="key1=value1", "key2=value2", "key3=value3",
+ refresh=15] {
+ Channels:
+ Type string : text "Text" [ stateTransformation="JSONPATH:$.metadata.data" ]
}
```
-## Vito WIFI (https://github.com/openhab/openhab-addons/issues/9480#issuecomment-751335696)
+# Xtend Examples
+
+## Vito WIFI (<https://github.com/openhab/openhab-addons/issues/9480#issuecomment-751335696>)
### .things
-```
+
+```java
Thing http:url:vitowifi "VitoWifi" @ "1stfloor" [baseURL="http://192.168.1.61/", commandMethod="POST", delay="1000", refresh="90", timeout="900"] {
Channels:
### .items
-```
+```java
Number Vito_ID "Vito_ID" <switch> (gHeating) {channel="http:url:vitowifi:Channel_Vito_ID" , expire="5m" }
Number Vito_Mode "Vito_Mode" <switch> (gHeating) {channel="http:url:vitowifi:Channel_Vito_Mode" , expire="5m" }// 0= Off 1= WW 2= WW+heat 0x42 (66)=party
Number Vito_OnOff "ONOFF Switch" <switch> (gHeating) {channel="http:url:vitowifi:Channel_Vito_OnOff" , expire="5m" }
```
-## Feinstaubsensor (https://community.openhab.org/t/http-binding-openhab-3-version/101851/235)
+## Feinstaubsensor (<https://community.openhab.org/t/http-binding-openhab-3-version/101851/235>)
-The http request http://feinstaubsensor-14255834/data.json is answering with a JSON string.
+The http request `http://feinstaubsensor-14255834/data.json` is answering with a JSON string.
So I need some simple JSONPATH transformation and one java script transformation.
Data is polled every 10 seconds.
### .things
-```
+```java
Thing http:url:feinstaub "Feinstaub" [ baseURL="http://feinstaubsensor-14255834/data.json", refresh=10] {
Channels:
Type number : SDS_PM10 [ stateTransformation="JSONPATH:$.sensordatavalues[0].value" ]
### .items
-```
+```java
/* **************************
* Feinstaub sensor data
* ************************** */
I have a BME2080 sensor connected. The Humidity must be diveded by 100 to show hPa.
-```
+```javascript
(function(x) {
var json = JSON.parse(x);
return json.sensordatavalues[3].value/100;
})(input)
-```
\ No newline at end of file
+```
Almost all available Hue devices are supported by this binding.
This includes not only the "Friends of Hue", but also products like the LivingWhites adapter.
-Additionally, it is possible to use OSRAM Lightify devices as well as other ZigBee LightLink compatible products, including the IKEA TRÅDFRI lights (when updated).
+Additionally, it is possible to use OSRAM Lightify devices as well as other ZigBee LightLink compatible products, including the IKEA TRÅDFRI lights (when updated).
Beside bulbs and luminaires the Hue binding also supports some ZigBee sensors. Currently only Hue specific sensors are tested successfully (Hue Motion Sensor and Hue Dimmer Switch).
Please note that the devices need to be registered with the Hue Bridge before it is possible for this binding to use them.
Beside bulbs and luminaires the Hue binding supports some ZigBee sensors.
Currently only Hue specific sensors are tested successfully (e.g. Hue Motion Sensor, Hue Dimmer Switch, Hue Tap, CLIP Sensor).
The Hue Motion Sensor registers a `ZLLLightLevel` sensor (0106), a `ZLLPresence` sensor (0107) and a `ZLLTemperature` sensor (0302) in one device.
-The Hue CLIP Sensor saves scene states with status or flag for HUE rules.
+The Hue CLIP Sensor saves scene states with status or flag for HUE rules.
They are presented by the following ZigBee Device ID and _Thing type_:
| Device type | ZigBee Device ID | Thing type |
Auto-discovery is enabled by default.
To disable it, you can add the following line to `<openHAB-conf>/services/runtime.cfg`:
-```
+```text
discovery.hue:background=false
```
The Hue Bridge requires the IP address as a configuration value in order for the binding to know where to access it.
In the thing file, this looks e.g. like
-```
+```java
Bridge hue:bridge:1 [ ipAddress="192.168.0.64" ]
```
The generated user name can be found, after pressing the authentication button on the bridge, with the following console command: `hue <bridgeUID> username`.
The user name can be set using the `userName` configuration value, e.g.:
-```
+```java
Bridge hue:bridge:1 [ ipAddress="192.168.0.64", userName="qwertzuiopasdfghjklyxcvbnm1234" ]
```
The devices are identified by the number that the Hue Bridge assigns to them (also shown in the Hue App as an identifier).
Thus, all it needs for manual configuration is this single value like
-```
+```java
0210 bulb1 "Lamp 1" @ "Office" [ lightId="1" ]
```
or
-```
+```java
0107 motion-sensor "Motion Sensor" @ "Entrance" [ sensorId="4" ]
```
The following device types also have an optional configuration value to specify the fade time in milliseconds for the transition to a new state:
-* Dimmable Light
-* Dimmable Plug-in Unit
-* Colour Light
-* Extended Colour Light
-* Colour Temperature Light
+- Dimmable Light
+- Dimmable Plug-in Unit
+- Colour Light
+- Extended Colour Light
+- Colour Temperature Light
| Parameter | Description |
|-----------|-------------------------------------------------------------------------------|
| lightId | Number of the device provided by the Hue Bridge. **Mandatory** |
| fadetime | Fade time in Milliseconds to a new state (min="0", step="100", default="400") |
-
### Groups
The groups are identified by the number that the Hue Bridge assigns to them.
Thus, all it needs for manual configuration is this single value like
-```
+```java
group kitchen-bulbs "Kitchen Lamps" @ "Kitchen" [ groupId="1" ]
```
| groupId | Number of the group provided by the Hue Bridge. **Mandatory** |
| fadetime | Fade time in Milliseconds to a new state (min="0", step="100", default="400") |
-
## Channels
The devices support some of the following channels:
| Button 3 | Button 3 | 17 |
| Button 4 | Button 4 | 18 |
-
## Rule Actions
This binding includes a rule action, which allows to change a light channel with a specific fading time from within rules.
### demo.things:
-```
+```java
Bridge hue:bridge:1 "Hue Bridge" [ ipAddress="192.168.0.64" ] {
0210 bulb1 "Lamp 1" @ "Kitchen" [ lightId="1" ]
0220 bulb2 "Lamp 2" @ "Kitchen" [ lightId="2" ]
### demo.items:
-```
+```java
// Bulb1
Switch Light1_Toggle { channel="hue:0210:1:bulb1:color" }
Dimmer Light1_Dimmer { channel="hue:0210:1:bulb1:color" }
### demo.sitemap:
-```
+```perl
sitemap demo label="Main Menu"
{
Frame {
## Supported Things
-
### Account Bridge Thing
-
-The Account Bridge Thing type represents the user's account on the Hydrawise cloud service. The bridge can have one or more child [Controllers](#Controller-Thing) linked.
+
+The Account Bridge Thing type represents the user's account on the Hydrawise cloud service. The bridge can have one or more child [Controllers](#controller-thing) linked.
An account must be manually added and configured.
### Controller Thing
-Controller Things are automatically discovered once an [Account Bridge](#Account-Bridge-Thing) has be properly configured.
+Controller Things are automatically discovered once an [Account Bridge](#account-bridge-thing) has be properly configured.
The Controller Thing type is the primary way most users will control and monitor their irrigation system.
This allows full control over zones, sensors and weather forecasts.
-Changes made through this Thing type will be reflected in the Hydrawise mobile and web applications as well as in their reporting modules.
+Changes made through this Thing type will be reflected in the Hydrawise mobile and web applications as well as in their reporting modules.
-Controller Things require a parent [Account Bridge](#Account-Bridge-Thing)
+Controller Things require a parent [Account Bridge](#account-bridge-thing)
#### Controller Thing Supported Channel Groups
| channel group ID |
|-----------------------------------------------|
-| [Controller](#Cloud-Controller-Channel-Group) |
-| [Zones](#Zone-Channel-Group) |
-| [All Zones](#All-Zones-Channel-Group) |
-| [Sensor](#Sensor-Channel-Group) |
-| [Forecast](#Sensor-Channel-Group) |
-
+| [Controller](#controller-thing-1) |
+| [Zones](#zone-channel-group) |
+| [All Zones](#all-zones-channel-group) |
+| [Sensor](#sensor-channel-group) |
+| [Forecast](#forecast-channel-group) |
+
### Local Thing
The Local Thing type uses an undocumented API that allows direct HTTP access to an irrigation controller on the user's network.
This provides a subset of features compared to the Cloud Thing type limited to basic zone control.
-Controlling zones through the local API will not be reported back to the cloud service or the Hydrawise mobile/web applications, and reporting functionality will not reflect the locally controlled state.
+Controlling zones through the local API will not be reported back to the cloud service or the Hydrawise mobile/web applications, and reporting functionality will not reflect the locally controlled state.
Local control may not be available on later Hydrawise controller firmware versions.
-Use Cases
+Use Cases
-* The Local thing can be useful when testing zones, as there is no delay when starting/stopping zones as compared to the cloud API which can take anywhere between 5-15 seconds.
-* This is also useful if you wish to not use the cloud scheduling at all and use openHAB as the irrigation scheduling system.
+- The Local thing can be useful when testing zones, as there is no delay when starting/stopping zones as compared to the cloud API which can take anywhere between 5-15 seconds.
+- This is also useful if you wish to not use the cloud scheduling at all and use openHAB as the irrigation scheduling system.
#### Local Thing Supported Channel Groups
| channel group ID |
|---------------------------------------|
-| [Zones](#Zone-Channel-Group) |
-| [All Zones](#All-Zones-Channel-Group) |
+| [Zones](#zone-channel-group) |
+| [All Zones](#all-zones-channel-group) |
## Thing Configuration
|--------------------|---------|----------|----------------------|
| controllerId | Integer | True | ID of the controller |
-
### Local Thing
| Configuration Name | type | required | Comments |
|------------------|------------------------|
| allzones | commands for all zones |
-
### Channels
Channels uses across zones, sensors and forecasts
+
| channel ID | type | Groups | description | Read Write |
|----------------------------|--------------------|----------------|-----------------------------------------------|------------|
| name | String | zone, sensor | Descriptive name | R |
| precipitation | Number | forecast | Daily precipitation amount | R |
| probabilityofprecipitation | Number | forecast | Daily probability of precipitation percentage | R |
-
## Full Example
-```
+```java
Group Sprinkler "Sprinkler"
Group SprinklerController "Controller" (Sprinkler)
Group SprinklerZones "Zones" (Sprinkler)
Number SprinklerZone3TimeLeft "3 Left of Drive Lawn Time Left" (SprinklerZone3) {channel="hydrawise:controller:myaccount:123456:zone3#timeleft"}
String SprinklerZone3Icon "3 Left of Drive Lawn Icon" (SprinklerZone3) {channel="hydrawise:controller:myaccount:123456:zone3#icon"}
```
-
## Supported Things
-* Hyperion Server (may be referred to as V1)
-* Hyperion.ng Server
+- Hyperion Server (may be referred to as V1)
+- Hyperion.ng Server
## Binding Configuration
| port | Integer | Y | 19444 |
| priority | Integer | Y | 50 |
| poll_frequency | Integer | Y | 15 |
-
-To manually configure a Hyperion Server you must specify the following parameters: host, port, priority and polling frequency.
-
+
+To manually configure a Hyperion Server you must specify the following parameters: host, port, priority and polling frequency.
+
In the thing file, this looks for e.g. like
-```
+```java
Thing hyperion:serverV1:myServer [ host="192.168.0.10", port=19444, priority=50, poll_frequency=15]
```
| priority | Integer | Y | 50 |
| poll_frequency | Integer | Y | 15 |
| origin | String | Y | "openHAB" |
-
+
To manually configure a Hyperion.ng Server you must specify the following parameters: host, port, priority, polling frequency and origin.
-
+
In the .things file, this looks for e.g. like
-```
+```java
Thing hyperion:serverNG:myServer [ host="192.168.0.10", port=19444, priority=50, poll_frequency=15, origin="openHAB"]
```
### Hyperion Server (V1):
-```
+```java
Dimmer Brightness "Brightness [%s]" {channel="hyperion:serverV1:myServer:brightness"}
Color MyColor "Color" {channel="hyperion:serverV1:myServer:color"}
String Effect "Current effect [%s]" {channel="hyperion:serverV1:myServer:effect"}
### Hyperion.ng Server
-```
+```java
Dimmer Brightness "Brightness [%s]" {channel="hyperion:serverNG:myServer:brightness"}
Color MyColor "Color" {channel="hyperion:serverNG:myServer:color"}
String Effect "Current effect [%s]" {channel="hyperion:serverNG:myServer:effect"}
Switch BoblightEnabled "Boblight" {channel="hyperion:serverNG:myServer:boblightserver"}
Switch GrabberEnabled "Grabber" {channel="hyperion:serverNG:myServer:grabber"}
Switch V4lEnabled "V4L" {channel="hyperion:serverNG:myServer:v4l"}
-Switch LedDeviceEnabled "LED Device" {channel="hyperion:serverNG:myServer:leddevice"}
+Switch LedDeviceEnabled "LED Device" {channel="hyperion:serverNG:myServer:leddevice"}
```
## Example Sitemap
-Using the above things channels and items
+Using the above things channels and items
Sitemap:
-```
+```perl
sitemap demo label="Main Menu" {
Frame {
// serverV1 & serverNG
-# Iammeter Binding
+# Iammeter Binding
[Iammeter](https://www.iammeter.com) provides real-time readings of single-phase (WEM3080, WEM3162) and three-phase (WEM3080T) meters from IAMMETER over Wi-Fi.
## Use of the binding
-The Iammeter is exposed as one thing with a number of channels that can be used to read the values for different aspects of your Iammeter devices.
+The Iammeter is exposed as one thing with a number of channels that can be used to read the values for different aspects of your Iammeter devices.
## Setup of the binding
You can add the Iammeter device via the openHAB UI manually.
-
## Available channels
The following table is taken from the official manual and contains all available channels.
| importenergy_a | kWh | Energy consumption from gird | Number:Energy |
| exportgrid_a | kWh | Energy export to grid | Number:Energy |
-
Three-phase energy meter (WEM3080T)
| Name | Unit | Description | Type |
|----------------|------|-----------------------|--------------------------|
| frequency_c | kWh | C phase frequency | Number:Frequency |
| pf_c | kWh | C phase power factor | Number |
-
-
## More information
-More information about the Iammeter devices can be found in the [Iammeter website](https://www.iammeter.com).
+More information about the Iammeter devices can be found in the [Iammeter website](https://www.iammeter.com).
# iAquaLink Binding
-
+
This binding supports:
-* Any iAquaLink based pool system
-* Reading auxiliary, temperature, pump, chemistry and system values
-* Controlling system, auxiliary, lighting, and temperature settings
+- Any iAquaLink based pool system
+- Reading auxiliary, temperature, pump, chemistry and system values
+- Controlling system, auxiliary, lighting, and temperature settings
## Binding Configuration
The binding requires the iAquaLink user name and password.
If you have more then one pool system registered to an account, you may optionally specify the pool serial ID/Number to use, otherwise the first pool controller will be used.
-
## Manual Thing Configuration
-```
+```java
Thing iaqualink:controller:pool [ userName="user@domain.com", password="somepassword"]
```
## Channels
-
The following is a list of supported channels.
Auxiliary and OneTouch channels will be dynamically added depending on what a system reports as being supported.
Auxiliary channels that are of a number type represent lighting modes (typically 0-15).
Auxiliary channels that are dimmer types can set the light value in increments of 25 (0,25,50,750,100).
-The Auxiliary channel type will be dynamically assigned based on the controller configuration.
+The Auxiliary channel type will be dynamically assigned based on the controller configuration.
Heater status can be OFF (0), Enabled/ON (3), or Heating (1).
| "13" | | Fat Tuesday | | | Hold |
| "14" | | Disco Tech | | | Recall |
-
-
-
## Sample Items
-```
+```java
Group Group_AquaLink
String AquaLinkStatus "Status [%s]" (Group_AquaLink) {channel="iaqualink:controller:pool:status"}
Switch AquaLinkBoosterPump "Booster Pump" (Group_AquaLink) {channel="iaqualink:controller:pool:aux_1"}
## Channels
-### Channels for `calendar`
+### Channels for `calendar`
The channels of `calendar` describe the current and the next forthcoming event.
They are all read-only.
The scheme replaces `<no>` by the results index, beginning at `0`. An `eventfilter` having `maxEvents` set to 3 will have following channels:
-* `result_0#begin`
-* `result_0#end`
-* `result_0#title`
-* `result_1#begin`
-* `result_1#end`
-* `result_1#title`
-* `result_2#begin`
-* `result_2#end`
-* `result_2#title`
+- `result_0#begin`
+- `result_0#end`
+- `result_0#title`
+- `result_1#begin`
+- `result_1#end`
+- `result_1#title`
+- `result_2#begin`
+- `result_2#end`
+- `result_2#title`
## Command Tags
A fourth field is optional.
The syntax is as follows:
-```
- BEGIN:Item_Name:New_State_Value
- BEGIN:Item_Name:New_State_Value:Authorization_Code
- END:Item_Name:New_State_Value
- END:Item_Name:New_State_Value:Authorization_Code
+```text
+BEGIN:Item_Name:New_State_Value
+BEGIN:Item_Name:New_State_Value:Authorization_Code
+END:Item_Name:New_State_Value
+END:Item_Name:New_State_Value:Authorization_Code
```
The first field **must** be either `BEGIN` or `END`.
It must be a value which is compatible with the item type.
See openHAB Core definitions for [command types](https://www.openhab.org/docs/concepts/items.html#state-and-command-type-formatting) for valid types and formats.
-The `Authorization_Code` may *optionally* be used as follows:
+The `Authorization_Code` may _optionally_ be used as follows:
- When the thing configuration parameter `authorizationCode` is not blank, the binding will compare the `Authorization_Code` field against the `authorizationCode` configuration parameter, and it will only execute the command if the two strings are the same.
All required information must be provided in the thing definition, either via UI or in the `.things` file..
-```
+```java
Bridge icalendar:calendar:deadbeef "My calendar" @ "Internet" [ url="http://example.org/calendar.ical", refreshTime=60 ]
Thing icalendar:eventfilter:feedd0d0 "Tomorrows events" (icalendar:calendar:deadbeef) [ maxEvents=1, datetimeUnit="DAY", datetimeStart=1, datetimeEnd=2, datetimeRound=true ]
```
Link the channels as usual to items:
-```
+```java
String current_event_name "current event [%s]" <calendar> { channel="icalendar:calendar:deadbeef:current_title" }
DateTime current_event_until "current until [%1$tT, %1$tY-%1$tm-%1$td]" <calendar> { channel="icalendar:calendar:deadbeef:current_end" }
String next_event_name "next event [%s]" <calendar> { channel="icalendar:calendar:deadbeef:next_title" }
Sitemap just showing the current event and the beginning of the next:
-```
+```perl
sitemap local label="My Calendar Sitemap" {
Frame label="events" {
Text item=current_event_name label="current event [%s]"
Command tags in a calendar event (in the case that configuration parameter `authorizationCode` equals `abc`):
-```
+```text
BEGIN:Calendar_Test_Temperature:12.3°C:abc
END:Calendar_Test_Temperature:23.4°F:abc
```
Command tags in a calendar event (in the case that configuration parameter `authorizationCode` is not set):
-```
+```text
BEGIN:Calendar_Test_Switch:ON
END:Calendar_Test_Switch:OFF
```
```
The device ID can be found in the Inbox after it has been discovered.
-The information *@ "World"* is optional.
+The information _@ "World"_ is optional.
### icloud.items
| createChannelsAutomatically | Create channels automatically from project file. Project file loading parameter should be enabled as well. | no | true |
| tlsVersion | TLS version used for controller communication. Choose `TLSv1` for older firmware versions and `TLSv1.2` for never versions (since fall 2021). `AUTO` mode try to recognize correct version. | no | TLSv1 |
-
## Channels
List of default controller channels.
There are several ways to find the correct resource id's:
1. Find directly from your IHC / ELKO LS project file (.vis file).
-2. Via IHC / ELKO Visual application. Hold ctrl button from keyboard while mouse over the select item in Visual.
-3. Enable debug level from binding. Binding will then print basic resource ID from the project file, if `loadProjectFile` configuration variable is enabled.
+1. Via IHC / ELKO Visual application. Hold ctrl button from keyboard while mouse over the select item in Visual.
+1. Enable debug level from binding. Binding will then print basic resource ID from the project file, if `loadProjectFile` configuration variable is enabled.
-The binding supports resource id's ***only*** in decimal format.
+The binding supports resource id's _**only**_ in decimal format.
Hexadecimal values (start with 0x prefix) need to be converted to decimal format.
Conversion can be done e.g. via Calculator in Windows or Mac.
| DOWN | Rollershutter |
| TOGGLE | Switch |
-All commands but `TOGGLE` are standard openHAB commands.
-When `TOGGLE` command is specified, profile will toggle switch item state.
+All commands but `TOGGLE` are standard openHAB commands.
+When `TOGGLE` command is specified, profile will toggle switch item state.
E.g. if item state has been OFF, profile will send ON command to item.
-
+
Example:
-```xtend
+```java
Dimmer test { channel="ihc:controller:elko:my_test_trigger"[profile="ihc:pushbutton-to-command", short-press-command="TOGGLE", long-press-command="INCREASE", long-press-time=1000, repeat-time=200] }
```
Will send TOGGLE (ON/OFF) command to Dimmer test item when short button press is detected (button press less than 1000ms) and send INCREASE commands as long button is pressed over 1000ms (200ms interval).
-
## Examples
### example.things
-```xtend
+```java
ihc:controller:elko [ hostname="192.168.1.2", username="openhab", password="secret", timeout=5000, loadProjectFile=true, createChannelsAutomatically=false, tlsVersion="TLSv1" ] {
Channels:
Type switch : my_test_switch "My Test Switch" [ resourceId=3988827 ]
### example.items
-```xtend
+```java
Switch test_switch "Test Switch" { channel="ihc:controller:elko:my_test_switch" }
Switch test_contact "Test Contact" { channel="ihc:controller:elko:my_test_contact" }
Number test_number "Test Number" { channel="ihc:controller:elko:my_test_number" }
### example.rules
-```xtend
+```java
rule "My test trigger test rule"
when
Channel 'ihc:controller:elko:my_test_trigger' triggered LONG_PRESS
It uses the official API 1.1 as provided by innogy as cloud service.
As all status updates and commands have to go through the API, a permanent internet connection is required.
-*Notice!*
+_Notice!_
-*This binding is deprecated!*
+_This binding is deprecated!_
-*LIVISI (formally innogy) has implemented a local API on their SHC from Software Version 1.2.XX.XXX.
-Please migrate to the "LIVISI SmartHome Binding" which is using the new local API and requires neither the LIVISI-cloud-servers nor an internet connection.*
+_LIVISI (formally innogy) has implemented a local API on their SHC from Software Version 1.2.XX.XXX.
+Please migrate to the "LIVISI SmartHome Binding" which is using the new local API and requires neither the LIVISI-cloud-servers nor an internet connection._
## Supported things
Authorization is done as oauth2 workflow with the innogy API.
To receive the auth-code, go to one of the following URLs depending on your brand and login with your credentials (you can find this link also in the SHC thing in the UI, if you edit it):
-https://auth.services-smarthome.de/AUTH
-* [innogy SmartHome authorization page](https://auth.services-smarthome.de/AUTH/authorize?response_type=code&client_id=24635748&redirect_uri=https%3A%2F%2Fwww.openhab.org%2Foauth%2Finnogy%2Finnogy-smarthome.html&scope&lang=de-DE)
-* [SmartHome Austria authorization page](https://auth.services-smarthome.de/AUTH/authorize?response_type=code&client_id=24635749&redirect_uri=https%3A%2F%2Fwww.openhab.org%2Foauth%2Finnogy%2Fsmarthome-austria.html&scope&lang=de-DE)
-* [Start SmartHome authorization page](https://auth.services-smarthome.de/AUTH/authorize?response_type=code&client_id=24635750&redirect_uri=https%3A%2F%2Fwww.openhab.org%2Foauth%2Finnogy%2Fstart-smarthome.html&scope&lang=de-DE)
+`https://auth.services-smarthome.de/AUTH`
+
+- [innogy SmartHome authorization page](https://auth.services-smarthome.de/AUTH/authorize?response_type=code&client_id=24635748&redirect_uri=https%3A%2F%2Fwww.openhab.org%2Foauth%2Finnogy%2Finnogy-smarthome.html&scope&lang=de-DE)
+- [SmartHome Austria authorization page](https://auth.services-smarthome.de/AUTH/authorize?response_type=code&client_id=24635749&redirect_uri=https%3A%2F%2Fwww.openhab.org%2Foauth%2Finnogy%2Fsmarthome-austria.html&scope&lang=de-DE)
+- [Start SmartHome authorization page](https://auth.services-smarthome.de/AUTH/authorize?response_type=code&client_id=24635750&redirect_uri=https%3A%2F%2Fwww.openhab.org%2Foauth%2Finnogy%2Fstart-smarthome.html&scope&lang=de-DE)
You will be redirected to openhab.org and the auth-code will be displayed.
Copy and paste it into your SHC configuration and you are done.
As an alternative to using automatic discovery, innogy things can be configured using .things files.
The innogy SmartHome Controller (SHC) can be configured using the following syntax:
-```
+```java
Bridge innogysmarthome:bridge:<bridge-id> []
```
Then the required authcode is retrieved and set **automatically**:
-```
+```java
Bridge innogysmarthome:bridge:<bridge-id> [ authcode="<authcode>" ]
```
-** *Security warning!**
+** _Security warning!_*
As the refresh-token is THE one and only credential one needs to access the innogy webservice with all device data, you have to make sure it is never given to another person.
Thus it is recommended to remove the line from the openhab.log and/or make sure, the logfile is definitely never accessible by others!
All other innogy devices can be added using the following syntax:
-```
+```java
Thing WDS <thing-id> "<thing-name>" @ "<room-name>" [ id="<the-device-id>" ]
```
However, a full example .things configuration look like this:
-```
+```java
Bridge innogysmarthome:bridge:mybride "innogy SmartHome Controller" {
Thing ISD2 myDimmer "Dimmer Kitchen" @ "Kitchen" [ id="<device-id>" ]
Thing ISS2 myLightSwitch "Light Livingroom" @ "Livingroom" [ id="<device-id>" ]
You can then configure your items in your *.items config files as usual, for example:
-```
+```java
Contact myWindowContact "Kitchen" <window> {channel="innogysmarthome:WDS:mybridge:myWindowContact:contact"}
Switch myWindowContactBattery "Battery low" <battery> {channel="innogysmarthome:WDS:mybridge:myWindowContact:battery_low"}
Number myHeatingTemp "Bath [%.1f °C]" <temperature> {channel="innogysmarthome:RST:mybridge:myHeating:temperature"}
The site configuration works a usual. One special example
-```
+```perl
sitemap default label="Home" {
Frame {
Text item=myHeatingTemp label="Temperature"
Pushbuttons provide trigger channels, that can only be used in rules.
Here is an example rule:
-```
+```java
rule "Button triggered rule"
when
- Channel 'innogysmarthome:WSC2:mybridge:myPushButton:button1' triggered PRESSED
+ Channel 'innogysmarthome:WSC2:mybridge:myPushButton:button1' triggered PRESSED
then
// do something...
- logInfo("testlogger", "Button 1 pressed")
+ logInfo("testlogger", "Button 1 pressed")
end
```
To solve this on a Linux system, follow this steps:
-1. Download the certificates (.cer-files) of https://home.innogy-smarthome.de and https://innogy.com including the "DigiCert Global Root G2" to your computer.
+1. Download the certificates (.cer-files) of <https://home.innogy-smarthome.de> and <https://innogy.com> including the "DigiCert Global Root G2" to your computer.
As this depends on the used browser and operating system, please use a web search engine to find out how to achieve this for your situation.
-2. On your Linux system, goto your Java Machine's certificate store, e.g. `/usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt/jre/lib/security`.
+1. On your Linux system, goto your Java Machine's certificate store, e.g. `/usr/lib/jvm/jdk-8-oracle-arm32-vfp-hflt/jre/lib/security`.
The path should include a file called `cacerts` (this is the certificate store) and may differ depending on the system used.
-3. Copy the .cer-files from step 1 into this directory.
-4. Import each certificate with the command: `sudo keytool –importcert –alias “innogysmarthome” –keystore cacerts –file innogy.cer`
+1. Copy the .cer-files from step 1 into this directory.
+1. Import each certificate with the command: `sudo keytool –importcert –alias “innogysmarthome” –keystore cacerts –file innogy.cer`
(alias can be freely chosen but must be unique; replace innogy.cer with the filename of the downloaded certificate)
-5. Restart the JVM and openHAB.
+1. Restart the JVM and openHAB.
The default password of the certificate store is "changeit".
Relevant messages from the Insteon network (like notifications about switches being toggled) are picked up by the modem and converted to openHAB status updates by the binding.
The binding also supports sending and receiving of legacy X10 messages.
-The binding does not support linking new devices on the fly, i.e. all devices must be linked with the modem *before* starting the Insteon binding.
+The binding does not support linking new devices on the fly, i.e. all devices must be linked with the modem _before_ starting the Insteon binding.
The openHAB binding supports minimal configuration of devices, currently only monitoring and sending messages.
For all other configuration and set up of devices, link the devices manually via the set buttons, or use the free [Insteon Terminal](https://github.com/pfrommerd/insteon-terminal) software.
## Thing Configuration
-#### Network Configuration
+### Network Configuration
The Insteon PLM or hub is configured with the following parameters:
>NOTE: For users upgrading from InsteonPLM, The parameter port_1 is now port.
-#### Device Configuration
+### Device Configuration
The Insteon device is configured with the following required parameters:
| update | Switch | Update |
| watts | Number:Power | Watts |
-
## Full Example
Sample things file:
-```
+```java
Bridge insteon:network:home [port="/dev/ttyUSB0"] {
Thing device 22F8A8 [address="22.F8.A8", productKey="F00.00.15"] {
Channels:
Sample items file:
-```
+```java
Switch switch1 { channel="insteon:device:home:243141:switch" }
Dimmer dimmer1 { channel="insteon:device:home:238F55:dimmer" }
Dimmer dimmer2 { channel="insteon:device:home:23B0D9:dimmer" }
Enter `openhab:insteon` or `insteon` in the console and you will get a list of available commands.
The `openhab:` prefix is optional:
-```
+```shell
openhab> openhab:insteon
Usage: openhab:insteon display_devices - display devices that are online, along with available channels
Usage: openhab:insteon display_channels - display channels that are linked, along with configuration information
## Insteon Groups and Scenes
-How do Insteon devices tell other devices on the network that their state has changed? They send out a broadcast message, labeled with a specific *group* number.
-All devices (called *responders*) that are configured to listen to this message will then go into a pre-defined state.
+How do Insteon devices tell other devices on the network that their state has changed? They send out a broadcast message, labeled with a specific _group_ number.
+All devices (called _responders_) that are configured to listen to this message will then go into a pre-defined state.
For instance when light switch A is switched to "ON", it will send out a message to group #1, and all responders will react to it, e.g they may go into the "ON" position as well.
Since more than one device can participate, the sending out of the broadcast message and the subsequent state change of the responders is referred to as "triggering a scene".
At the device and PLM level, the concept of a "scene" does not exist, so you will find it notably absent in the binding code and this document.
Since Insteon devices can have multiple features (for instance a switchable relay and a contact sensor) under a single Insteon address, an openHAB item is not bound to a device, but to a given feature of a device.
For example, the following lines would create two Number items referring to the same thermostat device, but to different features of it:
-```
+```java
Number thermostatCoolPoint "cool point [%.1f °F]" { channel="insteon:device:home:32F422:coolSetPoint" }
Number thermostatHeatPoint "heat point [%.1f °F]" { channel="insteon:device:home:32F422:heatSetPoint" }
```
The following example shows how to configure a simple light switch (2477S) in the .items file:
-```
+```java
Switch officeLight "office light" { channel="insteon:device:home:AABBCC:switch" }
```
Here is how to configure a simple dimmer (2477D) in the .items file:
-```
+```java
Dimmer kitchenChandelier "kitchen chandelier" { channel="insteon:device:home:AABBCC:dimmer" }
```
The parameter dimmermax must be defined for the channel.
The below example sets a maximum level of 70% for dim 1 and 60% for dim 2:
-**Things**
+#### Things
-```
+```java
Bridge insteon:network:home [port="/dev/ttyUSB0"] {
Thing device AABBCC [address="AA.BB.CC", productKey="F00.00.11"] {
Channels:
}
```
-**Items**
+#### Items
-```
+```java
Dimmer d1 "dimmer 1" { channel="insteon:device:home:AABBCC:dimmer"}
Dimmer d2 "dimmer 2" { channel="insteon:device:home:AABBCD:loadDimmer"}
```
Here's how to configure the top and bottom outlet of the in-wall 2 outlet controller:
-```
+```java
Switch fOutTop "Front Outlet Top" <socket> { channel="insteon:device:home:AABBCC:topOutlet" }
Switch fOutBot "Front Outlet Bottom" <socket> { channel="insteon:device:home:AABBCC:bottomOutlet" }
```
The 4-button mini remote sends out messages on groups 0x01 - 0x04, each corresponding to one button.
The modem's link database (see [Insteon Terminal](https://github.com/pfrommerd/insteon-terminal)) should look like this:
-```
- 0000 xx.xx.xx xx.xx.xx RESP 10100010 group: 01 data: 02 2c 41
- 0000 xx.xx.xx xx.xx.xx RESP 10100010 group: 02 data: 02 2c 41
- 0000 xx.xx.xx xx.xx.xx RESP 10100010 group: 03 data: 02 2c 41
- 0000 xx.xx.xx xx.xx.xx RESP 10100010 group: 04 data: 02 2c 41
+```text
+0000 xx.xx.xx xx.xx.xx RESP 10100010 group: 01 data: 02 2c 41
+0000 xx.xx.xx xx.xx.xx RESP 10100010 group: 02 data: 02 2c 41
+0000 xx.xx.xx xx.xx.xx RESP 10100010 group: 03 data: 02 2c 41
+0000 xx.xx.xx xx.xx.xx RESP 10100010 group: 04 data: 02 2c 41
```
**Items**
This goes into the items file:
-```
- Switch miniRemoteButtonA "mini remote button a" { channel="insteon:device:home:AABBCC:buttonA", autoupdate="false" }
- Switch miniRemoteButtonB "mini remote button b" { channel="insteon:device:home:AABBCC:buttonB", autoupdate="false" }
- Switch miniRemoteButtonC "mini remote button c" { channel="insteon:device:home:AABBCC:buttonC", autoupdate="false" }
- Switch miniRemoteButtonD "mini remote button d" { channel="insteon:device:home:AABBCC:buttonD", autoupdate="false" }
+```java
+Switch miniRemoteButtonA "mini remote button a" { channel="insteon:device:home:AABBCC:buttonA", autoupdate="false" }
+Switch miniRemoteButtonB "mini remote button b" { channel="insteon:device:home:AABBCC:buttonB", autoupdate="false" }
+Switch miniRemoteButtonC "mini remote button c" { channel="insteon:device:home:AABBCC:buttonC", autoupdate="false" }
+Switch miniRemoteButtonD "mini remote button d" { channel="insteon:device:home:AABBCC:buttonD", autoupdate="false" }
```
**Sitemap**
This goes into the sitemap file:
-```
- Switch item=miniRemoteButtonA label="mini remote button a" mappings=[ OFF="Off", ON="On"]
- Switch item=miniRemoteButtonB label="mini remote button b" mappings=[ OFF="Off", ON="On"]
- Switch item=miniRemoteButtonC label="mini remote button c" mappings=[ OFF="Off", ON="On"]
- Switch item=miniRemoteButtonD label="mini remote button d" mappings=[ OFF="Off", ON="On"]
+```perl
+Switch item=miniRemoteButtonA label="mini remote button a" mappings=[ OFF="Off", ON="On"]
+Switch item=miniRemoteButtonB label="mini remote button b" mappings=[ OFF="Off", ON="On"]
+Switch item=miniRemoteButtonC label="mini remote button c" mappings=[ OFF="Off", ON="On"]
+Switch item=miniRemoteButtonD label="mini remote button d" mappings=[ OFF="Off", ON="On"]
```
The switches in the GUI just display the mini remote's most recent button presses.
Create a contact.map file in the transforms directory as described elsewhere in this document.
Then create entries in the .items file like this:
-**Items**
+#### Items
-```
- Contact motionSensor "motion sensor [MAP(contact.map):%s]" { channel="insteon:device:home:AABBCC:contact"}
- Number motionSensorBatteryLevel "motion sensor battery level" { channel="insteon:device:home:AABBCC:batteryLevel" }
- Number motionSensorLightLevel "motion sensor light level" { channel="insteon:device:home:AABBCC:lightLevel" }
+```java
+Contact motionSensor "motion sensor [MAP(contact.map):%s]" { channel="insteon:device:home:AABBCC:contact"}
+Number motionSensorBatteryLevel "motion sensor battery level" { channel="insteon:device:home:AABBCC:batteryLevel" }
+Number motionSensorLightLevel "motion sensor light level" { channel="insteon:device:home:AABBCC:lightLevel" }
```
This will give you a contact, the battery level, and the light level.
The motion sensor II includes three additional channels:
-**Items**
-
-```
- Number motionSensorBatteryPercent "motion sensor battery percent" { channel="insteon:device:home:AABBCC:batteryPercent" }
- Contact motionSensorTamperSwitch "motion sensor tamper switch [MAP(contact.map):%s]" { channel="insteon:device:home:AABBCC:tamperSwitch"}
- Number motionSensorTemperatureLevel "motion sensor temperature level" { channel="insteon:device:home:AABBCC:temperatureLevel" }
+```java
+Number motionSensorBatteryPercent "motion sensor battery percent" { channel="insteon:device:home:AABBCC:batteryPercent" }
+Contact motionSensorTamperSwitch "motion sensor tamper switch [MAP(contact.map):%s]" { channel="insteon:device:home:AABBCC:tamperSwitch"}
+Number motionSensorTemperatureLevel "motion sensor temperature level" { channel="insteon:device:home:AABBCC:temperatureLevel" }
```
The battery, light level and temperature level are updated when either there is motion, light level above/below threshold, tamper switch activated, or the sensor battery runs low.
This can be configured with the device configuration parameter of the device.
The key in the JSON object is `heartbeatOnly` and the value is a boolean:
-**Things**
+#### Things
-```
+```java
Bridge insteon:network:home [port="/dev/ttyUSB0"] {
Thing device AABBCC [address="AA.BB.CC", productKey="F00.00.24", deviceConfig="{'heartbeatOnly': true}"]
}
The temperature can be calculated in Fahrenheit using the following formulas:
-* If the device is battery powered: `temperature = 0.73 * motionSensorTemperatureLevel - 20.53`
-* If the device is USB powered: `temperature = 0.72 * motionSensorTemperatureLevel - 24.61`
+- If the device is battery powered: `temperature = 0.73 * motionSensorTemperatureLevel - 20.53`
+- If the device is USB powered: `temperature = 0.72 * motionSensorTemperatureLevel - 24.61`
Since the motion sensor II might not be calibrated correctly, the values `20.53` and `24.61` can be adjusted as necessary to produce the correct temperature.
Link such that the modem is a responder to the motion sensor.
Create a contact.map file in the transforms directory like the following:
-```
- OPEN=open
- CLOSED=closed
- -=unknown
+```text
+OPEN=open
+CLOSED=closed
+-=unknown
```
**Items**
Then create entries in the .items file like this:
-```
- Contact doorSensor "Door sensor [MAP(contact.map):%s]" { channel="insteon:device:home:AABBCC:contact" }
- Number doorSensorBatteryLevel "Door sensor battery level [%.1f]" { channel="insteon:device:home:AABBCC:batteryLevel" }
+```java
+Contact doorSensor "Door sensor [MAP(contact.map):%s]" { channel="insteon:device:home:AABBCC:contact" }
+Number doorSensorBatteryLevel "Door sensor battery level [%.1f]" { channel="insteon:device:home:AABBCC:batteryLevel" }
```
This will give you a contact and the battery level.
**Items**
Put something like this into your .items file:
-```
- Switch doorLock "Front Door [MAP(lock.map):%s]" { channel="insteon:device:home:AABBCC:switch" }
+```java
+Switch doorLock "Front Door [MAP(lock.map):%s]" { channel="insteon:device:home:AABBCC:switch" }
```
and create a file "lock.map" in the transforms directory with these entries:
-```
- ON=Lock
- OFF=Unlock
- -=unknown
+```text
+ON=Lock
+OFF=Unlock
+-=unknown
```
### I/O Linc (garage door openers)
Add this map into your transforms directory as "contact.map":
-```
- OPEN=open
- CLOSED=closed
- -=unknown
+```text
+OPEN=open
+CLOSED=closed
+-=unknown
```
**Items**
Along with this into your .items file:
-```
- Switch garageDoorOpener "garage door opener" <garagedoor> { channel="insteon:device:home:AABBCC:switch", autoupdate="false" }
- Contact garageDoorContact "garage door contact [MAP(contact.map):%s]" { channel="insteon:device:home:AABBCC:contact" }
+```java
+Switch garageDoorOpener "garage door opener" <garagedoor> { channel="insteon:device:home:AABBCC:switch", autoupdate="false" }
+Contact garageDoorContact "garage door contact [MAP(contact.map):%s]" { channel="insteon:device:home:AABBCC:contact" }
```
**Sitemap**
To make it visible in the GUI, put this into your sitemap file:
-```
- Switch item=garageDoorOpener label="garage door opener" mappings=[ ON="OPEN/CLOSE"]
- Text item=garageDoorContact
+```perl
+Switch item=garageDoorOpener label="garage door opener" mappings=[ ON="OPEN/CLOSE"]
+Text item=garageDoorContact
```
For safety reasons, only close the garage door if you have visual contact to make sure there is no obstruction! The use of automated rules for closing garage doors is dangerous.
When e.g. the "A" button is pressed (that's button #3 internally) a broadcast message will be sent out to all responders configured to listen to Insteon group #3.
This means you must configure the modem as a responder to group #3 (and #4, #5, #6) messages coming from your keypad.
-For instructions how to do this, check out the [Insteon Terminal](https://github.com/pfrommerd/insteon-terminal.
+For instructions how to do this, check out the [Insteon Terminal](https://github.com/pfrommerd/insteon-terminal).
You can even do that with the set buttons (see instructions that come with the keypad).
While capturing the messages that the buttons emit is pretty straight forward, controlling the buttons is another matter.
Then link the buttons such that they respond to those groups, and link the modem as a controller for them (see [Insteon Terminal](https://github.com/pfrommerd/insteon-terminal) documentation.
In your items file you specify these groups with the "group=" parameters such that the binding knows what group number to put on the outgoing message.
-
#### Keypad Switches
-**Items**
+##### Items
Here is a simple example, just using the load (main) switch:
-```
- Switch keypadSwitch "main load" { channel="insteon:device:home:AABBCC:loadSwitch" }
- Number keypadSwitchManualChange "main manual change" { channel="insteon:device:home:AABBCC:loadSwitchManualChange" }
- Switch keypadSwitchFastOnOff "main fast on/off" { channel="insteon:device:home:AABBCC:loadSwitchFastOnOff" }
+```java
+Switch keypadSwitch "main load" { channel="insteon:device:home:AABBCC:loadSwitch" }
+Number keypadSwitchManualChange "main manual change" { channel="insteon:device:home:AABBCC:loadSwitchManualChange" }
+Switch keypadSwitchFastOnOff "main fast on/off" { channel="insteon:device:home:AABBCC:loadSwitchFastOnOff" }
```
Most people will not use the fast on/off features or the manual change feature, so you really only need the first line.
To make the buttons available, add the following:
-**Things**
+###### Things
-```
+```java
Bridge insteon:network:home [port="/dev/ttyUSB0"] {
Thing device AABBCC [address="AA.BB.CC", productKey="F00.00.15"] {
Channels:
The value after group must either be a number or string.
The hexadecimal value 0xf3 can either converted to a numeric value 243 or the string value "0xf3".
-**Items**
+###### Items
-```
- Switch keypadSwitchA "keypad button A" { channel="insteon:device:home:AABBCC:keypadButtonA"}
- Switch keypadSwitchB "keypad button B" { channel="insteon:device:home:AABBCC:keypadButtonB"}
- Switch keypadSwitchC "keypad button C" { channel="insteon:device:home:AABBCC:keypadButtonC"}
- Switch keypadSwitchD "keypad button D" { channel="insteon:device:home:AABBCC:keypadButtonD"}
+```java
+Switch keypadSwitchA "keypad button A" { channel="insteon:device:home:AABBCC:keypadButtonA"}
+Switch keypadSwitchB "keypad button B" { channel="insteon:device:home:AABBCC:keypadButtonB"}
+Switch keypadSwitchC "keypad button C" { channel="insteon:device:home:AABBCC:keypadButtonC"}
+Switch keypadSwitchD "keypad button D" { channel="insteon:device:home:AABBCC:keypadButtonD"}
```
-**Sitemap**
+##### Sitemap
The following sitemap will bring the items to life in the GUI:
-```
- Frame label="Keypad" {
- Switch item=keypadSwitch label="main"
- Switch item=keypadSwitchFastOnOff label="fast on/off"
- Switch item=keypadSwitchManualChange label="manual change" mappings=[ 0="DOWN", 1="STOP", 2="UP"]
- Switch item=keypadSwitchA label="button A"
- Switch item=keypadSwitchB label="button B"
- Switch item=keypadSwitchC label="button C"
- Switch item=keypadSwitchD label="button D"
- }
+```perl
+Frame label="Keypad" {
+ Switch item=keypadSwitch label="main"
+ Switch item=keypadSwitchFastOnOff label="fast on/off"
+ Switch item=keypadSwitchManualChange label="manual change" mappings=[ 0="DOWN", 1="STOP", 2="UP"]
+ Switch item=keypadSwitchA label="button A"
+ Switch item=keypadSwitchB label="button B"
+ Switch item=keypadSwitchC label="button C"
+ Switch item=keypadSwitchD label="button D"
+}
```
#### Keypad Dimmers
The keypad dimmers are like keypad switches, except that the main load is dimmable.
-**Items**
+##### Items
-```
- Dimmer keypadDimmer "dimmer" { channel="insteon:device:home:AABBCC:loadDimmer" }
- Switch keypadDimmerButtonA "keypad dimmer button A [%d %%]" { channel="insteon:device:home:AABBCC:keypadButtonA" }
+```java
+Dimmer keypadDimmer "dimmer" { channel="insteon:device:home:AABBCC:loadDimmer" }
+Switch keypadDimmerButtonA "keypad dimmer button A [%d %%]" { channel="insteon:device:home:AABBCC:keypadButtonA" }
```
-**Sitemap**
+##### Sitemap
-```
- Slider item=keypadDimmer switchSupport
- Switch item=keypadDimmerButtonA label="buttonA"
+```perl
+Slider item=keypadDimmer switchSupport
+Switch item=keypadDimmerButtonA label="buttonA"
```
### Thermostats
The thermostat (2441TH) is one of the most complex Insteon devices available.
-It must first be properly linked to the modem using configuration software like [Insteon Terminal](https://github.com/pfrommerd/insteon-terminal.
+It must first be properly linked to the modem using configuration software like [Insteon Terminal](<https://github.com/pfrommerd/insteon-terminal>.
The Insteon Terminal wiki describes in detail how to link the thermostat, and how to make it publish status update reports.
When all is set and done the modem must be configured as a controller to group 0 (not sure why), and a responder to groups 1-5 such that it picks up when the thermostat switches on/off heating and cooling etc, and it must be a responder to special group 0xEF to get status update reports when measured values (temperature) change.
The linking process is not difficult but needs some persistence.
Again, refer to the [Insteon Terminal](https://github.com/pfrommerd/insteon-terminal) documentation.
-**Items**
+#### Items
This is an example of what to put into your .items file:
-```
- Number thermostatCoolPoint "cool point [%.1f °F]" { channel="insteon:device:home:AABBCC:coolSetPoint" }
- Number thermostatHeatPoint "heat point [%.1f °F]" { channel="insteon:device:home:AABBCC:heatSetPoint" }
- Number thermostatSystemMode "system mode [%d]" { channel="insteon:device:home:AABBCC:systemMode" }
- Number thermostatFanMode "fan mode [%d]" { channel="insteon:device:home:AABBCC:fanMode" }
- Number thermostatIsHeating "is heating [%d]" { channel="insteon:device:home:AABBCC:isHeating"}
- Number thermostatIsCooling "is cooling [%d]" { channel="insteon:device:home:AABBCC:isCooling" }
- Number:Temperature thermostatTemperature "temperature [%.1f %unit%]" { channel="insteon:device:home:AABBCC:temperature" }
- Number thermostatHumidity "humidity [%.0f %%]" { channel="insteon:device:home:AABBCC:humidity" }
+```java
+Number thermostatCoolPoint "cool point [%.1f °F]" { channel="insteon:device:home:AABBCC:coolSetPoint" }
+Number thermostatHeatPoint "heat point [%.1f °F]" { channel="insteon:device:home:AABBCC:heatSetPoint" }
+Number thermostatSystemMode "system mode [%d]" { channel="insteon:device:home:AABBCC:systemMode" }
+Number thermostatFanMode "fan mode [%d]" { channel="insteon:device:home:AABBCC:fanMode" }
+Number thermostatIsHeating "is heating [%d]" { channel="insteon:device:home:AABBCC:isHeating"}
+Number thermostatIsCooling "is cooling [%d]" { channel="insteon:device:home:AABBCC:isCooling" }
+Number:Temperature thermostatTemperature "temperature [%.1f %unit%]" { channel="insteon:device:home:AABBCC:temperature" }
+Number thermostatHumidity "humidity [%.0f %%]" { channel="insteon:device:home:AABBCC:humidity" }
```
Add this as well for some more exotic features:
-```
- Number thermostatACDelay "A/C delay [%d min]" { channel="insteon:device:home:AABBCC:acDelay" }
- Number thermostatBacklight "backlight [%d sec]" { channel="insteon:device:home:AABBCC:backlightDuration" }
- Number thermostatStage1 "A/C stage 1 time [%d min]" { channel="insteon:device:home:AABBCC:stage1Duration" }
- Number thermostatHumidityHigh "humidity high [%d %%]" { channel="insteon:device:home:AABBCC:humidityHigh" }
- Number thermostatHumidityLow "humidity low [%d %%]" { channel="insteon:device:home:AABBCC:humidityLow" }
+```java
+Number thermostatACDelay "A/C delay [%d min]" { channel="insteon:device:home:AABBCC:acDelay" }
+Number thermostatBacklight "backlight [%d sec]" { channel="insteon:device:home:AABBCC:backlightDuration" }
+Number thermostatStage1 "A/C stage 1 time [%d min]" { channel="insteon:device:home:AABBCC:stage1Duration" }
+Number thermostatHumidityHigh "humidity high [%d %%]" { channel="insteon:device:home:AABBCC:humidityHigh" }
+Number thermostatHumidityLow "humidity low [%d %%]" { channel="insteon:device:home:AABBCC:humidityLow" }
```
-**Sitemap**
+#### Sitemap
For the thermostat to display in the GUI, add this to the sitemap file:
-```
- Text item=thermostatTemperature icon="temperature"
- Text item=thermostatHumidity
- Setpoint item=thermostatCoolPoint icon="temperature" minValue=63 maxValue=90 step=1
- Setpoint item=thermostatHeatPoint icon="temperature" minValue=50 maxValue=80 step=1
- Switch item=thermostatSystemMode label="system mode" mappings=[ 0="OFF", 1="HEAT", 2="COOL", 3="AUTO", 4="PROGRAM"]
- Switch item=thermostatFanMode label="fan mode" mappings=[ 0="AUTO", 1="ALWAYS ON"]
- Switch item=thermostatIsHeating label="is heating" mappings=[ 0="OFF", 1="HEATING"]
- Switch item=thermostatIsCooling label="is cooling" mappings=[ 0="OFF", 1="COOLING"]
- Setpoint item=thermostatACDelay minValue=2 maxValue=20 step=1
- Setpoint item=thermostatBacklight minValue=0 maxValue=100 step=1
- Setpoint item=thermostatHumidityHigh minValue=0 maxValue=100 step=1
- Setpoint item=thermostatHumidityLow minValue=0 maxValue=100 step=1
- Setpoint item=thermostatStage1 minValue=1 maxValue=60 step=1
+```perl
+Text item=thermostatTemperature icon="temperature"
+Text item=thermostatHumidity
+Setpoint item=thermostatCoolPoint icon="temperature" minValue=63 maxValue=90 step=1
+Setpoint item=thermostatHeatPoint icon="temperature" minValue=50 maxValue=80 step=1
+Switch item=thermostatSystemMode label="system mode" mappings=[ 0="OFF", 1="HEAT", 2="COOL", 3="AUTO", 4="PROGRAM"]
+Switch item=thermostatFanMode label="fan mode" mappings=[ 0="AUTO", 1="ALWAYS ON"]
+Switch item=thermostatIsHeating label="is heating" mappings=[ 0="OFF", 1="HEATING"]
+Switch item=thermostatIsCooling label="is cooling" mappings=[ 0="OFF", 1="COOLING"]
+Setpoint item=thermostatACDelay minValue=2 maxValue=20 step=1
+Setpoint item=thermostatBacklight minValue=0 maxValue=100 step=1
+Setpoint item=thermostatHumidityHigh minValue=0 maxValue=100 step=1
+Setpoint item=thermostatHumidityLow minValue=0 maxValue=100 step=1
+Setpoint item=thermostatStage1 minValue=1 maxValue=60 step=1
```
### Power Meters
You can also manually update the current values from the device and reset the device.
See the example below:
-**Items**
+#### Items
-```
- Number:Power iMeterWatts "iMeter [%d watts]" { channel="insteon:device:home:AABBCC:watts" }
- Number:Energy iMeterKwh "iMeter [%.04f kWh]" { channel="insteon:device:home:AABBCC:kWh" }
- Switch iMeterUpdate "iMeter Update" { channel="insteon:device:home:AABBCC:update" }
- Switch iMeterReset "iMeter Reset" { channel="insteon:device:home:AABBCC:reset" }
+```java
+Number:Power iMeterWatts "iMeter [%d watts]" { channel="insteon:device:home:AABBCC:watts" }
+Number:Energy iMeterKwh "iMeter [%.04f kWh]" { channel="insteon:device:home:AABBCC:kWh" }
+Switch iMeterUpdate "iMeter Update" { channel="insteon:device:home:AABBCC:update" }
+Switch iMeterReset "iMeter Reset" { channel="insteon:device:home:AABBCC:reset" }
```
### Fan Controllers
Here is an example configuration for a FanLinc module, which has a dimmable light and a variable speed fan:
-**Items**
+#### Items
-```
- Dimmer fanLincDimmer "fanlinc dimmer [%d %%]" { channel="insteon:device:home:AABBCC:lightDimmer" }
- Number fanLincFan "fanlinc fan" { channel="insteon:device:home:AABBCC:fan"}
+```java
+Dimmer fanLincDimmer "fanlinc dimmer [%d %%]" { channel="insteon:device:home:AABBCC:lightDimmer" }
+Number fanLincFan "fanlinc fan" { channel="insteon:device:home:AABBCC:fan"}
```
-**Sitemap**
+#### Sitemap
-```
- Slider item=fanLincDimmer switchSupport
- Switch item=fanLincFan label="fan speed" mappings=[ 0="OFF", 1="LOW", 2="MEDIUM", 3="HIGH"]
+```perl
+Slider item=fanLincDimmer switchSupport
+Switch item=fanLincFan label="fan speed" mappings=[ 0="OFF", 1="LOW", 2="MEDIUM", 3="HIGH"]
```
### X10 Devices
Be aware that most X10 switches/dimmers send no status updates, i.e. openHAB will not learn about switches that are toggled manually.
Further note that X10 devices are addressed with `houseCode.unitCode`, e.g. `A.2`.
-**Items**
+#### Items
-```
- Switch x10Switch "X10 switch" { channel="insteon:device:home:AABB:switch" }
- Dimmer x10Dimmer "X10 dimmer" { channel="insteon:device:home:AABB:dimmer" }
- Contact x10Motion "X10 motion" { channel="insteon:device:home:AABB:contact" }
+```java
+Switch x10Switch "X10 switch" { channel="insteon:device:home:AABB:switch" }
+Dimmer x10Dimmer "X10 dimmer" { channel="insteon:device:home:AABB:dimmer" }
+Contact x10Motion "X10 motion" { channel="insteon:device:home:AABB:contact" }
```
## Direct Sending of Group Broadcasts (Triggering Scenes)
The binding can command the modem to send broadcasts to a given Insteon group.
-Since it is a broadcast message, the corresponding item does *not* take the address of any device, but of the modem itself.
+Since it is a broadcast message, the corresponding item does _not_ take the address of any device, but of the modem itself.
The format is `broadcastOnOff#X` where X is the group that you want to be able to broadcast messages to:
-**Things**
+### Things
-```
+```java
Bridge insteon:network:home [port="/dev/ttyUSB0"] {
Thing device AABBCC [address="AA.BB.CC", productKey="0x000045"] {
Channels:
```
-**Items**
+### Items
-```
- Switch broadcastOnOff "group on/off" { channel="insteon:device:home:AABBCC:broadcastOnOff#2" }
+```java
+Switch broadcastOnOff "group on/off" { channel="insteon:device:home:AABBCC:broadcastOnOff#2" }
```
Flipping this switch to "ON" will cause the modem to send a broadcast message with group=2, and all devices that are configured to respond to it should react.
Channels can also be configured using the device configuration parameter of the device.
The key in the JSON object is `broadcastGroups` and the value is an array of integers:
-**Things**
+### Things (device Config)
-```
+```java
Bridge insteon:network:home [port="/dev/ttyUSB0"] {
Thing device AABBCC [address="AA.BB.CC", productKey="0x000045", deviceConfig="{'broadcastGroups': [2]}"]
}
## Channel "related" Property
When an Insteon device changes its state because it is directly operated (for example by flipping a switch manually), it sends out a broadcast message to announce the state change, and the binding (if the PLM modem is properly linked as a responder) should update the corresponding openHAB items.
-Other linked devices however may also change their state in response, but those devices will *not* send out a broadcast message, and so openHAB will not learn about their state change until the next poll.
+Other linked devices however may also change their state in response, but those devices will _not_ send out a broadcast message, and so openHAB will not learn about their state change until the next poll.
One common scenario is e.g. a switch in a 3-way configuration, with one switch controlling the load, and the other switch being linked as a controller.
In this scenario, the "related" keyword can be used to have the binding poll a related device whenever a state change occurs for another device.
A typical example would be two dimmers (A and B) in a 3-way configuration:
-```
+```java
Bridge insteon:network:home [port="/dev/ttyUSB0"] {
Thing device AABBCC [address="AA.BB.CC", productKey="F00.00.11"] {
Channels:
In this scenario, the "related" keyword can be used to have the binding poll one or more related device when group message are sent.
A typical example would be a switch configured to broadcast to a group, and one or more devices configured to respond to the message:
-```
+```java
Bridge insteon:network:home [port="/dev/ttyUSB0"] {
Thing device AABBCC [address="AA.BB.CC", productKey="0x000045"] {
Channels:
```
More than one device can be polled by separating them with "+" sign, e.g. "related=aa.bb.cc+xx.yy.zz" would poll both of these devices.
-The implemenation of the *related* keyword is simple: if you add it to a channel, and that channel changes its state, then the *related* device will be polled to see if its state has updated.
+The implemenation of the _related_ keyword is simple: if you add it to a channel, and that channel changes its state, then the _related_ device will be polled to see if its state has updated.
## Troubleshooting
Example commands to grant openHAB access (adjust for your distribution):
-````
+```shell
usermod -a -G dialout openhab
usermod -a -G lock openhab
-````
+```
Insufficient access to the lock directory will result in openHAB failing to access the device, even if the device itself is writable.
Device types are defined in the file `device_types.xml`, which is inside the Insteon bundle and thus not visible to the user.
You can however load your own device_types.xml by referencing it in the network config parameters:
- additionalDevices="/usr/local/openhab/rt/my_own_devices.xml"
+```text
+additionalDevices="/usr/local/openhab/rt/my_own_devices.xml"
+```
Where the `my_own_devices.xml` file defines a new device like this:
</xml>
```
-Finding the Insteon product key can be tricky since Insteon has not updated the product key table (https://www.insteon.com/pdf/insteon_devcats_and_product_keys_20081008.pdf) since 2008.
+Finding the Insteon product key can be tricky since Insteon has not updated the product key table (<https://www.insteon.com/pdf/insteon_devcats_and_product_keys_20081008.pdf>) since 2008.
If a web search does not turn up the product key, make one up, starting with "F", like: F00.00.99.
Avoid duplicate keys by finding the highest fake product key in the `device_types.xml` file, and incrementing by one.
If you can't build a new device out of the existing device features (for a complete list see `device_features.xml`) you can add new features by specifying a file (let's call it `my_own_features.xml`) with the "additionalDevices" option in the network config parameters:
- additionalFeatures="/usr/local/openhab/rt/my_own_features.xml"
+```text
+additionalFeatures="/usr/local/openhab/rt/my_own_features.xml"
+```
- In this file you can define your own features (or even overwrite an existing feature.
+In this file you can define your own features (or even overwrite an existing feature.
In the example below a new feature "MyFeature" is defined, which can then be referenced from the `device_types.xml` file (or from `my_own_devices.xml`):
```xml
## Known Limitations and Issues
-* Devices cannot be linked to the modem while the binding is running.
+- Devices cannot be linked to the modem while the binding is running.
If new devices are linked, the binding must be restarted.
-* Setting up Insteon groups and linking devices cannot be done from within openHAB.
+- Setting up Insteon groups and linking devices cannot be done from within openHAB.
Use the [Insteon Terminal](https://github.com/pfrommerd/insteon-terminal) for that.
If using Insteon Terminal (especially as root), ensure any stale lock files (For example, /var/lock/LCK..ttyUSB0) are removed before starting openHAB runtime.
Failure to do so may result in "found no ports".
-* The Insteon PLM or hub is know to break in about 2-3 years due to poorly sized capacitors.
+- The Insteon PLM or hub is know to break in about 2-3 years due to poorly sized capacitors.
You can repair it yourself using basic soldering skills, search for "Insteon PLM repair" or "Insteon hub repair".
-* Using the Insteon Hub 2014 in conjunction with other applications (such as the InsteonApp) is not supported. Concretely, openHAB will not learn when a switch is flipped via the Insteon App until the next poll, which could take minutes.
+- Using the Insteon Hub 2014 in conjunction with other applications (such as the InsteonApp) is not supported. Concretely, openHAB will not learn when a switch is flipped via the Insteon App until the next poll, which could take minutes.
This binding connects to WiFi [IntesisHome](https://www.intesis.com/products/cloud-solutions/ac-cloud-control) devices using their local REST Api and to [IntesisBox](https://www.intesis.com/products/ac-interfaces/wifi-gateways) devices using TCP connection.
-
-
## Supported Things
This binding only supports one thing type:
| password | IntesisHome | Password to login to the local webserver of IntesisHome device |
| port | IntesisBox | TCP port to connect to IntesisBox device, defaults to 3310 |
-
## Channels
| Channel ID | Item Type | Description | Possible Values |
The binding can be fully setup from the UI but if you decide to use files here is a full example:
-**Things**
+### Things
-```
+```java
Thing intesis:intesisHome:acOffice "AC Unit Adapter" @ "AC" [ipAddress="192.168.1.100", password="xxxxx"]
Thing intesis:intesisBox:acOffice "AC Unit Adapter" @ "AC" [ipAddress="192.168.1.100", port=3310]
```
-**Items**
+### Items
-```intesishome.items
+```java
Switch ac "Power" { channel="intesis:intesisHome:acOffice:power" }
String acMode "Mode" { channel="intesis:intesisHome:acOffice:mode" }
String acFanSpeed "Fan Speed" <fan> { channel="intesis:intesisHome:acOffice:fanSpeed" }
String acWifiSignal "Wifi Signal Quality" <qualityofservice> { channel="intesis:intesisBox:acOffice:wifiSignal" }
```
-**Sitemap**
+### Sitemap
-```intesisHome.sitemap
+```perl
sitemap intesishome label="My AC control" {
Frame label="Climate" {
## How to Get Help
-+ Check this readme for any setup steps for your brand.
-+ Check if the camera is offline, if so there will be a reason listed.
-+ Always look at the log files with TRACE enabled, as any FFmpeg and camera errors may not reach the INFO logs.
+- Check this readme for any setup steps for your brand.
+- Check if the camera is offline, if so there will be a reason listed.
+- Always look at the log files with TRACE enabled, as any FFmpeg and camera errors may not reach the INFO logs.
To enable TRACE logging, enter this in the openHAB console `log:set TRACE org.openhab.binding.ipcamera`.
-+ Search the forum using any log messages to find how others have already solved it.
-+ Only after doing the above ask for help in the forum and create a new thread.
+- Search the forum using any log messages to find how others have already solved it.
+- Only after doing the above ask for help in the forum and create a new thread.
## Special Notes for Different Brands
Example:
-```
+```java
Thing ipcamera:generic:Esp32Cam
[
ipAddress="192.168.1.181",
It is better to always setup your Amcrest camera as a `dahua` thing type.
The old alarm polling based method is used if you setup as `amcrest`, and the newer/better event based method is used if you setup as `dahua` instead.
-All other features should be the same between the two.
+All other features should be the same between the two.
### Dahua
### Foscam
-* If the user/pass is wrong, the camera can lockout and refuse to answer the binding requiring a reboot of the camera, so be sure the details are correct before the camera tries to poll the camera too many times.
-* To use MJPEG streaming, you need to enable one of the streams to use this format. This can be done by entering this into any browser:`http://ip:88/cgi-bin/CGIProxy.fcgi?cmd=setSubStreamFormat&format=1&usr=admin&pwd=password`
-* If your camera does not support MJPEG as some Foscams no longer do, then you can set `mjpegUrl` to contain *ffmpeg* to use your CPU to generate a MJPEG stream.
-* Some Foscam cameras need to have a detection area listed in the URL when you enable the motion alarm.
+- If the user/pass is wrong, the camera can lockout and refuse to answer the binding requiring a reboot of the camera, so be sure the details are correct before the camera tries to poll the camera too many times.
+- To use MJPEG streaming, you need to enable one of the streams to use this format. This can be done by entering this into any browser:`http://ip:88/cgi-bin/CGIProxy.fcgi?cmd=setSubStreamFormat&format=1&usr=admin&pwd=password`
+- If your camera does not support MJPEG as some Foscams no longer do, then you can set `mjpegUrl` to contain _ffmpeg_ to use your CPU to generate a MJPEG stream.
+- Some Foscam cameras need to have a detection area listed in the URL when you enable the motion alarm.
-As each Foscam model has a different resolution and two different URLs, this makes it difficult to automate, so an override feature was added to create your own "enable the alarm" URL.
+As each Foscam model has a different resolution and two different URLs, this makes it difficult to automate, so an override feature was added to create your own "enable the alarm" URL.
This setting is called `customMotionAlarmUrl` and the steps to using it are:
1. Enable the motion alarm in the web interface of your camera and setup any areas you wish movement to be ignored in. E.g. tree branches moving in the wind.
-2. Use any web browser to fetch this URL `https://x.x.x.x/cgi-bin/CGIProxy.fcgi?cmd=getMotionDetectConfig1&usr=xxxxx&pwd=xxxxx`
-3. Use the information returned by the above URL to create the override settings.
+1. Use any web browser to fetch this URL `https://x.x.x.x/cgi-bin/CGIProxy.fcgi?cmd=getMotionDetectConfig1&usr=xxxxx&pwd=xxxxx`
+1. Use the information returned by the above URL to create the override settings.
An example for a Foscam C2 is...
-```
+```text
/cgi-bin/CGIProxy.fcgi?cmd=setMotionDetectConfig1&isEnable=1&snapInterval=1&schedule0=281474976710655&schedule1=281474976710655&schedule2=281474976710655&schedule3=281474976710655&schedule4=281474976710655&schedule5=281474976710655&schedule6=281474976710655&x1=0&y1=0&width1=10000&height1=10000&sensitivity1=1&valid1=1&linkage=6&usr=xxxxx&pwd=xxxxx
```
Another example is:
-```
+```text
/cgi-bin/CGIProxy.fcgi?cmd=setMotionDetectConfig&isEnable=1&linkage=0001&sensitivity=1&triggerInterval=15&schedule0=281474976710655&schedule1=281474976710655&schedule2=281474976710655&schedule3=281474976710655&schedule4=281474976710655&schedule5=281474976710655&schedule6=281474976710655&area0=1023&area1=1023&area2=1023&area3=1023&area4=1023&area5=1023&area6=1023&area7=1023&area7=1023&area8=1023&area9=1023&usr=username&pwd=password
```
### Hikvision
-+ For MJPEG to work, you need to set the first sub-stream to be in MJPEG format, otherwise you can override the default with the `mjpegUrl` config with a valid URL for MJPEG streams.
-+ The CGI/API and also ONVIF features are disabled by default on these cameras, so enable and create user details for ONVIF that are the same user/pass as what you have given the binding.
+- For MJPEG to work, you need to set the first sub-stream to be in MJPEG format, otherwise you can override the default with the `mjpegUrl` config with a valid URL for MJPEG streams.
+- The CGI/API and also ONVIF features are disabled by default on these cameras, so enable and create user details for ONVIF that are the same user/pass as what you have given the binding.
If your camera does not have PTZ (Pan Tilt Zoom) then you can leave ONVIF disabled and just enable the CGI/API.
-+ Each alarm you wish to use must have `Notify Surveillance Center` enabled under each alarms settings in the control panel of the camera itself.
+- Each alarm you wish to use must have `Notify Surveillance Center` enabled under each alarms settings in the control panel of the camera itself.
### Hikvision NVRs
In case your Hikvision NVR does not communicate with the binding, make sure that:
-* ISAPI is enabled in the NVR settings.
-* ONVIF is enabled and a user/pass created that match the bindings.
-* RTSP is enabled.
-* Some NVR's allow each camera to be exposed on a set port to give direct access to each camera, some users report this works the best and needs to be enabled.
+- ISAPI is enabled in the NVR settings.
+- ONVIF is enabled and a user/pass created that match the bindings.
+- RTSP is enabled.
+- Some NVR's allow each camera to be exposed on a set port to give direct access to each camera, some users report this works the best and needs to be enabled.
-Some older versions of these NVRs require setting a different snapshot URL (`snapshotUrl`), as well as `ffmpegInput`.
+Some older versions of these NVRs require setting a different snapshot URL (`snapshotUrl`), as well as `ffmpegInput`.
The older ones use the same URLs just with 'ISAPI' removed.
```java
### Instar
-+ For MJPEG to work, you need to set the first sub-stream to be MJPEG format for the default settings to work, otherwise you can override the default with mjpegUrl with a valid URL for MJPEG streams.
-+ Be sure to update to the latest firmware for your camera as Instar have made a lot of improvements recently, including adding MQTT features (MQTT is not needed for this binding to work).
+- For MJPEG to work, you need to set the first sub-stream to be MJPEG format for the default settings to work, otherwise you can override the default with mjpegUrl with a valid URL for MJPEG streams.
+- Be sure to update to the latest firmware for your camera as Instar have made a lot of improvements recently, including adding MQTT features (MQTT is not needed for this binding to work).
## Discovery
-The discovery feature of openHAB can be used to find and setup any ONVIF cameras.
+The discovery feature of openHAB can be used to find and setup any ONVIF cameras.
This method should be preferred as it will discover the cameras IP, ports and URLs for you, making the setup much easier.
The binding needs to use UDP port 3702 to discover the cameras with, so this port needs to be unblocked by your firewall or add the camera manually if the camera is not auto found.
To use the discovery, just press the `+` icon located in the Inbox, then select the IpCamera binding from the list of installed bindings.
NOTE: Leave any `user:pass@` out of any URLs, the binding will handle this for you.
Not only does this hide your login details, it will also make changing your password much easier if it is only located in 1 field.
-Below is a list of all configuration parameters (useful for textual config) with a short description.
+Below is a list of all configuration parameters (useful for textual config) with a short description.
If you do not specify any of these, the binding will use the default which should work in most cases and should be tried first.
| Parameter | Description |
## Channels
-Each camera brand will have different channels depending on how much of the support for an API has been added.
+Each camera brand will have different channels depending on how much of the support for an API has been added.
The channels are kept consistent as much as possible from brand to brand to make upgrading to a different camera easier.
| Channel | Type | Description |
To move a camera with this binding you need an ONVIF camera that supports one of the following:
-+ Absolute movements
-+ Relative movements
-+ Continuous movements
-+ Presets
+- Absolute movements
+- Relative movements
+- Continuous movements
+- Presets
To test your cameras compatibility and also to create some preset locations, use a free program called `ONVIF Device Manager` (ODM for short).
Not all ONVIF cameras work with all of the methods, so testing first to confirm what works is a good idea and the presets can not be created with the binding, only loaded after they are already created in a program like ODM.
-After creating new or changing existing presets, it is necessary to send the REFRESH command to the `gotoPreset` channel or you can restart the binding if that is easier.
+After creating new or changing existing presets, it is necessary to send the REFRESH command to the `gotoPreset` channel or you can restart the binding if that is easier.
You can create names using the mappings feature of the selection element.
See docs here <https://www.openhab.org/docs/configuration/sitemaps.html#mappings>
-Moving the camera using *Relative* or *Continuous* (config `ptzContinuous` must be true) movements can be done by sending the INCREASE and DECREASE commands to the Pan, Tilt and Zoom channels.
+Moving the camera using _Relative_ or _Continuous_ (config `ptzContinuous` must be true) movements can be done by sending the INCREASE and DECREASE commands to the Pan, Tilt and Zoom channels.
The OFF command (to any of the PTZ channels) will stop the cameras movements in the case of continuous being selected.
-When the config is set to false (the default if not specified) the binding will send relative movements.
+When the config is set to false (the default if not specified) the binding will send relative movements.
There are some widgets created in the HABpanel widget gallery that you can download and use right away saving you time if your camera supports either presets, relative or continuous modes.
For sitemaps, the below examples can be used.
-
item:
```java
To get this working:
-+ Provide a URL to the bindings config `alarmInputUrl` or leave it blank to use the auto detected URL if your camera has ONVIF.
-+ Install FFmpeg.
-+ You have the resolution and FPS at realistic settings for your CPU. You need to reach 1.x speed otherwise the alarm will lag further behind realtime the longer you have this running.
+- Provide a URL to the bindings config `alarmInputUrl` or leave it blank to use the auto detected URL if your camera has ONVIF.
+- Install FFmpeg.
+- You have the resolution and FPS at realistic settings for your CPU. You need to reach 1.x speed otherwise the alarm will lag further behind realtime the longer you have this running.
1080p and 10 fps maximum for an ARM processor is probably a good place to start testing or even lower if you can.
-+ Set the `ffmpegMotionControl` channel to 16 with a slider control and if the alarm stays on increase the value until it works as desired.
+- Set the `ffmpegMotionControl` channel to 16 with a slider control and if the alarm stays on increase the value until it works as desired.
If it will not trigger, lower the control until it does.
-+ Set the `ffmpegMotionControl` to OFF or 0 and it stops using your CPU.
+- Set the `ffmpegMotionControl` to OFF or 0 and it stops using your CPU.
You can link this same channel to BOTH a switch and a slider at the same time if you like to have both types of controls.
-+ The output of the alarm will go to a channel called `ffmpegMotionAlarm` and you can use the `lastMotionType` channel to determine which alarm was last tripped if your camera has multiple alarm types.
+- The output of the alarm will go to a channel called `ffmpegMotionAlarm` and you can use the `lastMotionType` channel to determine which alarm was last tripped if your camera has multiple alarm types.
-**audioAlarm**
+### audioAlarm
-This works in the same way, just with different channels.
+This works in the same way, just with different channels.
If you setup a lower resolution URL in the config `alarmInputUrl` you need to ensure it contains audio otherwise this feature wont work.
A value of 10 on a slider translates to -10dB below max volume (digital full scale) and when the audio goes above the -10dB threshold the alarm will turn ON.
**Ways to use snapshots are:**
-+ Use the cameras URL so it passes from the camera directly to your end device. ie a tablet.
+- Use the cameras URL so it passes from the camera directly to your end device. ie a tablet.
This is always the best option if it works.
-+ Request a snapshot with the URL `http://openhabIP:8080/ipcamera/{cameraUID}/ipcamera.jpg`.
-The IP is for your openHAB server not the camera.
+- Request a snapshot with the URL `http://openhabIP:8080/ipcamera/{cameraUID}/ipcamera.jpg`.
+The IP is for your openHAB server not the camera.
If you find the snapshot is old, you can set the `gifPreroll` to a number above 0 and this forces the camera to keep updating the stored JPG in RAM.
The ipcamera.jpg can also be cast, as most cameras can not directly cast their snapshots.
-+ Use the `http://openHAB:8080/ipcamera/{cameraUID}/snapshots.mjpeg` to request a stream of snapshots to be delivered in MJPEG format.
-+ Use the record GIF action and use a `gifPreroll` value > 0.
-This creates a number of snapshots in the FFmpeg output folder called snapshotXXX.jpg where XXX starts at 0 and increases each `pollTime`.
-This allows you to get a snapshot from an exact amount of time before, on, or after starting the record to GIF action.
+- Use the `http://openHAB:8080/ipcamera/{cameraUID}/snapshots.mjpeg` to request a stream of snapshots to be delivered in MJPEG format.
+- Use the record GIF action and use a `gifPreroll` value > 0.
+This creates a number of snapshots in the FFmpeg output folder called snapshotXXX.jpg where XXX starts at 0 and increases each `pollTime`.
+This allows you to get a snapshot from an exact amount of time before, on, or after starting the record to GIF action.
Handy for cameras which lag due to slow processors, or if you do not want a hand blocking the image when the door bell was pushed.
-These snapshots can be fetched either directly as they exist on disk, or via this URL format.
+These snapshots can be fetched either directly as they exist on disk, or via this URL format.
`http://openHAB:8080/ipcamera/{cameraUID}/snapshot0.jpg`
-+ Also worth a mention is that you can off load cameras to a software package running on a separate server such as, Motion, Shinobi and Zoneminder.
+- Also worth a mention is that you can off load cameras to a software package running on a separate server such as, Motion, Shinobi and Zoneminder.
See this forum thread for examples of how to use snapshots and streams in a sitemap.
<https://community.openhab.org/t/ip-camera-how-to-clickable-thumbnail-overview-in-sitemaps-that-opens-up-to-a-larger-view/77990>
To get video streams working, this forum thread has working widget examples that you can use.
<https://community.openhab.org/t/oh3-widget-building-a-camera-widget/110069>
-To get some of the video formats working, you need to install FFmpeg.
+To get some of the video formats working, you need to install FFmpeg.
Visit their site here to learn how <https://ffmpeg.org/>
Under Linux, FFmpeg can be installed very easily with this one command.
-```
+```shell
sudo apt update && sudo apt install ffmpeg
```
**IMPORTANT:**
-The binding has its own file server that works by allowing access to the snapshot and video streams with no user/password for requests that come from an IP located in the `ipWhitelist`.
-Requests from external IPs or internal requests that are not on the `ipWhitelist` will fail to get any answer.
+The binding has its own file server that works by allowing access to the snapshot and video streams with no user/password for requests that come from an IP located in the `ipWhitelist`.
+Requests from external IPs or internal requests that are not on the `ipWhitelist` will fail to get any answer.
If you prefer to use your own firewall instead, you can also choose to make the `ipWhitelist` equal "DISABLE" and then all internal IPs will have access.
There are multiple ways to get a moving picture, to use them just enter the URL into any browser using `http://openHAB:8080/ipcamera/{cameraUID}/name.format` replacing the name.format with one of the options that are listed below:
-+ **ipcamera.m3u8** HLS (HTTP Live Streaming) which uses H.264 compression.
+- **ipcamera.m3u8** HLS (HTTP Live Streaming) which uses H.264 compression.
This can be used to cast to Chromecast devices, or can display video in many browsers (some browsers require a plugin to be installed).
Please understand that this format due to the way it works will give you lag behind real time, more on this below.
-+ **ipcamera.mjpeg** whilst needing more bandwidth, it is far more compatible for displaying in a wider range of UIs and browsers.
+- **ipcamera.mjpeg** whilst needing more bandwidth, it is far more compatible for displaying in a wider range of UIs and browsers.
It is normally 1 second or less behind real-time.
-FFmpeg can be used to create this stream if your camera does not create one for you, but this uses more CPU.
+FFmpeg can be used to create this stream if your camera does not create one for you, but this uses more CPU.
A lot of cameras limit the resolution in this format, so consider using HLS, autofps.mjpeg, or snapshots.mjpeg instead which will be in a higher resolution.
-+ **snapshots.mjpeg** is a special MJPEG stream created from the cameras snapshots that are taken at the polling rate.
-+ **autofps.mjpeg** This requires a camera that has a motion alarm to be turned on or it will only send a picture every 8 seconds.
+- **snapshots.mjpeg** is a special MJPEG stream created from the cameras snapshots that are taken at the polling rate.
+- **autofps.mjpeg** This requires a camera that has a motion alarm to be turned on or it will only send a picture every 8 seconds.
You can also use the `externalMotion` channel to change the framerate.
This feature is designed to keep data traffic to your mobile devices as low as possible by automatically sending 1fps when motion is occurring, but only 1 picture every 8 seconds when the picture has no motion.
The idea is to not send lots of pictures if the picture has not changed as doing so only eats up your data plan.
-+ **ipcamera.gif** This is small in size and very compatible and handy to use in push notifications, Pushover, Telegram, or emails.
-You can cast it which can be handy to show a moving picture that keeps repeating on a Google/Nest home hub or your wall mounted tablet.
-+ MP4 recordings can be created by the binding and FFmpeg, more on this below.
+- **ipcamera.gif** This is small in size and very compatible and handy to use in push notifications, Pushover, Telegram, or emails.
+You can cast it which can be handy to show a moving picture that keeps repeating on a Google/Nest home hub or your wall mounted tablet.
+- MP4 recordings can be created by the binding and FFmpeg, more on this below.
## MJPEG Streams
<http://openHAB:8080/ipcamera/{cameraUID}/ipcamera.mjpeg>
-**Creating MJPEG with FFmpeg**
+### Creating MJPEG with FFmpeg
To use this feature, all you need to do is set the config `mjpegUrl` to contain "ffmpeg" to use your CPU to generate the MJPEG stream with FFmpeg.
For cameras that have an API you can opt to not use the cameras stream and use FFmpeg instead should you run out of available streams.
FFmpeg may require you to lower the resolution and/or the FPS to lower the CPU load down enough to run, you may need to experiment.
To change the settings used by this feature the binding exposes the config `mjpegOptions` which the default is currently `-q:v 5 -r 2 -vf scale=640:-2 -update 1` where 5 is the JPG quality/compression setting, and -r 2 is how many frames per second to try and create.
-In this case it will create 2 frames every second.
+In this case it will create 2 frames every second.
`-vf scale=640:-2` will lower the resolution down to make the video 640 pixels wide.
You can remove this to use the same resolution as the camera is set to use, however it may become a trade off and you may get less frames per second if you raise the resolution.
Always try to get the default settings working first before you begin to experiment and if your stream is above 1080p and 10 frames per second, consider lowering it if you have issues on an ARM based server like a Raspberry PIx.
-
+
## snapshots.mjpeg and autofps.mjpeg
These similar features allow you to request a MJPEG stream created by the binding with low CPU usage from the cameras snapshots.
The reason this is more useful than snapshots on their own, is some UIs will flash white or black when a snapshot is refreshing, this does not happen with snapshots.mjpeg and is the same bandwidth and CPU load as just using snapshots!
The autofps.mjpeg feature will display a snapshot that updates every 8 seconds to keep network traffic low, then when motion is detected it will automatically increase the frames to every second until the motion stops.
-This means lower traffic unless the picture is actually changing.
+This means lower traffic unless the picture is actually changing.
-Request the stream to be sent to an item with this URL.
+Request the stream to be sent to an item with this URL.
NOTE: The IP is openHAB's not your cameras IP.
`http://openHAB:8080/ipcamera/{cameraUID}/snapshots.mjpeg`
Use the following to display it in your sitemap.
-```
+```java
Video url="http://openHAB:8080/ipcamera/{cameraUID}/autofps.mjpeg" encoding="mjpeg"
Video url="http://openHAB:8080/ipcamera/{cameraUID}/snapshots.mjpeg" encoding="mjpeg"
## HLS (HTTP Live Streaming)
HLS is a way of splitting the live stream up into small H.264 based files so it can be played in many browsers (some require addons to be installed) without using much CPU power as cameras generally are already in H.264 and this does not transcode the data.
-Because the files need to be created, this creates a lag/delay behind real time that can be reduced (more on that below).
+Because the files need to be created, this creates a lag/delay behind real time that can be reduced (more on that below).
-The channel called 'startStream' can be used to create HLS files non stop and will remove the startup delay that comes with using this type of stream.
+The channel called 'startStream' can be used to create HLS files non stop and will remove the startup delay that comes with using this type of stream.
The startup delay and the lag are two different things, with the startup delay easily solved by turning this channel ON.
If the channel is OFF, the stream will start and stop automatically as required and the channel will reflect its current status.
With a fast openHAB server it should only need to be requested once, but on slower ARM systems it takes a while for FFmpeg to get up and running at full speed.
To use the HLS feature, you need to:
-+ Ensure FFmpeg is installed.
-+ For `generic` cameras, you will need to use the config `ffmpegInput` to provide a HTTP or RTSP URL.
-+ Consider using a SSD/HDD, zram location, or a tmpfs (ram drive) can be used if you only have micro SD/flash based storage.
+- Ensure FFmpeg is installed.
+- For `generic` cameras, you will need to use the config `ffmpegInput` to provide a HTTP or RTSP URL.
+- Consider using a SSD/HDD, zram location, or a tmpfs (ram drive) can be used if you only have micro SD/flash based storage.
### Ram Drive Setup
-To create a tmpfs of 20mb at /tmpfs/ run this command to open the file for editing.
+To create a tmpfs of 20mb at /tmpfs/ run this command to open the file for editing.
Recommend using 20Mb per camera that uses this location although it could use less than half that amount if carefully streamlined for less ram.
-If using the FFmpeg `-hls_wrap wrap` option (causes issues for my Home Hub), you can get away with 5Mb per camera.
+If using the FFmpeg `-hls_wrap wrap` option (causes issues for my Home Hub), you can get away with 5Mb per camera.
-```
+```shell
nano /etc/fstab
```
Enter and save this at the bottom of the file using ctrl X when done.
-```
+```shell
tmpfs /tmpfs tmpfs defaults,nosuid,nodev,noatime,size=20m 0 0
```
Less delay behind realtime (no audio) if your cameras iFrames are 1 second apart (-hls_time 1):
-```bash
+```shell
-strict -2 -f lavfi -i aevalsrc=0 -acodec aac -vcodec copy -hls_flags delete_segments -hls_time 1 -hls_list_size 4
```
For cameras with no audio in the stream (default setting).
-```bash
+```shell
-strict -2 -f lavfi -i aevalsrc=0 -acodec aac -vcodec copy -hls_flags delete_segments -hls_time 2 -hls_list_size 4
```
For cameras with audio in the stream.
Note: will break Chromecast if the camera does not send audio which is why this is not the default.
-```bash
+```shell
-strict -2 -acodec aac -vcodec copy -hls_flags delete_segments -hls_time 2 -hls_list_size 4
```
Some browsers require larger segment sizes to prevent choppy playback, this can be done with this setting to create 10 second segment files which increases the time before you can get playback working.
-```bash
+```shell
-strict -2 -f lavfi -i aevalsrc=0 -acodec aac -vcodec copy -hls_flags delete_segments -hls_time 10 -hls_list_size 4
```
The webview version allows you to zoom in on the video when using the iOS app, the Video element version does not zoom, but it will pass through myopenHAB.
-```
-
+```java
Text label="HLS Video Stream" icon="camera"{Video url="http://openHAB:8080/ipcamera/{cameraUID}/ipcamera.m3u8" encoding="hls"}
Text label="HLS Webview Stream" icon="camera"{Webview url="http://openHAB:8080/ipcamera/{cameraUID}/ipcamera.m3u8" height=15}
-
```
-**Display multiple HLS streams side by side**
+#### Display multiple HLS streams side by side
In order to display camera hls streams side by side you can also create a webView item and link it to a HTML file in the conf/html directory as follows:
The webView URL is that of your openHAB installation.
-```
+```java
Webview url="http://192.168.6.4:8080/static/html/file.html" height=5
-
```
```html
There are two ways to cast a camera.
1. openHAB Cloud Connector and using metadata/tags.
-2. Chromecast Bindings `playuri` channel.
+1. Chromecast Bindings `playuri` channel.
The first method once setup allows you to ask "OK Google show X camera", or "OK Google show X camera on Y display".
By optionally naming the display that you wish to use, it can be cast directly to your Chromecast (connected to your TV) by speaking to a Google Nest Mini.
This must use the HLS format and use the metadata tag shown below with the openHAB Cloud Connector setup.
-Don't forget to ask Google to 'sync my devices' after adding the metadata.
+Don't forget to ask Google to 'sync my devices' after adding the metadata.
The synonyms in the tag allows Google to understand multiple names that the camera may be called by different people in your family.
Example of how this is done in an items file.
-```
+```java
String FrontDoorCamHlsUrl "Front Door" { channel="ipcamera:ONVIF:FrontDoor:hlsUrl", synonyms="door bell, front camera", ga="Camera" [ protocols="hls" ] }
-
```
The second method is by using the Chromecast Binding and by sending the URL you wish to cast to the `playuri` channel.
items
-```
+```java
String KitchenHomeHubPlayURI { channel="chromecast:chromecast:KitchenHomeHub:playuri" }
-
```
In a rule...
-```
+```java
KitchenHomeHubPlayURI.sendCommand("http://openHAB:8080/ipcamera/{cameraUID}/ipcamera.m3u8")
-
```
## MP4 and GIF Recordings
The steps to do this are:
-+ Use the Action called `recordMP4(String filename, int secondsToRecord)` or `recordGIF(String filename, int secondsToRecord)` with the first argument being the filename you wish to use, and the second the time in seconds you wish to record for.
-+ Once the file is created, the channel `recordingMp4` or `recordingGif` will change itself back to `0`, which can be used to trigger a rule to send/use the file which will appear in the `ffmpegOutput` folder.
-+ The channel `mp4History` or `gifHistory` keeps a string of the last 50 filenames (comma separated values CSV) until you reset the history. If you use `ipcamera` as the filename, this stops the history from growing.
-+ The channel `mp4HistoryLength` and `gifHistoryLength` keeps track of how many recordings were made since it was last reset.
+- Use the Action called `recordMP4(String filename, int secondsToRecord)` or `recordGIF(String filename, int secondsToRecord)` with the first argument being the filename you wish to use, and the second the time in seconds you wish to record for.
+- Once the file is created, the channel `recordingMp4` or `recordingGif` will change itself back to `0`, which can be used to trigger a rule to send/use the file which will appear in the `ffmpegOutput` folder.
+- The channel `mp4History` or `gifHistory` keeps a string of the last 50 filenames (comma separated values CSV) until you reset the history. If you use `ipcamera` as the filename, this stops the history from growing.
+- The channel `mp4HistoryLength` and `gifHistoryLength` keeps track of how many recordings were made since it was last reset.
You can send the `0` command to this channel to clear the `mp4History` at the same time as setting this channel back to 0.
-+ You can use the `mp4OutOptions` or `gifOutOptions` config's to apply any FFmpeg filters that you wish.
+- You can use the `mp4OutOptions` or `gifOutOptions` config's to apply any FFmpeg filters that you wish.
There is also a HABpanel Widget worth checking out that uses the history feature to display a list of recent recordings.
<https://community.openhab.org/t/custom-widget-camera-history-and-live-popup/103082>
**NOTE:** If you are using a tmpfs folder, you will need to ensure you do not run out of space by moving the files with a rule.
-**GIF Preroll**
+### GIF Preroll
There is also a config called `gifPreroll` to be aware of.
When `gifPreroll` is 0 (the default) the binding will use the `ffmpegInput` stream to record from.
Some additional checks to get it working are:
-+ If using the groups HLS feature, the poll time of the group must be the same or less than the total time contained in each cameras m3u8 file.
+- If using the groups HLS feature, the poll time of the group must be the same or less than the total time contained in each cameras m3u8 file.
If you have 3 seconds worth of video segments in each cameras HLS stream, this is the max you can set the poll time of the group to.
-+ All cameras in a group should have the same HLS segment size setting, 1 and 2 second long segments have been tested to work.
-+ Mixing cameras with different aspect ratios may cause issues when cast.
-+ The HLS files need to remain on disk for the number of cameras X pollTime, use the `-hls_delete_threshold` ffmpeg option to control this.
+- All cameras in a group should have the same HLS segment size setting, 1 and 2 second long segments have been tested to work.
+- Mixing cameras with different aspect ratios may cause issues when cast.
+- The HLS files need to remain on disk for the number of cameras X pollTime, use the `-hls_delete_threshold` ffmpeg option to control this.
## Sitemap Example
This binding works fully offline and can work via one of two methods:
1. Local scraping of the weather station's `livedata` webpage at 12 second resolution (non WiFi models only).
-2. Both WiFi and RJ45 models can be setup to push the data directly to the openHAB (default 8080) server directly and the binding can parse the data from the weather underground data.
+1. Both WiFi and RJ45 models can be setup to push the data directly to the openHAB (default 8080) server directly and the binding can parse the data from the weather underground data.
The other binding worth mentioning is the weather underground binding that allows the data to be intercepted on its way to WU, however many of the weather stations do not allow the redirection of the WU data and require you to know how to do redirections with a custom DNS server on your network.
This binding with method 1 and a RJ45 model is by far the easiest method and works for all the brands and will not stop the data still being sent to WU if you wish to do both at the same time.
# iRobot Binding
-This binding provides integration of products by iRobot company (https://www.irobot.com/). It is currently developed
+This binding provides integration of products by iRobot company (<https://www.irobot.com/>). It is currently developed
to support Roomba vacuum cleaner/mopping robots with built-in Wi-Fi module. The binding interfaces to the robot directly
without any need for a dedicated MQTT server.
## Supported Things
-- iRobot Roomba robotic vacuum cleaner (https://www.irobot.com/roomba).
+- iRobot Roomba robotic vacuum cleaner (<https://www.irobot.com/roomba>).
- iRobot Braava has also been reported to (partially) work.
- In general, the channel list is far from complete. There is a lot to do now.
After you've done this procedure you can write the password somewhere in case if you need to reconfigure your binding. It's
not known, however, whether the password is eternal or can change during factory reset.
If you have issues getting the password make sure there are no other devices like your smartphone communicating with the robot.
-You can also try using [these python scripts](https://github.com/NickWaterton/Roomba980-Python) to get the password.
+You can also try using [these python scripts](https://github.com/NickWaterton/Roomba980-Python) to get the password.
## Thing Configuration
You can clean one or many specific regions of a given map by sending the following String to the command channel:
-```
-
cleanRegions:<pmapId>;[r=]<region_id1>,[r=]<region_id2>,z=<zone_id1>,...;[<user_pmapv_id>]
+```text
+cleanRegions:<pmapId>;[r=]<region_id1>,[r=]<region_id2>,z=<zone_id1>,...;[<user_pmapv_id>]
```
Some devices support cleaning rooms (aka regions). Additionally, support for cleaning rectangle areas previously defined in the iRobot-App (aka zones) may be available.
## Known Problems / Caveats
1. Sending "pause" command during missions other than "clean" is equivalent to sending "stop"
-2. Switching to "spot" mission is possible only in "stop" state. Attempt to do it otherwise causes error: the command is rejected and error tones are played.
-3. Roomba's built-in MQTT server, used for communication, supports only a single local connection at a time. Bear this in mind when you want to do something that requires local connection from your phone, like reconfiguring the network. Disable openHAB Thing before doing this.
-4. Sometimes during intensive testing Roomba just stopped communicating over the local connection. If this happens, try rebooting it. On my robot it's done by holding "Clean" button for about 10 seconds until all the LEDs come on. Release the button and the reboot tone will be played. It looks like there are some bugs in the firmware.
-
+1. Switching to "spot" mission is possible only in "stop" state. Attempt to do it otherwise causes error: the command is rejected and error tones are played.
+1. Roomba's built-in MQTT server, used for communication, supports only a single local connection at a time. Bear this in mind when you want to do something that requires local connection from your phone, like reconfiguring the network. Disable openHAB Thing before doing this.
+1. Sometimes during intensive testing Roomba just stopped communicating over the local connection. If this happens, try rebooting it. On my robot it's done by holding "Clean" button for about 10 seconds until all the LEDs come on. Release the button and the reboot tone will be played. It looks like there are some bugs in the firmware.
## Example
irobot.things:
-```
+```java
Thing irobot:roomba:my_roomba [ ipaddress="192.168.0.5", password="xxxxxxxx" ]
```
irobot.items:
-```
+```java
String Roomba_Command { channel="irobot:roomba:my_roomba:command" }
String Roomba_Cycle { channel="irobot:roomba:my_roomba:cycle" }
String Roomba_Phase { channel="irobot:roomba:my_roomba:phase" }
irobot.sitemap:
-```
+```perl
Selection item=Roomba_Command mappings=["clean"="Clean", "spot"="Spot", dock="Dock", pause="Pause", stop="Stop"]
Text item=Roomba_Cycle label="Current cycle"
Text item=Roomba_Phase label="Current phase"
## Credits
-This code is a result of development of an abandoned draft by hkunh42 (https://github.com/hkuhn42/openhab2.roomba)
+This code is a result of development of an abandoned draft by hkunh42 (<https://github.com/hkuhn42/openhab2.roomba>)
and heavily uses the following projects as a reference:
-- Roomba980-Python by Nick Waterton (https://github.com/NickWaterton/Roomba980-Python)
-- Dorita980 by Facu ZAK (https://github.com/koalazak/dorita980)
+- Roomba980-Python by Nick Waterton (<https://github.com/NickWaterton/Roomba980-Python>)
+- Dorita980 by Facu ZAK (<https://github.com/koalazak/dorita980>)
## Supported Things
-The *ethernet* Bridge supports the Ethernet (PoE) IRtrans transceiver equipped with an on-board IRDB database. Blasters and receivers are defined as Channels on the Bridge, but one can also define blasters as a *blaster* child Thing on the Bridge.
+The _ethernet_ Bridge supports the Ethernet (PoE) IRtrans transceiver equipped with an on-board IRDB database. Blasters and receivers are defined as Channels on the Bridge, but one can also define blasters as a _blaster_ child Thing on the Bridge.
## Discovery
## Thing Configuration
-The *ethernet* Bridge requires an *ipAddress* IP address and *portNumber* TCP port number in order to configure it. Optionally, one can add the following parameters to the configuration:
+The _ethernet_ Bridge requires an _ipAddress_ IP address and _portNumber_ TCP port number in order to configure it. Optionally, one can add the following parameters to the configuration:
-*bufferSize* : Buffer size used by the TCP socket when sending and receiving commands to the transceiver (default: 1024)
-*responseTimeOut* : Specifies the time milliseconds to wait for a response from the transceiver when sending a command (default: 100)
-*pingTimeOut* : Specifies the time milliseconds to wait for a response from the transceiver when pinging the device (default: 1000)
-*reconnectInterval* : Specifies the time seconds to wait before reconnecting to a transceiver after a communication failure (default: 10)
+_bufferSize_ : Buffer size used by the TCP socket when sending and receiving commands to the transceiver (default: 1024)
+_responseTimeOut_ : Specifies the time milliseconds to wait for a response from the transceiver when sending a command (default: 100)
+_pingTimeOut_ : Specifies the time milliseconds to wait for a response from the transceiver when pinging the device (default: 1000)
+_reconnectInterval_ : Specifies the time seconds to wait before reconnecting to a transceiver after a communication failure (default: 10)
-The *blaster* Thing requires a *led* parameter to specify on which infrared commands will be emitted, *remote* the remote or manufacturer name which's commands will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '*' for 'any' remote), and *command* the name of the command will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '*' for 'any' command).
+The _blaster_ Thing requires a _led_ parameter to specify on which infrared commands will be emitted, _remote_ the remote or manufacturer name which's commands will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be ' \*' for 'any' remote), and _command_ the name of the command will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '*' for 'any' command).
## Channels
-The *ethernet* Thing supports the following Channel Types:
+The _ethernet_ Thing supports the following Channel Types:
| Channel Type ID | Item Type | Description |
|-----------------|-----------|-------------------------------------------------------------------------------------|
| blaster | String | Send (filtered) infrared commands over the specified blaster LED of the transceiver |
| receiver | String | Receive (filtered) infrared commands on the receiver LED of the transceiver |
-The *blaster* Channel Type requires a *led* configuration parameter to specify on which infrared commands will be emitted, *remote* the remote or manufacturer name which's commands will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '*' for 'any' remote), and *command* the name of the command will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '*' for 'any' command).
+The _blaster_ Channel Type requires a _led_ configuration parameter to specify on which infrared commands will be emitted, _remote_ the remote or manufacturer name which's commands will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '\*' for 'any' remote), and _command_ the name of the command will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '*' for 'any' command).
-The *receiver* Channel Type requires *remote* the remote or manufacturer name which's commands will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '*' for 'any' remote), and *command* the name of the command will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '*' for 'any' command).
+The _receiver_ Channel Type requires _remote_ the remote or manufacturer name which's commands will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '\*' for 'any' remote), and _command_ the name of the command will be allowed, as defined in the IRtrans server database that is flashed into the transceiver (can be '*' for 'any' command).
-The *blaster* Thing supports a *io* Channel (of Item Type String) that allows to read infrared commands received by the blaster, as well as to write infrared commands to be sent by the blaster.
+The _blaster_ Thing supports a _io_ Channel (of Item Type String) that allows to read infrared commands received by the blaster, as well as to write infrared commands to be sent by the blaster.
-The IRtrans transceivers store infrared commands in a "remote,command" table, e.g. "telenet,power". Sending the literal text string "telenet,power" to the transceiver will make the transceiver "translate" that into the actual infrared command that will be emitted by the transceiver. A "remote,command" string sent to a Channel that does not match the defined filter will be ignored.
+The IRtrans transceivers store infrared commands in a "remote,command" table, e.g. "telenet,power". Sending the literal text string "telenet,power" to the transceiver will make the transceiver "translate" that into the actual infrared command that will be emitted by the transceiver. A "remote,command" string sent to a Channel that does not match the defined filter will be ignored.
## Full Example
demo.things:
-```
+```java
Bridge irtrans:ethernet:kitchen [ ipAddress="192.168.0.56", portNumber=21000, bufferSize=1024, responseTimeOut=100, pingTimeOut=2000, reconnectInterval=10 ]
{
Channels:
The led can be "E"-External, "I"-Internal, "B"-Both, and a numeric for a selected led.
Depending on the number of remotes, the bufferSize must be adjusted. E.g. for 7 remotes and 47 commands a bufferSize of 2048 is needed.
-```
+```java
Bridge irtrans:ethernet:technicalfacilities [ ipAddress="192.168.0.58", portNumber=21000, bufferSize=1024, responseTimeOut=100, pingTimeOut=2000, reconnectInterval=10 ]
{
Channels:
demo.items:
-```
+```java
String KitchenIRReceiverAny {channel="irtrans:ethernet:kitchen:any"}
String KitchenIRReceiverTelenetPower {channel="irtrans:ethernet:kitchen:telenet_power"}
String KitchenIRBlasterSamsung {channel="irtrans:ethernet:kitchen:samsung"}
demo.rules:
-```
+```java
rule "Kitchen switch IR rule"
when
Item KitchenIRReceiverTelenetPower received update
_This binding can receive values of the Wolf heating system._
-The ISM8 card can be placed into the Wolf heating system.
-The card is usually used in combination with an object server, where the object server does forward those messages into the KNX bus system.
-In case there is no need to handle the heating system values directly in the KNX system you can use this binding to monitor and control your heating system without the need to buy an object server.
-The system works in a way that the ISM8 connects to a partner and sends from time to time an update. The frequency depends on the change of the values.
+The ISM8 card can be placed into the Wolf heating system.
+The card is usually used in combination with an object server, where the object server does forward those messages into the KNX bus system.
+In case there is no need to handle the heating system values directly in the KNX system you can use this binding to monitor and control your heating system without the need to buy an object server.
+The system works in a way that the ISM8 connects to a partner and sends from time to time an update. The frequency depends on the change of the values.
This binding is listening to those messages.
After the first connection there is an active command send to the ISM8 in order to receive all available data points.
-The manual of the ISM8 can be downloaded from the supplier (https://www.wolf.eu/fileadmin/Wolf_Profi/Downloads/Montage-Bedienungsanleitungen/Regelungen/Zubehoer/3064356_201611_ISM8i_Montage-u.Bedienungsanleitung.pdf)
+The manual of the ISM8 can be downloaded from the supplier (<https://www.wolf.eu/fileadmin/Wolf_Profi/Downloads/Montage-Bedienungsanleitungen/Regelungen/Zubehoer/3064356_201611_ISM8i_Montage-u.Bedienungsanleitung.pdf>)
## Supported Things
_Auto-discovery is not supported._
-
## Thing Configuration
The intention was to have a generic ISM8 binding in order to offer the full flexibilty for the different heating systems.
## Channels
You can use any channel supported by the ISM8 as data point. Please have a look at the official manual from Wolf.
-Within this document you'll find a table containing all supported data points.
-The available data points are depending on your heating system configuration.
+Within this document you'll find a table containing all supported data points.
+The available data points are depending on your heating system configuration.
The ISM8 does currently support 4 different devices at the same moment of time (e.g. CGB-2, CWL Excellent, Solar, ...).
Once you have an overview of your heating system set you can start to create the channels accordingly.
Each channel should be created in the following way:
- | Type | Name | Description | Configuration |
- |--------|---------|----------------------------|-----------------|
- | Number | DpId004 | "Kesseltemperatur" | id, type, write |
+| Type | Name | Description | Configuration |
+|--------|---------|----------------------------|-----------------|
+| Number | DpId004 | "Kesseltemperatur" | id, type, write |
Type:
-+ Switch use for boolean values
-+ Number use for any number
-+ Other types may work as well.
+- Switch use for boolean values
+- Number use for any number
+- Other types may work as well.
Name:
-+ Put here any name you'd like. This name is used for creating the binding.
-
+- Put here any name you'd like. This name is used for creating the binding.
Description:
-+ Put here any description you'd like or the description for the data point ID from the Wolf manual.
-
+- Put here any description you'd like or the description for the data point ID from the Wolf manual.
Configuration:
-+ id=1 - Please enter here the ID of the data point you'd like to map to this channel.
-A list of the available IDs are available within the Wolf manual.
+- id=1 - Please enter here the ID of the data point you'd like to map to this channel.
+A list of the available IDs are available within the Wolf manual.
The supported IDs are depending on the firmware version of the ISM8 and the connected systems.
-+ type="1.001" - Please enter here the knx type of the data point.
+- type="1.001" - Please enter here the knx type of the data point.
You can find the data type in the Wolf ISM8 document as well.
-+ write=true - This parameter defines if the channel is bidirectional, but the parameter is optional and by default false.
+- write=true - This parameter defines if the channel is bidirectional, but the parameter is optional and by default false.
Note:
Not all available types of the ISM8 interface are fully supported, but this can be extended.
For the moment the following data types are implemented:
-+ DPT-Bool: `1.001`, `1.002`, `1.003`, `1.009`
-+ DPT-Scaling: `5.001`
-+ DPT-Value: `9.001`, `9.002`, `9.006`
-+ DPT-FlowRate: `13.002`
-+ DPT-Mode: `20.102`, `20.103`, `20.105`
-
+- DPT-Bool: `1.001`, `1.002`, `1.003`, `1.009`
+- DPT-Scaling: `5.001`
+- DPT-Value: `9.001`, `9.002`, `9.006`
+- DPT-FlowRate: `13.002`
+- DPT-Mode: `20.102`, `20.103`, `20.105`
## Full Example
-_ism8.things_
+### ism8.things
- Thing ism8:device:heater "Wolf Heizung" [portNumber=12004]
+```java
+Thing ism8:device:heater "Wolf Heizung" [portNumber=12004]
{
Type switch-readonly : DpId001 "Störung Heizgerät" [id=1, type="1.001"]
Type number-readonly : DpId002 "Betriebsart" [id=2, type="20.105"]
Type number-readonly : DpId167 "CWL Luftdurchsatz Abluft" [id=167, type="13.002"]
Type number-readonly : DpId192 "CML Filterwarnung" [id=192, type="1.001"]
}
-
-_ism8.items_
-
- Switch ISM_HeizungStoerung "Störung Heizgerät" { channel="ism8:device:heater:DpId001" }
- Number ISM_HeizungBetriebsart "Betriebsart" { channel="ism8:device:heater:DpId002" }
- Number ISM_HeizungBrennerleistung "Brennerleistung [%.1f %%]" { channel="ism8:device:heater:DpId003" }
- Number ISM_HeizungKesseltemperatur "Kesseltemperatur [%.1f °C]" { channel="ism8:device:heater:DpId004" }
- Number ISM_HeizungRuecklauftemperatur "Rücklauftemperatur [%.1f °C]" { channel="ism8:device:heater:DpId006" }
- Number ISM_HeizungWarmwassertemperatur "Warmwassertemperatur [%.1f °C]" { channel="ism8:device:heater:DpId007" }
- Number ISM_HeizungAussentemperatur "Außentemperatur [%.1f °C]" { channel="ism8:device:heater:DpId008" }
- Switch ISM_HeizungStatusFlamme "Status Flamme" { channel="ism8:device:heater:DpId009" }
- Number ISM_HeizungAnlagendruck "Anlagendruck [%.2f bar]" { channel="ism8:device:heater:DpId013" }
- Switch ISM_HeizungSysStoerung "Störung Systemmodul" { channel="ism8:device:heater:DpId053" }
- Number ISM_HeizungSysAussentemperatur "Außentemperatur Systemmodul [%.1f °C]" { channel="ism8:device:heater:DpId054" }
- Number ISM_HeizungSollwertWarmwasser "Sollwert Warmwasser [%.1f °C]" { channel="ism8:device:heater:DpId056" }
- Number ISM_HeizungBetriebsartHeizkreis "Betriebsart Heizkreis" { channel="ism8:device:heater:DpId057" }
- Number ISM_HeizungBetriebsartWarmwasser "Betriebsart Warmwasser" { channel="ism8:device:heater:DpId058" }
- Number ISM_HeizungSollwertverschiebung "Sollwertverschiebung [%.1f °C]" { channel="ism8:device:heater:DpId065" }
- Switch ISM_LueftungStoerung "CML Störung" { channel="ism8:device:heater:DpId148" }
- Number ISM_LueftungBetriebsart "CWL Betriebsart" { channel="ism8:device:heater:DpId149" }
- Number ISM_LueftungLueftungsstufe "CWL Lüftungsstufe [%.1f %%]" { channel="ism8:device:heater:DpId163" }
- Number ISM_LueftungAblufttemperatur "CWL Ablufttemperatur [%.1f °C]" { channel="ism8:device:heater:DpId164" }
- Number ISM_LueftungZulufttemperatur "CWL Zulufttemperatur [%.1f °C]" { channel="ism8:device:heater:DpId165" }
- Number ISM_LueftungLuftdurchsatzZuluft "CWL Luftdurchsatz Zuluft [%.1f m³/h]" { channel="ism8:device:heater:DpId166" }
- Number ISM_LueftungLuftdurchsatzAbluft "CWL Luftdurchsatz Abluft [%.1f m³/h]" { channel="ism8:device:heater:DpId167" }
- Switch ISM_LueftungFilterwarnung "CML Filterwarnung" { channel="ism8:device:heater:DpId192" }
-
-_demo.sitemap_
-
- Frame label="Heizung"
- {
- Text item=ISM_HeizungSysStoerung icon="siren"
- Text item=ISM_HeizungStoerung icon="siren"
- Text item=ISM_HeizungAussentemperatur icon="temperature"
- Text item=ISM_HeizungBetriebsart icon="radiator" label="Modus [MAP(HVACContrMode.map):%s]"
- Text item=ISM_HeizungAnlagendruck icon="pressure"
- Text item=ISM_HeizungBrennerleistung icon="chart"
- Selection item=ISM_HeizungBetriebsartHeizkreis icon="radiator" mappings=[0="Auto", 1="Komfort", 2="Stand By", 3="Eco", 4="Frost Schutz"]
- Text item=ISM_HeizungStatusFlamme icon="fire"
- Text item=ISM_HeizungKesseltemperatur icon="temperature"
- Text item=ISM_HeizungRuecklauftemperatur icon="temperature_cold"
- Setpoint item=ISM_HeizungSollwertverschiebung icon="radiator" minValue=-5 maxValue=5 step=1
- }
- Frame label="Wasser"
- {
- Text item=ISM_HeizungWarmwassertemperatur icon="temperature_hot"
- Setpoint item=ISM_HeizungSollwertWarmwasser icon="temperature" minValue=40 maxValue=60 step=1
- Selection item=ISM_HeizungBetriebsartWarmwasser icon="faucet" mappings=[0="Auto", 1="Legionellen Schutz", 2="Normal", 3="Eco", 4="Frost Schutz"]
- }
- Frame label="Lüftung"
- {
- Text item=ISM_LueftungStoerung icon="siren"
- Selection item=ISM_LueftungBetriebsart icon="fan" mappings=[0="Auto", 1="Minimum", 2="Reduziert", 3="Normal", 4="Intensiv"]
- Text item=ISM_LueftungLueftungsstufe icon="qualityofservice"
- Text item=ISM_LueftungFilterwarnung icon="siren"
- Text item=ISM_LueftungAblufttemperatur icon="temperature_hot"
- Text item=ISM_LueftungZulufttemperatur icon="temperature_cold"
- Text item=ISM_LueftungLuftdurchsatzZuluft icon="flow"
- Text item=ISM_LueftungLuftdurchsatzAbluft icon="flow"
- }
-
-_HVACContrMode.map_
-
- 0=Auto
- 1=Heizen
- 2=Aufwärmen
- 3=Abkühlen
- 4=Nächtliche Reinigung
- 5=Vorkühlen
- 6=Aus
- 7=Test
- 8=Notfall Heizen
- 9=Nur Lüften
- 10=Freies Kühlen
- 11=Eis
- 12=Maximum Heizen
- 13=Eco Heiz-/Kühlmodus
- 14=Entfeuchten
- 15=Kalibriermodus
- 16=Notfall Kühlmodus
- 17=Emergency Dampfmodus
- 20=Reserviert
- NULL=Undefiniert
+```
+
+### ism8.items
+
+```java
+Switch ISM_HeizungStoerung "Störung Heizgerät" { channel="ism8:device:heater:DpId001" }
+Number ISM_HeizungBetriebsart "Betriebsart" { channel="ism8:device:heater:DpId002" }
+Number ISM_HeizungBrennerleistung "Brennerleistung [%.1f %%]" { channel="ism8:device:heater:DpId003" }
+Number ISM_HeizungKesseltemperatur "Kesseltemperatur [%.1f °C]" { channel="ism8:device:heater:DpId004" }
+Number ISM_HeizungRuecklauftemperatur "Rücklauftemperatur [%.1f °C]" { channel="ism8:device:heater:DpId006" }
+Number ISM_HeizungWarmwassertemperatur "Warmwassertemperatur [%.1f °C]" { channel="ism8:device:heater:DpId007" }
+Number ISM_HeizungAussentemperatur "Außentemperatur [%.1f °C]" { channel="ism8:device:heater:DpId008" }
+Switch ISM_HeizungStatusFlamme "Status Flamme" { channel="ism8:device:heater:DpId009" }
+Number ISM_HeizungAnlagendruck "Anlagendruck [%.2f bar]" { channel="ism8:device:heater:DpId013" }
+Switch ISM_HeizungSysStoerung "Störung Systemmodul" { channel="ism8:device:heater:DpId053" }
+Number ISM_HeizungSysAussentemperatur "Außentemperatur Systemmodul [%.1f °C]" { channel="ism8:device:heater:DpId054" }
+Number ISM_HeizungSollwertWarmwasser "Sollwert Warmwasser [%.1f °C]" { channel="ism8:device:heater:DpId056" }
+Number ISM_HeizungBetriebsartHeizkreis "Betriebsart Heizkreis" { channel="ism8:device:heater:DpId057" }
+Number ISM_HeizungBetriebsartWarmwasser "Betriebsart Warmwasser" { channel="ism8:device:heater:DpId058" }
+Number ISM_HeizungSollwertverschiebung "Sollwertverschiebung [%.1f °C]" { channel="ism8:device:heater:DpId065" }
+Switch ISM_LueftungStoerung "CML Störung" { channel="ism8:device:heater:DpId148" }
+Number ISM_LueftungBetriebsart "CWL Betriebsart" { channel="ism8:device:heater:DpId149" }
+Number ISM_LueftungLueftungsstufe "CWL Lüftungsstufe [%.1f %%]" { channel="ism8:device:heater:DpId163" }
+Number ISM_LueftungAblufttemperatur "CWL Ablufttemperatur [%.1f °C]" { channel="ism8:device:heater:DpId164" }
+Number ISM_LueftungZulufttemperatur "CWL Zulufttemperatur [%.1f °C]" { channel="ism8:device:heater:DpId165" }
+Number ISM_LueftungLuftdurchsatzZuluft "CWL Luftdurchsatz Zuluft [%.1f m³/h]" { channel="ism8:device:heater:DpId166" }
+Number ISM_LueftungLuftdurchsatzAbluft "CWL Luftdurchsatz Abluft [%.1f m³/h]" { channel="ism8:device:heater:DpId167" }
+Switch ISM_LueftungFilterwarnung "CML Filterwarnung" { channel="ism8:device:heater:DpId192" }
+```
+
+### demo.sitemap
+
+```perl
+Frame label="Heizung"
+{
+ Text item=ISM_HeizungSysStoerung icon="siren"
+ Text item=ISM_HeizungStoerung icon="siren"
+ Text item=ISM_HeizungAussentemperatur icon="temperature"
+ Text item=ISM_HeizungBetriebsart icon="radiator" label="Modus [MAP(HVACContrMode.map):%s]"
+ Text item=ISM_HeizungAnlagendruck icon="pressure"
+ Text item=ISM_HeizungBrennerleistung icon="chart"
+ Selection item=ISM_HeizungBetriebsartHeizkreis icon="radiator" mappings=[0="Auto", 1="Komfort", 2="Stand By", 3="Eco", 4="Frost Schutz"]
+ Text item=ISM_HeizungStatusFlamme icon="fire"
+ Text item=ISM_HeizungKesseltemperatur icon="temperature"
+ Text item=ISM_HeizungRuecklauftemperatur icon="temperature_cold"
+ Setpoint item=ISM_HeizungSollwertverschiebung icon="radiator" minValue=-5 maxValue=5 step=1
+}
+Frame label="Wasser"
+{
+ Text item=ISM_HeizungWarmwassertemperatur icon="temperature_hot"
+ Setpoint item=ISM_HeizungSollwertWarmwasser icon="temperature" minValue=40 maxValue=60 step=1
+ Selection item=ISM_HeizungBetriebsartWarmwasser icon="faucet" mappings=[0="Auto", 1="Legionellen Schutz", 2="Normal", 3="Eco", 4="Frost Schutz"]
+}
+Frame label="Lüftung"
+{
+ Text item=ISM_LueftungStoerung icon="siren"
+ Selection item=ISM_LueftungBetriebsart icon="fan" mappings=[0="Auto", 1="Minimum", 2="Reduziert", 3="Normal", 4="Intensiv"]
+ Text item=ISM_LueftungLueftungsstufe icon="qualityofservice"
+ Text item=ISM_LueftungFilterwarnung icon="siren"
+ Text item=ISM_LueftungAblufttemperatur icon="temperature_hot"
+ Text item=ISM_LueftungZulufttemperatur icon="temperature_cold"
+ Text item=ISM_LueftungLuftdurchsatzZuluft icon="flow"
+ Text item=ISM_LueftungLuftdurchsatzAbluft icon="flow"
+}
+```
+
+### HVACContrMode.map
+
+```text
+0=Auto
+1=Heizen
+2=Aufwärmen
+3=Abkühlen
+4=Nächtliche Reinigung
+5=Vorkühlen
+6=Aus
+7=Test
+8=Notfall Heizen
+9=Nur Lüften
+10=Freies Kühlen
+11=Eis
+12=Maximum Heizen
+13=Eco Heiz-/Kühlmodus
+14=Entfeuchten
+15=Kalibriermodus
+16=Notfall Kühlmodus
+17=Emergency Dampfmodus
+20=Reserviert
+NULL=Undefiniert
+```
_Result_
<img src="doc/Sitemap-Example.png" width="800" height="600">
# Jablotron Alarm Binding
This is the binding for Jablotron alarms.
-https://www.jablotron.com/en/jablotron-products/alarms/
+<https://www.jablotron.com/en/jablotron-products/alarms/>
## Supported Things
| JA-80 | the OASIS alarm |
| JA-100 | with the thermometer support |
| JA-100F | without the thermometer support |
-
+
## Discovery
This binding supports auto discovery. Just manually add a bridge thing and supply login & password to your Jablonet account.
The state, pgm, thermometer, thermostat, sec and pg channels for the JA-100/JA-100F alarms are dynamically created according to your configuration.
-* The sections are represented by String channels (with possible values "set", "unset", "partialSet" for JA-100 and possible values "ARM", "PARTIAL_ARM" and "DISARM" for JA100-F)
+- The sections are represented by String channels (with possible values "set", "unset", "partialSet" for JA-100 and possible values "ARM", "PARTIAL_ARM" and "DISARM" for JA100-F)
## Full Example
# items file for JA80
-```
+```java
String HouseAlarm "Alarm [%s]" <alarm>
String JablotronCode { channel="jablotron:oasis:8c93a5ed:50139:command", autoupdate="false" }
-Switch ArmSectionA "Garage arming" <jablotron> (Alarm) { channel="jablotron:oasis:8c93a5ed:50139:statusA" }
-Switch ArmSectionAB "1st floor arming" <jablotron> (Alarm) { channel="jablotron:oasis:8c93a5ed:50139:statusB" }
-Switch ArmSectionABC "2nd floor arming" <jablotron> (Alarm) { channel="jablotron:oasis:8c93a5ed:50139:statusABC" }
+Switch ArmSectionA "Garage arming" <jablotron> (Alarm) { channel="jablotron:oasis:8c93a5ed:50139:statusA" }
+Switch ArmSectionAB "1st floor arming" <jablotron> (Alarm) { channel="jablotron:oasis:8c93a5ed:50139:statusB" }
+Switch ArmSectionABC "2nd floor arming" <jablotron> (Alarm) { channel="jablotron:oasis:8c93a5ed:50139:statusABC" }
String LastEvent "Last event code [%s]" <jablotron> { channel="jablotron:oasis:8c93a5ed:50139:lastEvent" }
String LastEventClass "Last event class [%s]" <jablotron> { channel="jablotron:oasis:8c93a5ed:50139:lastEventClass" }
String LastEventInvoker "Last event class [%s]" <jablotron> { channel="jablotron:oasis:8c93a5ed:50139:lastEventInvoker" }
DateTime LastEventTime "Last event [%1$td.%1$tm.%1$tY %1$tR]" <clock> { channel="jablotron:oasis:8c93a5ed:50139:lastEventTime" }
DateTime LastCheckTime "Last check [%1$td.%1$tm.%1$tY %1$tR]" <clock> { channel="jablotron:oasis:8c93a5ed:50139:lastCheckTime" }
-Switch ArmControlPGX "PGX" <jablotron> (Alarm) { channel="jablotron:oasis:8c93a5ed:50139:statusPGX" }
-Switch ArmControlPGY "PGY" <jablotron> (Alarm) { channel="jablotron:oasis:8c93a5ed:50139:statusPGY" }
+Switch ArmControlPGX "PGX" <jablotron> (Alarm) { channel="jablotron:oasis:8c93a5ed:50139:statusPGX" }
+Switch ArmControlPGY "PGY" <jablotron> (Alarm) { channel="jablotron:oasis:8c93a5ed:50139:statusPGY" }
```
# sitemap example for JA80
-```
+```java
Text item=HouseAlarm icon="alarm" {
Switch item=ArmSectionA
Switch item=ArmSectionAB
# rule example for JA80
-```
+```java
rule "Alarm"
when
Item ArmSectionA changed or Item ArmSectionAB changed or Item ArmSectionABC changed or
This binding supports:
-* JeeLink (connected to USB)
-* JeeLink (connected over TCP)
-* LaCrosseGateway (connected to USB)
-* LaCrosseGateway (connected over TCP)
-* LaCrosse temperature sensors
-* EC3000 power monitors
-* Revolt power monitors
-* PCA301 power monitoring wireless sockets
-* TX22 temperature & humidity Sensors (including connected TX23 wind and TX26 rain sensors)
+- JeeLink (connected to USB)
+- JeeLink (connected over TCP)
+- LaCrosseGateway (connected to USB)
+- LaCrosseGateway (connected over TCP)
+- LaCrosse temperature sensors
+- EC3000 power monitors
+- Revolt power monitors
+- PCA301 power monitoring wireless sockets
+- TX22 temperature & humidity Sensors (including connected TX23 wind and TX26 rain sensors)
## Binding configuration
## Thing configuration
-#### JeeLink / LaCrosseGateway (connected to USB)
+### JeeLink / LaCrosseGateway (connected to USB)
| Parameter | Item Type | Description |
|---------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------|
The available init commands depend on the sketch that is running on the USB stick / LaCrosseGateway.
-
-#### JeeLink / LaCrosseGateway (connected over TCP)
+### JeeLink / LaCrosseGateway (connected over TCP)
| Parameter | Item Type | Description |
|---------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------|
| TCP Port | Number | The TCP port over which the serial port is made available, or the LaCrosseGateway port (which usually is 81) |
| Init Commands | String | A semicolon separated list of init commands that will be send to the Jeelink / LaCrosseGateway, e.g. "0a" for disabling the LED |
-
-#### LaCrosse temperature sensors
+### LaCrosse temperature sensors
| Parameter | Item Type | Description |
|----------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| Upper Temperature Limit | Decimal | The highest allowed valid temperature. Higher temperature readings will be ignored |
| Maximum allowed difference | Decimal | The maximum allowed difference from a value to the previous value (0 disables this check). If the difference is higher, the reading will be ignored. |
-#### EC3000 power monitors
+### EC3000 power monitors
| Parameter | Item Type | Description |
|-----------------|-----------|-------------------------------------------------------------------------------------------------------------------------|
| Update Interval | Number | The update interval in seconds how often value updates are propagated. A value of 0 leads to propagation of every value |
| Buffer Size | Number | The number of readings used for computing the rolling average |
-#### PCA301 power monitoring wireless sockets
+### PCA301 power monitoring wireless sockets
| Parameter | Item Type | Description |
|-------------------|--------------|------------------------------------------------------------------------------------------------------------------------|
| Sensor Timeout | Number | The amount of time in seconds that should result in OFFLINE status when no readings have been received from the sensor |
| Retry Count | Number | The number of times a switch command will be resent to the socket until giving up |
-#### Revolt power monitors
+### Revolt power monitors
| Parameter | Item Type | Description |
|-------------------|--------------|------------------------------------------------------------------------------------------------------------------------|
## Channels
-#### LaCrosse temperature sensors
+### LaCrosse temperature sensors
| Channel Type ID | Item Type | Description |
|-----------------|-----------------------|---------------------------------------------------|
| batteryNew | Contact | Whether the battery is new (CLOSED) or not (OPEN) |
| batteryLow | Contact | Whether the battery is low (CLOSED) or not (OPEN) |
-#### TX22 temperature and humidity sensors
+### TX22 temperature and humidity sensors
| Channel Type ID | Item Type | Description |
|-----------------|-----------------------|----------------------------|
| windAngle | Number:Angle | Current wind direction |
| gustStrength | Number:Speed | Gust speed |
-#### EC3000 power monitors
+### EC3000 power monitors
| Channel Type ID | Item Type | Description |
|------------------|---------------|-------------------------------------------|
| sensorTime | Number:Time | Total turn on time of power monitor |
| resets | Number | Number of resets |
-#### PCA301 power monitoring wireless sockets
+### PCA301 power monitoring wireless sockets
| Channel Type ID | Item Type | Description |
|-------------------------|---------------|------------------------------------------------------|
| currentPower | Number:Power | Current power draw |
| consumptionTotal | Number:Energy | Total energy consumption |
-#### Revolt power monitors
+### Revolt power monitors
| Channel Type ID | Item Type | Description |
|-------------------|--------------------------|-------------------------------------------|
## Commands
-#### PCA301 power monitoring wireless sockets
+### PCA301 power monitoring wireless sockets
| Channel Type ID | Item Type | Description |
|-------------------------|--------------|---------------------------------------------------|
A typical thing configuration for PCA301 looks like this:
-```
+```java
Bridge jeelink:jeelinkUsb:pca301 "Jeelink pca301" @ "home" [ serialPort="/dev/ttyUSB0" ]
Thing jeelink:pca301:1-160-236 "ec3k 1" (jeelink:jeelinkUsb:pca301) @ "home" [ sensorId="1-160-236"]
```
A typical thing configuration for EC3000 looks like this:
-```
+```java
Bridge jeelink:jeelinkUsb:ec3k "Jeelink ec3k" @ "home" [ serialPort="COM4" ]
Thing jeelink:ec3k:0E3D "ec3k 1" (jeelink:jeelinkUsb:ec3k) @ "home" [ sensorId="0E3D"]
Thing jeelink:ec3k:14E7 "ec3k 2" (jeelink:jeelinkUsb:ec3k) @ "home" [ sensorId="14E7"]
A typical Thing configuration for lacrosse looks like this:
-```
+```java
Bridge jeelink:jeelinkUsb:lacrosse "Jeelink lacrosse" @ "home" [ serialPort="COM6" ]
Thing jeelink:lacrosse:sensor1 "Jeelink lacrosse 1" (jeelink:jeelinkUsb:lacrosse) @ "home" [ sensorId="16", minTemp=10, maxTemp=32]
Thing jeelink:lacrosse:sensor2 "Jeelink lacrosse 2" (jeelink:jeelinkUsb:lacrosse) @ "home" [ sensorId="18", minTemp=10, maxTemp=32]
A typical thing configuration for Revolt looks like this:
-```
+```java
Bridge jeelink:jeelinkUsb:revolt "Jeelink revolt" @ "home" [ serialPort="COM4" ]
Thing jeelink:revolt:4F1B "revolt 1" (jeelink:jeelinkUsb:revolt) @ "home" [ sensorId="4F1B"]
```
A typical item configuration for a LaCrosse temperature sensor looks like this:
-```
+```java
Number:Dimensionless Humidty_LR "Living Room [%.1f %unit%]" <humidity> {channel="jeelink:lacrosse:42:humidity"}
Number:Temperature Temperature_LR "Living Room [%.1f %unit%]" <temperature> {channel="jeelink:lacrosse:42:temperature"}
Contact Battery_Low_LR "Battery Low Living Room" {channel="jeelink:lacrosse:42:batteryLow"}
A typical item configuration for a PCA301 power monitoring wireless sockets looks like this:
-```
+```java
Switch SocketSwitch {channel="jeelink:pca301:1-160-236:switchingState"}
Number:Power SocketWattage {channel="jeelink:pca301:1-160-236:currentPower"}
Number:Energy SocketConsumption {channel="jeelink:pca301:1-160-236:consumptionTotal"}
A typical item configuration for a TX22 temperature and humidity sensor looks like this:
-```
+```java
Number:Dimensionless Humidity "Outside [%.1f %unit%]" <humidity> {channel="jeelink:tx22:42:humidity"}
Number:Temperature Temperature "Outside [%.1f %unit%]" <temperature> {channel="jeelink:tx22:42:temperature"}
Contact Battery_Low_LR "Battery Low Outside" {channel="jeelink:tx22:42:batteryLow"}
A typical item configuration for a Revolt power monitor looks like this:
-```
+```java
Number:Power SocketWattage {channel="jeelink:revolt:4F1B:currentPower"}
Number:Energy SocketConsumption {channel="jeelink:revolt:4F1B:consumptionTotal"}
Number:Dimensionless POwerFactor {channel="jeelink:revolt:4F1B:powerFactor"}
Number:ElectricPotential Voltage {channel="jeelink:revolt:4F1B:electricPotential"}
Number:Frequency PowerFrequency {channel="jeelink:revolt:4F1B:powerFrequency"}
```
-
# Jellyfin Binding
-This is the binding for [Jellyfin](https://jellyfin.org) the volunteer-built media solution that puts you in control of your media.
-Stream to any device from your own server, with no strings attached.
+This is the binding for [Jellyfin](https://jellyfin.org) the volunteer-built media solution that puts you in control of your media.
+Stream to any device from your own server, with no strings attached.
Your media, your server, your way.
This binding allows connect to Jellyfin clients that supports remote control, it's build on top of the official Jellyfin kotlin sdk.
Compatible with Jellyfin servers in version 10.8.x.
## Discovery
-Before you are able to discover clients you should have a bridge to the server so until one is online the discovery will only look for servers on your local network. Once one is online the discovery will detect controllable clients connected to that server.
+Before you are able to discover clients you should have a bridge to the server so until one is online the discovery will only look for servers on your local network. Once one is online the discovery will detect controllable clients connected to that server.
## Thing Types
To allow the server thing to go online you should provide valid credentials for the user that the biding will use to interact with the server api (userId and token configuration properties).
Please note that the user should be allowed on the Jellyfin server to remote control devices.
-In order to assist you with this process the binding expose a simple login form you can access on \<local openHAB server url\>/jellyfin/\<server thing id\> for example http://127.0.0.1:8080/jellyfin/2846b8fb60ad444f9ebd085335e3f6bf.
+In order to assist you with this process the binding expose a simple login form you can access on \<local openHAB server url\>/jellyfin/\<server thing id\> for example `http://127.0.0.1:8080/jellyfin/2846b8fb60ad444f9ebd085335e3f6bf`.
## Server Thing Configuration
| play-next-by-id | String | Add to playback queue as next by id, works for series, episodes and movies |
| play-last-by-id | String | Add to playback queue as last by id, works for series, episodes and movies |
| browse-by-id | String | Browse media by id, works for series, episodes and movies |
+
### Terms search:
The terms search has a default behavior that can be modified sending some predefined prefixes.
### Example Server (Bridge) - jellyfin.bridge.things
-```
+```java
Bridge jellyfin:server:exampleServerId "Jellyfin Server" [
- clientActiveWithInSeconds=0,
- hostname="192.168.1.177",
- port=8096,
- refreshSeconds=30,
- ssl="false"
+ clientActiveWithInSeconds=0,
+ hostname="192.168.1.177",
+ port=8096,
+ refreshSeconds=30,
+ ssl="false"
token=XXXXX # Optional, read bellow
userId=XXXXX # Optional, read bellow
]
```
- * token and userId could be retrieved using the login form at http://YOUROPENHABIP:PORT/jellyfin/exampleServerId
+- token and userId could be retrieved using the login form at `http://YOUROPENHABIP:PORT/jellyfin/exampleServerId`
### Example Client - jellyfin.clients.things
-```
+```java
Thing jellyfin:client:exampleServerId:<JELLYFIN_DEVICE_ID> "Jellyfin Web client" (jellyfin:server:exampleServerId)
Thing jellyfin:client:exampleServerId:<JELLYFIN_DEVICE_ID> "Jellyfin Android client" (jellyfin:server:exampleServerId)
```
-* I recommend creating the clients using the discovery. For getting the device ids manually I recommend to use the Jellyfin web interface with the web inspector and look for the request that is launched when you click the cast button (<jellyfin url>/Sessions?ControllableByUserId=XXXXXXXXXXXX).
+- I recommend creating the clients using the discovery. For getting the device ids manually I recommend to use the Jellyfin web interface with the web inspector and look for the request that is launched when you click the cast button (<jellyfin url>/Sessions?ControllableByUserId=XXXXXXXXXXXX).
### Example Items - jellyfin.items
-```
+```java
String strJellyfinAndroidSendNotification { channel="jellyfin:client:exampleServerId:<JELLYFIN_DEVICE_ID>:send-notification " }
Player plJellyfinAndroidMediaControl { channel="jellyfin:client:exampleServerId:<JELLYFIN_DEVICE_ID>:media-control" }
String strJellyfinAndroidPlayingItemId { channel="jellyfin:client:exampleServerId:<JELLYFIN_DEVICE_ID>:playing-item-id" }
This binding supports the following things:
| thing | type | description |
-|---------- |-------- |------------------------------ |
+|---------- |-------- |------------------------------ |
| JuiceNet Account | Bridge | This represents the cloud account to interface with the JuiceNet API. |
| JuiceBox EV Charger | Device | This interfaces to a specific JuiceBox EV charger associated with the JuiceNet account. |
Once a JuiceNet Account bridge has been created, any JuiceBox EV Chargers associated with this account will be discovered.
-
### Thing Configuration
The configuration required is to create a JuiceNet account thing and fill in the appropriate API token.
-The API token can be found on the Account page at https://home.juice.net/Manage.
+The API token can be found on the Account page at <https://home.juice.net/Manage>.
A JuiceBox EV Charger requires a unitID which can also be found in the device settings at the JuiceNet web page.
If configuring the binding with manual configuration an example thing file looks like this:
-```
+```java
Bridge juicenet:account:myaccount [ apiToken="xxxx-xxxx-xxxx-xxxx-xxxxx" ] {
Thing device JamesCharger [ unitID="xxxxxxx" ]
}
An example of an items file is here.
-```
+```java
String JuiceNet_Name "Name" { channel="juicenet:device:myaccount:JamesCharger:name" }
String JuiceNet_State "Device State" { channel="juicenet:device:myaccount:JamesCharger:state" }
String JuiceNet_ChargingState "Charging State" { channel="juicenet:device:myaccount:JamesCharger:chargingState" }
-```
+```yaml
uid: widget_JuiceBox
tags: []
props:
config:
text: =items[props.prefix + "_CarDescription"].state
```
-
Some notes:
-* Due to a bug in the control protocol, a Strato C player will be identified as a Premiere 'Player' by the auto discovery process.
-* The only caveat of note about this binding is the updatePeriod configuration parameter.
-* When set to the default of 0, the component only sends running time update messages sporadically (as an example: when the movie chapter changes) while content is playing.
-* In this case, the running time channels will also only sporadically update.
-* When updatePeriod is set to 1 (values greater than 1 are not yet supported by the control protocol), the component sends running time status update messages every second.
-* Be aware that this could cause performance impacts to your openHAB system.
-
-* On Linux, you may get an error stating the serial port cannot be opened when the Kaleidescape binding tries to load.
-* You can get around this by adding the `openhab` user to the `dialout` group like this: `usermod -a -G dialout openhab`.
-* Also on Linux you may have issues with the USB if using two serial USB devices e.g. Kaleidescape and RFXcom.
-* See the [general documentation about serial port configuration](/docs/administration/serial.html) for more on symlinking the USB ports.
+- Due to a bug in the control protocol, a Strato C player will be identified as a Premiere 'Player' by the auto discovery process.
+- The only caveat of note about this binding is the updatePeriod configuration parameter.
+- When set to the default of 0, the component only sends running time update messages sporadically (as an example: when the movie chapter changes) while content is playing.
+- In this case, the running time channels will also only sporadically update.
+- When updatePeriod is set to 1 (values greater than 1 are not yet supported by the control protocol), the component sends running time status update messages every second.
+- Be aware that this could cause performance impacts to your openHAB system.
+
+- On Linux, you may get an error stating the serial port cannot be opened when the Kaleidescape binding tries to load.
+- You can get around this by adding the `openhab` user to the `dialout` group like this: `usermod -a -G dialout openhab`.
+- Also on Linux you may have issues with the USB if using two serial USB devices e.g. Kaleidescape and RFXcom.
+- See the [general documentation about serial port configuration](/docs/administration/serial.html) for more on symlinking the USB ports.
## Channels
kaleidescape.things:
-```
+```java
kaleidescape:player:myzone1 "M500 Living Rm" [ host="192.168.1.10", updatePeriod=0, loadHighlightedDetails=true, loadAlbumDetails=true ]
kaleidescape:cinemaone:myzone2 "My Cinema One" [ host="192.168.1.11", updatePeriod=0, loadHighlightedDetails=true, loadAlbumDetails=true ]
kaleidescape:strato:myzone3 "Strato Theater Rm" [ host="192.168.1.12", updatePeriod=0, loadHighlightedDetails=true ]
-
```
kaleidescape.items:
-```
+```java
// Virtual switch to send a command, see sitemap and rules below
Switch z1_GoMovieCovers "Go to Movie Covers"
String z1_Detail_Country "Country: [%s]" { channel="kaleidescape:player:myzone1:detail#country" }
String z1_Detail_AspectRatio "Aspect Ratio: [%s]" { channel="kaleidescape:player:myzone1:detail#aspect_ratio" }
String z1_Detail_DiscLocation "Disc Location: [%s]" { channel="kaleidescape:player:myzone1:detail#disc_location" }
-
```
ksecondsformat.js:
-```
+```javascript
(function(totalSeconds) {
if (isNaN(totalSeconds)) {
return '-';
kaleidescape.sitemap:
-```
+```perl
sitemap kaleidescape label="Kaleidescape" {
Frame label="Zone 1" {
Image item=z1_Detail_CoverArt
kaleidescape.rules:
-```
+```java
var int lightPercent
val kactions = getActions("kaleidescape","kaleidescape:player:myzone1")
All devices support the following channels:
-| Channel ID | Item Type | Read-only | Description |
-|---------------------------|---------------------------|-----------|---------------------------------------------------------------------------|
-| state | Number | yes | current operational state of the wallbox |
-| enabled | Switch | no | activation state of the wallbox |
-| maxpresetcurrent | Number:ElectricCurrent | no | maximum current the charging station should deliver to the EV in A |
-| maxpresetcurrentrange | Number:Dimensionless | no | maximum current the charging station should deliver to the EV in % |
-| power | Number:Power | yes | active power delivered by the charging station |
-| wallbox | Switch | yes | plug state of wallbox |
-| vehicle | Switch | yes | plug state of vehicle |
-| locked | Switch | yes | lock state of plug at vehicle |
-| I1/2/3 | Number:ElectricCurrent | yes | current for the given phase |
-| U1/2/3 | Number:ElectricPotential | yes | voltage for the given phase |
-| output | Switch | no | state of the X1 relais |
-| input | Switch | yes | state of the X2 contact |
-| display | String | no | display text on wallbox |
-| error1 | String | yes | error code state 1, if in error (see the KeContact FAQ) |
-| error2 | String | yes | error code state 2, if in error (see the KeContact FAQ) |
-| maxsystemcurrent | Number:ElectricCurrent | yes | maximum current the wallbox can deliver |
-| failsafecurrent | Number:ElectricCurrent | yes | maximum current the wallbox can deliver, if network is lost |
-| uptime | Number:Time | yes | system uptime since the last reset of the wallbox |
-| sessionconsumption | Number:Energy | yes | energy delivered in current session |
-| totalconsumption | Number:Energy | yes | total energy delivered since the last reset of the wallbox |
-| authreq | Switch | yes | authentication required |
-| authon | Switch | yes | authentication enabled |
-| sessionrfidtag | String | yes | RFID tag used for the last charging session |
-| sessionrfidclass | String | yes | RFID tag class used for the last charging session |
-| sessionid | Number | yes | session ID of the last charging session |
-| setenergylimit | Number:Energy | no | set an energy limit for an already running or the next charging session |
-| authenticate | String | no | authenticate and start a session using RFID tag+RFID class |
-| maxpilotcurrent | Number:ElectricCurrent | yes | current offered to the vehicle via control pilot signalization |
-| maxpilotcurrentdutycyle | Number:Dimensionless | yes | duty cycle of the control pilot signal |
-
+| Channel ID | Item Type | Read-only | Description |
+| ----------------------- | ------------------------ | --------- | ----------------------------------------------------------------------- |
+| state | Number | yes | current operational state of the wallbox |
+| enabled | Switch | no | activation state of the wallbox |
+| maxpresetcurrent | Number:ElectricCurrent | no | maximum current the charging station should deliver to the EV in A |
+| maxpresetcurrentrange | Number:Dimensionless | no | maximum current the charging station should deliver to the EV in % |
+| power | Number:Power | yes | active power delivered by the charging station |
+| wallbox | Switch | yes | plug state of wallbox |
+| vehicle | Switch | yes | plug state of vehicle |
+| locked | Switch | yes | lock state of plug at vehicle |
+| I1/2/3 | Number:ElectricCurrent | yes | current for the given phase |
+| U1/2/3 | Number:ElectricPotential | yes | voltage for the given phase |
+| output | Switch | no | state of the X1 relais |
+| input | Switch | yes | state of the X2 contact |
+| display | String | no | display text on wallbox |
+| error1 | String | yes | error code state 1, if in error (see the KeContact FAQ) |
+| error2 | String | yes | error code state 2, if in error (see the KeContact FAQ) |
+| maxsystemcurrent | Number:ElectricCurrent | yes | maximum current the wallbox can deliver |
+| failsafecurrent | Number:ElectricCurrent | yes | maximum current the wallbox can deliver, if network is lost |
+| uptime | Number:Time | yes | system uptime since the last reset of the wallbox |
+| sessionconsumption | Number:Energy | yes | energy delivered in current session |
+| totalconsumption | Number:Energy | yes | total energy delivered since the last reset of the wallbox |
+| authreq | Switch | yes | authentication required |
+| authon | Switch | yes | authentication enabled |
+| sessionrfidtag | String | yes | RFID tag used for the last charging session |
+| sessionrfidclass | String | yes | RFID tag class used for the last charging session |
+| sessionid | Number | yes | session ID of the last charging session |
+| setenergylimit | Number:Energy | no | set an energy limit for an already running or the next charging session |
+| authenticate | String | no | authenticate and start a session using RFID tag+RFID class |
+| maxpilotcurrent | Number:ElectricCurrent | yes | current offered to the vehicle via control pilot signalization |
+| maxpilotcurrentdutycyle | Number:Dimensionless | yes | duty cycle of the control pilot signal |
## Example
demo.Things:
-```
+```java
Thing keba:kecontact:1 [ipAddress="192.168.0.64", refreshInterval=30]
```
demo.items:
-```
-Number:Dimensionless KebaCurrentRange "Maximum supply current [%.1f %%]" {channel="keba:kecontact:1:maxpresetcurrentrange"}
-Number:ElectricCurrent KebaCurrent "Maximum supply current [%.3f A]" {channel="keba:kecontact:1:maxpresetcurrent"}
-Number:ElectricCurrent KebaSystemCurrent "Maximum system supply current [%.3f A]" {channel="keba:kecontact:1:maxsystemcurrent"}
-Number:ElectricCurrent KebaFailSafeCurrent "Failsafe supply current [%.3f A]" {channel="keba:kecontact:1:failsafecurrent"}
-Number KebaState "Operating State [%s]" {channel="keba:kecontact:1:state"}
-Switch KebaSwitch "Enabled" {channel="keba:kecontact:1:enabled"}
-Switch KebaWallboxPlugged "Plugged into wallbox" {channel="keba:kecontact:1:wallbox"}
-Switch KebaVehiclePlugged "Plugged into vehicle" {channel="keba:kecontact:1:vehicle"}
-Switch KebaPlugLocked "Plug locked" {channel="keba:kecontact:1:locked"}
-DateTime KebaUptime "Uptime [%s s]" {channel="keba:kecontact:1:uptime"}
-Number:ElectricCurrent KebaI1 {channel="keba:kecontact:1:I1"}
-Number:ElectricCurrent KebaI2 {channel="keba:kecontact:1:I2"}
-Number:ElectricCurrent KebaI3 {channel="keba:kecontact:1:I3"}
-Number:ElectricPotential KebaU1 {channel="keba:kecontact:1:U1"}
-Number:ElectricPotential KebaU2 {channel="keba:kecontact:1:U2"}
-Number:ElectricPotential KebaU3 {channel="keba:kecontact:1:U3"}
-Number:Power KebaPower "Energy during current session [%.1f Wh]" {channel="keba:kecontact:1:power"}
-Number:Energy KebaSessionEnergy {channel="keba:kecontact:1:sessionconsumption"}
-Number:Energy KebaTotalEnergy "Energy during all sessions [%.1f Wh]" {channel="keba:kecontact:1:totalconsumption"}
-Switch KebaInputSwitch {channel="keba:kecontact:1:input"}
-Switch KebaOutputSwitch {channel="keba:kecontact:1:output"}
-Number:Energy KebaSetEnergyLimit "Set charge energy limit [%.1f Wh]" {channel="keba:kecontact:1:setenergylimit"}
+```java
+Number:Dimensionless KebaCurrentRange "Maximum supply current [%.1f %%]" {channel="keba:kecontact:1:maxpresetcurrentrange"}
+Number:ElectricCurrent KebaCurrent "Maximum supply current [%.3f A]" {channel="keba:kecontact:1:maxpresetcurrent"}
+Number:ElectricCurrent KebaSystemCurrent "Maximum system supply current [%.3f A]" {channel="keba:kecontact:1:maxsystemcurrent"}
+Number:ElectricCurrent KebaFailSafeCurrent "Failsafe supply current [%.3f A]" {channel="keba:kecontact:1:failsafecurrent"}
+Number KebaState "Operating State [%s]" {channel="keba:kecontact:1:state"}
+Switch KebaSwitch "Enabled" {channel="keba:kecontact:1:enabled"}
+Switch KebaWallboxPlugged "Plugged into wallbox" {channel="keba:kecontact:1:wallbox"}
+Switch KebaVehiclePlugged "Plugged into vehicle" {channel="keba:kecontact:1:vehicle"}
+Switch KebaPlugLocked "Plug locked" {channel="keba:kecontact:1:locked"}
+DateTime KebaUptime "Uptime [%s s]" {channel="keba:kecontact:1:uptime"}
+Number:ElectricCurrent KebaI1 {channel="keba:kecontact:1:I1"}
+Number:ElectricCurrent KebaI2 {channel="keba:kecontact:1:I2"}
+Number:ElectricCurrent KebaI3 {channel="keba:kecontact:1:I3"}
+Number:ElectricPotential KebaU1 {channel="keba:kecontact:1:U1"}
+Number:ElectricPotential KebaU2 {channel="keba:kecontact:1:U2"}
+Number:ElectricPotential KebaU3 {channel="keba:kecontact:1:U3"}
+Number:Power KebaPower "Energy during current session [%.1f Wh]" {channel="keba:kecontact:1:power"}
+Number:Energy KebaSessionEnergy {channel="keba:kecontact:1:sessionconsumption"}
+Number:Energy KebaTotalEnergy "Energy during all sessions [%.1f Wh]" {channel="keba:kecontact:1:totalconsumption"}
+Switch KebaInputSwitch {channel="keba:kecontact:1:input"}
+Switch KebaOutputSwitch {channel="keba:kecontact:1:output"}
+Number:Energy KebaSetEnergyLimit "Set charge energy limit [%.1f Wh]" {channel="keba:kecontact:1:setenergylimit"}
```
demo.sitemap:
-```
+```perl
sitemap demo label="Main Menu"
{
- Text label="Charging Station" {
- Text item=KebaState
- Text item=KebaUptime
- Switch item=KebaSwitch
- Switch item=KebaWallboxPlugged
- Switch item=KebaVehiclePlugged
- Switch item=KebaPlugLocked
- Slider item=KebaCurrentRange
- Text item=KebaCurrent
- Text item=KebaSystemCurrent
- Text item=KebaFailSafeCurrent
- Text item=KebaSessionEnergy
- Text item=KebaTotalEnergy
- Switch item=KebaSetEnergyLimit
- }
+ Text label="Charging Station" {
+ Text item=KebaState
+ Text item=KebaUptime
+ Switch item=KebaSwitch
+ Switch item=KebaWallboxPlugged
+ Switch item=KebaVehiclePlugged
+ Switch item=KebaPlugLocked
+ Slider item=KebaCurrentRange
+ Text item=KebaCurrent
+ Text item=KebaSystemCurrent
+ Text item=KebaFailSafeCurrent
+ Text item=KebaSessionEnergy
+ Text item=KebaTotalEnergy
+ Switch item=KebaSetEnergyLimit
+ }
}
```
Enable `DEBUG` or `TRACE` (even more verbose) logging for the logger named:
- org.openhab.binding.keba
+```text
+org.openhab.binding.keba
+```
If everything is working fine, you see the cyclic reception of `report 1`, `2` & `3` from the station. The frequency is according to the `refreshInterval` configuration.
### UDP Ports used
- Send port = UDP 7090
+```text
+Send port = UDP 7090
+```
The Keba station is the server
- Receive port = UDP 7090
+```text
+Receive port = UDP 7090
+```
This binding is providing the server
UDP port 7090 needs to be available/free on the openHAB server.
-
In order to enable the UDP port 7090 on the Keba station with full functionality, `DIP switch 1.3` must be `ON`.
With `DIP switch 1.3 OFF` only ident-data can be read (`i` and `report 1`) but not the other reports as well as the commands needed for the write access.
After setting the DIP switch, you need to `power OFF` and `ON` the station. SW-reset via WebGUI seems not to be sufficient in order to apply the new configuration.
-
The right configuration can be validated as follows:
- WebGUI DSW Settings:
# KM200 Binding
-The KM200 Binding is communicating with a [Buderus Logamatic web KM200 / KM100 / KM50](https://www.buderus.de/de/produkte/catalogue/alle-produkte/7719_gateway-logamatic-web-km200-km100-km50).
+The KM200 Binding is communicating with a [Buderus Logamatic web KM200 / KM100 / KM50](https://www.buderus.de/de/produkte/catalogue/alle-produkte/7719_gateway-logamatic-web-km200-km100-km50).
It is possible to receive and send parameters like string or float values.
-**Important**: If the communication is not working and you see in the logfile errors like "illegal key size" then you have to change the [Java Cryptography Extension to the Unlimited Strength Jurisdiction](https://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html).
+**Important**: If the communication is not working and you see in the logfile errors like "illegal key size" then you have to change the [Java Cryptography Extension to the Unlimited Strength Jurisdiction](https://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html).
## Supported Things
### kmdevice
-The *kmdevice* bridge requires the following configuration parameters:
+The _kmdevice_ bridge requires the following configuration parameters:
| Parameter Label | Parameter ID | Description | Required | Default | Example |
|---------------------------|-----------------|-----------------------------------------------------------------------------------|----------|----------------------|------------------------------------------------------------------|
`things/kmxxx.things`:
-```xtend
+```java
Bridge km200:kmdevice:0815 "testKMDevice" @ "Room" [ privateKey= "1234567890abcdef1234567890abcdef", maxnbrrepeats=10.0, readDelay=100, refreshInterval=30, maxNbrRepeats=10, ip4Address="192.168.1.111", refreshinterval=30.0, readdelay=100.0 ] {
- heatingCircuit 1 "TestHC1"
- sensor 1 "TestSensors"
+ heatingCircuit 1 "TestHC1"
+ sensor 1 "TestSensors"
}
```
`items/kmxxx.items`:
-```xtend
+```java
Number budWater "Water temperature [%.1f °C]" {channel="km200:dhwCircuit:0815:1:actualTemp"}
Number budOutdoor "Outdoor temperature [%.1f °C]" {channel="km200:sensor:0815:1:outdoor_t1"}
```
## Supported Things
The KNX binding supports two types of bridges, and one type of things to access the KNX bus.
-There is an *ip* bridge to connect to KNX IP Gateways, and a *serial* bridge for connection over a serial port to a host-attached gateway.
+There is an _ip_ bridge to connect to KNX IP Gateways, and a _serial_ bridge for connection over a serial port to a host-attached gateway.
## Binding Configuration
### IP Gateway
-The IP Gateway is the most commonly used way to connect to the KNX bus. At its base, the *ip* bridge accepts the following configuration parameters:
+The IP Gateway is the most commonly used way to connect to the KNX bus. At its base, the _ip_ bridge accepts the following configuration parameters:
| Name | Required | Description | Default value |
|---------------------|--------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
| tunnelUserPassword | No | KNX secure: Tunnel user key for secure tunnel mode | - |
| tunnelDeviceAuthentication | No | KNX secure: Tunnel device authentication for secure tunnel mode | - |
-
### Serial Gateway
-The *serial* bridge accepts the following configuration parameters:
+The _serial_ bridge accepts the following configuration parameters:
| Name | Required | Description | Default value |
|---------------------|----------|--------------------------------------------------------------------------------------------------------------|---------------|
## Things
-### *device* Things
+### _device_ Things
-*basic* Things are wrappers around arbitrary group addresses on the KNX bus.
-They have no specific function in the KNX binding, except that if the *address* is defined, the binding will actively poll the Individual Address on the KNX bus to detect that the KNX actuator is reachable.
+_basic_ Things are wrappers around arbitrary group addresses on the KNX bus.
+They have no specific function in the KNX binding, except that if the _address_ is defined, the binding will actively poll the Individual Address on the KNX bus to detect that the KNX actuator is reachable.
Under normal real-world circumstances, either all devices on a bus are reachable, or the entire bus is down.
If line couplers are installed, physical device addressing might be filtered; in this case please do not specify the addresses for devices on this line.
-When *fetch* is set to true, the binding will read-out the memory of the KNX actuator in order to detect configuration data and so forth.
+When _fetch_ is set to true, the binding will read-out the memory of the KNX actuator in order to detect configuration data and so forth.
This is however an experimental feature, very prone to the actual on the KNX bus.
| Name | Required | Description | Default value |
| readInterval | N | Interval (in seconds) to actively request reading of values from the bus (0 if they should only be read once at startup) | 0 |
Different kinds of channels are defined and can be used to group together Group Addresses.
-All channels of a device share one configuration parameter defined on device level: *readInterval*, an optional parameter which indicates if 'readable' group addresses of that Channel should be read periodically at the given interval, in seconds.
+All channels of a device share one configuration parameter defined on device level: _readInterval_, an optional parameter which indicates if 'readable' group addresses of that Channel should be read periodically at the given interval, in seconds.
'Readable' group addresses are marked with an `<` in the group address definition of a Channel, see below.
All readable group addresses are queried by openHAB during startup.
If readInterval is not specified or set to 0, no further periodic reading will be triggered (default: 0).
|-----------|-------------------------------------|-------------|
| ga | Group address for the binary switch | 1.001 |
-
##### Channel Type "dimmer"
| Parameter | Description | Default DPT |
|-----------|---------------|-------------|
| ga | Group address | 9.001 |
-
Note: Using the Units Of Measurement feature of openHAB (Quantitytype) requires that the DPT value is set correctly.
Automatic type conversion will be applied if required.
|-----------|---------------|-------------|
| ga | Group address | 19.001 |
-
#### Control Channel Types
In contrast to the standard channels above, the control channel types are used for cases where the KNX bus does not own the physical state of a device.
|-----------|-------------------------------------|-------------|
| ga | Group address for the binary switch | 1.001 |
-
##### Channel Type "dimmer-control"
| Parameter | Description | Default DPT |
#### Group Address Notation
-```
+```text
<config>="[<dpt>:][<]<mainGA>[[+[<]<listeningGA>][+[<]<listeningGA>..]]"
```
The `dpt` element is optional. If omitted, the corresponding default value will be used (see the channel descriptions above).
-
## KNX Secure
> NOTE: Support for KNX Secure is partly implemented for openHAB and should be considered as experimental.
KNX IP Secure protects the traffic between openHAB and your KNX installation.
It **requires a KNX Secure Router or a Secure IP Interface** and a KNX installation **with security features enabled in ETS tool**.
-For *Secure routing* mode, the so called `backbone key` needs to be configured in openHAB.
+For _Secure routing_ mode, the so called `backbone key` needs to be configured in openHAB.
It is created by the ETS tool and cannot be changed via the ETS user interface.
- The backbone key can be extracted from Security report (ETS, Reports, Security, look for a 32-digit key) and specified in parameter `routerBackboneKey`.
-For *Secure tunneling* with a Secure IP Interface (or a router in tunneling mode), more parameters are required.
+For _Secure tunneling_ with a Secure IP Interface (or a router in tunneling mode), more parameters are required.
A unique device authentication key, and a specific tunnel identifier and password need to be available.
- All information can be looked up in ETS and provided separately: `tunnelDeviceAuthentication`, `tunnelUserPassword`.
> NOTE: **openHAB currently ignores messages with secure group addresses.**
-
## Examples
The following two templates are sufficient for almost all purposes.
knx.things:
-```xtend
+```java
Bridge knx:ip:bridge [
type="ROUTER",
autoReconnectPeriod=60 //optional, do not set <30 sec.
knx.things:
-```xtend
+```java
Bridge knx:ip:bridge [
type="TUNNEL",
ipAddress="192.168.0.111",
### Full Example
-```xtend
+```java
//TUNNEL
Bridge knx:ip:bridge [
type="TUNNEL",
knx.items:
-```xtend
+```java
Switch demoSwitch "Light [%s]" <light> { channel="knx:device:bridge:generic:demoSwitch" }
Dimmer demoDimmer "Dimmer [%d %%]" <light> { channel="knx:device:bridge:generic:demoDimmer" }
Rollershutter demoRollershutter "Shade [%d %%]" <rollershutter> { channel="knx:device:bridge:generic:demoRollershutter" }
knx.sitemap:
-```xtend
+```perl
sitemap knx label="KNX Demo Sitemap" {
Frame label="Demo Elements" {
Switch item=demoSwitch
control.things:
-```xtend
+```java
Bridge knx:serial:bridge [
serialPort="/dev/ttyAMA0",
readingPause=50,
knx.items:
-```xtend
+```java
Switch demoSwitch "Light [%s]" <light> { channel="hue:0210:bridge:1:color", channel="knx:device:bridge:generic:controlSwitch" }
Dimmer demoDimmer "Dimmer [%d %%]" <light> { channel="hue:0210:bridge:1:color", channel="knx:device:bridge:generic:controlDimmer" }
```
In order to allow Kodi to be controlled through this binding, you need to enable the Kodi application remote control feature.
Please enable "Allow remote control from applications on this/other systems" in the Kodi settings menu under:
-* Settings ➔ Services ➔ Control ➔
- * Allow remote control from applications on **this** systems
- * Allow remote control from applications on **other** systems
+- Settings ➔ Services ➔ Control ➔
+ - Allow remote control from applications on **this** systems
+ - Allow remote control from applications on **other** systems
To make use of the auto-discovery feature, you additionally need to enable "Allow control of Kodi via UPnP" in the Kodi settings menu.
-* Settings ➔ Services ➔ UPnP / DLNA ➔ Allow remote control via UPnP
+- Settings ➔ Services ➔ UPnP / DLNA ➔ Allow remote control via UPnP
## Supported Things
Auto-discovery is enabled by default.
To disable it, you can add the following line to `<openHAB-conf>/services/runtime.cfg`:
-```
+```text
discovery.kodi:background=false
```
A manual setup through a `things/kodi.things` file could look like this:
-```
+```java
Thing kodi:kodi:myKodi "Kodi" @ "Living Room" [ipAddress="192.168.1.100", port=9090, httpPort=8080]
```
| input | String | Sends a key stroke to Kodi to navigate in the UI. Valid commands are: `Back`, `ContextMenu`, `Down`, `Home`, `Info`, `Left`, `Right`, `Select`, `ShowCodec`, `ShowOSD`, `ShowPlayerProcessInfo` and `Up`. `ExecuteAction` and `SendText` should be used with the dedicated channels `inputaction` and `inputtext`. |
| inputtext | String | Sends a generic input (unicode) text to Kodi. |
| inputaction | String | Sends a predefined action to Kodi to control the UI and/or perform other tasks. Valid commands are: `left`, `right`, `up`, `down`, `pageup`, `pagedown`, `select`, `highlight`, `parentdir`, `parentfolder`, `back`, `menu`, `previousmenu`, `info`, `pause`, `stop`, `skipnext`, `skipprevious`, `fullscreen`, `aspectratio`, `stepforward`, `stepback`, `bigstepforward`, `bigstepback`, `chapterorbigstepforward`, `chapterorbigstepback`, `osd`, `showsubtitles`, `nextsubtitle`, `cyclesubtitle`, `playerdebug`, `codecinfo`, `playerprocessinfo`, `nextpicture`, `previouspicture`, `zoomout`, `zoomin`, `playlist`, `queue`, `zoomnormal`, `zoomlevel1`, `zoomlevel2`, `zoomlevel3`, `zoomlevel4`, `zoomlevel5`, `zoomlevel6`, `zoomlevel7`, `zoomlevel8`, `zoomlevel9`, `nextcalibration`, `resetcalibration`, `analogmove`, `analogmovex`, `analogmovey`, `rotate`, `rotateccw`, `close`, `subtitledelayminus`, `subtitledelay`, `subtitledelayplus`, `audiodelayminus`, `audiodelay`, `audiodelayplus`, `subtitleshiftup`, `subtitleshiftdown`, `subtitlealign`, `audionextlanguage`, `verticalshiftup`, `verticalshiftdown`, `nextresolution`, `audiotoggledigital`, `number0`, `number1`, `number2`, `number3`, `number4`, `number5`, `number6`, `number7`, `number8`, `number9`, `smallstepback`, `fastforward`, `rewind`, `play`, `playpause`, `switchplayer`, `delete`, `copy`, `move`, `screenshot`, `rename`, `togglewatched`, `scanitem`, `reloadkeymaps`, `volumeup`, `volumedown`, `mute`, `backspace`, `scrollup`, `scrolldown`, `analogfastforward`, `analogrewind`, `moveitemup`, `moveitemdown`, `contextmenu`, `shift`, `symbols`, `cursorleft`, `cursorright`, `showtime`, `analogseekforward`, `analogseekback`, `showpreset`, `nextpreset`, `previouspreset`, `lockpreset`, `randompreset`, `increasevisrating`, `decreasevisrating`, `showvideomenu`, `enter`, `increaserating`, `decreaserating`, `setrating`, `togglefullscreen`, `nextscene`, `previousscene`, `nextletter`, `prevletter`, `jumpsms2`, `jumpsms3`, `jumpsms4`, `jumpsms5`, `jumpsms6`, `jumpsms7`, `jumpsms8`, `jumpsms9`, `filter`, `filterclear`, `filtersms2`, `filtersms3`, `filtersms4`, `filtersms5`, `filtersms6`, `filtersms7`, `filtersms8`, `filtersms9`, `firstpage`, `lastpage`, `guiprofile`, `red`, `green`, `yellow`, `blue`, `increasepar`, `decreasepar`, `volampup`, `volampdown`, `volumeamplification`, `createbookmark`, `createepisodebookmark`, `settingsreset`, `settingslevelchange`, `stereomode`, `nextstereomode`, `previousstereomode`, `togglestereomode`, `stereomodetomono`, `channelup`, `channeldown`, `previouschannelgroup`, `nextchannelgroup`, `playpvr`, `playpvrtv`, `playpvrradio`, `record`, `togglecommskip`, `showtimerrule`, `leftclick`, `rightclick`, `middleclick`, `doubleclick`, `longclick`, `wheelup`, `wheeldown`, `mousedrag`, `mousemove`, `tap`, `longpress`, `pangesture`, `zoomgesture`, `rotategesture`, `swipeleft`, `swiperight`, `swipeup`, `swipedown`, `error`, `noop`. |
-| inputbuttonevent | String | Send a button press event. The parameter can have the format "`<button>`", "`<button>;<keymap>`" or "`<button>;<keymap>;<holdtime>`". For details see https://kodi.wiki/view/JSON-RPC_API/v12#Input.ButtonEvent |
+| inputbuttonevent | String | Send a button press event. The parameter can have the format "`<button>`", "`<button>;<keymap>`" or "`<button>;<keymap>;<holdtime>`". For details see <https://kodi.wiki/view/JSON-RPC_API/v12#Input.ButtonEvent> |
| inputrequested | Switch | Indicates whether Kodi is currently asking the user for input |
| screensaver | Switch | Current state of the Screensaver |
| systemcommand | String | This channel allows to send system commands to `Shutdown`, `Suspend`, `Hibernate`, `Reboot` or `Quit` Kodi (channel's state options contains available system commands) |
| subtitle-enabled | Switch | Display/hidden subtitle |
| subtitle-index | Number | Set or get subtitle index of currently playing media |
| subtitle-language | String | Display subtitle language of currently playing media |
-| subtitle-name | String | Display subtitle title of currently playing media |
+| subtitle-name | String | Display subtitle title of currently playing media |
| audio-index | Number | Audio stream index of currently playing media |
| audio-codec | String | Audio codec of currently playing media **(Advanced)** |
| audio-language | String | Display language of currently playing audio stream **(Advanced)** |
-| audio-name | String | Display title of currently playing audio stream **(Advanced)** |
-| audio-channels | Number | Display channels of currently playing audio stream **(Advanced)** |
+| audio-name | String | Display title of currently playing audio stream **(Advanced)** |
+| audio-channels | Number | Display channels of currently playing audio stream **(Advanced)** |
| video-codec | String | Video codec of currently playing media **(Advanced)** |
| video-index | Number | Index of currently playing multi stream video **(Advanced)** |
| video-height | Number | Height of currently playing video **(Advanced)** |
Kodi things are extensible by channels of type `shownotification`, so that different notification pop-ups can be configured for different use cases.
-
### Channel Configuration
**group** The PVR channels can be put into user-defined PVR channel groups.
# Konnected Binding
-This binding is for interacting with a [Konnected Alarm Panel](https://konnected.io/).
-Konnected Alarm Panels can connect to security sensors directly or interface with existing alarm panels.
-Konnected is an open-source firmware and software that runs on a NodeMCU.
+This binding is for interacting with a [Konnected Alarm Panel](https://konnected.io/).
+Konnected Alarm Panels can connect to security sensors directly or interface with existing alarm panels.
+Konnected is an open-source firmware and software that runs on a NodeMCU.
The Konnected hardware is designed for an alarm panel installation, but the general purpose firmware/software can be run on a generic NodeMCU device.
## Supported Things
## Thing Configuration
-The binding attempts to discover The Konnected Alarm Panels via the UPnP service.
-The auto-discovery service of the binding will detect the base URL of the Konnected Alarm Panel.
-When manually adding things, the base URL of the Konnected Alarm Panel will need to be configured.
-The base URL should include scheme, address and port (for example http://192.168.1.123:9123).
+The binding attempts to discover The Konnected Alarm Panels via the UPnP service.
+The auto-discovery service of the binding will detect the base URL of the Konnected Alarm Panel.
+When manually adding things, the base URL of the Konnected Alarm Panel will need to be configured.
+The base URL should include scheme, address and port (for example `http://192.168.1.123:9123`).
The binding will attempt to obtain the ip address of your openHAB server as configured in the OSGi framework.
If it is unable to determine the IP address it will also attempt to use the network address service to obtain the IP address and port.
-Auto-discovery of the callback URL will fail if you are using reverse proxies and/or HTTPS for your openHAB server.
-In this case you will need to configure the callback URL in the advanced configuration section.
-The callback URL will normally end with /konnected (for example https://192.168.1.2/konnected).
+Auto-discovery of the callback URL will fail if you are using reverse proxies and/or HTTPS for your openHAB server.
+In this case you will need to configure the callback URL in the advanced configuration section.
+The callback URL will normally end with /konnected (for example `https://192.168.1.2/konnected`).
In addition you can also turn off discovery which when this setting is synced to the module will cause the device to no longer respond to UPnP requests as documented.
-https://help.konnected.io/support/solutions/articles/32000023968-disabling-device-discovery
+<https://help.konnected.io/support/solutions/articles/32000023968-disabling-device-discovery>
Please use this setting with caution and do not disable until a static ip address has been provided for your Konnected Alarm Panel via DHCP, router or otherwise.
The blink setting will disable the transmission LED on the Konnected Alarm Panel.
-
## Channels
You will need to add channels for the zones that you have connected and configure them with the appropriate configuration parameters for each channel.
A note about the Alarm Panel Pro.
Zones 1-8 can be configured for any Channel-Types.
Zones 9-12, out1, alarm1 and out2/alarm2 can only be configured as an actuator.
-For more information, see: https://help.konnected.io/support/solutions/articles/32000028978-alarm-panel-pro-inputs-and-outputs
+For more information, see: <https://help.konnected.io/support/solutions/articles/32000028978-alarm-panel-pro-inputs-and-outputs>
DSB1820 temperature probes.
These are one wire devices which can all be Konnected to the same "Zone" on the Konnected Alarm Panel.
The default behavior in absence of this configuration will be to simply log the address of the received event.
A channel should be added for each probe, as indicated above and configured with the appropriate address.
-
## Full Example
*.items
-```
+```java
Switch Siren "Siren" {channel="konnected:wifi-module:generic:siren"}
Switch Back_Door_Sensor "Back Door" {channel="konnected:pro-module:generic:backd"}
```
*.sitemap
-```
+```perl
Switch item=Back_Door_Sensor label="Back Door" icon="door" mappings=[OPEN="Open", CLOSED="Closed"]
Switch item=Siren label="Alarm Siren" icon="Siren" mappings=[ON="Open", OFF="Closed"]
```
*.things
-```
+```java
Thing konnected:wifi-module:generic "Konnected Module" [baseUrl="http://192.168.30.153:9586", macAddress="1586517"]{
Type switch-wifi : frontd "Front Door" [zone="1"]
Type actuator-wifi : siren "Siren" [zone="2", momentary = 50, times = 2, pause = 50]
Type temperature-pro : outhum "Outside Temperature (DS18B20)" [zone="4", dht22 = false, pollInterval = 1, ds18b20Address = "XX:XX:XX:XX:XX:XX:XX"]
}
```
-
Currently supported things are:
-* PIKO IQ 4.2
-* PIKO IQ 5.5
-* PIKO IQ 7.0
-* PIKO IQ 8.5
-* PIKO IQ 10.0
-* PLENTICORE plus 4.2 (with or without battery attached)
-* PLENTICORE plus 5.5 (with or without battery attached)
-* PLENTICORE plus 7.0 (with or without battery attached)
-* PLENTICORE plus 8.5 (with or without battery attached)
-* PLENTICORE plus 10.0 (with or without battery attached)
+- PIKO IQ 4.2
+- PIKO IQ 5.5
+- PIKO IQ 7.0
+- PIKO IQ 8.5
+- PIKO IQ 10.0
+- PLENTICORE plus 4.2 (with or without battery attached)
+- PLENTICORE plus 5.5 (with or without battery attached)
+- PLENTICORE plus 7.0 (with or without battery attached)
+- PLENTICORE plus 8.5 (with or without battery attached)
+- PLENTICORE plus 10.0 (with or without battery attached)
Others may be supported (like future devices using the same SCB or offering the same Web API, branded OEM devices, ...), but they were not tested!
-Kostal bindings to third generation devices require Java's strong cryptography to be enabled in order to establish connections. In case you are allowed to use
-strong cryptography in your country, you can achieve this by modifying the $JAVA_HOME/jre/lib/security/java.security file (find the line *crypto.policy=limited* and set it to *unlimited*).
-If you're using the official openHAB docker image you may also enable Java's strong cryptography by specifying an environment variable *CRYPTO_POLICY="unlimited"*.
+Kostal bindings to third generation devices require Java's strong cryptography to be enabled in order to establish connections. In case you are allowed to use
+strong cryptography in your country, you can achieve this by modifying the $JAVA_HOME/jre/lib/security/java.security file (find the line _crypto.policy=limited_ and set it to _unlimited_).
+If you're using the official openHAB docker image you may also enable Java's strong cryptography by specifying an environment variable _CRYPTO_POLICY="unlimited"_.
## Discovery
### First generation devices (PIKO)
-- acPower
-- totalEnergy
-- dayEnergy
-- status
-- str1Voltage
-- str1Current
-- str2Voltage
-- str2Current
-- l1Voltage
-- l1Power
-- l2Voltage
-- l2Power
-- l3Voltage
-- l3Power
+- acPower
+- totalEnergy
+- dayEnergy
+- status
+- str1Voltage
+- str1Current
+- str2Voltage
+- str2Current
+- l1Voltage
+- l1Power
+- l2Voltage
+- l2Power
+- l3Voltage
+- l3Power
### Second generation devices (PIKO 10-20, PIKO NEW GENERATION)
| Channel Type ID | Item Type | Description | Read Write |
-|------------------------------------------|--------------------------|----------------------------------------------------------------------------------|:----------:|
-| device-local-grid-output-power | Number:Power | Current output power to the grid | R |
-| statistic-yield-day-second-gen | Number:Energy | Total produced power today | R |
+|------------------------------------------|--------------------------|----------------------------------------------------------------------------------|:----------:|
+| device-local-grid-output-power | Number:Power | Current output power to the grid | R |
+| statistic-yield-day-second-gen | Number:Energy | Total produced power today | R |
| statistic-yield-total-second-gen | Number:Energy | Total produced power | R |
| device-local-operating-status | Number:Dimensionless | Current operating status, 0 = Standby, 3 = WO-IDLE | R |
| device-local-grid-voltage-l1 | Number:ElectricPotential | Current output voltage to the grid, L1 | R |
| statistic-operating-time-total | Number:Time | Total operating time | R |
| device-local-current | Number:ElectricCurrent | Current | R |
| device-local-current-dir | Number:Dimensionless | Current direction of loading/unloading the battery | R |
-| device-local-charge-cycles | Number:Dimensionless | Total number of charge cycles | R |
+| device-local-charge-cycles | Number:Dimensionless | Total number of charge cycles | R |
| device-local-battery-temperature | Number:Temperature | Battery current temperature | R |
| device-local-loginterval | Number:Time | Value for loginterval | R |
-| device-local-s0-inpulse-cnt | Number:Dimensionless | S0-pulse counter | R |
+| device-local-s0-inpulse-cnt | Number:Dimensionless | S0-pulse counter | R |
| statistic-own-cons-rate-total | Number:Dimensionless | Total own comsumption rate | R |
| statistic-autonomy-degree-total | Number:Dimensionless | Total autonomy degree | R |
| device-local-battery-voltage | Number:ElectricPotential | Battery current voltage | R |
The following Channels are writeable
| Channel Type ID | Item Type | Description | Read Write |
-|------------------------------------------|--------------------------|----------------------------------------------------------------------------------|:----------:|
+|------------------------------------------|--------------------------|----------------------------------------------------------------------------------|:----------:|
| device-local-battery-usage-consumption-set| String | Battery usage consumption level for power-consumption from battery, value = 100 (W) | W |
-| device-local-battery-usage-strategy-set | String | Battery usage strategy, Value = 1 = Automatic, Value = 2 = Automatic economical | W |
+| device-local-battery-usage-strategy-set | String | Battery usage strategy, Value = 1 = Automatic, Value = 2 = Automatic economical | W |
| device-local-smart-battery-control-set | Switch | Smart battery control, Value = OFF / ON | W |
| device-local-battery-charge-time-from-set| String | Battery charge time from, Value = 00:00 | W |
| device-local-battery-charge-time-to-set | String | Battery charge time to, Value = 23:59 | W |
| device-local-shadow-management-set | String | Shadow management, Value = 0 = No shadow management enabled, Value = 1 = Shadow management enabled for DC-Input String 1, Value = 2 = Shadow management enabled for DC-Input String 2, Value = 3 = Shadow management enabled for DC-Input String 1 and 2 | W |
| device-local-external-module-control-set | String | External module control, Value = 0 = Not Activated, Value = 1 = Activated | W |
-
### Third generation devices (PIKO IQ / PLENTICORE plus)
| Channel Type ID | Item Type | Description | Read Write |
demo.things
-```
+```java
Thing kostalinverter:kostalinverter:inverter [ url="http://192.168.0.128" ]
```
In case it is offline you should see an error message.
You optionally can define a `userName` and a `password` parameter if the access to the webinterface is protected and a desired `refreshInterval` (the time interval between updates, default 60 seconds).
-
### Second generation devices (PIKO 10-20, PIKO NEW GENERATION)
Second generation inverters require 4 mandatory parameters and 1 optional (hasBattery):
| username | Username for your inverter | Text | --- | --- | myUsername |
| password | Password for your inverter | Text | --- | --- | myPassword |
| refreshInterval | Pollingintervall of your inverter | Integer | Seconds | 60 | 60 |
-| hasBattery | Type of PIKO 10-20 inverter, with or without battery | boolean | --- | -- | false/true |
+| hasBattery | Type of PIKO 10-20 inverter, with or without battery | boolean | --- | -- | false/true |
demo.things
-```
-
+```java
Thing kostalinverter:piko1020:mypiko1020 [ url="http://'inverter-ip'", username="'myUsername'", password="'myPassword'", refreshInterval=60, hasBattery=false]
-
```
You can define which type of PIKO10-20 inverter you will connect to with parameter hasBattery.
-
-
### Third generation devices (PIKO IQ / PLENTICORE plus)
All third generation inverters require to define 3 mandatory configuration parameters:
Full sample of thing configuration:
-```
+```java
Thing kostalinverter:PLENTICOREPLUS100WITHBATTERY:MyPlentiCore100WithBattery [ url = "192.168.1.2", userPassword="myPassword", refreshInternalInSeconds="30"]
```
demo.items:
-```
+```java
Number:Power SolarPower "Solar power [%.1f %unit%]" <energy> { channel="kostalinverter:kostalinverter:inverter:acPower" }
Number:Energy SolarEnergyDay "Solar day energy [%.3f %unit%]" <energy> { channel="kostalinverter:kostalinverter:inverter:dayEnergy" }
Number:Energy SolarTotalEnergy "Solar total energy [%.3f %unit%]" <energy> { channel="kostalinverter:kostalinverter:inverter:totalEnergy" }
String SolarStatus "Solar status [%s]" <energy> { channel="kostalinverter:kostalinverter:inverter:status" }
```
-
### Second generation devices (PIKO NEW GENERATION)
demo.items:
-```
+```java
Number:Power GridOutputPower "Grid Output Power" <energy> { channel="kostalinverter:piko1020:mypiko1020:gridOutputPower" }
Number:Energy YieldDaySecondGen "PV Output Power Day" <energy> { channel="kostalinverter:piko1020:mypiko1020:yieldDaySecondGen" }
Number:Energy YieldTotalSecondGen "PV Output Power Total" <energy> { channel="kostalinverter:piko1020:mypiko1020:yieldTotalSecondgen" }
demo.items:
-```
-
+```java
Number:Energy MyPlentiCore100WithBattery_DEVICE_LOCAL_DC_POWER <energy> { channel="kostalinverter:PLENTICOREPLUS100WITHBATTERY:MyPlentiCore100WithBattery:deviceLocalDCPower"}
Number:Energy MyPlentiCore100WithBattery_DEVICE_LOCAL_HOMECONSUMPTION_FROM_BATTERY <energy> { channel="kostalinverter:PLENTICOREPLUS100WITHBATTERY:MyPlentiCore100WithBattery:deviceLocalHomeconsumptionFromBattery"}
Number:Energy MyPlentiCore100WithBattery_DEVICE_LOCAL_HOMECONSUMPTION_FROM_GRID <energy> { channel="kostalinverter:PLENTICOREPLUS100WITHBATTERY:MyPlentiCore100WithBattery:deviceLocalHomeconsumptionFromGrid"}
```
-
### Rules
Second generation devices (PIKO 10-20, PIKO NEW GENERATION)
-
-```
-
Ex. Set Smart battery control OFF with cron trigger:
+```yaml
triggers:
id: "1"
configuration:
type: application/vnd.openhab.dsl.rule
script: KOSTALPIKO1020_SmartBatteryControlSet.sendCommand("OFF")
type: script.ScriptAction
-
-
+```
### Example Call for Stop 'Gottesauer Platz/BGV'
-```bash
+```shell
export QUERY="gottesauer"
curl https://www.kvv.de/tunnelEfaDirect.php?action=XSLT_STOPFINDER_REQUEST&name_sf=${QUERY}&outputFormat=JSON&type_sf=any
```
The LaMetric binding allows to connect openHAB to LaMetric Time connected clock devices, providing following features:
-* Control the LaMetric Time Device
- * Control Display Brightness
- * Change Audio Volume
- * Enable / Disable Bluetooth
- * Activate an Application
-* Send notifications messages
-* Control the core (built-in) apps
+- Control the LaMetric Time Device
+ - Control Display Brightness
+ - Change Audio Volume
+ - Enable / Disable Bluetooth
+ - Activate an Application
+- Send notifications messages
+- Control the core (built-in) apps
## Supported Things
### Sample Thing Configuration
-```
+```java
Bridge lametrictime:device:demo [ host="somehost", apiKey="ksfjsdkfsksjfs" ]
{
Thing clockApp clock [ widgetId="generatedcorewidgetid1" ]
To post messages to these channels, simply map them to a String item, e.g. like this:
-```
+```java
String DeviceNotifyInfo "Info Message" {channel="lametrictime:device:demo:info"}
```
-By setting a text on the item, the binding will send the notification which is then shown on the LaMetric device.
+By setting a text on the item, the binding will send the notification which is then shown on the LaMetric device.
In a rule this can be done the following way:
-```
+```java
DeviceNotifyInfo.sendCommand("My Information Message to be displayed")
```
## Items
-
+
Sample item configuration:
-
-```
+
+```java
Dimmer DeviceBrightness "Brightness" { channel="lametrictime:device:demo:brightness" }
String DeviceBrightnessMode "Brightness Mode" { channel="lametrictime:device:demo:brightnessMode" }
Dimmer DeviceVolume "Volume" { channel="lametrictime:device:demo:volume" }
**Note:** Populating switch or selection options automatically from the state description is not currently possible with sitemaps.
For this reason, the brightness modes and example applications are repeated here.
-```
+```perl
Text label="LaMetric Time Demo" {
Frame label="Device Controls" {
Slider item=DeviceBrightness
Sample rules:
-```
+```java
import java.util.Calendar
rule "Notify Info"
### Thing: LCN Module
-Any LCN module that should be controlled or visualized, need to be added to openHAB as a *Thing*.
+Any LCN module that should be controlled or visualized, need to be added to openHAB as a _Thing_.
LCN modules with firmware versions 120612 (2008), 170602 (2013) and 1F080A (2021) were tested with this binding.
Modules with older and newer firmware should work, too.
### Bridge: LCN PCK Gateway
PCK is the protocol spoken over TCP/IP with a PCK gateway to communicate with the LCN bus.
-Examples for PCK gateways are the *LCN-PCHK* software running on Windows or Linux and the DIN rail mounting device *LCN-VISU*.
+Examples for PCK gateways are the _LCN-PCHK_ software running on Windows or Linux and the DIN rail mounting device _LCN-VISU_.
-For each LCN bus, interfaced to openHAB, a PCK gateway needs to be added to openHAB as a *Thing*.
+For each LCN bus, interfaced to openHAB, a PCK gateway needs to be added to openHAB as a _Thing_.
Several PCK gateways can be added to openHAB to control multiple LCN busses in distinct locations.
### Thing: LCN Group
-LCN modules can be assigned to groups with the programming software *LCN-PRO*.
+LCN modules can be assigned to groups with the programming software _LCN-PRO_.
-To send commands to an LCN group, the group needs to be added to openHAB as a *Thing*.
+To send commands to an LCN group, the group needs to be added to openHAB as a _Thing_.
One LCN module within the group is used to represent the status of the whole group.
-For example, when a Dimmer Output is controlled via a LCN group *Thing*, openHAB will always visualize the state of the Dimmer Output of the chosen module. The states of the other modules in the group are ignored for visualization.
+For example, when a Dimmer Output is controlled via a LCN group _Thing_, openHAB will always visualize the state of the Dimmer Output of the chosen module. The states of the other modules in the group are ignored for visualization.
Thing Type ID: `group`
| `moduleId` | The module ID of any module in the group. The state of this module is used for visualization of the group as representative for all modules. | Integer | Yes |
| `segmentId` | The segment ID of all modules in this group (0 if no segments are present) | Integer | Yes |
-The `groupId` must match the previously configured group number in the programming software *LCN-PRO*.
+The `groupId` must match the previously configured group number in the programming software _LCN-PRO_.
## Discovery
If not all LCN modules get listed on the first run, click on the refresh button to start another scan.
-When adding a module by discovery, the new *Thing*'s UID will be a combination of segment and module id using the following format:
+When adding a module by discovery, the new _Thing_'s UID will be a combination of segment and module id using the following format:
`S<segmentId>M<moduleId>` where `segmentId` and `moduleId` are formatted as three-digit numbers with leading zeros.
### Discover PCK Gateways
The discovery works only if the firewall of the PCK gateway is not configured too strictly.
This means on Windows PCs, that the network must be configured as 'private' and not as 'public'.
Also, some network switches may block multicast packets.
-Unfortunately, *LCN-PCHK* listens only on the first network interface of the computer for discovery packets.
-If your PCK gateway has multiple network interfaces, *LCN-PCHK* may listen on the wrong interface and fails to respond to the discovery request.
+Unfortunately, _LCN-PCHK_ listens only on the first network interface of the computer for discovery packets.
+If your PCK gateway has multiple network interfaces, _LCN-PCHK_ may listen on the wrong interface and fails to respond to the discovery request.
Discovery has successfully been tested with LCN-PCHK 3.2.2 running on a Raspberry Pi with Raspbian and openHAB running on Windows 10.
Please be aware that you **have to configure** username, password and the dimmer output resolution also if you use discovery.
See [Thing: PCK Gateway](#bridge-lcn-pck-gateway).
-When adding a PCK gateway by discovery, the new *Thing*'s UID is the MAC address of the device, running the PCK gateway.
+When adding a PCK gateway by discovery, the new _Thing_'s UID is the MAC address of the device, running the PCK gateway.
## Supported LCN Features and openHAB Channels
The following table lists all features of LCN and their mappings to openHAB Channels.
-These Channels are available for the *Thing* LCN module (`module`).
+These Channels are available for the _Thing_ LCN module (`module`).
LCN group (`group`) has the same Channels, except status-only Channels like binary sensors or transponders.
The PCK gateway (`pckGateway`) has no Channels.
| Remote Control | Fernbedienung | code#remotecontrolkey | | Trigger | Receive commands from remote control |
| Access Control | Zutrittskontrolle | code#remotecontrolcode | | Trigger | Receive serial numbers from remote control |
| Remote Control Battery Low | Fernbedienung Batterie schwach | code#remotecontrolbatterylow | | Trigger | Triggered when the sending remote control has a low battery |
-| Host Command (Send Keys) | Kommando an Host (Sende Tasten) | hostcommand#sendKeys | - | Trigger | Receive *send keys* command from LCN module |
+| Host Command (Send Keys) | Kommando an Host (Sende Tasten) | hostcommand#sendKeys | - | Trigger | Receive _send keys_ command from LCN module |
| Operating Hours Counter Outputs | Betriebsstundenzähler Ausgänge | operatinghourscounter | output[1-4] | Number:Time | Visualize Operating Hours Counter for outputs |
| Operating Hours Counter Outputs (rel. Work) | Betriebsstundenzähler Ausgänge (rel. Arbeit) | operatinghourscounter | outputrelativework[1-4] | Number:Time | Visualize Operating Hours Counter for outputs (relative work) |
| Operating Hours Counter Relays | Betriebsstundenzähler Relais | operatinghourscounter | relay[1-8] | Number:Time | Visualize Operating Hours Counter for relays |
| Set S0 Counters | S0-Zähler setzen | - | - | - | Not implemented |
| Status Command | Statuskommandos | - | - | - | Not implemented |
-*Notes:*
+_Notes:_
-- **For some *Channel*s (e.g. temperature) a unit should be configured in the channel configuration.** By default the native LCN value is used.
+- **For some _Channel_s (e.g. temperature) a unit should be configured in the channel configuration.** By default the native LCN value is used.
- S0 counter Channels need to be the pulses per kWh configured. If the value is left blank, a default value of 1000 pulses/kWh is set.
- When setting a variable via openHAB, the variable must be configured as counter in LCN-PRO. The variable must be set initially by the module after power up.
- The Rollershutter Channels provide the boolean parameter `invertUpDown`, which can be set to 'true' if the Up/Down wires are interchanged.
### Transponder/Fingerprints
LCN transponder readers or fingerprint readers can be integrated in openHAB e.g. for access control.
-The transponder function must be enabled in the module's I-port properties within *LCN-PRO*.
+The transponder function must be enabled in the module's I-port properties within _LCN-PRO_.
Example: When the transponder card with the ID "12ABCD" is seen by the reader connected to LCN module "S000M011", the item "M10_Relay7" is switched on:
-```
+```java
rule "My Transponder"
when
Channel "lcn:module:b827ebfea4bb:S000M011:code#transponder" triggered "12ABCD"
Example: When fingerprint with ID "AFFE12" is seen by reader connected to LCN module "S000M011", the item "M10_Relay7" is switched on:
-```
+```java
rule "My Fingerprint"
when
Channel "lcn:module:b827ebfea4bb:S000M011:code#fingerprint" triggered "AFFE12"
LCN modules can send commands to openHAB, e.g. by pressing a physical LCN key.
The command must be programmed into the LCN module by the programming software LCN-PRO.
-Only the *send keys* command (German: "Sende Tasten") is supported.
+Only the _send keys_ command (German: "Sende Tasten") is supported.
Program a command to a key of an LCN module via LCN-PRO.
When LCN-PRO asks you for the target address, don't select any module, but manually enter the PCK host ID, configured within PCHK (default: 4).
-Select the *send keys* command and "A-C (former command)", as PCHK 3.2.2 only supports the old command.
+Select the _send keys_ command and "A-C (former command)", as PCHK 3.2.2 only supports the old command.
Then, select any key(s) you want to send to openHAB. These can be freely chosen, as they are only evaluated by openHAB.
The following rule can be used to trigger any action:
-```
+```java
rule "Module 12 sent A1 Hit"
when
Channel "lcn:module:b827ebfea4bb:S000M012:hostcommand#sendKeys" triggered "A1:HIT"
end
```
-`A1` is the key of the *send keys* command, programmed by LCN-PRO.
+`A1` is the key of the _send keys_ command, programmed by LCN-PRO.
After the colon, the LCN "hit type" follows: HIT, MAKE or BREAK (German: kurz, lang, los)
If multiple keys or key tables are programmed in a single "send keys" command, multiple triggers will be executed.
### Remote Control
-To evaluate commands from LCN remote controls (e.g. LCN-RT or LCN-RT16), the module's I-port behavior must be configured as "IR access control" within *LCN-PRO*:
+To evaluate commands from LCN remote controls (e.g. LCN-RT or LCN-RT16), the module's I-port behavior must be configured as "IR access control" within _LCN-PRO_:
#### Remote Control Keys
-The trigger
*Channel* `lcn:module:<pckThing>:<moduleThing>:code#remotecontrolkey` can be used to execute commands, when a specific key on a remote control is pressed:
+The trigger
_Channel_ `lcn:module:<pckThing>:<moduleThing>:code#remotecontrolkey` can be used to execute commands, when a specific key on a remote control is pressed:
-```
+```java
rule "Remote Control Key 3 on Layer 1 hit"
when
Channel "lcn:module:b827ebfea4bb:S000M012:code#remotecontrolkey" triggered "A3:HIT"
The serial number of a remote control can be used for access control via the channel `lcn:module:<pckThing>:<moduleThing>:code#remotecontrolcode`. See the following example:
-```
+```java
rule "Remote Control Key 3 on Layer 1 hit (only executed for serial number AB1234)"
when
Channel "lcn:module:b827ebfea4bb:S000M012:code#remotecontrolcode" triggered "AB1234:A3:HIT" or
## Dimmer Outputs with Ramp and Multiple Outputs
-The *output* profile can be used to control multiple dimmer outputs of the *same* module simultaneously or control a dimmer output with a ramp (slowly dimming).
+The _output_ profile can be used to control multiple dimmer outputs of the _same_ module simultaneously or control a dimmer output with a ramp (slowly dimming).
-The optional *ramp* parameter must be float or integer.
+The optional _ramp_ parameter must be float or integer.
The lowest value is 0.25, which corresponds to 0.25s. The highest value is 486s.
-When no *ramp* parameter is specified or no profile is configured, the ramp is 0 (behavior like a switch).
-The ramp parameter is not available for Color *Item*s.
+When no _ramp_ parameter is specified or no profile is configured, the ramp is 0 (behavior like a switch).
+The ramp parameter is not available for Color _Item_s.
-```
+```java
// Dim output 2 in 0.25s
Switch M10_Output2 {channel="lcn:module:b827ebfea4bb:S000M010:output#2"[profile="lcn:output", ramp=0.25]} // with ramp of 0.25s (smallest value)
// Dim output 3 in 486s
Dimmer M10_Output3 {channel="lcn:module:b827ebfea4bb:S000M010:output#3"[profile="lcn:output", ramp=486]} // with ramp of 486s (biggest value)
```
-The optional parameters *controlAllOutputs* and *controlOutputs12* can be used to control multiple outputs simultaneously.
-Please note that the combination of these parameters with the *ramp* parameter is limited:
+The optional parameters _controlAllOutputs_ and _controlOutputs12_ can be used to control multiple outputs simultaneously.
+Please note that the combination of these parameters with the _ramp_ parameter is limited:
-```
+```java
// Control outputs 1+2 simultaneously. Status of Output 1 is visualized. Only ramps of 0s or 0.25s are supported.
Dimmer M10_Outputs12a {channel="lcn:module:b827ebfea4bb:S000M010:output#1"[profile="lcn:output", controlOutputs12=true]}
Dimmer M10_Outputs12b {channel="lcn:module:b827ebfea4bb:S000M010:output#1"[profile="lcn:output", controlOutputs12=true, ramp=0.25]}
### Hit Key
-This *Action* virtually hits a key of a key table in an LCN module.
+This _Action_ virtually hits a key of a key table in an LCN module.
Simply spoken, openHAB acts as a push button switch connected to an LCN module.
-This *Action* can be used to execute commands which are not natively supported by this binding.
-The function can be programmed via the software *LCN-PRO* onto a key in a module's key table.
-Then, the programmed key can be "hit" by this *Action* and the command will be executed.
+This _Action_ can be used to execute commands which are not natively supported by this binding.
+The function can be programmed via the software _LCN-PRO_ onto a key in a module's key table.
+Then, the programmed key can be "hit" by this _Action_ and the command will be executed.
-When programming a "Hit Key" *Action*, the following parameters need to be set:
+When programming a "Hit Key" _Action_, the following parameters need to be set:
-*table* - The module's key table: A, B, C or D<br />
-*key* - The number of the key within the key table: 1-8<br />
-*action* - The key's action: HIT (German: "kurz"), MAKE ("lang") or BREAK ("los")
+_table_ - The module's key table: A, B, C or D<br />
+_key_ - The number of the key within the key table: 1-8<br />
+_action_ - The key's action: HIT (German: "kurz"), MAKE ("lang") or BREAK ("los")
-```
+```java
rule "Hit key C4 hourly"
when
Time cron "0 0 * * * ?"
### Dynamic Text
-This *Action* can be used to send custom texts to an LCN-GTxD display.
-To make this function work, the row of the display has to be configured to allow dynamic text within *LCN-PRO*:
+This _Action_ can be used to send custom texts to an LCN-GTxD display.
+To make this function work, the row of the display has to be configured to allow dynamic text within _LCN-PRO_:
-When programming a "Dynamic Text" *Action*, the following parameters need to be set:
+When programming a "Dynamic Text" _Action_, the following parameters need to be set:
-*row* - The number of the row in the display: 1-4<br />
-*text* - The text to be displayed (UTF-8)
+_row_ - The number of the row in the display: 1-4<br />
+_text_ - The text to be displayed (UTF-8)
The length of the text may not exceed 60 bytes of characters.
Bear in mind that unicode characters can take more than one byte (e.g. umlauts (äöü) take two bytes).
-```
+```java
rule "Send dynamic Text to GT10D hourly"
when
Time cron "0 0 * * * ?"
### Flicker Output
-This *Action* realizes the LCN command "Output: Flicker" (German: "Ausgang: Flackern").
+This _Action_ realizes the LCN command "Output: Flicker" (German: "Ausgang: Flackern").
The command let a dimmer output flash a given number of times. This feature can be used e.g. for alert signals or visual door bells.
-When programming a "Flicker Output" *Action*, the following parameters need to be set:
+When programming a "Flicker Output" _Action_, the following parameters need to be set:
-*output* - The dimmer output number: 1-4<br />
-*depth* - The depth of the flickering: 0-2 (0=25% 1=50% 2=100% Example: When the output is fully on (100%), and 0 is selected, flashes will dim from 100% to 75% and back)<br />
-*ramp* - The duration/ramp of one flash: 0-2 (0=2sec 1=1sec 2=0.5sec)<br />
-*count* - The number of flashes: 1-15
+_output_ - The dimmer output number: 1-4<br />
+_depth_ - The depth of the flickering: 0-2 (0=25% 1=50% 2=100% Example: When the output is fully on (100%), and 0 is selected, flashes will dim from 100% to 75% and back)<br />
+_ramp_ - The duration/ramp of one flash: 0-2 (0=2sec 1=1sec 2=0.5sec)<br />
+_count_ - The number of flashes: 1-15
-This action has also effect, if the given output is off. The output will be dimmed from 0% to *depth* and back, then.
+This action has also effect, if the given output is off. The output will be dimmed from 0% to _depth_ and back, then.
-```
+```java
rule "Flicker output 1 when window opens"
when
Item M10_BinarySensor5 changed to OPEN
### Relay Timer
-This *Action* realizes the LCN commmand "Relay Timer" (German: "Relais-Timer").
+This _Action_ realizes the LCN commmand "Relay Timer" (German: "Relais-Timer").
The command switches the given relay immediately to on and after a given time back to off.
-When programming a "Relay Timer" *Action*, the following parameters need to be set:
+When programming a "Relay Timer" _Action_, the following parameters need to be set:
-*relayNumber* - The relay number: 1-8<br />
-*duration* - Timer duration in milliseconds: 30-240.000 ms<br />
+_relayNumber_ - The relay number: 1-8<br />
+_duration_ - Timer duration in milliseconds: 30-240.000 ms<br />
-```
+```java
rule "Start relay timer for led driver when dummy switch changed"
when
Item Dummy_Switch changed
### Beep
-This *Action* realizes the LCN commmand "audio" (German: "Piepen").
+This _Action_ realizes the LCN commmand "audio" (German: "Piepen").
It lets the beeper connected to the LCN module beep.
-When programming an "audio" *Action*, the following parameters can be set:
+When programming an "audio" _Action_, the following parameters can be set:
-*volume* - Sound volume in percent (if null, the previous volume will be used)<br />
-*tonality* - The tonality as a String. You need to use quotes. See below.<br />
-*count* - Number of beeps (max. 50)
+_volume_ - Sound volume in percent (if null, the previous volume will be used)<br />
+_tonality_ - The tonality as a String. You need to use quotes. See below.<br />
+_count_ - Number of beeps (max. 50)
Tonalities:
- "6"=error
- "7"=long
-```
+```java
rule "Beep when dummy switch changed"
when
Item Dummy_Switch changed
LCN segments are supported by this binding, but could not be tested, due to lack of hardware.
-LEDs do not support the *OnOffCommand* and respectively the *Switch* Item type, because they have the additional states *BLINK* and *FLICKER*. They must be configured as *String* Item. When used in rules, the parameter must be of type string. Example: `M10_LED1.sendCommand("ON")`. Note the quotation marks.
+LEDs do not support the _OnOffCommand_ and respectively the _Switch_ Item type, because they have the additional states _BLINK_ and _FLICKER_. They must be configured as _String_ Item. When used in rules, the parameter must be of type string. Example: `M10_LED1.sendCommand("ON")`. Note the quotation marks.
## Full Example
Config `.things`
-```
+```java
Bridge lcn:pckGateway:myPCHK [ hostname="192.168.123.123", port=4114, username="myUser", password="myPassword", mode="native200" ] {
- Thing module M99 "M99 MyModule" [ moduleId=99, segmentId=0 ] {
- Channels:
+ Thing module M99 "M99 MyModule" [ moduleId=99, segmentId=0 ] {
+ Channels:
Rollershutter : rollershutterrelay#1 "My twisted rollershutter relay" [ invertUpDown = true ]
- Contact : binarysensor#6 [ invertState=true ]
- Number : rvarsetpoint#1 [ unit="temperature" ]
- Number : variable#3 [ unit="temperature" ]
- }
+ Contact : binarysensor#6 [ invertState=true ]
+ Number : rvarsetpoint#1 [ unit="temperature" ]
+ Number : variable#3 [ unit="temperature" ]
+ }
}
```
Config `.items`
-```
+```java
// Dimmer Outputs
Dimmer M10_Output1 {channel="lcn:module:b827ebfea4bb:S000M010:output#1"}
Switch M10_Output2 {channel="lcn:module:b827ebfea4bb:S000M010:output#2"[profile="lcn:output", ramp=0.25]} // with ramp of 0.25s (smallest value)
Config `.sitemap`
-```
+```perl
sitemap lcn label="My home automation" {
Frame label="Demo Items" {
// Dimmer Outputs
demo.things:
-```
+```java
Thing leapmotion:controller:1 MyLeapMotion
```
demo.items:
-```
+```java
Switch DemoSwitch "Switch" { channel="leapmotion:controller:1:gesture" }
Color RGBLight "RGB Light" { channel="leapmotion:controller:1:gesture" }
Dimmer DimmedLight "Dimmer [%d %%]" { channel="leapmotion:controller:1:gesture"[profile="leapmotion:dimmer", mode="fingers"] }
## Channels
-
| Channel Type ID | Item Type | Description | Read/Write |
|-----------------|-----------|--------------------------------------------------------------------------|------------|
| state | String | Current state of the HomBot. | R |
demo.thing
-```
+```java
Thing lghombot:LGHomBot:mycleanerbot "LGHomBot" @ "Living Room" [ ipAdress="192.168.0.2", pollingPeriod="3", port="6260" ]
```
demo.items:
-```
+```java
String HomBot_State "State [%s]" <CleaningRobot> { channel="lghombot:LGHomBot:a4_24_56_8f_2c_5b:state" }
Number HomBot_Battery "Battery [%d%%]" { channel="lghombot:LGHomBot:a4_24_56_8f_2c_5b:battery" }
Switch HomBot_Clean "Clean" { channel="lghombot:LGHomBot:a4_24_56_8f_2c_5b:clean" }
demo.sitemap:
-```
+```perl
sitemap demo label="Main Menu"
{
Frame label="HomBot" {
## Binding Configuration
-The binding has no configuration parameter.
+The binding has no configuration parameter.
## Discovery
Set host and key parameter as in the following example:
-```
+```java
Thing lgwebos:WebOSTV:tv1 [host="192.168.2.119", key="6ef1dff6c7c936c8dc5056fc85ea3aef", macAddress="3c:cd:93:c2:20:e0"]
```
| PAUSE | "PAUSE" button |
| STOP | "STOP" button |
-
A sample HABPanel remote control widget can be found [in this GitHub repository.](https://github.com/bbrodt/openhab2-misc)
## Console Commands
The binding provides a few commands you can use in the console.
Enter the command `openhab:lgwebos` to get the usage.
-```
+```shell
Usage: openhab:lgwebos <thingUID> applications - list applications
Usage: openhab:lgwebos <thingUID> channels - list channels
Usage: openhab:lgwebos <thingUID> accesskey - show the access key
demo.things:
-```
+```java
Thing lgwebos:WebOSTV:3aab9eea-953b-4272-bdbd-f0cd0ecf4a46 [host="192.168.2.119", key="6ef1dff6c7c936c8dc5056fc85ea3aef", macAddress="3c:cd:93:c2:20:e0"]
```
demo.items:
-```
+```java
Switch LG_TV0_Power "TV Power" <television> { autoupdate="false", channel="lgwebos:WebOSTV:3aab9eea-953b-4272-bdbd-f0cd0ecf4a46:power" }
Switch LG_TV0_Mute "TV Mute" { channel="lgwebos:WebOSTV:3aab9eea-953b-4272-bdbd-f0cd0ecf4a46:mute"}
Dimmer LG_TV0_Volume "Volume [%d]" { channel="lgwebos:WebOSTV:3aab9eea-953b-4272-bdbd-f0cd0ecf4a46:volume" }
demo.sitemap:
-```
+```perl
sitemap demo label="Main Menu"
{
Frame label="TV" {
}
```
-
demo.rules:
-```
+```java
// for relative volume changes
rule "VolumeUpDown"
when Item LG_TV0_VolDummy received command
end
```
-
Example of a toast message.
-```
+```java
LG_TV0_Toast.sendCommand("Hello World")
```
Example
-```
+```java
val actions = getActions("lgwebos","lgwebos:WebOSTV:3aab9eea-953b-4272-bdbd-f0cd0ecf4a46")
if(null === actions) {
logInfo("actions", "Actions not found, check thing ID")
Example:
-```
+```java
actions.showToast("Hello World")
```
Example:
-```
+```java
actions.showToast("http://localhost:8080/icon/energy?format=png","Hello World")
```
Example:
-```
+```java
actions.launchBrowser("https://www.openhab.org")
```
Examples:
-```
+```java
actions.launchApplication("com.webos.app.tvguide") // TV Guide
actions.launchApplication("com.webos.app.livetv") // TV
actions.launchApplication("com.webos.app.hdmi1") // HDMI1
Examples:
-```
+```java
actions.launchApplication("appId","{\"key\":\"value\"}")
```
Example:
-```
+```java
actions.sendText("Some text")
```
Example:
-```
+```java
actions.sendButton("HOME")
```
Example:
-```
+```java
actions.sendKeyboard("ENTER")
```
Example:
-```
+```java
actions.increaseChannel
```
Example:
-```
+```java
actions.decreaseChannel
```
In case of issues you may find it helpful to enable debug level logging and check you log file. Log into openHAB console and enable debug logging for this binding:
-```
+```shell
log:set debug org.openhab.binding.lgwebos
```
-
The binding is able to auto-discover all lights in a network over the LIFX UDP protocol.
Therefore all lights must be turned on.
-*Note:* To get the binding working, all lights must be added to the WLAN network first with the help of the [LIFX smart phone applications](https://www.lifx.com/pages/app).
+_Note:_ To get the binding working, all lights must be added to the WLAN network first with the help of the [LIFX smart phone applications](https://www.lifx.com/pages/app).
The binding is NOT able to add or detect lights outside the network.
## Thing Configuration
However, in the thing file, a manual configuration looks e.g. like
-```
+```java
Thing lifx:colorlight:living [ deviceId="D073D5A1A1A1", fadetime=200 ]
```
-The *fadetime* is an optional thing configuration parameter which configures the time to fade to a new color value (in ms).
-When the *fadetime* is not configured, the binding uses 300ms as default.
+The _fadetime_ is an optional thing configuration parameter which configures the time to fade to a new color value (in ms).
+When the _fadetime_ is not configured, the binding uses 300ms as default.
You can optionally also configure a fixed Host or IP address when lights are in a different subnet and are not discovered.
-```
+```java
Thing lifx:colorirlight:porch [ host="10.120.130.4", fadetime=0 ]
```
| colorzone | Color | This channel supports full zone color control with hue, saturation and brightness values. | colormzlight |
| effect | String | This channel represents a type of light effect (e.g. for tile light: off, morph, flame) | tilelight |
| hevcycle | Switch | This channel supports starting and stopping the HEV clean cycle. | colorhevlight |
-| infrared | Dimmer | This channel supports adjusting the infrared value. *Note:* IR capable lights only activate their infrared LEDs when the brightness drops below a certain level. | colorirlight |
+| infrared | Dimmer | This channel supports adjusting the infrared value. _Note:_ IR capable lights only activate their infrared LEDs when the brightness drops below a certain level. | colorirlight |
| signalstrength | Number | This channel represents signal strength with values 0, 1, 2, 3 or 4; 0 being worst strength and 4 being best strength. | colorlight, colorhevlight, colorirlight, colormzlight, tilelight, whitelight |
| temperature | Dimmer | This channel supports adjusting the color temperature from cold (0%) to warm (100%). | colorlight, colorhevlight, colorirlight, colormzlight, tilelight, whitelight |
| temperaturezone | Dimmer | This channel supports adjusting the zone color temperature from cold (0%) to warm (100%). | colormzlight |
-The *color* and *brightness* channels have a "Power On Brightness" configuration option that is used to determine the brightness when a light is switched on.
+The _color_ and _brightness_ channels have a "Power On Brightness" configuration option that is used to determine the brightness when a light is switched on.
When it is left empty, the brightness of a light remains unchanged when a light is switched on or off.
-The *color* channels have a "Power On Color" configuration option that is used to determine the hue, saturation, brightness levels when a light is switched on.
+The _color_ channels have a "Power On Color" configuration option that is used to determine the hue, saturation, brightness levels when a light is switched on.
When it is left empty, the color of a light remains unchanged when a light is switched on or off.
Configuration options contains 3 comma separated values, where first value is hue (0-360), second saturation (0-100) and third brightness (0-100).
If both "Power on brightness" and "Power On Color" configuration options are defined, "Power on brightness" option overrides the brightness level defined on the "Power on color" configuration option.
-The *temperature* channels have a "Power On Temperature" configuration option that is used to determine the color temperature when a light is switched on. When it is left empty, the color temperature of a light remains unchanged when a light is switched on or off.
+The _temperature_ channels have a "Power On Temperature" configuration option that is used to determine the color temperature when a light is switched on. When it is left empty, the color temperature of a light remains unchanged when a light is switched on or off.
-MultiZone lights (*colormzlight*) have several channels (e.g. *colorzone0*, *temperaturezone0*, *abstemperaturezone0*, etc.) that allow for controlling specific zones of the light.
-Changing the *color*, *temperature* and *abstemperature* channels will update the states of all zones.
-The *color*, *temperature* and *abstemperature* channels of MultiZone lights always return the same state as *colorzone0*, *temperaturezone0*, *abstemperaturezone0*.
+MultiZone lights (_colormzlight_) have several channels (e.g. _colorzone0_, _temperaturezone0_, _abstemperaturezone0_, etc.) that allow for controlling specific zones of the light.
+Changing the _color_, _temperature_ and _abstemperature_ channels will update the states of all zones.
+The _color_, _temperature_ and _abstemperature_ channels of MultiZone lights always return the same state as _colorzone0_, _temperaturezone0_, _abstemperaturezone0_.
-The *hevcycle* channels have an optional "HEV Cycle Duration" configuration option that can be used to override the cycle duration configured in the light.
+The _hevcycle_ channels have an optional "HEV Cycle Duration" configuration option that can be used to override the cycle duration configured in the light.
-LIFX Tile (*tilelight*) supports special tile effects: morph and flame.
+LIFX Tile (_tilelight_) supports special tile effects: morph and flame.
These effects are predefined to their appearance using LIFX application.
Each effect has a separate speed configuration option.
## Full Example
-In this example **living** is a Color 1000 light that has a *colorlight* thing type which supports *color* and *temperature* channels.
-
-The **desk** light is a LIFX Clean that has a *colorhevlight* thing type which supports *color*, *temperature* and *hevcycle* channels.
+In this example **living** is a Color 1000 light that has a _colorlight_ thing type which supports _color_ and _temperature_ channels.
-The **porch** light is a LIFX+ BR30 that has a *colorirlight* thing type which supports *color*, *temperature* and *infrared* channels.
+The **desk** light is a LIFX Clean that has a _colorhevlight_ thing type which supports _color_, _temperature_ and _hevcycle_ channels.
-The **ceiling** light is a LIFX Z with 2 strips (16 zones) that has a *colormzlight* thing type which supports *color*, *colorzone*, *temperature* and *temperaturezone* channels.
+The **porch** light is a LIFX+ BR30 that has a _colorirlight_ thing type which supports _color_, _temperature_ and _infrared_ channels.
-Finally, **kitchen** is a White 800 (Low Voltage) light that has a *whitelight* thing type which supports *brightness* and *temperature* channels.
+The **ceiling** light is a LIFX Z with 2 strips (16 zones) that has a _colormzlight_ thing type which supports _color_, _colorzone_, _temperature_ and _temperaturezone_ channels.
-Either create a single *Color* item linked to the *color* channel and define *Switch*, *Slider* and *Colorpicker* entries with this item in the sitemap.
-Or create items for each type (*Color*, *Switch*, *Dimmer*) and define the correspondent entries in the sitemap.
+Finally, **kitchen** is a White 800 (Low Voltage) light that has a _whitelight_ thing type which supports _brightness_ and _temperature_ channels.
+Either create a single _Color_ item linked to the _color_ channel and define _Switch_, _Slider_ and _Colorpicker_ entries with this item in the sitemap.
+Or create items for each type (_Color_, _Switch_, _Dimmer_) and define the correspondent entries in the sitemap.
### demo.things:
-```
+```java
Thing lifx:colorlight:living [ deviceId="D073D5A1A1A1" ]
Thing lifx:colorlight:living2 [ deviceId="D073D5A2A2A2" ] {
### demo.items:
-```
+```java
// Living
Color Living_Color { channel="lifx:colorlight:living:color" }
Dimmer Living_Temperature { channel="lifx:colorlight:living:temperature" }
### demo.sitemap:
-```
+```perl
sitemap demo label="Main Menu"
{
Frame label="Living" {
You need to create an Enedis account [here](https://espace-client-connexion.enedis.fr/auth/UI/Login?realm=particuliers) if you don't have one already.
Please ensure that you have accepted their conditions, and check that you can see graphs on the website.
-Especially, check hourly view/graph. Enedis may ask for permission the first time to start collecting hourly data.
+Especially, check hourly view/graph. Enedis may ask for permission the first time to start collecting hourly data.
The binding will not provide these informations unless this step is ok.
## Supported Things
This version is now compatible with the new API of Enedis (deployed from june 2020).
To avoid the captcha login, it is necessary to log before on a classical browser (e.g Chrome, Firefox) and to retrieve the user cookies (internalAuthId).
-Instructions given for Firefox :
+Instructions given for Firefox :
-1. Go to https://mon-compte-client.enedis.fr/.
-2. Select "Particulier" in the drop down list and click on the "Connexion" button.
-3. You'll be redirected to a page where you'll have to enter you Enedis account email address and check the "Je ne suis pas un robot" checkbox.
-4. Clic on "Suivant".
-5. In the login page, prefilled with your mail address, enter your Enedis account password and click on "Connexion à Espace Client Enedis".
-6. You will be directed to your Enedis account environment. Get back to previous page in you browser.
-7. Disconnect from your Enedis account
-8. Repeat steps 1, 2. You should arrive directly on step 5, then open the developer tool window (F12) and select "Stockage" tab. In the "Cookies" entry, select "https://mon-compte-enedis.fr". You'll find an entry named "internalAuthId", copy this value in your openHAB configuration.
+1. Go to <https://mon-compte-client.enedis.fr/>.
+1. Select "Particulier" in the drop down list and click on the "Connexion" button.
+1. You'll be redirected to a page where you'll have to enter you Enedis account email address and check the "Je ne suis pas un robot" checkbox.
+1. Clic on "Suivant".
+1. In the login page, prefilled with your mail address, enter your Enedis account password and click on "Connexion à Espace Client Enedis".
+1. You will be directed to your Enedis account environment. Get back to previous page in you browser.
+1. Disconnect from your Enedis account
+1. Repeat steps 1, 2. You should arrive directly on step 5, then open the developer tool window (F12) and select "Stockage" tab. In the "Cookies" entry, select "https://mon-compte-enedis.fr". You'll find an entry named "internalAuthId", copy this value in your openHAB configuration.
## Channels
The binding provides one specific command you can use in the console.
Enter the command `openhab:linky` to get the usage.
-```
-Usage: openhab:linky <thingUID> report <start day> <end day> [<separator>] - report daily consumptions between two dates
+```shell
+openhab:linky <thingUID> report <start day> <end day> [<separator>] - report daily consumptions between two dates
```
The command `report` reports in the console the daily consumptions between two dates.
### Thing
-```
+```java
Thing linky:linky:local "Compteur Linky" [ username="example@domaine.fr", password="******" ]
```
### Items
-```
+```java
Number:Energy ConsoHier "Conso hier [%.0f %unit%]" <energy> { channel="linky:linky:local:daily#yesterday" }
Number:Energy ConsoSemaineEnCours "Conso cette semaine [%.0f %unit%]" <energy> { channel="linky:linky:local:weekly#thisWeek" }
Number:Energy ConsoSemaineDerniere "Conso semaine dernière [%.0f %unit%]" <energy> { channel="linky:linky:local:weekly#lastWeek" }
## Thing Configuration
Each thing has has to be explicitly enabled after it is configured.
-While it is enabled *all* of the generated events will be consumed by openHAB.
+While it is enabled _all_ of the generated events will be consumed by openHAB.
The device will not be available for normal input processing!
-
### Static configuration
#### Thing
-```
+```java
Thing linuxinput:input-device:some-keyboard [ enable=true, path="/dev/input/eventXX" ]
```
#### Item
-```
+```java
Contact SomeButton "Some Button" { channel="linuxinput:input-device:event17:keypresses#KEY_0" }
```
Each Thing provides multiple channels
-* A `key` channel that aggregates all events.
-* Per physical key channels.
+- A `key` channel that aggregates all events.
+- Per physical key channels.
### Events
#### Press
-1) State of global key channel updated to new key.
-2) State of per-key channel updated to `"CLOSED"`.
-3) Global key channel triggered with the current key name.
-4) Per-key channel triggered with `"PRESSED"`".
-5) State of global key channel updated to `""` (Empty string)
+1. State of global key channel updated to new key.
+1. State of per-key channel updated to `"CLOSED"`.
+1. Global key channel triggered with the current key name.
+1. Per-key channel triggered with `"PRESSED"`".
+1. State of global key channel updated to `""` (Empty string)
#### Release
-1) State of per-key channel updated to `"OPEN"`
-2) Per-key channel triggered with `"RELEASED"`
+1. State of per-key channel updated to `"OPEN"`
+1. Per-key channel triggered with `"RELEASED"`
#### Rationale
A list of remote configuration files for LIRC is available [here](http://lirc-remotes.sourceforge.net/remotes-table.html).
-
## Supported Things
This binding supports LIRC and WinLIRC as bridges for accessing the configured remotes.
By default, LIRC will listen on IP address 0.0.0.0 (any available IP address) and port 8765. If you would
rather run LIRC on a specific port or IP address, you can use `--listen=192.168.1.100:9001` instead.
-
## Discovery
Discovery of the LIRC bridge is not supported. However, remotes will be automatically discovered once
### Things
-```xtend
+```java
Bridge lirc:bridge:local [ host="192.168.1.120", portNumber="9001" ] {
Thing remote Onkyo_RC_799M [ remote="Onkyo_RC-799M" ]
Thing remote Samsung [ remote="Samsung" ]
Bridge:
-* **host**: IP address or hostname of the LIRC server. Defaults to localhost
-* **port**: The port number the LIRC server is listening on. Defaults to 8765
+- **host**: IP address or hostname of the LIRC server. Defaults to localhost
+- **port**: The port number the LIRC server is listening on. Defaults to 8765
Remote:
-* **remote**: The name of the remote as known by LIRC
+- **remote**: The name of the remote as known by LIRC
### Items
-```xtend
+```java
String Remote_AVReceiver { channel="lirc:remote:local:Onkyo_RC_799M:transmit" }
String Remote_TV { channel="lirc:remote:local:Samsung:transmit" }
```
### Rules
-```xtend
+```java
rule "LIRC Test"
when
Channel 'lirc:remote:local:Samsung:event' triggered KEY_DVD
end
```
-
## Channels
This binding currently supports following channels:
This means `100` on LIVISI is `UP` and `0` is `DOWN`.
When `invert` is `true` than `0` on LIVISI is `UP` and `100` is `DOWN`.
-
## Triggers
| Trigger Type | Description | Available on thing |
| LONG_PRESSED | Fired when you press a button longer | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
| PRESSED | Fired when you press a button (short or long) | BRC8, ISC2, ISD2, ISR2, ISS2, WSC2 |
-
## Thing configuration
### Configuring the SmartHome Controller (SHC)
As an alternative to the automatic discovery process and graphical configuration using the UI, LIVISI things can be configured manually.
The LIVISI SmartHome Controller (SHC) can be configured using the following syntax:
-```
+```java
Bridge livisismarthome:bridge:<bridge-id> "Livisi: SmartHome Controller (SHC)" [ host="192.168.0.99", password="SomethingSecret", webSocketIdleTimeout=900]
```
-** *Security warning!**
+** _Security warning!_*
The communication between the binding and the SHC is not encrypted and can be traced.
So be careful and secure your local network from unauthorized access.
All other LIVISI devices can be added using the following syntax:
-```
+```java
Thing WDS <thing-id> "<thing-name>" @ "<room-name>" [ id="<the-device-id>" ]
```
However, a full example .things configuration look like this:
-```
+```java
Bridge livisismarthome:bridge:mybride "LIVISI SmartHome Controller" {
Thing ISD2 myDimmer "Dimmer Kitchen" @ "Kitchen" [ id="<device-id>" ]
Thing ISS2 myLightSwitch "Light Livingroom" @ "Livingroom" [ id="<device-id>" ]
You can then configure your items in your *.items config files as usual, for example:
-```
+```java
Contact myWindowContact "Kitchen" <window> {channel="livisismarthome:WDS:mybridge:myWindowContact:contact"}
Switch myWindowContactBattery "Battery low" <battery> {channel="livisismarthome:WDS:mybridge:myWindowContact:batteryLow"}
Number myHeatingTemp "Bath [%.1f °C]" <temperature> {channel="livisismarthome:RST:mybridge:myHeating:currentTemperature"}
Example:
-```
+```perl
sitemap default label="Home" {
Frame {
Text item=myHeatingTemp label="Temperature"
Push-buttons provide trigger channels, that can only be used in rules.
Here is an example rule:
-```
+```java
rule "Button triggered rule"
when
Channel 'livisismarthome:WSC2:mybridge:myPushButton:button1' triggered PRESSED
This binding supports one ThingType: `reader`.
A reader supports 3 separate channels
- * One for errors
- * one for warnings
- * one custom channel for other purposes.
+- One for errors
+- one for warnings
+- one custom channel for other purposes.
## Thing Configuration
-The `reader` Thing has the following configuration parameters:
+The `reader` Thing has the following configuration parameters:
| Parameter | Type | Required | Default if omitted | Description |
| ------------------------------| ------- | -------- | -------------------------------- |-----------------------------------------------------------------------------------------|
### example.things
-```xtend
+```java
logreader:reader:openhablog[ refreshRate=1000, errorPatterns="ERROR+", errorBlacklistingPatterns="annoying error which should be ignored|Another annoying error which should be ignored" ]
### example.items
-```xtend
+```java
DateTime logreaderLogRotated "Last Log Rotation [%1$tY.%1$tm.%1$te %1$tR]" <time> { channel="logreader:reader:openhablog:logRotated" }
Number logreaderErrors "Error events matched [%d]" <alarm> { channel="logreader:reader:openhablog:errorEvents" }
### example.sitemap
-```xtend
+```perl
sitemap logreader_example label="Example" {
- Frame label="openHAB Log Reader" {
- Text item=logreaderErrors
- Text item=logreaderLastError
- Text item=logreaderWarnings
- Text item=logreaderLastWarning
- Text item=logreaderCustoms
- Text item=logreaderLastCustom
- Text item=logreaderLogRotated
- }
+ Frame label="openHAB Log Reader" {
+ Text item=logreaderErrors
+ Text item=logreaderLastError
+ Text item=logreaderWarnings
+ Text item=logreaderLastWarning
+ Text item=logreaderCustoms
+ Text item=logreaderLastCustom
+ Text item=logreaderLogRotated
+ }
}
```
### example.rules
-```xtend
+```java
rule "LogReader"
when
Channel "logreader:reader:openhablog:newErrorEvent" triggered
Use the rules with your Telegram Bot (need openHAB Telegram Binding installed and configured)
-```xtend
+```java
rule "LogReader"
when
Channel 'logreader:reader:openhablog:newErrorEvent' triggered
```
Be careful when sending e.g. email notifications.
-You could easily send thousand of *spam* emails in short period if e.g. one binding is in error loop.
+You could easily send thousand of _spam_ emails in short period if e.g. one binding is in error loop.
### Thing status
The following features are currently supported:
-* [Discovery](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol) of Miniservers available on the local network
-* Creation of channels for Loxone controls that are exposed in the Loxone [UI](https://www.loxone.com/enen/kb/user-interface-configuration/)
-* Tagging of channels and [items](https://www.openhab.org/docs/configuration/items.html) with tags that can be recognized by [Alexa](https://en.wikipedia.org/wiki/Amazon_Alexa) openHAB [skill](https://www.amazon.com/openHAB-Foundation/dp/B01MTY7Z5L), so voice can be used to command Loxone controls
-* Management of a Websocket connection to the Miniserver and updating Thing status accordingly
-* Updates of openHAB channel's state in runtime according to control's state changes on the Miniserver
-* Passing channel commands to the Miniserver's controls
-* Hash-based and token-based authentication methods
-* Command encryption and response decryption
+- [Discovery](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol) of Miniservers available on the local network
+
+- Creation of channels for Loxone controls that are exposed in the Loxone [UI](https://www.loxone.com/enen/kb/user-interface-configuration/)
+- Tagging of channels and [items](https://www.openhab.org/docs/configuration/items.html) with tags that can be recognized by [Alexa](https://en.wikipedia.org/wiki/Amazon_Alexa) openHAB [skill](https://www.amazon.com/openHAB-Foundation/dp/B01MTY7Z5L), so voice can be used to command Loxone controls
+- Management of a Websocket connection to the Miniserver and updating Thing status accordingly
+- Updates of openHAB channel's state in runtime according to control's state changes on the Miniserver
+- Passing channel commands to the Miniserver's controls
+- Hash-based and token-based authentication methods
+- Command encryption and response decryption
## Things
Where:
-* `<thing-id>` is a unique ID for your Miniserver (you can but do not have to use Miniserver's MAC address here)
-
* `<user>` and `<password>` are the credentials used to log into the Miniserver
-* `<host>` is a host name or IP of the Miniserver
-
* `<port>` is a port of web services on the Miniserver (please notice that port, as a number, is not surrounded by quotation marks, while the other values described above are)
-* `...` are optional advanced parameters - please refer to _Advanced parameters_ section at the end of this instruction for a list of available options
+- `<thing-id>` is a unique ID for your Miniserver (you can but do not have to use Miniserver's MAC address here)
+
- `<user>` and `<password>` are the credentials used to log into the Miniserver
+- `<host>` is a host name or IP of the Miniserver
+
- `<port>` is a port of web services on the Miniserver (please notice that port, as a number, is not surrounded by quotation marks, while the other values described above are)
+- `...` are optional advanced parameters - please refer to _Advanced parameters_ section at the end of this instruction for a list of available options
Example 1 - minimal required configuration:
- `loxone:miniserver:504F2414780F [ user="kryten", password="jmc2017", host="loxone.local", port=80 ]`
+```java
+loxone:miniserver:504F2414780F [ user="kryten", password="jmc2017", host="loxone.local", port=80 ]
+```
Example 2 - additionally keep alive period is set to 2 minutes and Websocket maximum binary message size to 8MB:
- `loxone:miniserver:504F2414780F [ user="kryten", password="jmc2017", host="192.168.0.210", port=80, keepAlivePeriod=120, maxBinMsgSize=8192 ]`
+```java
+loxone:miniserver:504F2414780F [ user="kryten", password="jmc2017", host="192.168.0.210", port=80, keepAlivePeriod=120, maxBinMsgSize=8192 ]
+```
### Thing Offline Reasons
There can be following reasons why Miniserver status is `OFFLINE`:
-* __Configuration Error__
- * _Unknown host_
- * Miniserver host/ip address can't be resolved. No connection attempt will be made.
- * _User authentication error_
- * Invalid user name or password or user not authorized to connect to the Miniserver. Binding will make another attempt to connect after some time.
- * _Too many failed login attempts - stopped trying_
- * Miniserver locked out user for too many failed login attempts. In this case binding will stop trying to connect to the Miniserver. A new connection will be attempted only when user corrects user name or password in the configuration parameters.
- * _Enter password to generate a new token_
- * Authentication using stored token failed - either token is wrong or it. A password must be reentered in the binding settings to acquire a new token.
- * _Internal error_
- * Probably a code defect, collect debug data and submit an issue. Binding will try to reconnect, but with unknown chance for success.
- * _Other_
- * An exception occured and its details will be displayed
-* __Communication Error__
- * _Error communicating with Miniserver_
- * I/O error occurred during established communication with the Miniserver, most likely due to network connectivity issues, Miniserver going offline or Loxone Config is uploading a new configuration. A reconnect attempt will be made soon. Please consult detailed message against one of the following:
- * _"Text message size &lsqbXX&rsqb exceeds maximum size &lsqbYY&rsqb"_ - adjust text message size in advanced parameters to be above XX value
- * _"Binary message size &lsqbXX&rsqb exceeds maximum size &lsqbYY&rsqb"_ - adjust binary message size in advanced parameters to be above XX value
- * _User authentication timeout_
- * Authentication procedure took too long time and Miniserver closed connection. It should not occur under normal conditions and may indicate performance issue on binding's OS side.
- * _Timeout due to no activity_
- * Miniserver closed connection because there was no activity from binding. It should not occur under normal conditions, as it is prevented by sending keep-alive messages from the binding to the Miniserver. By default Miniserver's timeout is 5 minutes and period between binding's keep-alive messages is 4 minutes. If you see this error, try changing the keep-alive period in binding's configuration to a smaller value.
- * _Other_
- * An exception occured and its details will be displayed
+- **Configuration Error**
+ - _Unknown host_
+ - Miniserver host/ip address can't be resolved. No connection attempt will be made.
+ - _User authentication error_
+ - Invalid user name or password or user not authorized to connect to the Miniserver. Binding will make another attempt to connect after some time.
+ - _Too many failed login attempts - stopped trying_
+ - Miniserver locked out user for too many failed login attempts. In this case binding will stop trying to connect to the Miniserver. A new connection will be attempted only when user corrects user name or password in the configuration parameters.
+ - _Enter password to generate a new token_
+ - Authentication using stored token failed - either token is wrong or it. A password must be reentered in the binding settings to acquire a new token.
+ - _Internal error_
+ - Probably a code defect, collect debug data and submit an issue. Binding will try to reconnect, but with unknown chance for success.
+ - _Other_
+ - An exception occured and its details will be displayed
+- **Communication Error**
+ - _Error communicating with Miniserver_
+ - I/O error occurred during established communication with the Miniserver, most likely due to network connectivity issues, Miniserver going offline or Loxone Config is uploading a new configuration. A reconnect attempt will be made soon. Please consult detailed message against one of the following:
+ - _"Text message size &lsqbXX&rsqb exceeds maximum size &lsqbYY&rsqb"_ - adjust text message size in advanced parameters to be above XX value
+ - _"Binary message size &lsqbXX&rsqb exceeds maximum size &lsqbYY&rsqb"_ - adjust binary message size in advanced parameters to be above XX value
+ - _User authentication timeout_
+ - Authentication procedure took too long time and Miniserver closed connection. It should not occur under normal conditions and may indicate performance issue on binding's OS side.
+ - _Timeout due to no activity_
+ - Miniserver closed connection because there was no activity from binding. It should not occur under normal conditions, as it is prevented by sending keep-alive messages from the binding to the Miniserver. By default Miniserver's timeout is 5 minutes and period between binding's keep-alive messages is 4 minutes. If you see this error, try changing the keep-alive period in binding's configuration to a smaller value.
+ - _Other_
+ - An exception occured and its details will be displayed
### Security
| Hash-based | 8.x | HMAC-SHA1 hash on user and password | None | None |
| Token-based | From 9.x | Token acquired on the first connection and used later instead of the password. | AES-256 | JRE must have unrestricted security policy configured |
-For the token-based authentication, the password is required only for the first login and acquiring the token. After the token is acquired, the password is cleared in the binding configuration.
+For the token-based authentication, the password is required only for the first login and acquiring the token. After the token is acquired, the password is cleared in the binding configuration.
The acquired token will remain active for several weeks following the last succesful authentication with this token. If the connection is not established used during that period and the token expires, a user password has to be re-entered in the binding settings to acquire a new token.
| EIBDimmer | EIB Dimmer (undocumented) | `Dimmer` | `OnOffType.*`, `PercentType`, `IncreaseDecreaseType.*` |
| InfoOnlyAnalog | Analog [virtual inputs](https://www.loxone.com/enen/kb/virtual-inputs-outputs/) (virtual state) | `Number` | Read-only channel |
| InfoOnlyDigital | Digital [virtual inputs](https://www.loxone.com/enen/kb/virtual-inputs-outputs/) (virtual state) | `String` | Read-only channel |
-| IRoomControllerV2 | [Intelligent Room Controller V2](https://www.loxone.com/enen/kb/irc-v2/) | `Number` - active mode | Read-only channel |
-| | | `Number` - operating mode | `DecimalType` - operating mode |
-| | | `Number` - prepare state | Read-only channel |
-| | | `Switch` - open window | Read-only channel |
-| | | `Number` - current temperature | Read-only channel |
-| | | `Number` - target temperature | `DecimalType` |
-| | | `Number` - comfort temperature | `DecimalType` |
-| | | `Number` - comfort temperature offset | `DecimalType` |
-| | | `Number` - comfort tolerance | `DecimalType` |
-| | | `Number` - absent minimum temperature offset | `DecimalType` |
-| | | `Number` - absent maximum temperature offset | `DecimalType` |
-| | | `Number` - frost protect temperature | Read-only channel |
-| | | `Number` - heat protect temperature | Read-only channel |
+| IRoomControllerV2 | [Intelligent Room Controller V2](https://www.loxone.com/enen/kb/irc-v2/) | `Number` - active mode | Read-only channel |
+| | | `Number` - operating mode | `DecimalType` - operating mode |
+| | | `Number` - prepare state | Read-only channel |
+| | | `Switch` - open window | Read-only channel |
+| | | `Number` - current temperature | Read-only channel |
+| | | `Number` - target temperature | `DecimalType` |
+| | | `Number` - comfort temperature | `DecimalType` |
+| | | `Number` - comfort temperature offset | `DecimalType` |
+| | | `Number` - comfort tolerance | `DecimalType` |
+| | | `Number` - absent minimum temperature offset | `DecimalType` |
+| | | `Number` - absent maximum temperature offset | `DecimalType` |
+| | | `Number` - frost protect temperature | Read-only channel |
+| | | `Number` - heat protect temperature | Read-only channel |
| Jalousie | Blinds, [Automatic Blinds](https://www.loxone.com/enen/kb/automatic-blinds/), Automatic Blinds Integrated | `Rollershutter` - main control element | `UpDownType.*`, `StopMoveType.*`, `PercentType` |
| | | `Switch` - shading | `OnOffType.ON` - shade |
| | | `Switch` - automatic shading | `OnOffType.*` - automatic shading enabled/disabled |
Most controls have a single channel. Such channel ID is defined in the following way:
-* `loxone:miniserver:<serial>:<control-UUID>`
+- `loxone:miniserver:<serial>:<control-UUID>`
Controls, which have more than one channel, define the channel ID of the extra channels in the following way:
-* `loxone:miniserver:<serial>:<control-UUID>-<channel-index>`, where `<channel-index>` is equal to 1, 2, ...
+- `loxone:miniserver:<serial>:<control-UUID>-<channel-index>`, where `<channel-index>` is equal to 1, 2, ...
Channel label is defined in the following way:
-* For controls that belong to a room: `<Room name> / <Control name>`
-* For controls without a room: `<Control name>`
+- For controls that belong to a room: `<Room name> / <Control name>`
+- For controls without a room: `<Control name>`
Channels have the default tags as follows:
-* **Dimmer**: when it belongs to a category of _Lights_ type, the channel will be tagged with _Lighting_ tag.
-* **InfoOnlyAnalog**: when it belongs to a category of _Indoor Temperature_ type, it will be tagger with _CurrentTemperature_ tag.
-* **Jalousie**: main rollershutter channel will be tagged with _Blinds_ tag. Shade and automatic shade switch channels will be tagged with _Switchable_ tag.
-* **LightController (V1 and V2)**: main channel with selected scene will be tagged with _Scene_ tag.
-* **Switch**, **TimedSwitch** and **Pushbutton** controls: when it belongs to a category that is of a _Lights_ type, the channel will be tagged with _Lighting_ tag. Otherwise it will be tagged with _Switchable_ tag.
+- **Dimmer**: when it belongs to a category of _Lights_ type, the channel will be tagged with _Lighting_ tag.
+- **InfoOnlyAnalog**: when it belongs to a category of _Indoor Temperature_ type, it will be tagger with _CurrentTemperature_ tag.
+- **Jalousie**: main rollershutter channel will be tagged with _Blinds_ tag. Shade and automatic shade switch channels will be tagged with _Switchable_ tag.
+- **LightController (V1 and V2)**: main channel with selected scene will be tagged with _Scene_ tag.
+- **Switch**, **TimedSwitch** and **Pushbutton** controls: when it belongs to a category that is of a _Lights_ type, the channel will be tagged with _Lighting_ tag. Otherwise it will be tagged with _Switchable_ tag.
## Advanced Parameters
To define a parameter value in a .things file, please refer to it by parameter's ID, for example:
- keepAlivePeriod=120
+```text
+keepAlivePeriod=120
+```
### Security
## Limitations
-* As there is no push button item type in openHAB, Loxone's push button is an openHAB's switch, which always generates a short pulse on changing its state to on. If you use simple UI mode and framework generates items for you, switches for push buttons will still be toggle switches. To change it to the push button style, you have to create item manually with `autoupdate=false` parameter. An example of such item definition is given in the _Items_ section above.
+- As there is no push button item type in openHAB, Loxone's push button is an openHAB's switch, which always generates a short pulse on changing its state to on. If you use simple UI mode and framework generates items for you, switches for push buttons will still be toggle switches. To change it to the push button style, you have to create item manually with `autoupdate=false` parameter. An example of such item definition is given in the _Items_ section above.
## Automatic Configuration Example
The simplest and quickest way of configuring a Loxone Miniserver with openHAB is to use automatic configuration features:
-* Make sure your Miniserver is up and running and on the same network segment as openHAB server.
-* Add Loxone binding from the available `Add-ons`.
-* In `Configuration/System` page, set `Item Linking` to `Simple Mode` (don't forget to save your choice).
-* Add your Miniserver Thing from the `Inbox`, after automatic discovery is performed by the framework during binding initialization.
-* Configure your Miniserver by editing Miniserver Thing in `Configuration/Things` page and providing user name and password.
-* Miniserver Thing should go online. Channels and Items will be automatically created and configured.
-* On the `Control` page, you can test Miniserver Items and interact with them.
-* As the user interface, you may use [HABPanel](https://www.openhab.org/docs/configuration/habpanel.html), where all Miniserver's items are ready for picking up, using entirely the graphical user interface.
+- Make sure your Miniserver is up and running and on the same network segment as openHAB server.
+- Add Loxone binding from the available `Add-ons`.
+- In `Configuration/System` page, set `Item Linking` to `Simple Mode` (don't forget to save your choice).
+- Add your Miniserver Thing from the `Inbox`, after automatic discovery is performed by the framework during binding initialization.
+- Configure your Miniserver by editing Miniserver Thing in `Configuration/Things` page and providing user name and password.
+- Miniserver Thing should go online. Channels and Items will be automatically created and configured.
+- On the `Control` page, you can test Miniserver Items and interact with them.
+- As the user interface, you may use [HABPanel](https://www.openhab.org/docs/configuration/habpanel.html), where all Miniserver's items are ready for picking up, using entirely the graphical user interface.
## Manual Configuration Example
A more advanced setup requires manual creation and editing of openHAB configuration files, according to the instructions provided in [configuration user guide](https://www.openhab.org/docs/configuration/).
In this example we will manually configure:
-* A Miniserver with serial number 504F2414780F, available at IP 192.168.0.220 and with web services port 80
-* A Miniserver's user named "kryten" and password "jmc2017"
-* Items for:
- * Temperature of the Miniserver - a Virtual Analog State functional block
- * State of a garage door - a Virtual Digital State funtional block (ON=door open, OFF=door closed)
- * Kitchen lights switch - a Switch Subcontrol at the AI1 output of a Lighting Controller functional block (with a tag recognizable by Alexa service)
- * Pushbutton to switch all lights off - a Virtual Input of Pushbutton type functional block (pushbutton realized by adding `autoupdate="false"` parameter)
- * Kitchen blinds - a Jalousie functional block
- * Lighting scene - a Lighting Controller functional block
- * Output valve selection for garden watering - 8x Radio Button functional block, where only one valve can be open at a time
- * A text displaying current alarm's state - a State functional block
+- A Miniserver with serial number 504F2414780F, available at IP 192.168.0.220 and with web services port 80
+- A Miniserver's user named "kryten" and password "jmc2017"
+- Items for:
+ - Temperature of the Miniserver - a Virtual Analog State functional block
+ - State of a garage door - a Virtual Digital State funtional block (ON=door open, OFF=door closed)
+ - Kitchen lights switch - a Switch Subcontrol at the AI1 output of a Lighting Controller functional block (with a tag recognizable by Alexa service)
+ - Pushbutton to switch all lights off - a Virtual Input of Pushbutton type functional block (pushbutton realized by adding `autoupdate="false"` parameter)
+ - Kitchen blinds - a Jalousie functional block
+ - Lighting scene - a Lighting Controller functional block
+ - Output valve selection for garden watering - 8x Radio Button functional block, where only one valve can be open at a time
+ - A text displaying current alarm's state - a State functional block
### things/loxone.things:
-```
+```java
loxone:miniserver:504F2414780F [ user="kryten", password="jmc2017", host="192.168.0.220", port=80 ]
```
### items/loxone.items:
-```
+```java
// Type ID Label Icon Tags Settings
Number Miniserver_Temp "Miniserver temperature: [%.1f °C]" <temperature> {channel="loxone:miniserver:504F2414780F:0F2F2133-017D-3C82-FFFF203EB0C34B9E"}
### sitemaps/loxone.sitemap:
-```
+```perl
sitemap loxone label="Loxone Example Menu"
{
Frame label="Demo Controls" {
### transform/garagedoor.map:
-```java
+```text
OFF=Closed
ON=Open
-=Unknown
| Parameter | Description |
|-----------------|----------------------------------------------------------------------|
| ipAddress | Local IP address of your personal owned sensor |
-| sensorid | Sensor ID obtained from https://deutschland.maps.sensor.community/ |
+| sensorid | Sensor ID obtained from <https://deutschland.maps.sensor.community/> |
### Local Sensor
Perform the following steps to get the appropriate Sensor ID
-* Go to to [luftdaten.info map](https://deutschland.maps.sensor.community/)
-* Choose your desired value in bottom list - now only the Sensors are displayed which are supporting this
-* Click on your / any Sensor and the ID is displayed in the top right corner. Note: Sensor ID is just the number without beginning hash #
-* Enter this Sensor ID into the thing configuration
+- Go to to [luftdaten.info map](https://deutschland.maps.sensor.community/)
+- Choose your desired value in bottom list - now only the Sensors are displayed which are supporting this
+- Click on your / any Sensor and the ID is displayed in the top right corner. Note: Sensor ID is just the number without beginning hash #
+- Enter this Sensor ID into the thing configuration
## Channels
-### Particulate Sensor
+### Particulate Sensor
| Channel ID | Item Type | Description |
|----------------------|----------------------|------------------------------------------|
| pm25 | Number:Density | [Ultrafine particulates](https://en.wikipedia.org/wiki/Particulates#Size,_shape_and_solubility_matter) microgram per cubic meter |
| pm100 | Number:Density | [Coarse particulate matter](https://en.wikipedia.org/wiki/Particulates#Size,_shape_and_solubility_matter) microgram per cubic meter |
-### Conditions Sensor
+### Conditions Sensor
| Channel ID | Item Type | Description |
|----------------------|----------------------|------------------------------------------|
| pressure | Number:Pressure | Atmospheric Pressure (not supported by all sensors) |
| pressure-sea | Number:Pressure | Atmospheric Pressure on sea level (not supported by all sensors) |
-
-### Noise Sensor
+### Noise Sensor
| Channel ID | Item Type | Description |
|----------------------|----------------------|------------------------------------------------------|
| noise-min | Number:Dimensionless | Minimum noise covered in the last 2.5 minutes in db |
| noise-main | Number:Dimensionless | Maximum noise covered in the last 2.5 minutes in db |
-
## Full Example
### Things
luftdaten.things
-```
+```java
Thing luftdateninfo:particulate:pm_sensor "PM Sensor" [ ipAddress=192.168.178.50 ]
Thing luftdateninfo:conditions:cond_sensor "Condition Sensor" [ sensorid=28843 ]
Thing luftdateninfo:noise:noise_sensor "Noise Sensor" [ sensorid=39745 ]
luftdaten.items
-```
+```java
Number:Density PM_25 "PM2.5" { channel="luftdateninfo:particulate:pm_sensor:pm25" }
Number:Density PM_100 "PM10" { channel="luftdateninfo:particulate:pm_sensor:pm100" }
LuftdatenInfo.sitemap
-```
+```perl
sitemap LuftdatenInfo label="LuftdatenInfo" {
Text item=PM_25 label="Particulate Matter 2.5 [%.1f %unit%]"
Text item=PM_100 label="Particulate Matter 10 [%.1f %unit%]"
This binding integrates with [Lutron](https://www.lutron.com) lighting control and home automation systems.
It contains support for four different types of Lutron systems via different bridge things:
-* RadioRA 2, HomeWorks QS, Caseta, RA2 Select, and other current systems that can be controlled via Lutron Integration Protocol (LIP) or LEAP
-* The original RadioRA system, referred to here as RadioRA Classic
-* Legacy HomeWorks RS232 Processors
-* Grafik Eye 3x/4x systems with GRX-PRG or GRX-CI-PRG control interfaces
+- RadioRA 2, HomeWorks QS, Caseta, RA2 Select, and other current systems that can be controlled via Lutron Integration Protocol (LIP) or LEAP
+- The original RadioRA system, referred to here as RadioRA Classic
+- Legacy HomeWorks RS232 Processors
+- Grafik Eye 3x/4x systems with GRX-PRG or GRX-CI-PRG control interfaces
Each is described in a separate section below.
This binding currently supports the following thing types:
-* **ipbridge** - The Lutron main repeater/processor/hub
-* **leapbridge** - Experimental bridge that uses LEAP protocol (Caseta & RA2 Select only)
-* **dimmer** - Light dimmer
-* **switch** - Switch or relay module
-* **fan** - Fan controller
-* **occupancysensor** - Occupancy/vacancy sensor
-* **ogroup** - Occupancy group
-* **keypad** - Lutron seeTouch or Hybrid seeTouch Keypad
-* **ttkeypad** - Tabletop seeTouch Keypad
-* **intlkeypad** - International seeTouch Keypad (HomeWorks QS only)
-* **palladiomkeypad** - Palladiom Keypad (HomeWorks QS only)
-* **pico** - Pico Keypad
-* **grafikeyekeypad** - GRAFIK Eye QS Keypad (RadioRA 2/HomeWorks QS only)
-* **virtualkeypad** - Repeater/processor integration buttons or Caseta Smart Bridge scene buttons
-* **vcrx** - Visor control receiver module (VCRX)
-* **qsio** - QS IO Interface (HomeWorks QS only)
-* **wci** - QS Wallbox Closure Interface (WCI) (HomeWorks QS only)
-* **cco** - Contact closure output module or VCRX CCO
-* **shade** - Lutron shade, motorized drape, or motor controller
-* **blind** - Lutron venetian blind or horizontal sheer blind [**Experimental**]
-* **greenmode** - Green Mode subsystem
-* **timeclock** - Scheduling subsystem
-* **sysvar** - System state variable (HomeWorks QS only) [**Experimental**]
+- **ipbridge** - The Lutron main repeater/processor/hub
+- **leapbridge** - Experimental bridge that uses LEAP protocol (Caseta & RA2 Select only)
+- **dimmer** - Light dimmer
+- **switch** - Switch or relay module
+- **fan** - Fan controller
+- **occupancysensor** - Occupancy/vacancy sensor
+- **ogroup** - Occupancy group
+- **keypad** - Lutron seeTouch or Hybrid seeTouch Keypad
+- **ttkeypad** - Tabletop seeTouch Keypad
+- **intlkeypad** - International seeTouch Keypad (HomeWorks QS only)
+- **palladiomkeypad** - Palladiom Keypad (HomeWorks QS only)
+- **pico** - Pico Keypad
+- **grafikeyekeypad** - GRAFIK Eye QS Keypad (RadioRA 2/HomeWorks QS only)
+- **virtualkeypad** - Repeater/processor integration buttons or Caseta Smart Bridge scene buttons
+- **vcrx** - Visor control receiver module (VCRX)
+- **qsio** - QS IO Interface (HomeWorks QS only)
+- **wci** - QS Wallbox Closure Interface (WCI) (HomeWorks QS only)
+- **cco** - Contact closure output module or VCRX CCO
+- **shade** - Lutron shade, motorized drape, or motor controller
+- **blind** - Lutron venetian blind or horizontal sheer blind [**Experimental**]
+- **greenmode** - Green Mode subsystem
+- **timeclock** - Scheduling subsystem
+- **sysvar** - System state variable (HomeWorks QS only) [**Experimental**]
## Discovery
You should be aware of the following functional differences between the protocols:
-* Using LIP on Caseta you can’t receive notifications of occupancy group status changes (occupied/unoccupied/unknown), but using LEAP you can.
-* Conversely, LIP provides notifications of keypad key presses, while LEAP does not (as far as is currently known).
+- Using LIP on Caseta you can’t receive notifications of occupancy group status changes (occupied/unoccupied/unknown), but using LEAP you can.
+- Conversely, LIP provides notifications of keypad key presses, while LEAP does not (as far as is currently known).
This means that using ipbridge you can trigger rules and take actions on keypad key presses/releases, but using leapbridge you can’t.
-* Caseta and RA2 Select device discovery is supported via LEAP, but not via LIP.
-* The leapbridge is a bit more complicated to configure because LEAP uses an SSL connections and authenticates using certificates.
-* LIP is a publicly documented protocol, while LEAP is not. This means that Lutron could make a change that breaks LEAP support at any time.
+- Caseta and RA2 Select device discovery is supported via LEAP, but not via LIP.
+- The leapbridge is a bit more complicated to configure because LEAP uses an SSL connections and authenticates using certificates.
+- LIP is a publicly documented protocol, while LEAP is not. This means that Lutron could make a change that breaks LEAP support at any time.
-It is possible to run leapbridge and ipbridge at the same time, for the same bridge device, but each managed device (e.g. keypad or dimmer) should only be configured through *one* bridge.
+It is possible to run leapbridge and ipbridge at the same time, for the same bridge device, but each managed device (e.g. keypad or dimmer) should only be configured through _one_ bridge.
Remember that LEAP device IDs and LIP integration IDs are not necessarily equal!
#### ipbridge
Thing configuration file example:
-```
+```java
Bridge lutron:ipbridge:radiora2 [ ipAddress="192.168.1.2", user="lutron", password="integration" ] {
Thing ...
Thing ...
Thing configuration file example:
-```
+```java
Bridge lutron:leapbridge:caseta [ ipAddress="192.168.1.3", keystore="/home/openhab/lutron.keystore", keystorePassword="secret" ] {
Thing ...
Thing ...
If set to "true", the dimmer will go to its last non-zero level when sent an ON command.
If the last non-zero level cannot be determined, the value of `onLevel` will be used instead.
-A **dimmer** thing has a single channel *lightlevel* with type Dimmer and category DimmableLight.
+A **dimmer** thing has a single channel _lightlevel_ with type Dimmer and category DimmableLight.
The **dimmer** thing was previously also used to control fan speed controllers, but now you should use the **fan** thing instead.
Thing configuration file example:
-```
+```java
Thing dimmer livingroom [ integrationId=8, fadeInTime=0.5, fadeOutTime=5 ]
```
The parameters are:
-* `level` The new light level to set (0-100)
-* `fadeTime` The time in seconds over which the dimmer should fade to the new level
-* `delayTime` The time in seconds to delay before starting to fade to the new level
+- `level` The new light level to set (0-100)
+- `fadeTime` The time in seconds over which the dimmer should fade to the new level
+- `delayTime` The time in seconds to delay before starting to fade to the new level
The fadeTime and delayTime parameters are significant to 2 digits after the decimal point (i.e. to hundredths of a second), but some Lutron systems may round the time to the nearest 0.25 seconds when processing the command.
Times of 100 seconds or more will be rounded to the nearest integer value.
#### Switches
Switches take no additional parameters besides `integrationId`.
-A **switch** thing has a single channel *switchstatus* with type Switch and category Switch.
+A **switch** thing has a single channel _switchstatus_ with type Switch and category Switch.
Thing configuration file example:
-```
+```java
Thing switch porch [ integrationId=8 ]
```
Fan speed controllers are interfaced with using the **fan** thing.
It accepts no additional parameters besides `integrationId`.
-A **fan** thing has two channels, *fanspeed* and *fanlevel*.
+A **fan** thing has two channels, _fanspeed_ and _fanlevel_.
Thing configuration file example:
-```
+```java
Thing fan porchfan [ integrationId=12 ]
```
It accepts no configuration parameters other than `integrationId`.
-The binding creates one *occupancystatus* channel, Item type Switch, category Motion.
+The binding creates one _occupancystatus_ channel, Item type Switch, category Motion.
It is read-only, and ignores all commands.
The channel state can be monitored for occupied (ON) or unoccupied (OFF) events coming from the sensor.
The sensors cannot be queried for their state, so initial channel state at startup will be undefined (NULL).
Thing configuration file example:
-```
+```java
Thing occupancysensor shopsensor [ integrationId=7 ]
```
A **ogroup** thing interfaces to an occupancy group, which shows occcupancy/vacancy status for an area or room with one or more occupancy sensors.
On RadioRA2 and HomeWorks QS systems, you should generally choose to interface to either an occupancy group or individual occupancy sensors for a given area.
-On Caseta systems, you cannot interface to individual sensors and must use the *ogroup* thing.
+On Caseta systems, you cannot interface to individual sensors and must use the _ogroup_ thing.
The `integrationId` parameter must be set to the occupancy group ID.
-The binding creates one read-only *groupstate* channel, item type String, category Motion.
+The binding creates one read-only _groupstate_ channel, item type String, category Motion.
The value can be "OCCUPIED", "UNOCCUPIED", or "UNKNOWN".
Thing configuration file example:
-```
+```java
Thing ogroup lrgroup [ integrationId=7 ]
```
If `autorelease` is set, the handler will send action "release" to the device component immediately after sending action "press".
When the controller responds, the channel state will be transitioned back to OFF.
-A channel *button[nn]* with item type Switch and category Switch is created for each button, and a channel *led[nn]* with item type Switch and category Light is created for each button indicator LED.
+A channel _button[nn]_ with item type Switch and category Switch is created for each button, and a channel _led[nn]_ with item type Switch and category Light is created for each button indicator LED.
You can monitor button channels for ON and OFF state changes to indicate button presses and releases, and send ON and OFF commands to remotely press and release buttons.
Ditto for the indicator LED channels.
Note, however, that version 11.6 or higher of the RadioRA 2 software may be required in order to drive keypad LED states, and then this may only be done on unbound buttons.
-Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.104 (https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf).
+Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.104 (<https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf>).
If you are having problems determining which channels have been created for a given keypad model, select the appropriate keypad thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:keypad:radiora2:entrykeypad`) from the openHAB CLI to list the channels.
Thing configuration file example:
-```
+```java
Thing keypad entrykeypad [ integrationId=10, model="W7B" autorelease=true ]
```
Example rule triggered by a keypad button press:
-```
+```java
rule ExampleScene
when
Item entrykeypad_button4 received update ON
It accepts the same `integrationId`, `model`, and `autorelease` parameters and creates the same channel types as the **keypad** thing.
See the **keypad** section above for a full discussion of configuration and use.
-Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.110 (https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf).
+Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.110 (<https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf>).
If you are having problems determining which channels have been created for a given keypad model, select the appropriate ttkeypad thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:ttkeypad:radiora2:bedroomkeypad`) from the openHAB CLI to list the channels.
-
Supported settings for `model` parameter: T5RL, T10RL, T15RL, T5CRL, T10CRL, T15CRL, Generic (default)
Thing configuration file example:
-```
+```java
Thing ttkeypad bedroomkeypad [ integrationId=11, model="T10RL" autorelease=true ]
```
It accepts the same `integrationId`, `model`, and `autorelease` parameters and creates the same button and LED channel types as the **keypad** thing.
See the **keypad** section above for a full discussion of configuration and use.
-To support this keypad's contact closure inputs, CCI channels named *cci1* and *cci2* are created with item type Contact and category Switch.
+To support this keypad's contact closure inputs, CCI channels named _cci1_ and _cci2_ are created with item type Contact and category Switch.
They are marked as Advanced, so you will need to check "Show advanced" in order to see them listed in the Administration UI.
They present ON/OFF states the same as a keypad button.
-Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.107 (https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf).
+Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.107 (<https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf>).
If you are having problems determining which channels have been created for a given keypad model, select the appropriate intlkeypad thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:intlkeypad:hwprocessor:kitchenkeypad`) from the openHAB CLI to list the channels.
Thing configuration file example:
-```
+```java
Thing intlkeypad kitchenkeypad [ integrationId=15, model="10BRL" autorelease=true ]
```
It accepts the same `integrationId`, `model`, and `autorelease` parameters and creates the same button and LED channel types as the **keypad** thing.
See the **keypad** section above for a full discussion of configuration and use.
-Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.95 (https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf).
+Component numbering: For button and LED layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.95 (<https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf>).
If you are having problems determining which channels have been created for a given keypad model, select the appropriate palladiomkeypad thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:palladiomkeypad:hwprocessor:kitchenkeypad`) from the openHAB CLI to list the channels.
Thing configuration file example:
-```
+```java
Thing palladiomkeypad kitchenkeypad [ integrationId=16, model="4W" autorelease=true ]
```
-
#### Pico Keypads
Pico keypads use the **pico** thing.
The only difference is that no LED channels will be created, since Pico keypads have no indicator LEDs.
See the discussion above for a full discussion of configuration and use.
-Component numbering: For button layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.113 (https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf).
+Component numbering: For button layouts and numbering, see the Lutron Integration Protocol Guide (rev. AA) p.113 (<https://www.lutron.com/TechnicalDocumentLibrary/040249.pdf>).
If you are having problems determining which channels have been created for a given keypad model, select the appropriate pico thing under Settings/Things in the Administration UI and click on the Channels tab.
You can also run the command `things show <thingUID>` (e.g. `things show lutron:pico:radiora2:hallpico`) from the openHAB CLI to list the channels.
Thing configuration file example:
-```
+```java
Thing pico hallpico [ integrationId=12, model="3BRL", autorelease=true ]
```
The **grafikeyekeypad** thing is used to interface to the GRAFIK Eye QS front panel keypad when it is used in a RadioRA 2 or HomeWorks QS system.
In this configuration, the integrated dimmers will appear to openHAB as separate output devices.
-If your GRAFIK Eye is being used as a stand-alone device and is not integrated in to a RadioRA 2 or HomeWorks QS system, then *this is not the thing you are looking for*.
+If your GRAFIK Eye is being used as a stand-alone device and is not integrated in to a RadioRA 2 or HomeWorks QS system, then _this is not the thing you are looking for_.
You should instead be using the **grafikeye** thing (see below).
The **grafikeyekeypad** thing accepts the same `integrationId`, `model`, and `autorelease` parameters and creates the same button, LED, and CCI, channel types as the other keypad things (see above).
The model parameter should be set to indicate whether there are zero, one, two, or three columns of buttons on the left side of the panel.
Note that this count does not include the column of 5 scene buttons always found on the right side of the panel.
-To support the GRAFIK Eye's contact closure input, a CCI channel named *cci1* will be created with item type Contact and category Switch.
+To support the GRAFIK Eye's contact closure input, a CCI channel named _cci1_ will be created with item type Contact and category Switch.
It is marked as Advanced, so you will need to check "Show advanced" in order to see it listed in the Administration UI.
It presents ON/OFF states the same as a keypad button.
Thing configuration file example:
-```
+```java
Thing lutron:grafikeyekeypad:theaterkeypad (lutron:ipbridge:radiora2) [ integrationId=12, model="3COL", autorelease="true" ]
```
Thing configuration file example:
-```
+```java
Thing virtualkeypad repeaterbuttons [ integrationId=1, autorelease=true ]
```
Supported options are `integrationId` and `autorelease`.
Supplying a model is not required, as there is only one model.
-To support the contact closure inputs, CCI channels named *cci[n]* are created with item type Contact and category Switch.
+To support the contact closure inputs, CCI channels named _cci[n]_ are created with item type Contact and category Switch.
The VCRX security (Full/Flash) input controls both the cci1 and cci2 channels, while input connections 1 and 2 map to the cci3 and cci4 channels respectively.
The cci channels are marked as Advanced, so you will need to check "Show advanced" in order to see them listed in the Administration UI.
They present OPEN/CLOSED states but do not accept commands since Contact items are read-only in openHAB.
Thing configuration file example:
-```
+```java
Thing vcrx vcrx1 [ integrationId=13, autorelease=true ]
```
The 5 contact closure outputs (CCOs) are handled by the **cco** thing (see below).
The only configuration option is `integrationId`
-To support the contact closure inputs, CCI channels named *cci[n]* are created with item type Contact and category Switch.
+To support the contact closure inputs, CCI channels named _cci[n]_ are created with item type Contact and category Switch.
They are marked as Advanced, so you will need to check "Show advanced" in order to see them listed in the Administration UI.
They present OPEN/CLOSED states but do not accept commands as Contact items are read-only in openHAB.
Thing configuration file example:
-```
+```java
Thing qsio sensorinputs [ integrationId=42 ]
```
Thing configuration file example:
-```
+```java
Thing wci specialkeypad [ integrationId=48, autorelease=true ]
```
**Note:** The **ccopulsed** and **ccomaintained** things are now deprecated.
You should use the **cco** thing with the appropriate `outputType` setting instead.
-Each **cco** thing creates one switch channel called *switchstatus*.
+Each **cco** thing creates one switch channel called _switchstatus_.
For pulsed CCOs, sending an ON command will close the output for the configured pulse time.
Sending an OFF command does nothing.
Because of limitations in RadioRA 2, you cannot monitor the state of a pulsed CCO.
Thing configuration file example:
-```
+```java
Thing cco garage [ integrationId=5, outputType="Pulsed", pulseLength=0.5 ]
Thing cco relay1 [ integrationId=7, outputType="Maintained"]
```
Each Lutron shade, motorized drape, or QS motor controller output (LQSE-4M-D) is controlled by a **shade** thing.
The only configuration parameter it accepts is `integrationId`.
-A single channel *shadelevel* with item type Rollershutter and category Rollershutter will be created for each **shade** thing.
+A single channel _shadelevel_ with item type Rollershutter and category Rollershutter will be created for each **shade** thing.
It accepts Percent, Up, Down, Stop and Refresh commands.
Sending a Percent command will cause the shade to immediately move so as to be open the specified percentage.
You can also read the current shade level from the channel.
Motor controller outputs on a LQSE-4M-D (HomeWorks QS only) behave similarly to a shade.
The only difference is that percentages other than 0% and 100% will be ignored, since arbitrary positioning is not supported by the hardware.
-The value of *shadelevel* for a motor will likewise always be either 0% or 100%, depending on whether the last command sent was Up or Down.
+The value of _shadelevel_ for a motor will likewise always be either 0% or 100%, depending on whether the last command sent was Up or Down.
**Note:** While a shade is moving to a specific level because of a Percent command, the system will report the target level for the shade rather than the actual current level.
While a shade is moving because of an Up or Down command, it will report the previous level until it stops moving.
Thing configuration file example:
-```
+```java
Thing shade libraryshade [ integrationId=33]
```
There is no default.
If discovery is used, the `type` parameter will set automatically when the **blind** thing is created.
-Two channels, *blindliftlevel* and *blindtiltlevel*, with item type Rollershutter and category Rollershutter will be created for each **blind** thing.
+Two channels, _blindliftlevel_ and _blindtiltlevel_, with item type Rollershutter and category Rollershutter will be created for each **blind** thing.
They control the up/down motion and the slat tilt motions of the blinds, respectively.
Each channel accepts Percent, Up, Down, Stop and Refresh commands.
Sending a Percent command will cause the blind to immediately move so as to be open the specified percentage.
Thing configuration file example:
-```
+```java
Thing blind officeblinds [ integrationId=76, type="Venetian"]
```
The **greenmode** thing is used to interface to the green mode subsystem.
It requires that the `integrationId` parameter be set to the ID of the green mode subsystem.
This should generally be 22.
-It creates a single channel *step* that can be used to set or query the active green mode step number.
+It creates a single channel _step_ that can be used to set or query the active green mode step number.
Unlike other Lutron system state settings, the binding is not automatically notified by the bridge device of changes to the current green mode step.
This may be due to a bug in the Lutron firmware.
Thing configuration file example:
-```
+```java
Thing greenmode greenmode [ integrationId=22 ]
```
It creates the following six channels:
-* *clockmode* - Gets or sets the current timeclock mode.
-* *sunrise* - The timeclock's local sunrise time for the current day. Read only. You must send a refresh command (RefreshType.REFRESH) to query the system for the current day's sunrise time, as it is not automatically updated.
-* *sunset* - The timeclock's local sunset time for the current day. Read only. You must send a refresh command to query the system for the current day's sunset time, as it is not automatically updated.
-* *execevent* - Updates with the index number of each executing event. Send an event's index number to start execution of it.
-* *enableevent* - Updates with an event's index number when it is enabled. Send an event's index number to enable it.
-* *disableevent* - Updates with an event's index number when it is disabled. Send an event's index number to disable it.
+- _clockmode_ - Gets or sets the current timeclock mode.
+- _sunrise_ - The timeclock's local sunrise time for the current day. Read only. You must send a refresh command (RefreshType.REFRESH) to query the system for the current day's sunrise time, as it is not automatically updated.
+- _sunset_ - The timeclock's local sunset time for the current day. Read only. You must send a refresh command to query the system for the current day's sunset time, as it is not automatically updated.
+- _execevent_ - Updates with the index number of each executing event. Send an event's index number to start execution of it.
+- _enableevent_ - Updates with an event's index number when it is enabled. Send an event's index number to enable it.
+- _disableevent_ - Updates with an event's index number when it is disabled. Send an event's index number to disable it.
-All channels except *clockmode* are marked as advanced.
+All channels except _clockmode_ are marked as advanced.
Thing configuration file example:
-```
+```java
Thing timeclock timeclock [ integrationId=23 ]
```
Example rule to refresh sunrise/sunset channels daily and at restart:
-```
+```java
import org.openhab.core.types.RefreshType
rule "Lutron sunrise/sunset daily refresh"
The **sysvar** thing allows state variable values to be read and set from openHAB.
This makes sophisticated integration schemes possible.
Each **sysvar** thing represents one system state variable.
-It has a single channel *varstate* with type Number and category Number.
+It has a single channel _varstate_ with type Number and category Number.
Automatic discovery of state variables is not yet supported.
They must be manually configured.
Thing configuration file example:
-```
+```java
Thing sysvar qsstate [ integrationId=80 ]
```
|switch |switchstatus |OnOffType |OnOffType |
|fan |fanspeed |StringType |"OFF","LOW","MEDIUM","MEDIUMHIGH","HIGH" |
|fan |fanlevel |PercentType |OnOffType, PercentType |
-|occ. sensor|occupancystatus|OnOffType |(*readonly*) |
-|ogroup |groupstate |StringType |"OCCUPIED","UNOCCUPIED","UNKNOWN" (*readonly*) |
+|occ. sensor|occupancystatus|OnOffType |(_readonly_) |
+|ogroup |groupstate |StringType |"OCCUPIED","UNOCCUPIED","UNKNOWN" (_readonly_) |
|cco |switchstatus |OnOffType |OnOffType, RefreshType |
|keypads |button* |OnOffType |OnOffType |
| |led* |OnOffType |OnOffType, RefreshType |
-| |cci* |OpenClosedType|(*readonly*) |
+| |cci* |OpenClosedType|(_readonly_) |
|shade |shadelevel |PercentType |PercentType, UpDownType, StopMoveType.STOP, RefreshType|
|blind |blindliftlevel |PercentType |PercentType, UpDownType, StopMoveType.STOP, RefreshType|
| |blindtiltlevel |PercentType |PercentType, UpDownType, StopMoveType.STOP, RefreshType|
|greenmode |step |DecimalType |DecimalType, OnOffType (ON=2,OFF=1), RefreshType |
|timeclock |clockmode |DecimalType |DecimalType, RefreshType |
-| |sunrise |DateTimeType |RefreshType (*readonly*) |
-| |sunset |DateTimeType |RefreshType (*readonly*) |
+| |sunrise |DateTimeType |RefreshType (_readonly_) |
+| |sunset |DateTimeType |RefreshType (_readonly_) |
| |execevent |DecimalType |DecimalType |
| |enableevent |DecimalType |DecimalType |
| |disableevent |DecimalType |DecimalType |
|sysvar |varstate |DecimalType |DecimalType (rounded/truncated to integer) |
Most channels receive immediate notifications of device state changes from the Lutron control system.
-The only exceptions are **greenmode** *step*, which is periodically polled and accepts REFRESH commands to initiate immediate polling, and **timeclock** *sunrise* and *sunset*, which must be polled daily using REFRESH commands to retrieve current values.
+The only exceptions are **greenmode** _step_, which is periodically polled and accepts REFRESH commands to initiate immediate polling, and **timeclock** _sunrise_ and _sunset_, which must be polled daily using REFRESH commands to retrieve current values.
Many other channels accept REFRESH commands to initiate a poll, but sending one should not normally be necessary.
-
## RadioRA 2/HomeWorks QS Configuration File Examples:
demo.things:
-```
+```java
Bridge lutron:ipbridge:radiora2 [ ipAddress="192.168.1.123", user="lutron", password="integration" ] {
Thing dimmer lrtable "Table Lamp" @ "Living Room" [ integrationId=45, fadeInTime=0.5, fadeOutTime=5 ]
Thing dimmer lrtorch "Torch Lamp" @ "Living Room" [ integrationId=44, fadeInTime=0.5, fadeOutTime=5 ]
demo.items:
-```
+```java
Dimmer LivingRm_TableLamp "Table Lamp" { channel="lutron:dimmer:radiora2:lrtable:lightlevel" }
Switch FrontYard_PathLight "Path Light" { channel="lutron:switch:radiora2:path:switchstatus" }
Switch LaundryRm_Sensor "Occ Sensor" { channel="lutron:occupancysensor:radiora2:laundryocc:occupancystatus" }
dimmerAction.rules:
-```
+```java
rule "Test dimmer action"
when
Item TestSwitch received command ON
end
```
-
# Lutron RadioRA (Classic) Binding
This binding integrates with the legacy Lutron RadioRA (Classic) lighting system.
| ra-switch | Thing | Switch control |
| ra-phantomButton | Thing | Phantom Button to control multiple controls (Scenes) |
-
## Thing Configuration Parameters
| Thing | Parameter | Description |
lutronradiora.things
-```
+```java
Bridge lutronradiora:ra-rs232:chronos1 [portName="/dev/ttys002"] {
Thing ra-dimmer dimmer1 [ zoneNumber=1 ]
Thing ra-dimmer dimmer2 [ zoneNumber=2 ]
lutronradiora.items
-```
+```java
Dimmer Dimmer_Kitchen "Kitchen Lights" { channel="lutronradiora:dimmer:chronos1:dimmer1:lightlevel" }
Dimmer Dimmer_FamilyRoom "Family Room Lights" { channel="lutronradiora:dimmer:chronos1:dimmer2:lightlevel" }
Switch Switch_Patio "Patio Light" { channel="lutronradiora:dimmer:chronos1:switch1:switchstatus" }
## Supported Things
-* HomeWorks RS232-connected Processor Units
-* Dimmers
+- HomeWorks RS232-connected Processor Units
+- Dimmers
Supported in future updates:
-* Keypads
-* Keypad LEDs
+- Keypads
+- Keypad LEDs
## Discovery
The bridge requires the port location (e.g., /dev/ttyUSB1 or COM1) and the baud rate. The default baud rate for HomeWorks processors is set to 9600.
-```
+```java
lutron:hwserialbridge:home [serialPort="/dev/ttyUSB1", baudRate="9600]
```
Dimmers have one required parameter ``address`` that specifies the device address (e.g., [01:01:03:02:04]) and two optional parameters: ``fadeTime`` which sets the time it takes to set the light level when changed, and ``defaultLevel`` which sets the level to use for the dimmer when turning it on (with a switch rather than a slider).
-```
+```java
lutron:hwdimmer:dimmer1 [address="[01:01:03:02:04]", fadeTime="1", defaultLevel="75"]
```
|-----------------|-------------------|--------------|--------------------------------------------- |
| dimmer | lightlevel | Dimmer | Increase/decrease the light level |
-
# Lutron Grafik Eye 3x/4x binding via GRX-PRG or GRX-CI-PRG
This lutron binding will also work with Grafik Eye 3x/4x systems in conjuction with the GRX-PRG or GRX-CI-PRG interfaces.
Optionally, you may specify the username (defaults to 'nwk') and retryPolling (in seconds) to retry connections if the connection fails (defaults to 10 seconds).
This bridge does support two way communication with the Grafik Eye units (if a scene is selected or a zone changed on the unit or via a keypad, that information is immediately available in openHAB).
-```
+```java
lutron:prgbridge:home [ ipAddress="192.168.1.51", user="nwk", retryPolling=10 ]
```
If any of the zones control a QED shade (via the SG/SO-SVCN/SVCI keypad), those zones
should be listed (comma separated list) in the shadeZones.
-```
+```java
lutron:grafikeye:home (lutron:prgbridge:home) [ controlUnit=1, fade=10, polling=30, shadeZones="2,3,4" ]
```
| ssnextsecond | Yes | Number | How many seconds until the next step in the Super Sequence |
| buttonpress | Yes | String | Last keypad button pressed (see Appendix A) in protocol guide |
-
-
### Grafik Eye channels
| Channel Type ID | Readonly | Item Type | Description |
### Notes
-* The "buttonpress" channel reports which keypad button was pressed. DIP switch 6 must be set on the interface for this to be reported. The "buttonpress" channel is only useful in rules to take action when a specific button (on a specific keypad) has been pressed.
-* Sunset/sunrise will only be available if configured via the Liasion software
-* scenelock, sceneseq, zonelock cannot be determined from the API and will default to OFF on startup
-* Replace the "X" on zonelowerX, zoneraiseX, etc with the zone in question. "zonelower1" will affect zone 1. Specifying a zone larger than you have will have no effect (such as using zonelower8 on a Grafik Eye 3506 which only has 6 zones).
-* The zonefade value will only be used when zonelower/zonereaise/zoneintensity is issued.
-* zoneshade does not support PercentType nor StopMoveType.Move and those commands will be ignored
-* zoneintensity can be used on a shade zone if the intensity is from 0 to 5 and should be used if wanting to set a QED preset: 0=Stop, 1=Open, 2=Close, 3=Preset 1, 4=Preset 2, 5=Preset 3
-* If you started a zonelower or zoneraise, the only way to stop the action is by executing an all zone stop on the bridge (i.e. zonelowerstop or zoneraisestop). The PRG API does not provide a way to stop the lowering/raising of any specific zone.
-
+- The "buttonpress" channel reports which keypad button was pressed. DIP switch 6 must be set on the interface for this to be reported. The "buttonpress" channel is only useful in rules to take action when a specific button (on a specific keypad) has been pressed.
+- Sunset/sunrise will only be available if configured via the Liasion software
+- scenelock, sceneseq, zonelock cannot be determined from the API and will default to OFF on startup
+- Replace the "X" on zonelowerX, zoneraiseX, etc with the zone in question. "zonelower1" will affect zone 1. Specifying a zone larger than you have will have no effect (such as using zonelower8 on a Grafik Eye 3506 which only has 6 zones).
+- The zonefade value will only be used when zonelower/zonereaise/zoneintensity is issued.
+- zoneshade does not support PercentType nor StopMoveType.Move and those commands will be ignored
+- zoneintensity can be used on a shade zone if the intensity is from 0 to 5 and should be used if wanting to set a QED preset: 0=Stop, 1=Open, 2=Close, 3=Preset 1, 4=Preset 2, 5=Preset 3
+- If you started a zonelower or zoneraise, the only way to stop the action is by executing an all zone stop on the bridge (i.e. zonelowerstop or zoneraisestop). The PRG API does not provide a way to stop the lowering/raising of any specific zone.
## Example
demo.Things:
-```
+```java
lutron:prgbridge:home [ ipAddress="192.168.1.51", user="nwk", retryPolling=10 ]
lutron:grafikeye:home (lutron:prgbridge:home) [ controlUnit=1, fade=10, polling=10 ]
```
demo.items:
-```
+```java
String Prg_ButtonPress "Last Button Press [%s]" { channel = "lutron:prgbridge:home:buttonpress" }
Switch Prg_ZoneLowerStop "Zone Lower Stop" { channel = "lutron:prgbridge:home:zonelowerstop",autoupdate="false" }
Switch Prg_ZoneRaiseStop "Zone Raise Stop" { channel = "lutron:prgbridge:home:zoneraisestop",autoupdate="false" }
# Luxom Binding
-This binding integrates with a https://luxom.io/ based system through a Luxom IP interface module.
+This binding integrates with a <https://luxom.io/> based system through a Luxom IP interface module.
The binding has been tested with the DS65L IP interface, but it's not an official binding by Luxom.
-The API implementation is based on the following documentation:
+The API implementation is based on the following documentation:
-* https://old.luxom.io/uploads/ppfiles/27/LUXOM_ASCII.pdf
-* https://old.luxom.io/uploads/ppfiles/28/LUXOM_ASCII_extended.pdf
+- <https://old.luxom.io/uploads/ppfiles/27/LUXOM_ASCII.pdf>
+
+- <https://old.luxom.io/uploads/ppfiles/28/LUXOM_ASCII_extended.pdf>
## Supported Things
This binding currently supports the following thing types:
-* **ipbridge** - The Lutron main repeater/processor/hub
-* **dimmer** - Light dimmer
-* **switch** - Switch or relay module
+- **ipbridge** - The Lutron main repeater/processor/hub
+- **dimmer** - Light dimmer
+- **switch** - Switch or relay module
## Thing Configuration
The Bridge thing has two parameters:
-- ipAddress: This is the IP address of the IP interface module
+- ipAddress: This is the IP address of the IP interface module
- port: The listening port (optional, defaults to 2300)
-```
+```java
Bridge luxom:bridge:myhouse [ ipAddress="192.168.0.50", port="2300"] {
...
}
### Devices
-Each device has an address on the Luxom bus, this address must be specified in the 'address' parameter.
-You will have to look it up in your documentation or in the 'Luxom Plusconfig' software.
+Each device has an address on the Luxom bus, this address must be specified in the 'address' parameter.
+You will have to look it up in your documentation or in the 'Luxom Plusconfig' software.
-Sometimes a device does not send back a confirmation over the bus having set the correct state.
-Some dimmers do the dimming, but do not send back the set brightness level.
+Sometimes a device does not send back a confirmation over the bus having set the correct state.
+Some dimmers do the dimming, but do not send back the set brightness level.
To be able to use these devices, you can add the `doesNotReply=true` parameter so that the binding immediately sets the item's state and does not wait for confirmation.
#### Dimmers
Dimmers support the optional advanced parameters `onLevel`, `onToLast` and `stepPercentage`:
-* The `onLevel` parameter specifies the level to which the dimmer will go when sent an ON command. It defaults to 100.
-* The `onToLast` parameter is a boolean that defaults to false. If set to "true", the dimmer will go to its last non-zero level when sent an ON command. If the last non-zero level cannot be determined, the value of `onLevel` will be used instead.
-* The `stepPercentage` specifies the in-/decrease in percentage of brightness. Default is 5.
+- The `onLevel` parameter specifies the level to which the dimmer will go when sent an ON command. It defaults to 100.
+- The `onToLast` parameter is a boolean that defaults to false. If set to "true", the dimmer will go to its last non-zero level when sent an ON command. If the last non-zero level cannot be determined, the value of `onLevel` will be used instead.
+- The `stepPercentage` specifies the in-/decrease in percentage of brightness. Default is 5.
-A **dimmer** thing has a single channel *Lighting.Brightness* with type Dimmer and category DimmableLight.
+A **dimmer** thing has a single channel _Lighting.Brightness_ with type Dimmer and category DimmableLight.
Thing configuration file example:
-```
+```java
Thing dimmer dimmerLightLiving1 [address="A,02", onLevel="50", onToLast="false", stepPercentage="5"]
```
#### Switches
Switches take no additional parameters.
-A **switch** thing has a single channel *switch* with type Switch and category Switch.
+A _switch_ thing has a single channel **switch** with type Switch and category Switch.
Thing configuration file example:
-```
+```java
Thing switch switchLiving1 [address="A,02"]
```
| dimmer | brightness | Dimmer | Increase/decrease the light level |
| switch | switch | Switch | Switch the device on/off |
-
### Full Example
demo.things:
-```
+```java
Bridge luxom:bridge:myhouse [ ipAddress="192.168.0.50", port="2300"] {
Thing switch switchBedroom1 "Switch 1" @ "Bedroom" [address="1,01"]
Thing dimmer dimmerBedroom1 "dimmer 1" @ "Bedroom" [address="A,02"]
demo.items:
-```
+```java
Dimmer FF_Bedroom_Lights "Bedroom dimmer light" <light> (FF_Living, gLight) ["Lighting"] {channel="luxom:dimmer:myhouse:dimmerBedroom1:brightness", ga="Light", homekit="Lighting, Lighting.Brightness"}
Switch FF_Bedroom_PowerOutlet1 "Bedroom Power Outlet 1" <poweroutlet> (FF_Living, gPower) ["Switchable"] {channel="luxom:switch:myhouse:switchBedroom1:switch", ga="Outlet"}
Dimmer FF_Kitchen_Lights "Kitchen dimmer light" <light> (FF_Kitchen, gLight) ["Lighting"] {channel="luxom:dimmer:myhouse:dimmerKitchen1:brightness", ga="Light", homekit="Lighting, Lighting.Brightness"}
This binding gives the possibility to integrate any Heatpump that is based on the Luxtronik 2 contol unit of Alpha Innotec. This includes heatpumps of:
-* Alpha InnoTec
-* Buderus (Logamatic HMC20, HMC20 Z)
-* CTA All-In-One (Aeroplus)
-* Elco
-* Nibe (AP-AW10)
-* Roth (ThermoAura®, ThermoTerra)
-* (Siemens) Novelan (WPR NET)
-* Wolf Heiztechnik (BWL/BWS)
+- Alpha InnoTec
+- Buderus (Logamatic HMC20, HMC20 Z)
+- CTA All-In-One (Aeroplus)
+- Elco
+- Nibe (AP-AW10)
+- Roth (ThermoAura®, ThermoTerra)
+- (Siemens) Novelan (WPR NET)
+- Wolf Heiztechnik (BWL/BWS)
This binding was tested with:
-* Siemens Novelan LD 7
+- Siemens Novelan LD 7
-_If you have another heatpump the binding works with, let us know, so we can extend the list_
+:::tip Note
+If you have another heatpump the binding works with, let us know, so we can extend the list
+:::
Note: The whole functionality is based on data that was reverse engineered, so use it at your own risk.
The usage of the numbered channels above is currently unknown. If you are able to directly match one of the values to any value reported by your heat pump, feel free to report back on the forum, so we are able to give the channel a proper name instead.
-
The following channels are also writable:
| channel | type | advanced | description |
|----------|--------|----------|------------------------------|
| comfortCoolingATExcess | Number:Time | | AT Excess |
| comfortCoolingATUndercut | Number:Time | | AT undercut |
-
## Example
Below you can find some example textual configuration for a heatpump with some basic functionallity. This can be extended/adjusted according to your needs and depending on the availability of channels (see list above).
_heatpump.things:_
-```
+```java
Thing luxtronikheatpump:heatpump:heatpump "Heatpump" [
ipAddress="192.168.178.12",
port="8889",
_heatpump.items:_
-```
+```java
Group gHeatpump "Heatpump" <temperature>
Number:Temperature HeatPump_Temp_Outside "Temperature outside [%.1f °C]" <temperature> (gHeatpump) { channel="luxtronikheatpump:heatpump:heatpump:temperatureOutside" }
_heatpump.sitemap:_
-```
+```perl
sitemap heatpump label="Heatpump" {
Frame label="Heatpump" {
Text item=HeatPump_State_Ext
### Supported Models
-* Deutsche Telekom Media Receiver MR401B - fully supported
-* Deutsche Telekom Media Receiver MR201 - fully supported
-* Deutsche Telekom Media Receiver MR400 - supported with minor restrictions (POWER key)
-* Deutsche Telekom Media Receiver MR200 - supported with minor restrictions (POWER key)
-* Deutsche Telekom Media Receiver MR601 - should be supported (not verified)
-* Deutsche Telekom Media Receiver MR3xx - NOT supported (different platform)
-* Deutsche Telekom Media Receiver MR1xx - NOT supported (different platform)
+| Model | Status |
+|----------------------------------------|-----------------------------------------------|
+| Deutsche Telekom Media Receiver MR401B | fully supported |
+| Deutsche Telekom Media Receiver MR201 | fully supported |
+| Deutsche Telekom Media Receiver MR400 | supported with minor restrictions (POWER key) |
+| Deutsche Telekom Media Receiver MR200 | supported with minor restrictions (POWER key) |
+| Deutsche Telekom Media Receiver MR601 | should be supported (not verified) |
+| Deutsche Telekom Media Receiver MR3xx | NOT supported (different platform) |
+| Deutsche Telekom Media Receiver MR1xx | NOT supported (different platform) |
## Auto Discovery
Run the following command on the console and provide your Telekom account credentials:
-```
+```shell
openhab> openhab:magentatv login
Username (email): mail@example.com
Password: topsecret
On successful login the console will show the User ID value. Copy&Paste this value to the Thing configuration (parameter `userId`) of the receiver.
If you have multiple receivers under the same MagentaTV subscription you can use this value for all of them.
-2. Provide your credentials in the UI
+1. Provide your credentials in the UI
If you do not want to use the openHAB console, you can also setup the credentials in the Thing configuration
### magentatv.things
-```
+```java
Thing magentatv:receiver:XXXXXXXXXXX "MagentaTV" [
-udn="XXXXXXXXXXX",
-ipAddress="xxx.xxx.xxx.xxx",
-accountName="xxxxxx.xxxx@t-online.de",
-accountPassword="xxxxxxxxxx"
+ udn="XXXXXXXXXXX",
+ ipAddress="xxx.xxx.xxx.xxx",
+ accountName="xxxxxx.xxxx@t-online.de",
+ accountPassword="xxxxxxxxxx"
]
```
### magentatv.items
-```
+```java
# MagentaTV Control
Switch MagentaTV_Power "Power" {channel="magentatv:receiver:XXXXXXXXXXX:control#power"}
Number MagentaTV_Channel "Channel" {channel="magentatv:receiver:XXXXXXXXXXX:status#channel"}
or
-```
+```java
Group gRB_GF_LR_TVReceiver "RB_GF_LR: TV Receiver"
(gRB_GF_LivingRoom, gMedia, gSpeechCmnd)
### sitemap
-```
+```perl
Text label="TV" icon="it_television" {
Frame label="Bedienung" {
Switch item=RB_GF_LR_TVReceiver_Power label="Ein/Aus []" icon="control_on_off" mappings=[ ON="Ein/Aus" ]
Beginning with models 401/201 and new the binding is able to detect the Power-OFF condition, which can be used in a rule to improve this situation
-```
- if (MagentaTV_Power.state != ON) {
- sendCommand(MagentaTV_Power, ON)
- }
+```java
+if (MagentaTV_Power.state != ON) {
+ sendCommand(MagentaTV_Power, ON)
+}
```
to switch it ON and
-```
- if (MagentaTV_Power.state != OFF) {
- sendCommand(MagentaTV_Power, OFF)
- }
+```java
+if (MagentaTV_Power.state != OFF) {
+ sendCommand(MagentaTV_Power, OFF)
+}
```
to switch it off.
mail.things:
-```
+```java
Thing mail:smtp:samplesmtp [ hostname="smtp.example.com", sender="mail@example.com", security="SSL", username="user", password="pass" ]
Thing mail:imap:sampleimap [ hostname="imap.example.com", security="SSL", username="user", password="pass" ] {
mail.items:
-```
+```java
Number InboxTotal "INBOX [%d]" { channel="mail:imap:sampleimap:inbox_total" }
Number InboxUnread "INBOX Unread [%d]" { channel="mail:imap:sampleimap:inbox_unread" }
```
mail.sitemap:
-```
+```perl
sitemap demo label="Main Menu"
{
Frame {
This binding includes rule actions for sending email.
Six different actions available:
-* `boolean success = sendMail(String recipient, String subject, String text)`
-* `boolean success = sendMailWithAttachment(String recipient, String subject, String text, String URL)`
-* `boolean success = sendMailWithAttachments(String recipient, String subject, String text, List<String> URL)`
-* `boolean success = sendHtmlMail(String recipient, String subject, String htmlContent)`
-* `boolean success = sendHtmlMailWithAttachment(String recipient, String subject, String htmlContent, String URL)`
-* `boolean success = sendHtmlMailWithAttachments(String recipient, String subject, String htmlContent, List<String> URL)`
+- `boolean success = sendMail(String recipient, String subject, String text)`
+- `boolean success = sendMailWithAttachment(String recipient, String subject, String text, String URL)`
+- `boolean success = sendMailWithAttachments(String recipient, String subject, String text, List<String> URL)`
+- `boolean success = sendHtmlMail(String recipient, String subject, String htmlContent)`
+- `boolean success = sendHtmlMailWithAttachment(String recipient, String subject, String htmlContent, String URL)`
+- `boolean success = sendHtmlMailWithAttachments(String recipient, String subject, String htmlContent, List<String> URL)`
The `sendMail(...)` send a plain text mail (with attachments if supplied).
The `sendHtmlMail(...)` send a HTML mail (with attachments if supplied).
Examples:
-```
+```java
val mailActions = getActions("mail","mail:smtp:samplesmtp")
val success = mailActions.sendMail("mail@example.com", "Test subject", "This is the mail content.")
success = mailActions.sendMail("mail1@example.com, mail2@example.com", "Test subject", "This is the mail content sent to multiple recipients.")
```
-```
+```java
import java.util.List
val List<String> attachmentUrlList = newArrayList(
Headers can be added inside a rule by calling the `mailActions.addHeader()` method before calling the respective `mailActions.sendMail()` method.
See the example below.
-```
+```java
rule "Send Mail with a 'Reference' header; for threaded view in e-mail client"
when
...
max.items:
```java
-Group gMAX "MAX Heating" <temperature> [ "home-group" ]
+Group gMAX "MAX Heating" <temperature> [ "home-group" ]
Switch maxBattery "Battery Low" (gMAX) {channel="max:thermostat:KEQ0565026:KEQ0648949:battery_low"}
String maxMode "Thermostat Mode Setting" (gMAX) {channel="max:thermostat:KEQ0565026:KEQ0648949:mode"}
In the _Configuration Parameters_ section of the device Things you can update some of the device configuration parameters.
Currently the following parameters can be updated:
-* _name_ Name of the thermostat stored in the Cube (also used by the eQ-3 software).
+- _name_ Name of the thermostat stored in the Cube (also used by the eQ-3 software).
-_Cube device configurable parameters_
+### Cube device configurable parameters
-* _ntpServer1_ The hostname for NTP Server 1 used by the Cube to get the time
-* _ntpServer2_ The hostname for NTP Server 2 used by the Cube to get the time
+- _ntpServer1_ The hostname for NTP Server 1 used by the Cube to get the time
+- _ntpServer2_ The hostname for NTP Server 2 used by the Cube to get the time
## Thing Actions
Several Thing Actions are available to trigger special actions on the MAX! Cube
-* `reset()`: _Reset Cube Configuration_ resets the MAX! Cube room and device information. Devices will need to be included again!
+- `reset()`: _Reset Cube Configuration_ resets the MAX! Cube room and device information. Devices will need to be included again!
-* `reboot()`: _Restart Cube_ triggers the reboot of a Cube. This can be used if a Cube became unresponsive to commands or no connection can be made. (e.g. if you tried to connect to the Cube with multiple applications at the same time)
+- `reboot()`: _Restart Cube_ triggers the reboot of a Cube. This can be used if a Cube became unresponsive to commands or no connection can be made. (e.g. if you tried to connect to the Cube with multiple applications at the same time)
On the MAX! devices you can trigger the following action
-* `deleteFromCube()`: _Delete Device from Cube_ deletes the device from the MAX! Cube. Device will need to be included again!
+- `deleteFromCube()`: _Delete Device from Cube_ deletes the device from the MAX! Cube. Device will need to be included again!
### Example Rule
# MCD Binding
-This binding allows you to send sensor events from your openHAB environment to the cloud application Managing Care Digital (MCD) by [C&S Computer und Software GmbH](https://www.managingcare.de/).
+This binding allows you to send sensor events from your openHAB environment to the cloud application Managing Care Digital (MCD) by [C&S Computer und Software GmbH](https://www.managingcare.de/).
-MCD is the platform for inpatient and outpatient nursing services.
-Our REST API allows you to send a variety of sensor events to the system and thus being able to connect your Ambient Assisted Living (AAL) or smart home environment to the documentation software of your nursing service.
+MCD is the platform for inpatient and outpatient nursing services.
+Our REST API allows you to send a variety of sensor events to the system and thus being able to connect your Ambient Assisted Living (AAL) or smart home environment to the documentation software of your nursing service.
Please note that a valid account is needed to access MCD and the Sensor API.
-
## Supported Things
-There are two supported things: **MCD Bridge** and **MCD Sensor Thing**.
-
+There are two supported things: **MCD Bridge** and **MCD Sensor Thing**.
## Discovery
-Discovery is not supported.
-
+Discovery is not supported.
## Thing Configuration
### MCD Bridge
-The MCD Bridge (`mcdBridge`) needs to be configured with your valid C&S MCD / sync API credentials.
+The MCD Bridge (`mcdBridge`) needs to be configured with your valid C&S MCD / sync API credentials.
| parameter | description |
|-----------|------------------------------------|
### MCD Sensor Thing
-Each sensor thing (`mcdSensor`) needs to be configured with the identical serial number, that is assigned to this sensor in MCD.
+Each sensor thing (`mcdSensor`) needs to be configured with the identical serial number, that is assigned to this sensor in MCD.
| parameter | description |
|----------------|------------------------------------|
## Channels
-The `mcdSensor` thing supports the following channels. To see the sensors' events, please visit [Managing Care Digital](https://cundsdokumentation.de/) and navigate to the dashboard.
+The `mcdSensor` thing supports the following channels. To see the sensors' events, please visit [Managing Care Digital](https://cundsdokumentation.de/) and navigate to the dashboard.
| channel | type | description |
|-------------|--------|-----------------------------------------------|
| lastEvent | String | shows the last event that was sent with date and time |
| sendEvent | String | stateless channel for sending events to the API, see list below for valid commands |
-The channel `sendEvent` accepts valid Sensor Event Definitions as well as the corresponding ID.
-The following table contains all currently accepted Sensor Event Definitions that can be passed as String type commands.
-As soon as new events are added to the API, you can use their ID, even if the Definition is not yet added to this list.
+The channel `sendEvent` accepts valid Sensor Event Definitions as well as the corresponding ID.
+The following table contains all currently accepted Sensor Event Definitions that can be passed as String type commands.
+As soon as new events are added to the API, you can use their ID, even if the Definition is not yet added to this list.
For more information about the API, you can have a look at the [C&S Sync API](https://cunds-syncapi.azurewebsites.net/ApiDocumentation).
| Valid String Type Commands |
| NUMBERPERSONS |
| BRIGHTNESSZONE |
-
## Full Example
Here is an example for the textual configuration. You can of course use the Administration section of the GUI as well.
demo.things:
-```
+```java
Bridge mcd:mcdBridge:exampleBridge [userEmail="your.email@examle.com", userPassword="your.password"]{
Thing mcd:mcdSensor:examlpeSensor [serialNumber="123"]
Thing mcd:mcdSensor:secondExamlpeSensor [serialNumber="456"]
demo.items:
-```
+```java
String lastValue "Last Value" {channel="mcd:mcdSensor:examlpeSensor:lastValue"}
String sendEvent "Send Event" {channel="mcd:mcdSensor:examlpeSensor:sendEvent"}
```
demo.sitemap:
-```
+```perl
Text item=sendEvent
Text item=lastValue
```
As the MCP23017 has 3 address pins, you are restricted to 8 devices on an I2C bus.
To use more devices you have to open further I2C busses.
Therefore you can use overlays to enable bit banging I2C busses on the Raspberry Pi connector, up to I2C6.
-(https://github.com/raspberrypi/firmware/tree/master/boot/overlays)
+<https://github.com/raspberrypi/firmware/tree/master/boot/overlays>
## Dependencies
## Thing Configuration
-* Required configuration for mcp23017 thing:
+- Required configuration for mcp23017 thing:
| Parameter | Description | Default value |
|------------|-----------------------------------------------------------------------------------------------------------------------------------|---------------|
Let's imagine a setup with:
1. a wall switch connected to pin B1 on the MCP23017 chip which should turn on/off your LED light when pressed (released).
-2. a relay which is connected to pin A0 on the MCP23017 chip. This relay takes care of turning on/off your light.
+1. a relay which is connected to pin A0 on the MCP23017 chip. This relay takes care of turning on/off your light.
Pressing (and releasing) a wall switch should notify openHAB, and then openHAB should change state of relay to on/off the light.
Your pin B1 should work as DIGITAL_INPUT, because it READS state of a PIN (state of wall switch). Your pin A0 should work as DIGITAL_OUTPUT
because openHAB will SET state of this PIN. So your config should look like this:
-* Things:
+- Things:
Minimal configuration:
-```
+```java
Thing mcp23017:mcp23017:chipA "MCP23017 chip A" [address=20,bus=1]
```
Configuration with default_state and pull_mode:
-```
+```java
Thing mcp23017:mcp23017:chipA "MCP23017 chip A" [address=20,bus=1] {
Type output_pin : output#A0 [default_state="HIGH"]
Type output_pin : output#A1 [default_state="LOW"]
}
```
-* Items:
+- Items:
-```
+```java
Switch living_room_led_switch "Living room LED switch" {channel="mcp23017:mcp23017:chipA:output#A0"}
Contact living_room_led_contact "Living room LED contact" {channel="mcp23017:mcp23017:chipA:input#B1"}
```
-* Rules:
+- Rules:
-```
+```java
rule "living_room_led contact"
when
Item living_room_led_contact changed to OPEN
-
## Supported Things
This binding supports the following thing types:
- meaterapi: Bridge - Communicates with the MEATER Cloud REST API.
-
-- meaterprobe: The MEATER probe - Only support for cloud connected MEATER probes (MEATER Block and MEATER Plus)
+- meaterprobe: The MEATER probe - Only support for cloud connected MEATER probes (MEATER Block and MEATER Plus)
## Discovery
#### Configuration Options
-| Parameter | Description | Type | Default | Required |
+| Parameter | Description | Type | Default | Required |
|-----------|--------------------------------------------------------------|--------|----------|----------|
| email | The email used to login to your MEATER Cloud account | String | NA | yes |
| password | The password used to login to your MEATER Cloud account | String | NA | yes |
#### Configuration Options
-| Parameter | Description | Type | Default | Required |
+| Parameter | Description | Type | Default | Required |
|-----------|--------------------------------------------------------------|--------|----------|----------|
| deviceId | Unique id for your MEATER Probe | String | NA | yes |
-
-
#### Channels
-| Channel Type ID | Item Type | Description |
+| Channel Type ID | Item Type | Description |
|-----------------------|--------------------|------------------------------------------------------|
| internalTemperature | Number:Temperature | Internal temperature reading of MEATER probe |
| ambientTemperature | Number:Temperature | Ambient temperature reading of MEATER probe. If ambient is less than internal, ambient will equal internal |
| cookPeakTemperature | Number:Temperature | Peak temperature of current cook |
| lastConnection | DateTime | Date and time of last probe connection |
| cookId | String | Unique cook ID of current cook |
-| cookName | String | Name of selected meat or user given custom name |
+| cookName | String | Name of selected meat or user given custom name |
| cookState | String | One of Not Started, Configured, Started, Ready For Resting, Resting, Slightly Underdone, Finished, Slightly Overdone, OVERCOOK! |
| cookElapsedTime | Number:Time | Time since the start of cook in seconds. Default: 0 |
| cookRemainingTime | Number:Time | Remaining time in seconds or UNDEF when unknown. |
| cookEstimatedEndTime | DateTime | Date and time of estimated end time for current cook |
-
## Example
### Things-file
-````
+```java
Bridge meater:meaterapi:block "MEATER Block" [email="", password="", refresh=30] {
meaterprobe probe1 "Meater Probe 1" [deviceId=""]
meaterprobe probe2 "Meater Probe 2" [deviceId=""]
meaterprobe probe3 "Meater Probe 3" [deviceId=""]
meaterprobe probe4 "Meater Probe 4" [deviceId=""]
}
-````
+```
### Items-file
-````
+```java
Number:Temperature Probe1InternalTemperature {channel="meater:meaterprobe:block:probe1:internalTemperature"}
Number:Temperature Probe1AmbientTemperature {channel="meater:meaterprobe:block:probe1:ambientTemperature"}
String Probe1CookId {channel="meater:meaterprobe:block:probe1:cookId"}
DateTime Probe4CookEstimatedEndTime {channel="meater:meaterprobe:block:probe4:cookEstimatedEndTime"}
String Probe4Status {channel="meater:meaterprobe:block:probe4:status"}
DateTime Probe4LastConnection {channel="meater:meaterprobe:block:probe4:lastConnection"}
-````
-
-
+```
This binding reads data from MEC power meter for providing electrical information for the electric circuit.
-To use this binding the meter must be installed, initialized and connected to the same network as openHAB.
+To use this binding the meter must be installed, initialized and connected to the same network as openHAB.
## Supported Things
## Discovery
-MecMeters are automatically discovered via mDNS.
+MecMeters are automatically discovered via mDNS.
The IP of the Power Meter is automatically set and can be changed manually if needed.
The default update interval is set to 5 seconds. Intervals from 1 to 300 seconds can be set manually.
| ip | The IP address of the meter. Mandatory. |
| refreshInterval | Refresh interval in second. Optional, the default value is 5 seconds. |
-
## Channels
-The meter has the following channels:
+The meter has the following channels:
| Channel Type ID | Item Type | Label | Description |
|--------------------------------------------------------------|--------------------------|-----------------------------------|------------------------------------------|
### mecmeter.things
-```
+```java
mecmeter:meter:1 [ password="Test1234", ip="192.168.1.16", refreshInterval="10" ]
```
### mecmeter.items
-```
+```java
Number:Frequency MainFrequency { channel="mecmeter:meter:1:general_group#frequency" }
Number:Temperature InternalTemperature { channel="mecmeter:meter:1:general_group#temperature" }
Number:Time TimeinOperation { channel="mecmeter:meter:1:general_group#op_time" }
### mecmeter.sitemap
-```
+```perl
sitemap mecmeter label="MecMeter"
{
Frame label="General" {
# MELCloud Binding
-This is an openHAB binding for Mitsubishi MELCloud (https://www.melcloud.com/).
+This is an openHAB binding for [Mitsubishi MELCloud](https://www.melcloud.com/).
Installing this binding you can control your Mitsubishi devices from openHAB without accessing the MELCloud App and benefiting from all openHAB automations.
## Supported Things
Supported thing types
-* melcloudaccount (bridge)
-* acdevice
-* heatpumpdevice
+- melcloudaccount (bridge)
+- acdevice
+- heatpumpdevice
A bridge is required to connect to your MELCloud account.
-
## Discovery
Discovery is used _after_ a bridge has been created and configured with your login information.
1. Add the binding
-2. Add a new thing of type melcloudaccount and configure with username and password
-3. Go to Inbox and start discovery devices using MELCloud Binding
-4. Supported devices (A.C. Device, Heatpump Device) should appear in your inbox
+1. Add a new thing of type melcloudaccount and configure with username and password
+1. Go to Inbox and start discovery devices using MELCloud Binding
+1. Supported devices (A.C. Device, Heatpump Device) should appear in your inbox
Binding support also manual thing configuration by thing files.
| 24 | Romanian |
| 25 | Slovenian |
-
A.C. device and Heatpump device configuration:
| Config | Mandatory | Description |
| buildingID | | MELCloud building ID. If not defined, binding tries to find matching id by device ID. |
| pollingInterval | | Refresh time interval in seconds for updates from MELCloud. Defaults to 60 seconds. |
-
-
## Channels
A.C. device channels
## Full Example for items configuration
-**melcloud.things**
+### melcloud.things
-```
+```java
Bridge melcloud:melcloudaccount:myaccount "My MELCloud account" [ username="user.name@example.com", password="xxxxxx", language="0" ] {
- Thing acdevice livingroom "Livingroom A.C. device" [ deviceID=123456, pollingInterval=60 ]
- Thing heatpumpdevice attic "Attic Heatpump device" [ deviceID=789012, pollingInterval=60 ]
+ Thing acdevice livingroom "Livingroom A.C. device" [ deviceID=123456, pollingInterval=60 ]
+ Thing heatpumpdevice attic "Attic Heatpump device" [ deviceID=789012, pollingInterval=60 ]
}
```
-**melcloud.items**
+### melcloud.items
-```
+```java
Switch power { channel="melcloud:acdevice:myaccount:livingroom:power" }
String operationMode { channel="melcloud:acdevice:myaccount:livingroom:operationMode" }
Number setTemperature { channel="melcloud:acdevice:myaccount:livingroom:setTemperature" }
## Supported Things
-| Type | ID | Description |
+| Type | ID | Description |
|-----------------|---------------|-------------------------------------------------|
| Bridge | `account` | Connect your Mercedes Me account |
| Thing | `combustion` | Conventional fuel vehicle |
## Bridge Configuration
-Bridge needs configuration in order to connect properly to your Mercedes Me Account.
+Bridge needs configuration in order to connect properly to your Mercedes Me Account.
### Pre-Conditions
Perform the following steps to obtain the configuration data and perform the authorization flow.
1. Go to [Mercedes Developer Page](https://developer.mercedes-benz.com/). Login with your Mercedes Me credentials.
-2. Create a project in the [console tab](https://developer.mercedes-benz.com/console)
+1. Create a project in the [console tab](https://developer.mercedes-benz.com/console)
- _Project Name:_ unique name e.g. **openHAB Mercedes Me binding** plus **Your bridge ID**
- _Purpose URL:_ use link towards [this binding description](https://www.openhab.org/addons/bindings/mercedesme/)
- _Business Purpose:_ e.g. **Private usage in openHAB Smarthome system**
-3. After project is created subscribe [to these Mercedes Benz APIs](https://developer.mercedes-benz.com/products?vt=cars&vt=vans&vt=smart&p=BYOCAR) with _Add Products_ button
-4. For all Products perform the same steps
+1. After project is created subscribe [to these Mercedes Benz APIs](https://developer.mercedes-benz.com/products?vt=cars&vt=vans&vt=smart&p=BYOCAR) with _Add Products_ button
+1. For all Products perform the same steps
- Select product
- Choose _Get For Free_
- Choose _BYOCAR_ (Build Your Own Car)
- Button _Confirm_
-5. Select the following products
+1. Select the following products
- Vehicle Status
- Vehicle Lock Status
- Pay as you drive insurance
- Electric Vehicle Status
- Fuel Status
-6. Optional: Subscribe also to _Vehicle images_. Select the _Basic Trial_ version. The images will be stored so the API is used just a few times.
-7. Press _Subscribe_ button. Your project should have [these product subscriptions](#mb-product-subscriptions)
-8. Generate the [project credentials](#mb-credentials)
-9. Open in new browser tab your openHAB page. Add a new Thing _Mercedes Me Account_
-10. Copy paste _Client ID_ , _Client Secret_ and _API Key_ from the Mercedes tab into the openHAB configuration
-11. Check if the registered Mercedes products _excluding Vehicle Images_ are matching exactly with the openHab configuration switches
-12. Create Thing!
-13. The fresh created [account has one property](#openhab-configuration) `callbackUrl`. Copy it and paste it in a new browser tab
-14. A [simple HTML page is shown including a link towards the Authorization flow](#callback-page) - **don't click yet**. If page isn't shown please adapt IP and port in openHAB configuration with Advanced Options activated
-15. The copied URL needs to be added in your [Mercedes project credentials](#mb-credentials) from 8
-16. Now click onto the link from 14. You'll be asked one time if you [grant access](#mb-access-request) towards the API. Click OK and authorization is done!
+1. Optional: Subscribe also to _Vehicle images_. Select the _Basic Trial_ version. The images will be stored so the API is used just a few times.
+1. Press _Subscribe_ button. Your project should have [these product subscriptions](#mb-product-subscriptions)
+1. Generate the [project credentials](#mb-credentials)
+1. Open in new browser tab your openHAB page. Add a new Thing _Mercedes Me Account_
+1. Copy paste _Client ID_ , _Client Secret_ and _API Key_ from the Mercedes tab into the openHAB configuration
+1. Check if the registered Mercedes products _excluding Vehicle Images_ are matching exactly with the openHab configuration switches
+1. Create Thing!
+1. The fresh created [account has one property](#openhab-configuration) `callbackUrl`. Copy it and paste it in a new browser tab
+1. A [simple HTML page is shown including a link towards the Authorization flow](#callback-page) - **don't click yet**. If page isn't shown please adapt IP and port in openHAB configuration with Advanced Options activated
+1. The copied URL needs to be added in your [Mercedes project credentials](#mb-credentials) from 8
+1. Now click onto the link from 14. You'll be asked one time if you [grant access](#mb-access-request) towards the API. Click OK and authorization is done!
Some supporting screenshots for the setup
<img src="./doc/CallbackUrl_Page.png" width="500" height="350"/>
-
### Bridge Configuration Parameters
| Name | Type | Description | Default | Required | Advanced |
The `callbackPort` needs to be unique for all created Mercedes Me account things. Otherwise token exchange will be corrupted.
Set the advanced options by yourself if you know your IP and Port, otherwise give auto detect a try.
-
## Thing Configuration
For vehicle images Mercedes Benz Developer offers only a trial version with limited calls.
Check in **beforehand** if your vehicle has some restrictions or even if it's supported at all.
Visit [Vehicle Image Details](https://developer.mercedes-benz.com/products/vehicle_images/details) in order to check your vehicle capabilities.
-Visit [Image Settings](https://developer.mercedes-benz.com/products/vehicle_images/docs#_default_image_settings) to get more information about
+Visit [Image Settings](https://developer.mercedes-benz.com/products/vehicle_images/docs#_default_image_settings) to get more information about
For example the EQA doesn't provide `night` images with `background`.
If your configuration is set this way the API calls are wasted!
If you're not satisfied e.g. you want a background you need to
1. change the [Advanced Image Configuration Properties](#thing-configuration)
-2. Switch `clear-cache` channel item to `ON` to clear all images
-3. request them via `image-view`
+1. Switch `clear-cache` channel item to `ON` to clear all images
+1. request them via `image-view`
### Image View Options
-You can access the options either in a rule via `YOUR_IMAGE_VIEW_ITEM.getStateDescription().getOptions()` or in UI in widget configuration as _Action: Command options_ and as _Action Item: YOUR_IMAGE_VIEW_ITEM_
+You can access the options either in a rule via `YOUR_IMAGE_VIEW_ITEM.getStateDescription().getOptions()` or in UI in widget configuration as _Action: Command options_ and as _Action Item: YOUR_IMAGE_VIEW_ITEM_
<img src="./doc/ImageView-CommandOptions.png" width="400" height="350"/>
Most common errors:
- redirect URL doesn't match: Double check if `callbackUrl` is really saved correctly in your Mercedes Benz Developer project
-- scope failure: the requested scope doesn't match with the subscribed products.
- - Check [openHab configuration switches](#openhab-configuration)
- - apply changes if necessary and don't forget to save
- - after these steps refresh the `callbackUrl` in [your browser](#callback-page) to apply these changes
- - try a new authorization clicking the link
+- scope failure: the requested scope doesn't match with the subscribed products.
+ - Check [openHab configuration switches](#openhab-configuration)
+ - apply changes if necessary and don't forget to save
+ - after these steps refresh the `callbackUrl` in [your browser](#callback-page) to apply these changes
+ - try a new authorization clicking the link
### Receive no data
Especially after setting the frist Mercedes Benz Developer Project you'll receive no data.
-It seems that the API isn't _filled_ yet.
+It seems that the API isn't _filled_ yet.
-**Pre-Condition**
+#### Pre-Condition
- The Mercedes Me bridge is online = authorization is fine
-- The Mercedes Me thing is online = API calls are fine
+- The Mercedes Me thing is online = API calls are fine
-**Solution**
+#### Solution
- Reduce `refreshInterval` to 1 minute
-- Go to your vehicle, open doors and windows, turn on lights, drive a bit ...
+- Go to your vehicle, open doors and windows, turn on lights, drive a bit ...
- wait until values are providing the right states
### Images
Data is stored in directory `%USER_DATA%/jsondb` for handling tokens and vehicle images.
- * _StorageHandler.For.OAuthClientService.json_ - token is stored with key `clientId` which is provided by `account` [Brige Configuration Parameters](#bridge-configuration-parameters)
- * _mercedesme_%VEHICLE_VIN%.json_ - images are stored per vehicle. File name contains `vin` configured by [vehicle Thing Configuration](#thing-configuration)
+- _StorageHandler.For.OAuthClientService.json_ - token is stored with key `clientId` which is provided by `account` [Brige Configuration Parameters](#bridge-configuration-parameters)
+- _mercedesme_%VEHICLE_VIN%.json_ - images are stored per vehicle. File name contains `vin` configured by [vehicle Thing Configuration](#thing-configuration)
With this data the binding is able to operate without new authorization towards Mercedes each startup and reduces the restricted calls towards image API.
Also these files are properly stored in your [backup](https://community.openhab.org/t/docs-on-how-to-backup-openhab/100182) e.g. if you perform `openhab-cli backup`
-
## Full example
-The example is based on a battery electric vehicle.
+The example is based on a battery electric vehicle.
Exchange configuration parameters in the Things section
Bridge
-* 4711 - your desired bridge id
-* YOUR_CLIENT_ID - Client ID of the Mercedes Developer project
-* YOUR_CLIENT_SECRET - Client Secret of the Mercedes Developer project
-* YOUR_API_KEY - Image API Key of the Mercedes Developer project
-* YOUR_OPENHAB_SERVER_IP - IP address of your openHAB server
-* 8090 - a **unique** port number - each bridge in your openHAB installation needs to have different port number!
+- 4711 - your desired bridge id
+- YOUR_CLIENT_ID - Client ID of the Mercedes Developer project
+- YOUR_CLIENT_SECRET - Client Secret of the Mercedes Developer project
+- YOUR_API_KEY - Image API Key of the Mercedes Developer project
+- YOUR_OPENHAB_SERVER_IP - IP address of your openHAB server
+- 8090 - a **unique** port number - each bridge in your openHAB installation needs to have different port number!
Thing
-* eqa - your desired vehicle thing id
-* VEHICLE_VIN - your Vehicle Identification Number
+- eqa - your desired vehicle thing id
+- VEHICLE_VIN - your Vehicle Identification Number
### Things file
-```
+```java
Bridge mercedesme:account:4711 "MercedesMe John Doe" [ clientId="YOUR_CLIENT_ID", clientSecret="YOUR_CLIENT_SECRET", imageApiKey="YOUR_API_KEY", callbackIP="YOUR_OPENHAB_SERVER_IP", callbackPort=8092, odoScope=true, vehicleScope=true, lockScope=true, fuelScope=true, evScope=true] {
Thing bev eqa "Mercedes EQA" [ vin="VEHICLE_VIN", refreshInterval=5, background=false, night=false, cropped=false, roofOpen=false, format="webp"]
}
### Items file
-```
+```java
Number:Length EQA_Mileage "Odometer [%d %unit%]" {channel="mercedesme:bev:4711:eqa:range#mileage" }
Number:Length EQA_Range "Range [%d %unit%]" {channel="mercedesme:bev:4711:eqa:range#range-electric"}
Number:Length EQA_RangeRadius "Range Radius [%d %unit%]" {channel="mercedesme:bev:4711:eqa:range#radius-electric"}
### Sitemap
-```
+```perl
sitemap MB label="Mercedes Benz EQA" {
Frame label="EQA Image" {
Image item=EQA_Image
| avalanches-icon | Image | Pictogram of Avalanche alert level |
| vague-submersion-icon | Image | Pictogram of Wave Submersion alert level |
-(*) Each alert level is described by a color :
+(*) Each alert level is described by a color :
| Code | Color | Description |
|------|--------|-------------------------------------------|
| 2 | Orange | Be "very vigilant" in the concerned areas |
| 3 | Red | Absolute vigilance required |
-
## Full Example
meteoalert.things:
-```
+```java
Thing meteoalerte:department:yvelines @ "MyCity" [department="YVELINES", refresh=12]
```
meteoalert.items:
-```
+```java
Group gMeteoAlert "Alertes Météo" <weather>
String MA_Dept78 "Département 78 [%s]" <aqi> (gMeteoAlert) {channel="meteoalerte:department:yvelines:comment"}
Number MA_etat_canicule "Canicule [%s]" <aqi> (gMeteoAlert) {channel="meteoalerte:department:yvelines:canicule"}
The meteoblue binding uses the [meteoblue weather service](https://content.meteoblue.com/en/content/view/full/4511)
to provide weather information.
-
## Supported Things
The binding has two thing types.
The second thing type is the bridge thing. The bridge thing, which has the ID `bridge`, holds the API key to be used for all of
its child things.
-
## Thing Configuration
### Bridge Thing Configuration
| ------------- |:-------------:| :-------: | -------------------- |
| apiKey | | Yes | The api key to be used with the meteoblue service |
-
### Weather Thing Configuration
| Property | Default Value | Required? | Description |
| serviceType | NonCommercial | No | The service type to be used. Either 'Commercial' or 'NonCommercial' |
| timeZone | | No | The time zone to use for the location. Optional, but the service recommends it be specified. The service gets the time zone from a database if not specified. |
-
## Channels
### Channel Groups
| precipitationHours | Number | Total hours of the day with precipitation |
| humidityGreater90Hours | Number | Total hours of the day with relative humidity greater than 90% |
-
## Image Icons
To show the weather image icons in the UI, the [image files](https://content.meteoblue.com/hu/service-specifications/standards/symbols-and-pictograms) need to be downloaded and installed in the `conf/icons/classic` folder.
The files to extract from the zip file and install in the folder will be named "iday*.png" or "iday*.svg".
-
## Full Example
demo.things:
-```
+```java
Bridge meteoblue:bridge:metBridge "metBridge" [ apiKey="XXXXXXXXXXXX" ] {
- Thing weather A51 "Area 51" [ serviceType="NonCommercial", location="37.23,-115.5,1360", timeZone="America/Los_Angeles", refresh=240 ] {
- }
+ Thing weather A51 "Area 51" [ serviceType="NonCommercial", location="37.23,-115.5,1360", timeZone="America/Los_Angeles", refresh=240 ] {
+ }
}
```
demo.items:
-```
+```java
// ----------------- meteoblue GROUPS ------------------------------------------
Group weatherDay0 "Today's Weather"
Group weatherDay1 "Tomorrow's Weather"
String todayCond "Condition [%s]" <iday> (weatherDay0) {channel="meteoblue:weather:metBridge:A51:forecastToday#condition"}
Image todayIcon "Icon [%s]" (weatherDay0) {channel="meteoblue:weather:metBridge:A51:forecastToday#icon"}
Number todayUV "UV Index [%d]" (weatherDay0) {channel="meteoblue:weather:metBridge:A51:forecastToday#UVIndex"}
-Number:Temperature todayTempL "Low Temp [%.2f °F]" <temperature> (weatherDay0) {channel="meteoblue:weather:metBridge:A51:forecastToday#minTemperature"}
-Number:Temperature todayTempH "High Temp [%.2f °F]" <temperature> (weatherDay0) {channel="meteoblue:weather:metBridge:A51:forecastToday#maxTemperature"}
+Number:Temperature todayTempL "Low Temp [%.2f °F]" <temperature> (weatherDay0) {channel="meteoblue:weather:metBridge:A51:forecastToday#minTemperature"}
+Number:Temperature todayTempH "High Temp [%.2f °F]" <temperature> (weatherDay0) {channel="meteoblue:weather:metBridge:A51:forecastToday#maxTemperature"}
Number todayHumM "Mean Humidity [%d %%]" <humidity> (weatherDay0) {channel="meteoblue:weather:metBridge:A51:forecastToday#relativeHumidityMean"}
Number todayPrecPr "Prec. Prob. [%d %%]" (weatherDay0) {channel="meteoblue:weather:metBridge:A51:forecastToday#precipitationProbability"}
Number:Length todayPrec "Total Prec. [%.2f in]" <rain> (weatherDay0) {channel="meteoblue:weather:metBridge:A51:forecastToday#precipitation"}
demo.sitemap:
-````
+````perl
sitemap weather label="Weather"
{
Frame label="Weather" {
| meteostick_bridge | Bridge | This is the Meteostick USB stick |
| meteostick_davis_iss | Thing | This is the Davis Vue ISS |
-
## Binding Configuration
The Meteostick things need to be manually added - there is no discovery in the Meteostick binding.
1. [Register](https://www.wunderground.com/personal-weather-station/signup.asp) your personal weather station with Weather Underground and make note of the station ID and password issued.
1. Add the following files to your openHAB configuration:
-### things/meteostick.things
+### things/meteostick.things
Things can be defined in the .things file as follows:
-```
+```java
meteostick:meteostick_bridge:receiver [ port="/dev/tty.usbserial-AI02XA60", mode=1 ]
meteostick:meteostick_davis_iss:iss (meteostick:meteostick_bridge:receiver) [ channel=1, spoon=0.2 ]
```
### items/meteostick.items
-```
+```java
Number:Pressure MeteoStickPressure "Meteostick Pressure [%.1f hPa]"{ channel="meteostick:meteostick_bridge:receiver:pressure" }
Number:Temperature DavisVantageVueOutdoorTemperature "ISS Outdoor Temp [%.1f °C]" { channel="meteostick:meteostick_davis_iss:iss:outdoor-temperature" }
Number DavisVantageVueHumidity "ISS Humidity [%.0f %%]" { channel="meteostick:meteostick_davis_iss:iss:humidity" }
Replace `YOUR_ID` and `your_password` below with the values from the the Weather Underground registration process.
-```
+```java
import java.net.URLEncoder
import java.text.SimpleDateFormat
import java.util.Date
rule PWS
when
- Item DavisVantageVueWindDirectionAverage received update
+ Item DavisVantageVueWindDirectionAverage received update
then
- val id = 'YOUR_ID'
- val pw = 'your_password'
- val sdf = new SimpleDateFormat('yyyy-MM-dd HH:mm:ss')
- sdf.setTimeZone(TimeZone.getTimeZone('UTC'))
- val double rh = DavisVantageVueHumidity.getStateAs(DecimalType).doubleValue
- val double tempc = DavisVantageVueOutdoorTemperature.getStateAs(QuantityType).toUnit('°C').doubleValue
- val double dewptc = 243.04 * (Math.log(rh/100) + ((17.625 * tempc) / (243.04 + tempc))) / (17.625 - Math.log(rh/100) - ((17.625 * tempc) / (243.04 + tempc)))
- val double dewptf = new QuantityType(dewptc, CELSIUS).toUnit('°F').doubleValue
- val Map<String, Object> params = newLinkedHashMap(
- 'action' -> 'updateraw',
- 'ID' -> id,
- 'PASSWORD' -> pw,
- 'dateutc' -> sdf.format(new Date()),
- 'winddir' -> DavisVantageVueWindDirection.getStateAs(QuantityType).toUnit('°').intValue,
- 'windspeedmph' -> DavisVantageVueWindSpeed.getStateAs(QuantityType).toUnit('mph').doubleValue,
- 'windgustmph' -> DavisVantageVueWindSpeedMaximum.getStateAs(QuantityType).toUnit('mph').doubleValue,
- 'windgustdir' -> DavisVantageVueWindDirectionAverage.getStateAs(QuantityType).toUnit('°').intValue,
- 'windspdmph_avg2m' -> DavisVantageVueWindSpeedAverage.getStateAs(QuantityType).toUnit('mph').doubleValue,
- 'winddir_avg2m' -> DavisVantageVueWindDirectionAverage.getStateAs(QuantityType).toUnit('°').intValue,
- 'humidity' -> DavisVantageVueHumidity.state,
- 'dewptf' -> dewptf,
- 'tempf' -> DavisVantageVueOutdoorTemperature.getStateAs(QuantityType).toUnit('°F').doubleValue,
- 'rainin' -> DavisVantageVueRainCurrentHour.getStateAs(QuantityType).toUnit('in').doubleValue,
- 'baromin' -> MeteoStickPressure.getStateAs(QuantityType).toUnit('inHg').doubleValue,
- 'softwaretype' -> 'openHAB 2.4')
-
- var url = 'https://weatherstation.wunderground.com/weatherstation/updateweatherstation.php?'
- var first = true
- for (key : params.keySet()) {
- if (!first) {
- url += '&'
- }
- url += key + '=' + URLEncoder::encode(params.get(key).toString, 'UTF-8')
- first = false
- }
-
- logDebug('PWS', 'url is {}', url)
- sendHttpGetRequest(url)
+ val id = 'YOUR_ID'
+ val pw = 'your_password'
+ val sdf = new SimpleDateFormat('yyyy-MM-dd HH:mm:ss')
+ sdf.setTimeZone(TimeZone.getTimeZone('UTC'))
+ val double rh = DavisVantageVueHumidity.getStateAs(DecimalType).doubleValue
+ val double tempc = DavisVantageVueOutdoorTemperature.getStateAs(QuantityType).toUnit('°C').doubleValue
+ val double dewptc = 243.04 * (Math.log(rh/100) + ((17.625 * tempc) / (243.04 + tempc))) / (17.625 - Math.log(rh/100) - ((17.625 * tempc) / (243.04 + tempc)))
+ val double dewptf = new QuantityType(dewptc, CELSIUS).toUnit('°F').doubleValue
+ val Map<String, Object> params = newLinkedHashMap(
+ 'action' -> 'updateraw',
+ 'ID' -> id,
+ 'PASSWORD' -> pw,
+ 'dateutc' -> sdf.format(new Date()),
+ 'winddir' -> DavisVantageVueWindDirection.getStateAs(QuantityType).toUnit('°').intValue,
+ 'windspeedmph' -> DavisVantageVueWindSpeed.getStateAs(QuantityType).toUnit('mph').doubleValue,
+ 'windgustmph' -> DavisVantageVueWindSpeedMaximum.getStateAs(QuantityType).toUnit('mph').doubleValue,
+ 'windgustdir' -> DavisVantageVueWindDirectionAverage.getStateAs(QuantityType).toUnit('°').intValue,
+ 'windspdmph_avg2m' -> DavisVantageVueWindSpeedAverage.getStateAs(QuantityType).toUnit('mph').doubleValue,
+ 'winddir_avg2m' -> DavisVantageVueWindDirectionAverage.getStateAs(QuantityType).toUnit('°').intValue,
+ 'humidity' -> DavisVantageVueHumidity.state,
+ 'dewptf' -> dewptf,
+ 'tempf' -> DavisVantageVueOutdoorTemperature.getStateAs(QuantityType).toUnit('°F').doubleValue,
+ 'rainin' -> DavisVantageVueRainCurrentHour.getStateAs(QuantityType).toUnit('in').doubleValue,
+ 'baromin' -> MeteoStickPressure.getStateAs(QuantityType).toUnit('inHg').doubleValue,
+ 'softwaretype' -> 'openHAB 2.4')
+
+ var url = 'https://weatherstation.wunderground.com/weatherstation/updateweatherstation.php?'
+ var first = true
+ for (key : params.keySet()) {
+ if (!first) {
+ url += '&'
+ }
+ url += key + '=' + URLEncoder::encode(params.get(key).toString, 'UTF-8')
+ first = false
+ }
+
+ logDebug('PWS', 'url is {}', url)
+ sendHttpGetRequest(url)
end
```
# Miele@home Binding
This binding integrates Miele@home appliances.
-Miele@home allows controlling Miele appliances that are equipped with special communication modules.
+Miele@home allows controlling Miele appliances that are equipped with special communication modules.
There are devices that communicate through ZigBee and others that use WiFi.
See [www.miele.de](https://www.miele.de) for the list of available appliances.
This binding requires the XGW3000 gateway from Miele as all integration with openHAB is done through this gateway.
While users with ZigBee-enabled Miele appliances usually own such a gateway, this is often not the case for people that have only WiFi-enabled appliances.
-The types of appliances that are supported by this binding are:
+The types of appliances that are supported by this binding are:
- Coffeemachine
- Dishwasher
The default value is 15 seconds.
If you want to change this value just add the following line to your `$OPENHAB_CONF/services/runtime.cfg` file.
-```
+```text
discovery.miele:removalGracePeriod=30
```
## things/miele.things
-```
+```java
Bridge miele:xgw3000:home [ipAddress="192.168.0.18", interface="192.168.0.5"] {
Things:
Thing fridgefreezer freezer [uid="00124b000424be44#2"]
## items/miele.items
-```
+```java
String Dishwasher_State {channel="miele:dishwasher:home:dishwasher:state"}
Number Dishwasher_RawState {channel="miele:dishwasher:home:dishwasher:rawState"}
String Dishwasher_Program "Program [%s]" {channel="miele:dishwasher:home:dishwasher:program"}
## sitemaps/miele.sitemap
-```
+```perl
sitemap miele label="Miele" {
Frame label="Miele" {
Text item=Oven_State label="Oven [%s]" icon="kitchen" {
| email | required | E-mail address identifying this account. This exists only to distinguish accounts. If the address is changed after authorization then the account needs to be authorized again. |
| locale | optional | The locale to use for full text channels of things from this account. Possible values are `en`, `de`, `da`, `es`, `fr`, `it`, `nl`, `nb`. Default is `en`. |
-
### Appliance Configuration
The binding configuration UI will show a things-file template containing things for all supported appliances from the paired account.
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| deviceIdentifier | required | Technical device identifier uniquely identifying the Miele appliance. Use the discovery result or the things-file template to obtain it. |
-
## Channels
The following table lists all available channels.
### demo.things:
-```
+```java
Bridge mielecloud:account:home [ email="me@openhab.org", locale="en" ] {
Thing coffee_system 000703261234 "Coffee machine CVA7440" [ deviceIdentifier="000703261234" ]
Thing hob 000160102345 "Cooktop KM7677" [ deviceIdentifier="000160102345" ]
### demo.items:
-```
+```java
// Coffee system
Switch coffee_system_remote_control_can_be_started { channel="mielecloud:coffee_system:home:000703261234:remote_control_can_be_started" }
Switch coffee_system_remote_control_can_be_stopped { channel="mielecloud:coffee_system:home:000703261234:remote_control_can_be_stopped" }
### demo.sitemap:
-```
+```perl
sitemap demo label="Kitchen"
{
Frame {
## Acknowledgements
The development of this binding was initiated and sponsored by Miele & Cie. KG.
-
# Xiaomi Mi Smart Home Binding
This binding allows your openHAB to communicate with the Xiaomi Smart Home Suite.
-It consists of devices communicating over a ZigBee network with a ZigBee - WiFi gateway.
+It consists of devices communicating over a ZigBee network with a ZigBee - WiFi gateway.
The devices are very affordable and you can get them from your favourite Chinese markets like [AliExpress](https://www.aliexpress.com/) or [GearBest](https://www.gearbest.com).
-The sensors run on a coin cell battery for over a year.
+The sensors run on a coin cell battery for over a year.
-After setup, you can disconnect the gateway from the internet to keep your sensor information private.
+After setup, you can disconnect the gateway from the internet to keep your sensor information private.
Please note that using the Xiaomi gateway with openHAB requires enabling the developer mode and that multiple user reports suggest that it is no longer possible.
Zigbee2Mqtt provides an alternative method to integrate Xiaomi devices.
| Device | Picture |
| --- | --- |
-| Gateway v2 (with radio support) or v3 |  |
-| Mijia Temperature and Humidity Sensor | |
-| Aqara Temperature, Humidity and Pressure Sensor |  |
-| Mijia Door/Window Sensor |  |
-| Aqara Door/Window Sensor |  |
-| Mijia Human Body Sensor |  |
-| Aqara Motion Sensor (with light intensity support) |  |
-| Smart Socket (Zigbee version) |  |
-| Magic Cube Controller |  |
-| Aqara Magic Cube Controller |  |
-| Aqara Vibration Sensor |  |
-| Mijia Wireless Switch |  |
-| Aqara Wireless Switch |  |
-| Aqara Wireless Switch (with acceleration sensor) |  |
-| Aqara Wall Switch (1 & 2 Button / With or Without Neutral Line) |  |
-| Aqara Wireless Light Control (1 & 2 Button) |  |
-| Aqara Curtain Motor |  |
-| Aqara Water Leak Sensor |  |
-| Honeywell Gas Detector |  |
-| Honeywell Smoke Detector |  |
-| Aqara Fingerprint & Keyless Card & PIN Lock |  |
+| Gateway v2 (with radio support) or v3 |  |
+| Mijia Temperature and Humidity Sensor | |
+| Aqara Temperature, Humidity and Pressure Sensor |  |
+| Mijia Door/Window Sensor |  |
+| Aqara Door/Window Sensor |  |
+| Mijia Human Body Sensor |  |
+| Aqara Motion Sensor (with light intensity support) |  |
+| Smart Socket (Zigbee version) |  |
+| Magic Cube Controller |  |
+| Aqara Magic Cube Controller |  |
+| Aqara Vibration Sensor |  |
+| Mijia Wireless Switch |  |
+| Aqara Wireless Switch |  |
+| Aqara Wireless Switch (with acceleration sensor) |  |
+| Aqara Wall Switch (1 & 2 Button / With or Without Neutral Line) |  |
+| Aqara Wireless Light Control (1 & 2 Button) |  |
+| Aqara Curtain Motor |  |
+| Aqara Water Leak Sensor |  |
+| Honeywell Gas Detector |  |
+| Honeywell Smoke Detector |  |
+| Aqara Fingerprint & Keyless Card & PIN Lock |  |
## Setup
-* Install the binding
-* Is your gateway already configured to connect to your WiFi? If not:
-
- 1. Install MiHome app from [Google Play](https://play.google.com/store/apps/details?id=com.xiaomi.smarthome) or [AppStore](https://itunes.apple.com/app/mi-home-xiaomi-for-your-smarthome/id957323480) (your phone may need to be changed to English language first)
- 2. In the app create a Mi Home account and make sure to set your region to Mainland (China) under Settings -> Locale
- 3. If asked, do NOT update your gateway to the latest firmware (note that update window may pop up sequentially). If you update, you may not be able to access the developer mode below.
-
-* Enable developer mode of your gateway:
-
- 1. Select your Gateway in the MiHome app
- 2. Go to the "..." menu on the top right corner and click "About"
- 3. You now see two options "Smart Home Kit Forum" and "Gameplay Tutorial". Tap 5 times below the "Gameplay Tutorial" in the empty space (not the button itself) until you enable developer mode
- 4. You should now have 2 extra options listed: `wireless communication protocol` and `hub info`, it may appear in Chinese
- 5. Choose `wireless communication protocol`
- 6. Tap the toggle switch to enable WiFi functions. Note down the developer key (aka password), something like: 91bg8zfkf9vd6uw7
- 7. Make sure you hit the OK button (to the right of the cancel button) to save your changes
- 8. Now update the gateway to the latest firmware
-
-* Enable developer mode of your gateway (legacy app):
-
- 1. Select your Gateway in the MiHome app
- 2. Go to the "..." menu on the top right corner and click "About"
- 3. Tap the version number "Plug-in version : 2.XX.X" at the bottom of the screen repeatedly until you enable developer mode
- 4. You should now have 2 extra options listed: `wireless communication protocol` and `hub info`
- 5. Choose `wireless communication protocol`
- 6. Tap the toggle switch to enable WiFi functions. Note down the developer key (aka password), something like: 91bg8zfkf9vd6uw7
- 7. Make sure you hit the OK button (to the right of the cancel button) to save your changes
- 8. Now update the gateway to the latest firmware
-
-* In openHAB you should now be able to discover the Xiaomi Gateway
-* From now on you don't really need the app anymore. Only if you want to update the gateway firmware or if you want to add devices (see below). But adding devices can also be done without the app (see below)
-* Enter the previously noted developer key in openHAB Administration -> Settings -> Things -> Xiaomi Gateway -> Edit -> Developer Key. Save (This is required if you want to be able to send controls to the devices like the light of the gateway)
+- Install the binding
+- Is your gateway already configured to connect to your WiFi? If not:
+ 1. Install MiHome app from [Google Play](https://play.google.com/store/apps/details?id=com.xiaomi.smarthome) or [AppStore](https://itunes.apple.com/app/mi-home-xiaomi-for-your-smarthome/id957323480) (your phone may need to be changed to English language first)
+ 1. In the app create a Mi Home account and make sure to set your region to Mainland (China) under Settings -> Locale
+ 1. If asked, do NOT update your gateway to the latest firmware (note that update window may pop up sequentially). If you update, you may not be able to access the developer mode below.
+- Enable developer mode of your gateway:
+ 1. Select your Gateway in the MiHome app
+ 1. Go to the "..." menu on the top right corner and click "About"
+ 1. You now see two options "Smart Home Kit Forum" and "Gameplay Tutorial". Tap 5 times below the "Gameplay Tutorial" in the empty space (not the button itself) until you enable developer mode
+ 1. You should now have 2 extra options listed: `wireless communication protocol` and `hub info`, it may appear in Chinese
+ 1. Choose `wireless communication protocol`
+ 1. Tap the toggle switch to enable WiFi functions. Note down the developer key (aka password), something like: 91bg8zfkf9vd6uw7
+ 1. Make sure you hit the OK button (to the right of the cancel button) to save your changes
+ 1. Now update the gateway to the latest firmware
+- Enable developer mode of your gateway (legacy app):
+ 1. Select your Gateway in the MiHome app
+ 1. Go to the "..." menu on the top right corner and click "About"
+ 1. Tap the version number "Plug-in version : 2.XX.X" at the bottom of the screen repeatedly until you enable developer mode
+ 1. You should now have 2 extra options listed: `wireless communication protocol` and `hub info`
+ 1. Choose `wireless communication protocol`
+ 1. Tap the toggle switch to enable WiFi functions. Note down the developer key (aka password), something like: 91bg8zfkf9vd6uw7
+ 1. Make sure you hit the OK button (to the right of the cancel button) to save your changes
+ 1. Now update the gateway to the latest firmware
+- In openHAB you should now be able to discover the Xiaomi Gateway
+- From now on you don't really need the app anymore. Only if you want to update the gateway firmware or if you want to add devices (see below). But adding devices can also be done without the app (see below)
+- Enter the previously noted developer key in openHAB Administration -> Settings -> Things -> Xiaomi Gateway -> Edit -> Developer Key. Save (This is required if you want to be able to send controls to the devices like the light of the gateway)
## Connecting devices to the gateway
There are three ways of connecting supported devices to the gateway:
-* Online - within the MiHome App
-* Offline - manual
-
- 1. Click 3 times on the Gateway's button
- 2. Gateway will flash in blue and you will hear female voice in Chinese, you have 30 seconds to include your new device
- 3. Place the needle into the sensor and hold it for at least 3 seconds
- 4. You will hear confirmation message in Chinese
- 5. The device appears in openHAB thing Inbox
+- Online - within the MiHome App
+- Offline - manual
+ 1. Click 3 times on the Gateway's button
+ 1. Gateway will flash in blue and you will hear female voice in Chinese, you have 30 seconds to include your new device
+ 1. Place the needle into the sensor and hold it for at least 3 seconds
+ 1. You will hear confirmation message in Chinese
+ 1. The device appears in openHAB thing Inbox
+- With the binding
+ 1. After adding the gateway make sure you have entered the right developer key
+ 1. In the UI, go to your Inbox and trigger a discovery for the binding
+ 1. The gateway flashes in blue and you hear a female voice in Chinese, you have 30 seconds to include your new device
+ 1. Follow the instructions for your device to pair it to the gateway
+ 1. You will hear a confirmation message in Chinese
+ 1. The device appears in openHAB thing Inbox
-* With the binding
+**Hints:**
- 1. After adding the gateway make sure you have entered the right developer key
- 2. In the UI, go to your Inbox and trigger a discovery for the binding
- 3. The gateway flashes in blue and you hear a female voice in Chinese, you have 30 seconds to include your new device
- 4. Follow the instructions for your device to pair it to the gateway
- 5. You will hear a confirmation message in Chinese
- 6. The device appears in openHAB thing Inbox
+- If you don't want to hear the Chinese voice every time, you can disable it by setting the volume to minimum in the MiHome App (same for the blinking light)
-__Hints:__
-
-* If you don't want to hear the Chinese voice every time, you can disable it by setting the volume to minimum in the MiHome App (same for the blinking light)
-
-* The devices don't need an Internet connection to be working after you have set up the developer mode BUT you will not be able to connect to them via App anymore - easiest way is to block their outgoing Internet connection in your router and enable it later, when you want to check for updates etc. This will ensure that your smart home data stays only with you!
+- The devices don't need an Internet connection to be working after you have set up the developer mode BUT you will not be able to connect to them via App anymore - easiest way is to block their outgoing Internet connection in your router and enable it later, when you want to check for updates etc. This will ensure that your smart home data stays only with you!
## Removing devices from the gateway
- The binding requires port `9898` to not be used by any other service on the system.
- Make sure multicast traffic is correctly routed between the gateway and your openHAB instance
- To correctly receive multicast traffic, when your openHAB machine is using multiple network interfaces, you might need to configure the optional `interface` property on the `Bridge` Thing, like so:
-```
+
+```java
Bridge mihome:bridge:f0b429XXXXXX "Xiaomi Gateway" [ ..., interface="eth0", ... ] {
```
### xiaomi.things:
-```
+```java
Bridge mihome:bridge:f0b429XXXXXX "Xiaomi Gateway" [ serialNumber="f0b429XXXXXX", ipAddress="192.168.0.3", port=9898, key="XXXXXXXXXXXXXXXX" ] {
Things:
gateway f0b429XXXXXX "Xiaomi Mi Smart Home Gateway" [itemId="f0b429XXXXXX"]
### xiaomi.items:
-```
+```java
// Replace <GwID> with itemId of gateway from Things file
// Replace <ID> with itemId of item from Things file
// Gateway
### xiaomi.rules:
-```
+```java
rule "Mijia & Aqara Wireless Switch"
when
Channel "mihome:sensor_switch:<GwID>:<ID>:button" triggered
### xiaomi.sitemap:
-```
+```perl
sitemap xiaomi label="Xiaomi" {
// Example for selection of predefined sound file - you can also upload your own files with the official MiHome App and play them!
- Frame {
+ Frame {
...
// Selection for Xiaomi Gateway Sounds
- Go through the normal procedure to add a device to the gateway
- The device will show up in your inbox as a new unsupported device and its model name
- Add the device as a new thing of type "basic device", now you have different channels to receive and send messages from/to the device
- - raw messages from the device
- - the data from the four different type of messages (see their details in the next chapter)
- - parameters you can send to the device
+ - raw messages from the device
+ - the data from the four different type of messages (see their details in the next chapter)
+ - parameters you can send to the device
### Gather information about the new device for future support
You have to capture as many of them as possible, so that the device is fully supported in the end.
1. Heartbeat (usually transmitted every 60 minutes)
-2. Report (device reports new sensor or status values)
-3. Read ACK (binding refreshes all sensor values after a restart of openHAB)
-4. Write ACK (device has received a command) __not available for sensor-only devices__
+1. Report (device reports new sensor or status values)
+1. Read ACK (binding refreshes all sensor values after a restart of openHAB)
+1. Write ACK (device has received a command) **not available for sensor-only devices**
### Open a new issue or get your hands dirty
-Every little help is welcome, be part of the community!
+Every little help is welcome, be part of the community!
Post an issue in the GitHub repository with as much information as possible about the new device:
+
- brand and link to device description
- model name
- content of all the different message types
That way you can make use of your device, even if it is not supported yet!
The following examples are a demonstration, where a basic device thing for the gateway was manually added.
-```
+```java
String Gateway_Raw { channel="mihome:basic:xxx:lastMessage" }
String Gateway_Heartbeat { channel="mihome:basic:xxx:heartbeatMessage" }
```
The following example uses a rule to enable device pairing on the gateway:
-__mihome.items__
+#### mihome.items
-```
+```java
String Gateway_Write { channel="mihome:basic:xxx:writeMessage" }
Switch Gateway_AddDevicesSwitch
```
-__mihome.rules__
+#### mihome.rules
-```
+```java
rule "Enable device pairing with gateway as basic device thing"
when
Item Gateway_AddDevicesSwitch changed to ON
Gateway_Write.sendCommand("\"join_permission\":\"yes\"")
end
```
+
You can also send multiple command at once:
-```
+
+```java
GatewayWrite.sendCommand("\"rgb\":150000,\"join_permission\":\"yes\"")
```
For the binding to function properly it is very important, that your network config allows the machine running openHAB to receive multicast traffic.
In case you want to check if the communication between the machine and the gateway is working, you can find some hints here.
+
- Set up the developer communication as described in the Setup section
### Check if your Linux machine receives multicast traffic
- Login to the Linux console
-- make sure you have __netcat__ installed
+- make sure you have **netcat** installed
- Enter ```netcat -ukl 9898```
- At least every 10 seconds you should see a message coming in from the gateway which looks like
```{"cmd":"heartbeat","model":"gateway","sid":"`xxx","short_id":"0","token":"xxx","data":"{\"ip\":\"`xxx\"}"}```
When the computer running openHAB has more than one network interface configured (typically, a VLAN for your segregated IoT devices, and the other for your regular traffic like internet, openHAB panel access, etc), it could be that openHAB will attempt to listen for Multicast traffic of the Gateway on the wrong network interface. That will prevent openHAB and `netcat` from receiving the messages from the Xiaomi Gateway. Within openHAB this manifests by seeing the Gateway and its devices online for a brief period after openHAB startup, after which they timeout and are shown Offline. No channel triggers from the Gateway work in this case.
In order to verify that traffic is actually received by the machine use `tcpdump` on each interface:
+
- List your network interfaces `ifconfig | grep MULTICAST` or `ip link | grep MULTICAST`
- Use `tcpdump -i <interface> port 9898` for each interface to verify if you receive traffic
If you already know the correct interface, or you found the correct one through tcpdump:
+
- Configure the `interface` property of the `Bridge` Thing with the correct name (for example `eth0`, etc)
### Check if your Windows/Mac machine receives multicast traffic
- At least every 10 seconds you should see a message coming in from the gateway which looks like
```{"cmd":"heartbeat","model":"gateway","sid":"`xxx","short_id":"0","token":"xxx","data":"{\"ip\":\"`xxx\"}"}```
-__My gateway shows up in openHAB and I have added all devices, but I don't get any value updates:__
+**My gateway shows up in openHAB and I have added all devices, but I don't get any value updates:**
+
- Most likely your machine is not receiving multicast messages
- Check your network config:
- - Routers often block multicast - enable it
- - Make sure the gateway and the machine are in the same subnet
- - Try to connect your machine via Ethernet instead of Wifi
- - Make sure you don't have any firewall rules blocking multicast
- - If you have multiple network interfaces, try to configure the `interface` property of the `Bridge` Thing
+ - Routers often block multicast - enable it
+ - Make sure the gateway and the machine are in the same subnet
+ - Try to connect your machine via Ethernet instead of Wifi
+ - Make sure you don't have any firewall rules blocking multicast
+ - If you have multiple network interfaces, try to configure the `interface` property of the `Bridge` Thing
+
+**I have connected my gateway to the network but it doesn't show up in openHAB:**
-__I have connected my gateway to the network but it doesn't show up in openHAB:__
- Make sure to have the developer mode enabled in the MiHome app
- Reinstall the binding
- Try to update the firmware of the gateway
- Search the openHAB Community forum
- Contact Xiaomi support - get your gateway replaced
-__Nothing works, I'm frustrated and have thrown my gateway into the bin. Now I don't know what to do with all the sensors:__
+**Nothing works, I'm frustrated and have thrown my gateway into the bin. Now I don't know what to do with all the sensors:**
+
Check out the Zigbee2Mqtt project on GitHub.
It allows you to use the sensors without the gateway and get their values through MQTT.
You will need some hardware to act as a gateway which is not expensive.
# Xiaomi Wifi devices (Mi IO) Binding
-This binding is used to control Xiaomi products implementing the Mi IO protocol.
+This binding is used to control Xiaomi products implementing the Mi IO protocol.
This protocol is used for most of Xiaomi Mi Ecosystem wifi devices which is branded as MiJia.
If your Xiaomi wifi device is controlled by the mihome app, most likely it communicates using the Mi IO protocol and can communicate with openHAB using this binding.
## Tokens
The binding needs a token from the Xiaomi Mi Device in order to be able to control it.
-The binding can retrieve the needed tokens from the Xiaomi cloud.
-Go to the binding config page and enter your cloud username and password.
-The server(s) to which your devices are connected need to be entered as well.
+The binding can retrieve the needed tokens from the Xiaomi cloud.
+Go to the binding config page and enter your cloud username and password.
+The server(s) to which your devices are connected need to be entered as well.
Use the one of the regional servers: cn,de,i2,tw,ru,sg,us.
Multiple servers can be separated with comma, or leave blank to test all known servers.
See [binding configuration](#binding-configuration) for more details about the binding config.
Some devices provide the token upon discovery. This may depends on the firmware version.
If the device does not discover your token, it needs to be retrieved from the Mi Home app.
-The easiest way to obtain tokens is to browse through log files of the Mi Home app version 5.4.49 for Android.
-It seems that version was released with debug messages turned on by mistake.
-An APK file with the old version can be easily found using one of the popular web search engines.
+The easiest way to obtain tokens is to browse through log files of the Mi Home app version 5.4.49 for Android.
+It seems that version was released with debug messages turned on by mistake.
+An APK file with the old version can be easily found using one of the popular web search engines.
After downgrading use a file browser to navigate to directory SmartHome/logs/plug_DeviceManager, then open the most recent file and search for the token. When finished, use Google Play to get the most recent version back.
-For iPhone, use an un-encrypted iTunes-Backup and unpack it and use a sqlite tool to view the files in it:
+For iPhone, use an un-encrypted iTunes-Backup and unpack it and use a sqlite tool to view the files in it:
Then search in "RAW, com.xiaomi.home," for "USERID_mihome.sqlite" and look for the 32-digit-token or 96 digit encrypted token.
Note. The Xiaomi devices change the token when inclusion is done. Hence if you get your token after reset and than include it with the Mi Home app, the token will change.
No binding configuration is required. However to enable cloud functionality enter your Xiaomi username, password and server(s).
The list of the known countries and related severs is [here](#country-servers).
-After successful Xiaomi cloud login, the binding will use the connection to retrieve the required device tokens from the cloud.
+After successful Xiaomi cloud login, the binding will use the connection to retrieve the required device tokens from the cloud.
For Xiaomi vacuums the map can be visualized in openHAB using the cloud connection.
To enter your cloud details go to the bindings page, click the Xiaomi Mi IO binding and than configure.
Each Xiaomi device (thing) needs the IP address and token configured to be able to communicate. See discovery for details.
Optional configuration is the refresh interval and the deviceID. Note that the deviceID is automatically retrieved when it is left blank.
-The configuration for model is automatically retrieved from the device in normal operation.
+The configuration for model is automatically retrieved from the device in normal operation.
However, for devices that are unsupported, you may override the value and try to use a model string from a similar device to experimentally use your device with the binding.
| Parameter | Type | Required | Description |
| communication | text | false | Communicate direct or via cloud (options values: 'direct', 'cloud') |
| cloudServer | text | false | Identifies the country server to use in case of cloud communication |
-Note: Suggest to use the cloud communication only for devices that require it.
+Note: Suggest to use the cloud communication only for devices that require it.
It is unknown at this time if Xiaomi has a rate limit or other limitations on the cloud usage. e.g. if having many devices would trigger some throttling from the cloud side.
Note2: communications parameter is not available for lumi devices. Lumi devices communicate using the bridge/gateway.
### Example Thing file
-`Thing miio:basic:light "My Light" [ host="192.168.x.x", token="put here your token", deviceId="326xxxx", model="philips.light.bulb", communication="direct" ]`
+`Thing miio:basic:light "My Light" [ host="192.168.x.x", token="put here your token", deviceId="326xxxx", model="philips.light.bulb", communication="direct" ]`
or in case of unknown models include the model information of a similar device that is supported:
in case of gateway, instead of defining it as a Thing, use Bridge
-`Bridge miio:gateway:lumigateway "Mi Smarter Gateway" [ host="10.10.x.x", token="put here your token", deviceId="326xxxx", model="lumi.gateway.mieu01", communication="direct", cloudServer="de" ]`
-
+`Bridge miio:gateway:lumigateway "Mi Smarter Gateway" [ host="10.10.x.x", token="put here your token", deviceId="326xxxx", model="lumi.gateway.mieu01", communication="direct", cloudServer="de" ]`
# Advanced: Unsupported devices
## Substitute model for unsupported devices
Replace the model with the model which is already supported.
-For this, first remove your unsupported thing. Manually add a miio:basic thing.
+For this, first remove your unsupported thing. Manually add a miio:basic thing.
Besides the regular configuration (like ip address, token) the modelId needs to be provided.
Normally the modelId is populated with the model of your device, however in this case, use the modelId of a similar device.
Look at the openHAB forum, or the openHAB GitHub repository for the modelId of similar devices.
Things using the basic handler (miio:basic things) are driven by json 'database' files.
This instructs the binding which channels to create, which properties and actions are associated with the channels etc.
-The conf/misc/miio (e.g. in Linux `/opt/openhab/conf/misc/miio/`) is scanned for database files and will be used for your devices.
-During the start of the binding the exact path used in your system will be printed in the _debug_ log.
+The conf/misc/miio (e.g. in Linux `/opt/openhab/conf/misc/miio/`) is scanned for database files and will be used for your devices.
+During the start of the binding the exact path used in your system will be printed in the _debug_ log.
Watch for a line containing `Started miio basic devices local databases watch service. Watching for database files at path: …` (
-If this folder is created after the start of the binding, you may need to restart the binding (or openHAB) to be able to use the local files.
-Note that local database files take preference over build-in ones, hence if a json file is local and in the database the local file will be used.
+If this folder is created after the start of the binding, you may need to restart the binding (or openHAB) to be able to use the local files.
+Note that local database files take preference over build-in ones, hence if a json file is local and in the database the local file will be used.
For format, please check the current database files in openHAB GitHub.
# FAQ.. what to do in case of problems
If your device is not getting online:
_Are you using text config?_
-Make sure you define all the fields as per above example.
+Make sure you define all the fields as per above example.
Or, better, try to get it going first without text config.
_The token is wrong_
_My token is coming from the cloud... how can it be wrong?_
Is not very likely but still can happen._
-This can happen e.g. if your device is defined on multiple country servers.
+This can happen e.g. if your device is defined on multiple country servers.
The binding may pull the token from the wrong country server.
First try to get the token from all country servers by leave the county setting empty.
If that does not solve it, you define only the country that the device is on in the binding config page (where the cloud userid/pwd is entered) this should pull the right token.
_You have the same device added multiple times._
-The communication each time send a sequential number.
+The communication each time send a sequential number.
If the device is twice defined, the numbers received by the device are no longer sequential and it will stop responding for some time.
_The connection is not too good, so you have timeouts etc._
Alternatively as described above, double check for multiple connections for single device.
_Your device is on a different subnet?_
-This is in most cases not working.
+This is in most cases not working.
Firmware of the device don't accept commands coming from other subnets.
Set the communication in the thing configuration to 'cloud'.
The most common problem is a wrong or missing userId/password. Update your Xiaomi cloud userId & password in the [miio binding configuration screen](#binding-configuration).
If the problem persists you can try the following:
-* Xiaomi Account verification might be needed. For some users login by the binding is unsuccessful as account verification is required, but the binding currently has no possibilities to handle this.
-In order to pass validation your (openHAB server) ip need to be validated/confirmed.
+- Xiaomi Account verification might be needed. For some users login by the binding is unsuccessful as account verification is required, but the binding currently has no possibilities to handle this.
+In order to pass validation your (openHAB server) ip need to be validated/confirmed.
Browse to [https://account.xiaomi.com/](https://account.xiaomi.com/) and logon to your account. Note: use the same external ip address as your openHAB server, e.g. you may need to disable your VPN.
-* If above is not possible or fails, You can try to find in the binding debug logging a `location url`. Try to login using this url (just after it fails) with your browser.
-* Several users also reported success by resetting their Xiaomi password.
+- If above is not possible or fails, You can try to find in the binding debug logging a `location url`. Try to login using this url (just after it fails) with your browser.
+- Several users also reported success by resetting their Xiaomi password.
-If it still fails, you're bit out of luck. You may try to restart openHAB (not just the binding) to clean the cookies.
+If it still fails, you're bit out of luck. You may try to restart openHAB (not just the binding) to clean the cookies.
As the cloud logon process is still little understood, your only luck might be to enable trace logging and see if you can translate the Chinese error code that it returns.
_My Roborock vacuum is not found or not reacting_
-Did you link the vacuum with the Roborock app?
-This won't work, the Roborock app is using a different communication method.
-Reset your vacuum and connect it to the Xiaomi MiHome app.
+Did you link the vacuum with the Roborock app?
+This won't work, the Roborock app is using a different communication method.
+Reset your vacuum and connect it to the Xiaomi MiHome app.
This will change the communication method and the Mi IO binding can communicate with the vacuum.
# Mi IO Devices
!!!devices
-note: Supported means we received feedback from users this device is working with the binding.
-For devices with experimental support, we did not yet confirmation that channels are correctly working.
+note: Supported means we received feedback from users this device is working with the binding.
+For devices with experimental support, we did not yet confirmation that channels are correctly working.
Please feedback your findings for these devices (e.g. Are all channels working, do they contain the right information, is controlling the devices working etc.)
-# Channels
+## Channels
Depending on the device, different channels are available.
| actions#rpc | String | send commands via cloud. see below |
note: the ADVANCED `actions#commands` and `actions#rpc` channels can be used to send commands that are not automated via the binding. This is available for all devices
-e.g. `openhab:send actionCommand 'upd_timer["1498595904821", "on"]'` would enable a pre-configured timer. See https://github.com/marcelrv/XiaomiRobotVacuumProtocol for all known available commands.
-
+e.g. `openhab:send actionCommand 'upd_timer["1498595904821", "on"]'` would enable a pre-configured timer. See <https://github.com/marcelrv/XiaomiRobotVacuumProtocol> for all known available commands.
### Robo Rock vacuum Channels
Note, cropping is disabled (hence showing like the maps in OH3.1 and earlier) for any `cropBorder` value < 0.
Note, not all the values need to be in the json file, e.g. a subset of the parameters also works, the parameters not in the `mapConfig.json` will take the default values.
-
!!!channelList
-
## Example item file Rockrobo vacuum
-```
+```java
Group gVac "Xiaomi Robot Vacuum" <fan>
Group gVacStat "Status Details" <status> (gVac)
Group gVacCons "Consumables Usage" <line-increase> (gVac)
Image map "Cleaning Map" (gVacLast) {channel="miio:vacuum:034F0E45:cleaning#map"}
```
-
!!!itemFileExamples
### Country Servers
Mapping of countries in mihome app to server:
| Country | Country Code | Server |
-|--------------------------|--------------|--------|
+|--------------------------|--------------|--------|
| Afghanistan | AF | sg |
| Albania | AL | de |
| Algeria | DZ | sg |
## Supported Things
-* `routeros` - An instance of the RouterOS device connection
-* `interface` - A network interface inside RouterOS device
-* `wifiRegistration` - Any wireless client connected to a RouterOS wireless network (regular or CAPsMAN-managed)
-
+- `routeros` - An instance of the RouterOS device connection
+- `interface` - A network interface inside RouterOS device
+- `wifiRegistration` - Any wireless client connected to a RouterOS wireless network (regular or CAPsMAN-managed)
## Discovery
Discovery is currently not supported, but may be implemented in future versions.
-
## Bridge Configuration
To use this binding you need at least one RouterOS-powered device (Bridge) accessible to the host running
openHAB via network.
-Make sure your RouterOS has the API enabled by visiting [<kbd>IP -> Services</kbd>](https://wiki.mikrotik.com/wiki/Manual:IP/Services)
-configuration section in
+Make sure your RouterOS has the API enabled by visiting [<kbd>IP -> Services</kbd>](https://wiki.mikrotik.com/wiki/Manual:IP/Services)
+configuration section in
[WinBox](https://wiki.mikrotik.com/wiki/Manual:Winbox).
Take note of the API port number as you'll need it below.
[SSL API connection](https://wiki.mikrotik.com/wiki/Manual:API-SSL) is not yet supported by this binding.
-To connect to the RouterOS API, you will need to provide user credentials for the bridge thing.
+To connect to the RouterOS API, you will need to provide user credentials for the bridge thing.
You may use your current credentials that you use to manage your devices, but it is highly recommended to **create a read-only RouterOS user** since this binding only need to read data from the device.
To do this, proceed to <kbd>System -> Users</kbd> configuration section and add a user to the `read` group.
**All things provided by this binding require a working bridge to be set up.**
-
### Bridge Channels
| Channel | Type | Description | Comment |
| cpuLoad | Number:Dimensionless | CPU load percentage | |
| upSince | DateTime | Time when thing got up | |
-
-
## WiFi Client Thing Configuration
> Thing type: `wifiRegistration`
Represents a network interface from RouterOS system (ethernet, wifi, vpn, etc.)
At the moment the binding supports the following RouterOS interface types:
-* `ether`
-* `bridge`
-* `wlan`
-* `cap`
-* `pppoe-out`
-* `ppp-out`
-* `lte`
-* `l2tp-in`
-* `l2tp-out`
+- `ether`
+- `bridge`
+- `wlan`
+- `cap`
+- `pppoe-out`
+- `ppp-out`
+- `lte`
+- `l2tp-in`
+- `l2tp-out`
The interface thing configuration parameters are:
**Change config options accordingly.**
-_things/mikrotik.things_
+### things/mikrotik.things
-```
+```java
Bridge mikrotik:routeros:rb1 "My RouterBoard" [ host="192.168.0.1", port=8728, login="openhab", password="thatsasecret", refresh=10 ] {
- Thing interface eth1 "Eth1" [ name="ether1" ]
- Thing interface eth2 "Eth2" [ name="ether2-wan1" ]
- Thing interface cap1 "Cap1" [ name="cap5" ]
- Thing interface ppp1 "PPPoE1" [ name="isp-pppoe" ]
- Thing interface tun1 "L2TPSrv1" [ name="l2tp-parents" ]
- Thing wifiRegistration wifi1 "Phone1" [ mac="F4:60:E2:C5:47:94", considerContinuous=60 ]
- Thing wifiRegistration wifi2 "Tablet2" [ mac="18:1D:EA:A5:A2:9E" ]
+ Thing interface eth1 "Eth1" [ name="ether1" ]
+ Thing interface eth2 "Eth2" [ name="ether2-wan1" ]
+ Thing interface cap1 "Cap1" [ name="cap5" ]
+ Thing interface ppp1 "PPPoE1" [ name="isp-pppoe" ]
+ Thing interface tun1 "L2TPSrv1" [ name="l2tp-parents" ]
+ Thing wifiRegistration wifi1 "Phone1" [ mac="F4:60:E2:C5:47:94", considerContinuous=60 ]
+ Thing wifiRegistration wifi2 "Tablet2" [ mac="18:1D:EA:A5:A2:9E" ]
}
```
+### items/mikrotik.items
-_items/mikrotik.items_
-
-```
+```java
Group gRB1 "RB3011 System"
Number:DataAmount My_RB_3011_Free_Space "Free space" (gRB1) {channel="mikrotik:routeros:rb1:freeSpace"}
Number:DataAmount My_RB_3011_Total_Space "Total space" (gRB1) {channel="mikrotik:routeros:rb1:totalSpace"}
Number Tablet_2_Rx_Packets "Received packets" (gRB1Wifi2) {channel="mikrotik:wifiRegistration:rb1:wifi2:rxPackets"}
```
-_sitemaps/mikrotik.sitemap_
+### sitemaps/mikrotik.sitemap
-```
+```perl
sitemap mikrotik label="Mikrotik Binding Demo"
{
- Frame label="RouterBOARD 1" {
- Group item=gRB1
- Group item=gRB1Eth1
- Group item=gRB1Eth2
- Group item=gRB1Ppp1
- Group item=gRB1Tun1
- Group item=gRB1Cap1
- Group item=gRB1Wifi1
- Group item=gRB1Wifi2
- }
+ Frame label="RouterBOARD 1" {
+ Group item=gRB1
+ Group item=gRB1Eth1
+ Group item=gRB1Eth2
+ Group item=gRB1Ppp1
+ Group item=gRB1Tun1
+ Group item=gRB1Cap1
+ Group item=gRB1Wifi1
+ Group item=gRB1Wifi2
+ }
}
```
iBox and iBox2 have the version 6, older Milight bridges have the version 3.
The ID is the MAC address of the bridge in hexadecimal digits.
- Bridge milight:bridgeV3:mybridge [ host="192.168.0.70", bridgeid="ACCF23A6C0B4", passwordByte1=0, passwordByte2=0, repeat=2, delayTime=75 ] {
- Thing whiteLed myWhite [ zone="0" ]
- Thing rgbwwLed myRGB [ zone="4" ]
- Thing rgbLed myOldRGB [ zone="1" ]
- }
+```java
+Bridge milight:bridgeV3:mybridge [ host="192.168.0.70", bridgeid="ACCF23A6C0B4", passwordByte1=0, passwordByte2=0, repeat=2, delayTime=75 ] {
+ Thing whiteLed myWhite [ zone="0" ]
+ Thing rgbwwLed myRGB [ zone="4" ]
+ Thing rgbLed myOldRGB [ zone="1" ]
+}
+```
The Thing configuration for the bridge uses the following syntax
-
* Bridge milight:bridgeV3:<any name> host="<IP-Address of bridge>", bridgeid="<mac>"
-
* Bridge milight:bridgeV6:<any name> host="<IP-Address of bridge>", bridgeid="<mac>", passwordByte1="<0-255>", passwordByte2="<0-255>"
-
+
- Bridge milight:bridgeV3:<any name> host="<IP-Address of bridge>", bridgeid="<mac>"
+
- Bridge milight:bridgeV6:<any name> host="<IP-Address of bridge>", bridgeid="<mac>", passwordByte1="<0-255>", passwordByte2="<0-255>"
+
Optionally, the following parameters can be added
-* repeat=<integer> (defaults to 1, if not defined)
+- repeat=<integer> (defaults to 1, if not defined)
Usually the bridge receives all commands albeit UDP is used. But the actual bulbs might be slightly out of bridge radio range and it sometimes helps to send commands multiple times.
-* delayTime=<integer for ms> (defaults to 100, if not defined)
+- delayTime=<integer for ms> (defaults to 100, if not defined)
Time to wait before sending another command to the bridge. It is safe to have a wait time of 1/10s but usually sufficient to just wait 50ms. If the value is too high, commands queue up.
-
The Thing configuration for the bulbs uses the following syntax:
Thing <type of bulb> <any name> zone="<0-4>"
The following bulb types are valid for configuration:
-* rgbv2Led: The very first available bulb. Not very common anymore.
-* whiteLed: The dual white bulbs (with cold/warm white) used with v3-v5 bridges.
-* rgbLed: The rgb+white bulbs (with cold/warm white) used with v3-v5 bridges. About 4080 colors (255 colors x 16 brightness steps).
-* rgbiboxLed: The iBox bridge integrated color bulb without a dedicated white channel.
-* rgbwLed: The 2016/2017 color bulb without saturation support. About 6630 (255x26) colors.
-* rgbwwLed: The 2016/2017 color bulb with saturation support. About 1.044.480 (255x64x64) different color shades. Use this also for the newer generation of the dual white bulbs.
+- rgbv2Led: The very first available bulb. Not very common anymore.
+- whiteLed: The dual white bulbs (with cold/warm white) used with v3-v5 bridges.
+- rgbLed: The rgb+white bulbs (with cold/warm white) used with v3-v5 bridges. About 4080 colors (255 colors x 16 brightness steps).
+- rgbiboxLed: The iBox bridge integrated color bulb without a dedicated white channel.
+- rgbwLed: The 2016/2017 color bulb without saturation support. About 6630 (255x26) colors.
+- rgbwwLed: The 2016/2017 color bulb with saturation support. About 1.044.480 (255x64x64) different color shades. Use this also for the newer generation of the dual white bulbs.
The zone number is either 0 for meaning all bulbs of the same type or a valid zone number (1-4).
Future bridges may support more zones.
For dual white bulbs these channels are supported:
- ledbrightness Controls the brightness of your bulbs
- ledtemperature Changes from cold white to warm white and vice versa
- lednightmode Dims your bulbs to a very low level to use them as a night light
- animation_mode_relative Changes the animation mode. Use an IncreaseDecrease type of widget
+```text
+ledbrightness Controls the brightness of your bulbs
+ledtemperature Changes from cold white to warm white and vice versa
+lednightmode Dims your bulbs to a very low level to use them as a night light
+animation_mode_relative Changes the animation mode. Use an IncreaseDecrease type of widget
+```
For rgbv2Led bulbs these channels are supported:
- ledbrightness Controls the brightness of your bulbs
- ledcolor Changes the color and brightness of your rgb bulbs when bound to a colorpicker
- or just the brightness if bound to a Dimmer or controls On/Off if bound to a switch.
- animation_mode_relative Changes the animation mode. Use an IncreaseDecrease type of widget
+```text
+ledbrightness Controls the brightness of your bulbs
+ledcolor Changes the color and brightness of your rgb bulbs when bound to a colorpicker
+ or just the brightness if bound to a Dimmer or controls On/Off if bound to a switch.
+animation_mode_relative Changes the animation mode. Use an IncreaseDecrease type of widget
+```
For rgbLed bulbs these channels are supported:
- lednightmode Dims your bulbs to a very low level to use them as a night light
- ledwhitemode Disable all color (saturation is 0)
- ledbrightness Controls the brightness of your bulbs
- ledcolor Changes the color and brightness of your rgb bulbs when bound to a colorpicker
- or just the brightness if bound to a Dimmer or controls On/Off if bound to a switch
- animation_mode_relative Changes the animation mode. Use an IncreaseDecrease type of widget
- animation_speed_relative Changes the speed of your chosen animation mode
+```text
+lednightmode Dims your bulbs to a very low level to use them as a night light
+ledwhitemode Disable all color (saturation is 0)
+ledbrightness Controls the brightness of your bulbs
+ledcolor Changes the color and brightness of your rgb bulbs when bound to a colorpicker
+ or just the brightness if bound to a Dimmer or controls On/Off if bound to a switch
+animation_mode_relative Changes the animation mode. Use an IncreaseDecrease type of widget
+animation_speed_relative Changes the speed of your chosen animation mode
+```
For rgbwLed/rgbwwLed bulbs these channels are supported:
- lednightmode Dims your bulbs to a very low level to use them as a night light
- ledwhitemode Disable all color (saturation is 0)
- ledbrightness Controls the brightness of your bulbs
- ledsaturation Controls the saturation of your bulbs (not for rgbwLed!)
- ledtemperature Changes from cold white to warm white and vice versa (not for rgbwLed!)
- ledcolor Changes the color and brightness of your rgb bulbs when bound to a colorpicker
- or just the brightness if bound to a Dimmer or controls On/Off if bound to a switch
- animation_mode Changes the animation mode. Chose between animation mode 1 to 9
- animation_mode_relative Changes the animation mode. Use an IncreaseDecrease type of widget
- animation_speed_relative Changes the speed of your chosen animation mode
- ledlink Sync bulb to this zone within 3 seconds of light bulb socket power on
- ledunlink Clear bulb from this zone within 3 seconds of light bulb socket power on
-
+```text
+lednightmode Dims your bulbs to a very low level to use them as a night light
+ledwhitemode Disable all color (saturation is 0)
+ledbrightness Controls the brightness of your bulbs
+ledsaturation Controls the saturation of your bulbs (not for rgbwLed!)
+ledtemperature Changes from cold white to warm white and vice versa (not for rgbwLed!)
+ledcolor Changes the color and brightness of your rgb bulbs when bound to a colorpicker
+ or just the brightness if bound to a Dimmer or controls On/Off if bound to a switch
+animation_mode Changes the animation mode. Chose between animation mode 1 to 9
+animation_mode_relative Changes the animation mode. Use an IncreaseDecrease type of widget
+animation_speed_relative Changes the speed of your chosen animation mode
+ledlink Sync bulb to this zone within 3 seconds of light bulb socket power on
+ledunlink Clear bulb from this zone within 3 seconds of light bulb socket power on
+```
+
Limitations:
-* Only the rgbww bulbs support changing their saturation, for rgbv2Led/rgbwLed the colorpicker will only set the hue and brightness and change to white mode if the saturation is under a given threshold of 50%.
+- Only the rgbww bulbs support changing their saturation, for rgbv2Led/rgbwLed the colorpicker will only set the hue and brightness and change to white mode if the saturation is under a given threshold of 50%.
## Example
.items
-```
-Switch Light_Groundfloor {channel="milight:whiteLed:ACCF23A6C0B4:0:ledbrightness"} //Switch for all white bulbs
-Dimmer Light_LivingroomB {channel="milight:whiteLed:ACCF23A6C0B4:1:ledbrightness"} //Dimmer changing brightness for bulb in zone 1
-Dimmer Light_LivingroomC {channel="milight:whiteLed:ACCF23A6C0B4:1:ledtemperature"} //Dimmer changing colorTemperature for bulb in zone 1
-Dimmer RGBW_LivingroomB {channel="milight:rgbwLed:ACCF23A6C0B4:2:ledbrightness"} //Dimmer changing brightness for RGBW bulb in zone 2
+```java
+Switch Light_Groundfloor {channel="milight:whiteLed:ACCF23A6C0B4:0:ledbrightness"} //Switch for all white bulbs
+Dimmer Light_LivingroomB {channel="milight:whiteLed:ACCF23A6C0B4:1:ledbrightness"} //Dimmer changing brightness for bulb in zone 1
+Dimmer Light_LivingroomC {channel="milight:whiteLed:ACCF23A6C0B4:1:ledtemperature"} //Dimmer changing colorTemperature for bulb in zone 1
+Dimmer RGBW_LivingroomB {channel="milight:rgbwLed:ACCF23A6C0B4:2:ledbrightness"} //Dimmer changing brightness for RGBW bulb in zone 2
Color Light_Party {channel="milight:rgbwLed:ACCF23A6C0B4:1:ledcolor"} //Colorpicker for rgb bulbs
# You have to link the items to the channels of your prefered group.
//The command types nightMode and whiteMode are stateless and should be configured as pushbuttons as they only support a trigger action:
-Switch Light_GroundfloorN {channel="milight:whiteLed:ACCF23A6C0B4:0:lednightmode", autoupdate="false"} //Activate the NightMode for all bulbs
+Switch Light_GroundfloorN {channel="milight:whiteLed:ACCF23A6C0B4:0:lednightmode", autoupdate="false"} //Activate the NightMode for all bulbs
//The command types animation_mode_relative and animation_speed are stateless and should be configured as pushbuttons as they only support INCREASE and DECREASE commands:
-Dimmer AnimationMode {channel="milight:rgbLed:ACCF23A6C0B4:5:animation_mode_relative", autoupdate="false"}
-Dimmer AnimationSpeed {channel="milight:rgbLed:ACCF23A6C0B4:5:animation_speed", autoupdate="false"}
+Dimmer AnimationMode {channel="milight:rgbLed:ACCF23A6C0B4:5:animation_mode_relative", autoupdate="false"}
+Dimmer AnimationSpeed {channel="milight:rgbLed:ACCF23A6C0B4:5:animation_speed", autoupdate="false"}
//Animation Mode for RGBWW bulbs is different, it allows to pick a mode directly.
-Switch AnimationModeRgbWW {channel="milight:rgbwwLed:ACCF23A6C0B4:5:animation_mode"}
+Switch AnimationModeRgbWW {channel="milight:rgbwwLed:ACCF23A6C0B4:5:animation_mode"}
```
.sitemap
-```
+```perl
Switch item=AnimationMode mappings=[DECREASE='-', INCREASE='+']
Switch item=AnimationSpeed mappings=[DECREASE='-', INCREASE='+']
Switch item=Light_GroundfloorN mappings=[ON='Night Mode']
# Millheat Binding
-This binding integrates the Mill Wi-Fi enabled panel heaters. See https://www.millheat.com/mill-wifi/
+This binding integrates the Mill Wi-Fi enabled panel heaters. See <https://www.millheat.com/mill-wifi/>
## Supported Things
This binding supports all Wi-Fi enabled heaters as well as the Wi-Fi socket.
-* `account` = Mill Heating API - the account bridge
-* `heater` = Panel/standalone heater
-* `room` = A room defined in the mobile app
-* `home` = A home defined in the mobile app
+- `account` = Mill Heating API - the account bridge
+- `heater` = Panel/standalone heater
+- `room` = A room defined in the mobile app
+- `home` = A home defined in the mobile app
## Discovery
### Account
-* `username` = email address used in app
-* `password` = password used in app
-* `refreshInterval` = number of seconds between refresh calls to the server
+- `username` = email address used in app
+- `password` = password used in app
+- `refreshInterval` = number of seconds between refresh calls to the server
### Home
-* `homeId` = id of home, type number (not string). Use auto discovery to find this value
+- `homeId` = id of home, type number (not string). Use auto discovery to find this value
### Room
-* `roomId` = id of room, type number (not string). Use auto discovery to find this value
+- `roomId` = id of room, type number (not string). Use auto discovery to find this value
### Heater
-* `macAddress` = network mac address of device in UPPERCASE.
+- `macAddress` = network mac address of device in UPPERCASE.
Can be found in the app by viewing devices. Or you can find it during discovery. Used for heaters connected to a room.
-* `heaterId` = id of device/heater, type number (not string)
+- `heaterId` = id of device/heater, type number (not string)
Use auto discovery to find this value. Used to identify independent heaters or heaters connected to a room.
-* `power` = number of watts this heater is consuming when active.
+- `power` = number of watts this heater is consuming when active.
Used to provide data for the currentPower channel.
Either `macAddres` or `heaterId` must be specified.
millheat.things:
-```
+```java
Bridge millheat:account:home "Millheat account" [username="email@address.com",password="topsecret"] {
Thing home monaco "Penthouse Monaco" [ homeId=100000000000000 ] // Note: numeric value
Thing room office "Office room" [ roomId=200000000000000 ] Note: numeric value
millheat.items:
-```
+```java
// Items connected to HOME channels
Number:Temperature Vacation_Target_Temperature "Vacation target temp [%d %unit%]" <temperature> {channel="millheat:home:home:monaco:vacationModeTargetTemperature"}
Switch Vacation_Mode "Vacation mode" <vacation> {channel="millheat:home:home:monaco:vacationMode"}
In order to activate vacation mode, follow these steps in a rule:
-* Set start time (DateTime) on `DateTime` item linked to channel type `vacationModeStart`
-* Set end time (DateTime) on `DateTime` item linked to channel type `vacationModeEnd`
-* Activate vacation mode on `Switch` item linked to channel type `vacationMode`
-* Optional - set advanced vacation mode on `Switch` item linked to channel type `vacationModeAdvanced`
+- Set start time (DateTime) on `DateTime` item linked to channel type `vacationModeStart`
+- Set end time (DateTime) on `DateTime` item linked to channel type `vacationModeEnd`
+- Activate vacation mode on `Switch` item linked to channel type `vacationMode`
+- Optional - set advanced vacation mode on `Switch` item linked to channel type `vacationModeAdvanced`
| players | Number | The number of players on server |
| maxPlayers | Number | The maximum number of players on server |
-
### Player
| Channel Type ID | Item Type | Description |
| playerLocation | Location | The player location |
| playerGameMode | Number | The players game mode |
-
### Sign
| Channel Type ID | Item Type | Description |
|-----------------|-----------|----------------------------------------------|
| signActive | Switch | Does the sign have powered redstone below it |
-
#### Active switch (Controllable from openHAB)
<a href="https://drive.google.com/uc?export=view&id=0B3UO0c11-Q6hMkNZSjJidGk4b28"><img src="https://drive.google.com/uc?export=view&id=0B3UO0c11-Q6hMkNZSjJidGk4b28" style="width: 500px; max-width: 100%; height: auto" title="Click for the larger version." /></a>
### Example Thing Definition
The easiest method to add Minecraft servers, players, and signs is use the automatic discovery.
-You can also manually define the objects using thing configuration files.
+You can also manually define the objects using thing configuration files.
Players and signs are connected through Minecraft server [bridges](https://www.openhab.org/docs/configuration/things.html#defining-bridges-using-files).
-```xtend
+```java
Bridge minecraft:server:myminecraftserver "Minecraft server for Friends" @ "Minecraft" [ hostname="192.168.1.100", port=10692 ] {
Thing player my_name "My Minecraft User" @ "Minecraft" [ playerName="minecraft_username" ]
Thing player friends_name "My Friend's Minecraft User" @ "Minecraft" [ playerName="friends_username" ]
# E3DC
-Integrates the Home Power Plants from E3/DC GmbH into openHAB.
+Integrates the Home Power Plants from E3/DC GmbH into openHAB.
See [E3DC Website](https://www.e3dc.com/) to find more informations about the device.
The Power Plant handles all your Electrical Energy Resources like Photovoltaic Producers, Battery Storage, Wallbox Power Supply, Household Consumption and even more.
-E3DC devices are integrated into the Modbus Binding.
+E3DC devices are integrated into the Modbus Binding.
-See chapter [Thing Configuration](#thing-configuration) how to set them up or check the [full example Things](#things) for manual setup.
+See chapter [Thing Configuration](#thing-configuration) how to set them up or check the [full example Things](#things) for manual setup.
## Supported Things
| E3DC Home Power Plant | e3dc | Provides Power values, String Details, Emergency Power Status and general Information of your E3DC Home Power Plant |
| E3DC Wallbox | e3dc-wallbox | Provides your Wallbox Settings. Switches like "Sunmode" or "1-Phase Charging" can be changed |
-
## Discovery
-There's no discovery.
-Modbus registers are available for all devices.
+There's no discovery.
+Modbus registers are available for all devices.
## Thing Configuration
1. Create _Modbus TCP Bridge_ with matching Settings of your E3DC Device
-* IP Address
-* Device ID
-* Port ID
+- IP Address
+- Device ID
+- Port ID
-2. Create _E3DC Home Power Plant_ and attach it to the previous installed _Modbus TCP Bridge_. Configuration requires an approriate Data Refresh Interval with more than 1000 Milliseconds
+1. Create _E3DC Home Power Plant_ and attach it to the previous installed _Modbus TCP Bridge_. Configuration requires an approriate Data Refresh Interval with more than 1000 Milliseconds
-3. If you have a Wallbox attached add _E3DC Wallbox_ Thing with your previous installed _E3DC Home Power Plant_ as Bridge. Configuration requires a Wallbox ID between 0 and 7.
+1. If you have a Wallbox attached add _E3DC Wallbox_ Thing with your previous installed _E3DC Home Power Plant_ as Bridge. Configuration requires a Wallbox ID between 0 and 7.
Check the [full example Things](#things) for manual setup.
-### Modbus TCP Slave
+### Modbus TCP Slave
-| Parameter | Type | Description |
+| Parameter | Type | Description |
|-----------------|---------|-------------------------------------------------------------------------|
| host | text | IP Address of your device |
| port | integer | TCP Port of your E3DC device Modbus Settings.. Default is 502 |
| deviceid | integer | Modbus ID of your E3DC device Modbus Settings. Default is 1 |
-### E3DC Home Power Plant
+### E3DC Home Power Plant
Select as Bridge your previously created Modbus TCP Slave.
-| Parameter | Type | Description |
+| Parameter | Type | Description |
|-----------------|---------|-------------------------------------------------------------------------|
| refresh | integer | Refresh Rate of E3DC values in Milliseconds |
-
### E3DC Wallbox
Select as Bridge your previously created E3DC Home Power Plant.
-| Parameter | Type | Description |
+| Parameter | Type | Description |
|-----------------|---------|-----------------------------------------------------------------------------|
| wallboxId | integer | E3DC supports up to 8 Wallboxes - select a value from 0 to 7 |
## Channels
-The E3DC device offers quite an amount of channels. For clustering 4 Channel Groups are used:
+The E3DC device offers quite an amount of channels. For clustering 4 Channel Groups are used:
### Channel Group _Information Block_
| E3DC Firmware Release | info | firmware-release | String | Firmware installed on this particular E3DC Device |
| E3DC Serial Number | info | serial-number | String | Serial Number of this particular E3DC Device |
-
### Channel Group _Power Block_
| Channel Label | Channel Group ID | Channel ID | Type | Description |
| Self Consumption | power | self-consumption | Number:Dimensionless | Your current Photovoltaic Self Consumption Level in Percent |
| Battery State Of Charge | power | battery-soc | Number:Dimensionless | Charge Level of your attached Battery in Percent |
-
### Channel Group _String Details Block_
| Channel Label | Channel Group ID | Channel ID | Type | Description |
| String 2 Power | strings | string2-dc-output | Number:Power | Power produced by String 2 |
| String 3 Power | strings | string3-dc-output | Number:Power | Power produced by String 3 |
-
### Channel _EMS Block_
| Channel Label | Channel Group ID | Channel ID | Type | Description |
## Full Example
-Following example provides the full configuration.
+Following example provides the full configuration.
If you enter the correct Connection Data, IP Address, Device ID and Port number in the thing configuration you should be fine.
### Things
-```
+```java
Bridge modbus:tcp:device "E3DC Modbus TCP" [ host="192.168.178.56", port=502, id=1 ] {
- Bridge e3dc powerplant "E3DC Power Plant" [ refresh=2500 ] {
- Thing e3dc-wallbox wallbox0 "E3DC Wallbox" [ wallboxId=0]
+ Bridge e3dc powerplant "E3DC Power Plant" [ refresh=2500 ] {
+ Thing e3dc-wallbox wallbox0 "E3DC Wallbox" [ wallboxId=0]
}
}
```
### Items
-```
+```java
String E3DC_ModbusId "E3DC Modbus ID" (e3dc) { channel="modbus:e3dc:device:powerplant:info#modbus-id" }
String E3DC_ModbusFirmware "E3DC Modbus Firmware" (e3dc) { channel="modbus:e3dc:device:powerplant:info#modbus-firmware" }
Number E3DC_SupportedRegisters "E3DC Supported Registers" (e3dc) { channel="modbus:e3dc:device:powerplant:info#supported-registers" }
### Sitemap
-```
+```perl
sitemap E3DC label="E3DC Binding Sitemap" {
Frame label="Info" {
Text item=E3DC_ModbusId label="Modbus-ID [%s]"
}
```
-
## Going further
Setup and configured everything the right way? Congratulations, you've now the recent E3DC values on your table. Don't stop and go ahead!
### Persistence
-You can see in the example item configuration, that I added some items to the "persist".
-Feel free to choose your own group name but this opens the possibility to store the items in a database.
+You can see in the example item configuration, that I added some items to the "persist".
+Feel free to choose your own group name but this opens the possibility to store the items in a database.
See following *.persist file configuration how this can be established.
-```
+```text
Strategies {
everyMinute : "0 * * * * ?"
everyHour : "0 0 * * * ?"
}
```
-### Visualization
+### Visualization
-After the timeline is available in your database you can continue with Visualization.
+After the timeline is available in your database you can continue with Visualization.
I like the Grafana approach and I used the [InfluxDB & Grafana Tutorial](https://community.openhab.org/t/influxdb-grafana-persistence-and-graphing/13761)
from the Community to set this up.
I prepared my machine and I'm quite pleased with the results.
In the above picture there are two graphs
-* The top one shows the Photovoltaic Production of my 2 attached Strings. You can clearly see when the sky wasn't bright the production goes down
-* The bottom graph show the producers & consumers.
- * Battery in blue charging during the day, discharging at night
- * Household consumption in green
- * Wallbox consumption in orange
- * Grid consumption / supply in yellow
+- The top one shows the Photovoltaic Production of my 2 attached Strings. You can clearly see when the sky wasn't bright the production goes down
+- The bottom graph show the producers & consumers.
+ - Battery in blue charging during the day, discharging at night
+ - Household consumption in green
+ - Wallbox consumption in orange
+ - Grid consumption / supply in yellow
-### Cross Connections
+### Cross Connections
-With the above setup you have now a great visualization and overview regarding your electric production and consumption.
-Now use the Power of openHAB and cross connect your data.
+With the above setup you have now a great visualization and overview regarding your electric production and consumption.
+Now use the Power of openHAB and cross connect your data.
For example you can use the [OpenweatherMap API Binding](https://www.openhab.org/addons/bindings/openweathermap/)
-the cloudiness in Percent.
+the cloudiness in Percent.
With a modified *.persist file I store the cloudiness forecast also in the database
-```
+```text
Strategies {
everyMinute : "0 * * * * ?"
everyHour : "0 0 * * * ?"
}
```
-Having these values in the timeline you're able to cross check how the forecast influences the Photovoltaic Production.
+Having these values in the timeline you're able to cross check how the forecast influences the Photovoltaic Production.
<img align="right" src="./doc/GrafanaCloudiness.png"/>
The configuration of a Helios Ventilation device via a `.things` file would look like the following code sample.
It's required to provide the device's IP address, port and unit ID (port and unit ID cannot be changed and always have to be 502 and 180; in fact the values provided here are ignored by the binding and the fixed values 502 and 180 are used):
-```
+```java
Bridge modbus:tcp:modbus-gateway "Modbus TCP/IP Gateway" [ host="x.x.x.x", port=502, id=180, enableDiscovery=true ] {
Thing helios-easycontrols kwl "KWL"
}
The following channels are supported:
-| Channel | Channel Group | Description | Item Type | RW |
-| -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | -- |
-| sysdate | general | The KWL's system date and time | DateTime | RW |
-| summerWinter | general | Indicates if summertime or wintertime is active (0 = wintertime, 1 = summertime) | Number | RW |
-| autoSwUpdate | general | Indicates if automatic software updates are enable | Switch | RW |
-| accessHeliosPortal | general | Indicates if access to Helios portal is enabled | Switch | RW |
-| minFanStage | unitConfig | Minimum fan stage (0 or 1) (0, 1) | Number | RW |
-| preHeaterStatus | general | Pre-Heater Status | Switch | RW |
-| humidityControlSetValue | humidityControl | Humidity control set value (in percent) (20 - 80 %) | Number:Dimensionless | RW |
-| humidityControlSteps | humidityControl | Humidity control steps (in percent) (5 - 20 %) | Number:Dimensionless | RW |
-| humidityStopTime | humidityControl | Humidity stop time in hours (0-24) (0 - 24 h) | Number:Time | RW |
-| co2ControlSetValue | co2Control | CO2 control set value (in ppm) (300 - 2000 ppm) | Number:Dimensionless | RW |
-| co2ControlSteps | co2Control | CO2 control steps (in ppm) (50 - 400 ppm) | Number:Dimensionless | RW |
-| vocControlSetValue | vocControl | VOC control set value (in ppm) (300 - 2000 ppm) | Number:Dimensionless | RW |
-| vocControlSteps | vocControl | VOC control steps (in ppm) (50 - 400 ppm) | Number:Dimensionless | RW |
-| comfortTemp | unitConfig | Comfort Temperature (10.0 - 25.0 °C) | Number:Temperature | RW |
-| partyModeDuration | operation | Party mode duration (in minutes) (5 - 180 min) | Number:Time | RW |
-| partyModeFanStage | operation | Party mode fan stage (0 - 4) | Number | RW |
-| partyModeRemainingTime | operation | Party mode remaining time (0 - 180 min) | Number:Time | R |
-| partyModeStatus | operation | Party mode status | Switch | RW |
-| standbyModeDuration | operation | Standby mode duration (in minutes) (5 - 180 min) | Number:Time | RW |
-| standbyModeFanStage | operation | Standby mode fan stage (0 - 4) | Number | RW |
-| standbyModeRemainingTime | operation | Standby mode remaining time (0 - 180 min) | Number:Time | R |
-| standbyModeStatus | operation | Standby mode status | Switch | RW |
-| operatingMode | operation | Operating mode (automatic/manual) (0 = automatic, 1 = manual) | Number | RW |
-| fanStage | operation | Fan stage (0 - 4) | Number | RW |
-| percentageFanStage | operation | Fan stage in percent (0 - 100 %) | Number:Dimensionless | R |
-| temperatureOutsideAir | general | Ouside air temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| temperatureSupplyAir | general | Supply air temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| temperatureOutgoingAir | general | Outgoing air temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| temperatureExtractAir | general | Extract air temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| vhzDuctSensor | general | Pre-heater intake temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| nhzReturnSensor | general | After-heater return temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| externalSensorKwlFtfHumidity1 | humidityControl | External humidity sensor 1 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
-| externalSensorKwlFtfHumidity2 | humidityControl | External humidity sensor 2 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
-| externalSensorKwlFtfHumidity3 | humidityControl | External humidity sensor 3 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
-| externalSensorKwlFtfHumidity4 | humidityControl | External humidity sensor 4 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
-| externalSensorKwlFtfHumidity5 | humidityControl | External humidity sensor 5 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
-| externalSensorKwlFtfHumidity6 | humidityControl | External humidity sensor 6 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
-| externalSensorKwlFtfHumidity7 | humidityControl | External humidity sensor 7 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
-| externalSensorKwlFtfHumidity8 | humidityControl | External humidity sensor 8 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
-| externalSensorKwlFtfTemperature1 | humidityControl | External temperature sensor 1 (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| externalSensorKwlFtfTemperature2 | humidityControl | External temperature sensor 2 (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| externalSensorKwlFtfTemperature3 | humidityControl | External temperature sensor 3 (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| externalSensorKwlFtfTemperature4 | humidityControl | External temperature sensor 4 (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| externalSensorKwlFtfTemperature5 | humidityControl | External temperature sensor 5 (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| externalSensorKwlFtfTemperature6 | humidityControl | External temperature sensor 6 (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| externalSensorKwlFtfTemperature7 | humidityControl | External temperature sensor 7 (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| externalSensorKwlFtfTemperature8 | humidityControl | External temperature sensor 8 (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| externalSensorKwlCo21 | co2Control | External CO2 sensor 1 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlCo22 | co2Control | External CO2 sensor 2 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlCo23 | co2Control | External CO2 sensor 3 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlCo24 | co2Control | External CO2 sensor 4 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlCo25 | co2Control | External CO2 sensor 5 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlCo26 | co2Control | External CO2 sensor 6 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlCo27 | co2Control | External CO2 sensor 7 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlCo28 | co2Control | External CO2 sensor 8 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlVoc1 | vocControl | External VOC sensor 1 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlVoc2 | vocControl | External VOC sensor 2 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlVoc3 | vocControl | External VOC sensor 3 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlVoc4 | vocControl | External VOC sensor 4 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlVoc5 | vocControl | External VOC sensor 5 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlVoc6 | vocControl | External VOC sensor 6 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlVoc7 | vocControl | External VOC sensor 7 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| externalSensorKwlVoc8 | vocControl | External VOC sensor 8 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
-| nhzDuctSensor | general | After-heater intake temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
-| weekProfileNhz | profiles | Week profile after-heater (0 = standard 1, 1 = standard 2, 2 = fixed value, 3 = individual 1, 4 = individual 2, 5 = NA, 6 = off) | Number | RW |
-| supplyAirRpm | general | Supply air fan RPM (0 - 9999) | Number | R |
-| extractAirRpm | general | Extract air fan RPM (0 - 9999) | Number | R |
-| holidayProgramme | operation | Holiday programme (0 = off, 1 = interval, 2 = constant) | Number | RW |
-| holidayProgrammeFanStage | operation | Holiday programme fan stage (0 - 4) | Number | RW |
-| holidayProgrammeStart | operation | Holiday programme start | DateTime | RW |
-| holidayProgrammeEnd | operation | Holiday programme end | DateTime | RW |
-| holidayProgrammeInterval | operation | Holiday programme interval in hours (1 - 24 h) | Number:Time | RW |
-| holidayProgrammeActivationTime | operation | Holiday programme activation time in minutes (5 - 300 min) | Number:Time | RW |
-| runOnTimeVhzNhz | unitConfig | Stopping time preheater/afterheater in seconds (60 - 120 s) | Number:Time | RW |
-| errorOutputFunction | unitConfig | Error output function (collective error or just error) (1 = collective error, 2 = only error) | Number | RW |
-| filterChange | unitConfig | Filter change (0 = No, 1 = Yes) | Number | RW |
-| filterChangeInterval | unitConfig | Filter change interval in months (1 - 12) | Number | RW |
-| filterChangeRemainingTime | general | Filter change remaining time in minutes (1 - 55000 min) | Number:Time | R |
-| bypassRoomTemperature | unitConfig | Bypass room temperature in °C (10 - 40 °C) | Number:Temperature | RW |
-| bypassMinOutsideTemperature | unitConfig | Bypass outside temperature in °C (5 - 20 °C) | Number:Temperature | RW |
-| supplyAirFanStage | operation | Supply air fan stage (0 - 4) | Number | RW |
-| extractAirFanStage | operation | Extract air fan stage (0 - 4) | Number | RW |
-| operatingHoursSupplyAirVent | general | Operating hours supply air fan (in minutes) (0 - 2^32-1 min) | Number:Time | R |
-| operatingHoursExtractAirVent | general | Operating hours extract air fan (in minutes) (0 - 2^32-1 min) | Number:Time | R |
-| operatingHoursVhz | general | Operating hours preheater (in minutes) (0 - 2^32-1 min) | Number:Time | R |
-| operatingHoursNhz | general | Operating hours afterheater (in minutes) (0 - 2^32-1 min) | Number:Time | R |
-| outputPowerVhz | general | Output power of preheater (in percent) (0 - 2^32-1 %) | Number:Dimensionless | R |
-| outputPowerNhz | general | Output power of afterheater (in percent) (0 - 2^32-1 %) | Number:Dimensionless | R |
-| errors | general | Errors as integer value (see [Errors / Warnings / Infos](#errors-warnings-infos)) (0 - 2^32-1) | Number | R |
-| warnings | general | Warnings as integer value (see [Errors / Warnings / Infos](#errors-warnings-infos)) (0 - 2^32-1) | Number | R |
-| infos | general | Infos as integer value (see [Errors / Warnings / Infos](#errors-warnings-infos)) (0 - 2^32-1) | Number | R |
-| noOfErrors | general | Number of bit-coded errors (see [Errors / Warnings / Infos](#errors-warnings-infos)) (0 - 32) | Number | R |
-| noOfWarnings | general | Number of bit-coded warnings (see [Errors / Warnings / Infos](#errors-warnings-infos)) (0 - 8) | Number | R |
-| noOfInfos | general | Number of bit-coded infos (see [Errors / Warnings / Infos](#errors-warnings-infos)) (0 - 8) | Number | R |
-| errorsMsg | general | Errors as string (see [Errors / Warnings / Infos](#errors-warnings-infos)) | String | R |
-| warningsMsg | general | Warnings as string (see [Errors / Warnings / Infos](#errors-warnings-infos)) | String | R |
-| infosMsg | general | Infos as string (see [Errors / Warnings / Infos](#errors-warnings-infos)) | String | R |
-| statusFlags | general | Status flags (see [Errors / Warnings / Infos](#errors-warnings-infos)) | String | R |
-| bypassStatus | general | Status of the bypass (OFF = closed, ON = open) | Switch | R |
-| bypassFrom | unitConfig | Bypass active from | DateTime | RW |
-| bypassTo | unitConfig | Bypass active to | DateTime | RW |
-
+| Channel | Channel Group | Description | Item Type | RW |
+| -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | -- |
+| sysdate | general | The KWL's system date and time | DateTime | RW |
+| summerWinter | general | Indicates if summertime or wintertime is active (0 = wintertime, 1 = summertime) | Number | RW |
+| autoSwUpdate | general | Indicates if automatic software updates are enable | Switch | RW |
+| accessHeliosPortal | general | Indicates if access to Helios portal is enabled | Switch | RW |
+| minFanStage | unitConfig | Minimum fan stage (0 or 1) (0, 1) | Number | RW |
+| preHeaterStatus | general | Pre-Heater Status | Switch | RW |
+| humidityControlSetValue | humidityControl | Humidity control set value (in percent) (20 - 80 %) | Number:Dimensionless | RW |
+| humidityControlSteps | humidityControl | Humidity control steps (in percent) (5 - 20 %) | Number:Dimensionless | RW |
+| humidityStopTime | humidityControl | Humidity stop time in hours (0-24) (0 - 24 h) | Number:Time | RW |
+| co2ControlSetValue | co2Control | CO2 control set value (in ppm) (300 - 2000 ppm) | Number:Dimensionless | RW |
+| co2ControlSteps | co2Control | CO2 control steps (in ppm) (50 - 400 ppm) | Number:Dimensionless | RW |
+| vocControlSetValue | vocControl | VOC control set value (in ppm) (300 - 2000 ppm) | Number:Dimensionless | RW |
+| vocControlSteps | vocControl | VOC control steps (in ppm) (50 - 400 ppm) | Number:Dimensionless | RW |
+| comfortTemp | unitConfig | Comfort Temperature (10.0 - 25.0 °C) | Number:Temperature | RW |
+| partyModeDuration | operation | Party mode duration (in minutes) (5 - 180 min) | Number:Time | RW |
+| partyModeFanStage | operation | Party mode fan stage (0 - 4) | Number | RW |
+| partyModeRemainingTime | operation | Party mode remaining time (0 - 180 min) | Number:Time | R |
+| partyModeStatus | operation | Party mode status | Switch | RW |
+| standbyModeDuration | operation | Standby mode duration (in minutes) (5 - 180 min) | Number:Time | RW |
+| standbyModeFanStage | operation | Standby mode fan stage (0 - 4) | Number | RW |
+| standbyModeRemainingTime | operation | Standby mode remaining time (0 - 180 min) | Number:Time | R |
+| standbyModeStatus | operation | Standby mode status | Switch | RW |
+| operatingMode | operation | Operating mode (automatic/manual) (0 = automatic, 1 = manual) | Number | RW |
+| fanStage | operation | Fan stage (0 - 4) | Number | RW |
+| percentageFanStage | operation | Fan stage in percent (0 - 100 %) | Number:Dimensionless | R |
+| temperatureOutsideAir | general | Ouside air temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| temperatureSupplyAir | general | Supply air temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| temperatureOutgoingAir | general | Outgoing air temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| temperatureExtractAir | general | Extract air temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| vhzDuctSensor | general | Pre-heater intake temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| nhzReturnSensor | general | After-heater return temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| externalSensorKwlFtfHumidity1 | humidityControl | External humidity sensor 1 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
+| externalSensorKwlFtfHumidity2 | humidityControl | External humidity sensor 2 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
+| externalSensorKwlFtfHumidity3 | humidityControl | External humidity sensor 3 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
+| externalSensorKwlFtfHumidity4 | humidityControl | External humidity sensor 4 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
+| externalSensorKwlFtfHumidity5 | humidityControl | External humidity sensor 5 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
+| externalSensorKwlFtfHumidity6 | humidityControl | External humidity sensor 6 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
+| externalSensorKwlFtfHumidity7 | humidityControl | External humidity sensor 7 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
+| externalSensorKwlFtfHumidity8 | humidityControl | External humidity sensor 8 (-0.0 - 9998.9 %) | Number:Dimensionless | R |
+| externalSensorKwlFtfTemperature1 | humidityControl | External temperature sensor 1 (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| externalSensorKwlFtfTemperature2 | humidityControl | External temperature sensor 2 (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| externalSensorKwlFtfTemperature3 | humidityControl | External temperature sensor 3 (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| externalSensorKwlFtfTemperature4 | humidityControl | External temperature sensor 4 (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| externalSensorKwlFtfTemperature5 | humidityControl | External temperature sensor 5 (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| externalSensorKwlFtfTemperature6 | humidityControl | External temperature sensor 6 (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| externalSensorKwlFtfTemperature7 | humidityControl | External temperature sensor 7 (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| externalSensorKwlFtfTemperature8 | humidityControl | External temperature sensor 8 (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| externalSensorKwlCo21 | co2Control | External CO2 sensor 1 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlCo22 | co2Control | External CO2 sensor 2 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlCo23 | co2Control | External CO2 sensor 3 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlCo24 | co2Control | External CO2 sensor 4 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlCo25 | co2Control | External CO2 sensor 5 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlCo26 | co2Control | External CO2 sensor 6 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlCo27 | co2Control | External CO2 sensor 7 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlCo28 | co2Control | External CO2 sensor 8 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlVoc1 | vocControl | External VOC sensor 1 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlVoc2 | vocControl | External VOC sensor 2 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlVoc3 | vocControl | External VOC sensor 3 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlVoc4 | vocControl | External VOC sensor 4 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlVoc5 | vocControl | External VOC sensor 5 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlVoc6 | vocControl | External VOC sensor 6 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlVoc7 | vocControl | External VOC sensor 7 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| externalSensorKwlVoc8 | vocControl | External VOC sensor 8 (-0.0 - 9998.9 ppm) | Number:Dimensionless | R |
+| nhzDuctSensor | general | After-heater intake temperature in °C (-27.0 - 9998.9 °C) | Number:Temperature | R |
+| weekProfileNhz | profiles | Week profile after-heater (0 = standard 1, 1 = standard 2, 2 = fixed value, 3 = individual 1, 4 = individual 2, 5 = NA, 6 = off) | Number | RW |
+| supplyAirRpm | general | Supply air fan RPM (0 - 9999) | Number | R |
+| extractAirRpm | general | Extract air fan RPM (0 - 9999) | Number | R |
+| holidayProgramme | operation | Holiday programme (0 = off, 1 = interval, 2 = constant) | Number | RW |
+| holidayProgrammeFanStage | operation | Holiday programme fan stage (0 - 4) | Number | RW |
+| holidayProgrammeStart | operation | Holiday programme start | DateTime | RW |
+| holidayProgrammeEnd | operation | Holiday programme end | DateTime | RW |
+| holidayProgrammeInterval | operation | Holiday programme interval in hours (1 - 24 h) | Number:Time | RW |
+| holidayProgrammeActivationTime | operation | Holiday programme activation time in minutes (5 - 300 min) | Number:Time | RW |
+| runOnTimeVhzNhz | unitConfig | Stopping time preheater/afterheater in seconds (60 - 120 s) | Number:Time | RW |
+| errorOutputFunction | unitConfig | Error output function (collective error or just error) (1 = collective error, 2 = only error) | Number | RW |
+| filterChange | unitConfig | Filter change (0 = No, 1 = Yes) | Number | RW |
+| filterChangeInterval | unitConfig | Filter change interval in months (1 - 12) | Number | RW |
+| filterChangeRemainingTime | general | Filter change remaining time in minutes (1 - 55000 min) | Number:Time | R |
+| bypassRoomTemperature | unitConfig | Bypass room temperature in °C (10 - 40 °C) | Number:Temperature | RW |
+| bypassMinOutsideTemperature | unitConfig | Bypass outside temperature in °C (5 - 20 °C) | Number:Temperature | RW |
+| supplyAirFanStage | operation | Supply air fan stage (0 - 4) | Number | RW |
+| extractAirFanStage | operation | Extract air fan stage (0 - 4) | Number | RW |
+| operatingHoursSupplyAirVent | general | Operating hours supply air fan (in minutes) (0 - 2^32-1 min) | Number:Time | R |
+| operatingHoursExtractAirVent | general | Operating hours extract air fan (in minutes) (0 - 2^32-1 min) | Number:Time | R |
+| operatingHoursVhz | general | Operating hours preheater (in minutes) (0 - 2^32-1 min) | Number:Time | R |
+| operatingHoursNhz | general | Operating hours afterheater (in minutes) (0 - 2^32-1 min) | Number:Time | R |
+| outputPowerVhz | general | Output power of preheater (in percent) (0 - 2^32-1 %) | Number:Dimensionless | R |
+| outputPowerNhz | general | Output power of afterheater (in percent) (0 - 2^32-1 %) | Number:Dimensionless | R |
+| errors | general | Errors as integer value (see [Errors / Warnings / Infos](#errors--warnings--infos)) (0 - 2^32-1) | Number | R |
+| warnings | general | Warnings as integer value (see [Errors / Warnings / Infos](#errors--warnings--infos)) (0 - 2^32-1) | Number | R |
+| infos | general | Infos as integer value (see [Errors / Warnings / Infos](#errors--warnings--infos)) (0 - 2^32-1) | Number | R |
+| noOfErrors | general | Number of bit-coded errors (see [Errors / Warnings / Infos](#errors--warnings--infos)) (0 - 32) | Number | R |
+| noOfWarnings | general | Number of bit-coded warnings (see [Errors / Warnings / Infos](#errors--warnings--infos)) (0 - 8) | Number | R |
+| noOfInfos | general | Number of bit-coded infos (see [Errors / Warnings / Infos](#errors--warnings--infos)) (0 - 8) | Number | R |
+| errorsMsg | general | Errors as string (see [Errors / Warnings / Infos](#errors--warnings--infos)) | String | R |
+| warningsMsg | general | Warnings as string (see [Errors / Warnings / Infos](#errors--warnings--infos)) | String | R |
+| infosMsg | general | Infos as string (see [Errors / Warnings / Infos](#errors--warnings--infos)) | String | R |
+| statusFlags | general | Status flags (see [Errors / Warnings / Infos](#errors--warnings--infos)) | String | R |
+| bypassStatus | general | Status of the bypass (OFF = closed, ON = open) | Switch | R |
+| bypassFrom | unitConfig | Bypass active from | DateTime | RW |
+| bypassTo | unitConfig | Bypass active to | DateTime | RW |
## Thing Actions
Resets the timer for the next filter change back to 0.
-```
+```java
public void resetFilterChangeTimer()
```
Resets the error messages.
-```
+```java
public void resetErrors()
```
Resets the device to its factory defaults.
-```
+```java
public void presetToFactoryDefaults()
```
Resets the device's individual switching times back to the default values.
-```
+```java
public void resetSwitchingTimes()
```
-
### Set System Date and Time
Sets the device's system date and time to the openHAB server's system date and time.
-```
+```java
public void setSysDateTime()
```
Sets the devices start and end date for the active bypass functionality.
-```
+```java
public void setBypassFrom(int day, int month)
```
-*Parameters:*
-
-* *day:* The day from when the bypass should be active
-* *month:* The month from when the bypass should be active
+_Parameters:_
+- _day:_ The day from when the bypass should be active
+- _month:_ The month from when the bypass should be active
-```
+```java
public void setBypassTo(int day, int month)
```
-*Parameters:*
-
-* *day:* The day until when the bypass should be active
-* *month:* The month until when the bypass should be active
+_Parameters:_
+- _day:_ The day until when the bypass should be active
+- _month:_ The month until when the bypass should be active
-```
+```java
public Map<String, Object> getErrorMessages()
```
-*Return values:*
-
-* *errorMessages:* A `List<String>` object containing all error messages
+_Return values:_
+- _errorMessages:_ A `List<String>` object containing all error messages
-```
+```java
public Map<String, Object> getWarningMessages()
```
-*Return values:*
+_Return values:_
-* *warningMessages:* A `List<String>` object containing all warning messages
+- _warningMessages:_ A `List<String>` object containing all warning messages
-
-```
+```java
public Map<String, Object> getInfoMessages()
```
-*Return values:*
+_Return values:_
-* *infoMessages:* A `List<String>` object containing all info messages
+- _infoMessages:_ A `List<String>` object containing all info messages
-
-```
+```java
public Map<String, Object> getStatusMessages()
```
-*Return values:*
+_Return values:_
-* *statusMessages:* A `List<String>` object containing all status messages
+- _statusMessages:_ A `List<String>` object containing all status messages
-
-```
+```java
public Map<String, Object> getMessages()
```
-*Return values:*
-
-* *errorMessages:* A `List<String>` object containing all error messages
-* *warningMessages:* A `List<String>` object containing all warning messages
-* *infoMessages:* A `List<String>` object containing all info messages
-* *statusMessages:* A `List<String>` object containing all status messages
+_Return values:_
+- _errorMessages:_ A `List<String>` object containing all error messages
+- _warningMessages:_ A `List<String>` object containing all warning messages
+- _infoMessages:_ A `List<String>` object containing all info messages
+- _statusMessages:_ A `List<String>` object containing all status messages
## Properties
The binding provides the following properties:
-| Property | Description |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| articleDescription | The KWL's article description |
-| refNo | The KWL's reference number |
-| macAddress | The KWL's MAC Address |
-| language | The KWL user interface's language (de, en, fr, hr, hu, it, pl, sk, sl) |
-| voltageFanStage1ExtractAir | Voltage of extract air fan mapped to fan stage 1 (1.6 - 10 V) |
-| voltageFanStage2ExtractAir | Voltage of extract air fan mapped to fan stage 2 (1.6 - 10 V) |
-| voltageFanStage3ExtractAir | Voltage of extract air fan mapped to fan stage 3 (1.6 - 10 V) |
-| voltageFanStage4ExtractAir | Voltage of extract air fan mapped to fan stage 4 (1.6 - 10 V) |
-| voltageFanStage1SupplyAir | Voltage of supply air fan mapped to fan stage 1 (1.6 - 10 V) |
-| voltageFanStage2SupplyAir | Voltage of supply air fan mapped to fan stage 2 (1.6 - 10 V) |
-| voltageFanStage3SupplyAir | Voltage of supply air fan mapped to fan stage 3 (1.6 - 10 V) |
-| voltageFanStage4SupplyAir | Voltage of supply air fan mapped to fan stage 4 (1.6 - 10 V) |
-| kwlBe | Slide switch controller KWL-BE activated |
-| kwlBec | Comfort controller KWL-BEC activated |
-| unitConfig | Ventilation unit configuration (type of house) (1 = DiBt, 2 = passive-house) |
-| kwlFtfConfig0 | Humidity/temperature sensor configuration 0 (1 = only humidity, 2 = only temperature, 3 = combined) |
-| kwlFtfConfig1 | Humidity/temperature sensor configuration 1 (1 = only humidity, 2 = only temperature, 3 = combined) |
-| kwlFtfConfig2 | Humidity/temperature sensor configuration 2 (1 = only humidity, 2 = only temperature, 3 = combined) |
-| kwlFtfConfig3 | Humidity/temperature sensor configuration 3 (1 = only humidity, 2 = only temperature, 3 = combined) |
-| kwlFtfConfig4 | Humidity/temperature sensor configuration 4 (1 = only humidity, 2 = only temperature, 3 = combined) |
-| kwlFtfConfig5 | Humidity/temperature sensor configuration 5 (1 = only humidity, 2 = only temperature, 3 = combined) |
-| kwlFtfConfig6 | Humidity/temperature sensor configuration 6 (1 = only humidity, 2 = only temperature, 3 = combined) |
-| kwlFtfConfig7 | Humidity/temperature sensor configuration 7 (1 = only humidity, 2 = only temperature, 3 = combined) |
-| humidityControlStatus | Humidity control status (0 = off, 1 = stepped, 2 = stepless) |
-| co2ControlStatus | CO2 control status (0 = off, 1 = stepped, 2 = stepless) |
-| vocControlStatus | VOC control status (0 = off, 1 = stepped, 2 = stepless) |
-| dateFormat | Date format (0 = dd.mm.yyyy, 1 = mm.dd.yyyy, 2 = yyyy.mm.dd) |
-| heatExchangerType | Heat exchanger type (1 = plastic, 2 = aluminium, 3 = enthalpy) |
-| serNo | Serial number |
-| prodCode | Production Code |
-| vhzType | Pre-heater type (1 = EH-Basis, 2 EH-ERW, 3 = SEWT, 4 = LEWT) |
-| functionTypeKwlEm | Function KWL-EM (1 = function 1, 2 = function 2) |
-| externalContact | External contact (1 -6 (function 1-6)) |
-| fanStageStepped0to2v | Fan stage for stepped mode - range 0-2V (0 - 2) |
-| fanStageStepped2to4v | Fan stage for stepped mode - range 2-4V (0 - 4) |
-| fanStageStepped4to6v | Fan stage for stepped mode - range 4-6V (0 - 4) |
-| fanStageStepped6to8v | Fan stage for stepped mode - range 6-8V (0 - 4) |
-| fanStageStepped8to10v | Fan stage for stepped mode - range 8-10V (0 - 4) |
-| offsetExtractAir | Offset extract air (float) |
-| assignmentFanStages | Assignment fan stages - stepped or 0-10V (OFF = 0-10V, ON = stepped) |
-| sensorNameHumidityAndTemp1 | Sensor name - humidity and temperature 1 |
-| sensorNameHumidityAndTemp2 | Sensor name - humidity and temperature 2 |
-| sensorNameHumidityAndTemp3 | Sensor name - humidity and temperature 3 |
-| sensorNameHumidityAndTemp4 | Sensor name - humidity and temperature 4 |
-| sensorNameHumidityAndTemp5 | Sensor name - humidity and temperature 5 |
-| sensorNameHumidityAndTemp6 | Sensor name - humidity and temperature 6 |
-| sensorNameHumidityAndTemp7 | Sensor name - humidity and temperature 7 |
-| sensorNameHumidityAndTemp8 | Sensor name - humidity and temperature 8 |
-| sensorNameCo21 | Sensor name - CO2 1 |
-| sensorNameCo22 | Sensor name - CO2 2 |
-| sensorNameCo23 | Sensor name - CO2 3 |
-| sensorNameCo24 | Sensor name - CO2 4 |
-| sensorNameCo25 | Sensor name - CO2 5 |
-| sensorNameCo26 | Sensor name - CO2 6 |
-| sensorNameCo27 | Sensor name - CO2 7 |
-| sensorNameCo28 | Sensor name - CO2 8 |
-| sensorNameVoc1 | Sensor name - VOC 1 |
-| sensorNameVoc2 | Sensor name - VOC 2 |
-| sensorNameVoc3 | Sensor name - VOC 3 |
-| sensorNameVoc4 | Sensor name - VOC 4 |
-| sensorNameVoc5 | Sensor name - VOC 5 |
-| sensorNameVoc6 | Sensor name - VOC 6 |
-| sensorNameVoc7 | Sensor name - VOC 7 |
-| sensorNameVoc8 | Sensor name - VOC 8 |
-| softwareVersionBasis | Software version basis (format xx.xx) |
-| sensorConfigKwlFtf1 | Sensor configuration (installed or not) KWL-FTF 1 (OFF = no sensor, ON = sensor installed) |
-| sensorConfigKwlFtf2 | Sensor configuration (installed or not) KWL-FTF 2 (OFF = no sensor, ON = sensor installed) |
-| sensorConfigKwlFtf3 | Sensor configuration (installed or not) KWL-FTF 3 (OFF = no sensor, ON = sensor installed) |
-| sensorConfigKwlFtf4 | Sensor configuration (installed or not) KWL-FTF 4 (OFF = no sensor, ON = sensor installed) |
-| sensorConfigKwlFtf5 | Sensor configuration (installed or not) KWL-FTF 5 (OFF = no sensor, ON = sensor installed) |
-| sensorConfigKwlFtf6 | Sensor configuration (installed or not) KWL-FTF 6 (OFF = no sensor, ON = sensor installed) |
-| sensorConfigKwlFtf7 | Sensor configuration (installed or not) KWL-FTF 7 (OFF = no sensor, ON = sensor installed) |
-| sensorConfigKwlFtf8 | Sensor configuration (installed or not) KWL-FTF 8 (OFF = no sensor, ON = sensor installed) |
-
+| Property | Description |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| articleDescription | The KWL's article description |
+| refNo | The KWL's reference number |
+| macAddress | The KWL's MAC Address |
+| language | The KWL user interface's language (de, en, fr, hr, hu, it, pl, sk, sl) |
+| voltageFanStage1ExtractAir | Voltage of extract air fan mapped to fan stage 1 (1.6 - 10 V) |
+| voltageFanStage2ExtractAir | Voltage of extract air fan mapped to fan stage 2 (1.6 - 10 V) |
+| voltageFanStage3ExtractAir | Voltage of extract air fan mapped to fan stage 3 (1.6 - 10 V) |
+| voltageFanStage4ExtractAir | Voltage of extract air fan mapped to fan stage 4 (1.6 - 10 V) |
+| voltageFanStage1SupplyAir | Voltage of supply air fan mapped to fan stage 1 (1.6 - 10 V) |
+| voltageFanStage2SupplyAir | Voltage of supply air fan mapped to fan stage 2 (1.6 - 10 V) |
+| voltageFanStage3SupplyAir | Voltage of supply air fan mapped to fan stage 3 (1.6 - 10 V) |
+| voltageFanStage4SupplyAir | Voltage of supply air fan mapped to fan stage 4 (1.6 - 10 V) |
+| kwlBe | Slide switch controller KWL-BE activated |
+| kwlBec | Comfort controller KWL-BEC activated |
+| unitConfig | Ventilation unit configuration (type of house) (1 = DiBt, 2 = passive-house) |
+| kwlFtfConfig0 | Humidity/temperature sensor configuration 0 (1 = only humidity, 2 = only temperature, 3 = combined) |
+| kwlFtfConfig1 | Humidity/temperature sensor configuration 1 (1 = only humidity, 2 = only temperature, 3 = combined) |
+| kwlFtfConfig2 | Humidity/temperature sensor configuration 2 (1 = only humidity, 2 = only temperature, 3 = combined) |
+| kwlFtfConfig3 | Humidity/temperature sensor configuration 3 (1 = only humidity, 2 = only temperature, 3 = combined) |
+| kwlFtfConfig4 | Humidity/temperature sensor configuration 4 (1 = only humidity, 2 = only temperature, 3 = combined) |
+| kwlFtfConfig5 | Humidity/temperature sensor configuration 5 (1 = only humidity, 2 = only temperature, 3 = combined) |
+| kwlFtfConfig6 | Humidity/temperature sensor configuration 6 (1 = only humidity, 2 = only temperature, 3 = combined) |
+| kwlFtfConfig7 | Humidity/temperature sensor configuration 7 (1 = only humidity, 2 = only temperature, 3 = combined) |
+| humidityControlStatus | Humidity control status (0 = off, 1 = stepped, 2 = stepless) |
+| co2ControlStatus | CO2 control status (0 = off, 1 = stepped, 2 = stepless) |
+| vocControlStatus | VOC control status (0 = off, 1 = stepped, 2 = stepless) |
+| dateFormat | Date format (0 = dd.mm.yyyy, 1 = mm.dd.yyyy, 2 = yyyy.mm.dd) |
+| heatExchangerType | Heat exchanger type (1 = plastic, 2 = aluminium, 3 = enthalpy) |
+| serNo | Serial number |
+| prodCode | Production Code |
+| vhzType | Pre-heater type (1 = EH-Basis, 2 EH-ERW, 3 = SEWT, 4 = LEWT) |
+| functionTypeKwlEm | Function KWL-EM (1 = function 1, 2 = function 2) |
+| externalContact | External contact (1 -6 (function 1-6)) |
+| fanStageStepped0to2v | Fan stage for stepped mode - range 0-2V (0 - 2) |
+| fanStageStepped2to4v | Fan stage for stepped mode - range 2-4V (0 - 4) |
+| fanStageStepped4to6v | Fan stage for stepped mode - range 4-6V (0 - 4) |
+| fanStageStepped6to8v | Fan stage for stepped mode - range 6-8V (0 - 4) |
+| fanStageStepped8to10v | Fan stage for stepped mode - range 8-10V (0 - 4) |
+| offsetExtractAir | Offset extract air (float) |
+| assignmentFanStages | Assignment fan stages - stepped or 0-10V (OFF = 0-10V, ON = stepped) |
+| sensorNameHumidityAndTemp1 | Sensor name - humidity and temperature 1 |
+| sensorNameHumidityAndTemp2 | Sensor name - humidity and temperature 2 |
+| sensorNameHumidityAndTemp3 | Sensor name - humidity and temperature 3 |
+| sensorNameHumidityAndTemp4 | Sensor name - humidity and temperature 4 |
+| sensorNameHumidityAndTemp5 | Sensor name - humidity and temperature 5 |
+| sensorNameHumidityAndTemp6 | Sensor name - humidity and temperature 6 |
+| sensorNameHumidityAndTemp7 | Sensor name - humidity and temperature 7 |
+| sensorNameHumidityAndTemp8 | Sensor name - humidity and temperature 8 |
+| sensorNameCo21 | Sensor name - CO2 1 |
+| sensorNameCo22 | Sensor name - CO2 2 |
+| sensorNameCo23 | Sensor name - CO2 3 |
+| sensorNameCo24 | Sensor name - CO2 4 |
+| sensorNameCo25 | Sensor name - CO2 5 |
+| sensorNameCo26 | Sensor name - CO2 6 |
+| sensorNameCo27 | Sensor name - CO2 7 |
+| sensorNameCo28 | Sensor name - CO2 8 |
+| sensorNameVoc1 | Sensor name - VOC 1 |
+| sensorNameVoc2 | Sensor name - VOC 2 |
+| sensorNameVoc3 | Sensor name - VOC 3 |
+| sensorNameVoc4 | Sensor name - VOC 4 |
+| sensorNameVoc5 | Sensor name - VOC 5 |
+| sensorNameVoc6 | Sensor name - VOC 6 |
+| sensorNameVoc7 | Sensor name - VOC 7 |
+| sensorNameVoc8 | Sensor name - VOC 8 |
+| softwareVersionBasis | Software version basis (format xx.xx) |
+| sensorConfigKwlFtf1 | Sensor configuration (installed or not) KWL-FTF 1 (OFF = no sensor, ON = sensor installed) |
+| sensorConfigKwlFtf2 | Sensor configuration (installed or not) KWL-FTF 2 (OFF = no sensor, ON = sensor installed) |
+| sensorConfigKwlFtf3 | Sensor configuration (installed or not) KWL-FTF 3 (OFF = no sensor, ON = sensor installed) |
+| sensorConfigKwlFtf4 | Sensor configuration (installed or not) KWL-FTF 4 (OFF = no sensor, ON = sensor installed) |
+| sensorConfigKwlFtf5 | Sensor configuration (installed or not) KWL-FTF 5 (OFF = no sensor, ON = sensor installed) |
+| sensorConfigKwlFtf6 | Sensor configuration (installed or not) KWL-FTF 6 (OFF = no sensor, ON = sensor installed) |
+| sensorConfigKwlFtf7 | Sensor configuration (installed or not) KWL-FTF 7 (OFF = no sensor, ON = sensor installed) |
+| sensorConfigKwlFtf8 | Sensor configuration (installed or not) KWL-FTF 8 (OFF = no sensor, ON = sensor installed) |
## Errors / Warnings / Infos
Based on that concept, errors, warnings and infos are provided in 3 different ways:
-* As an unsigned integer value with the decimal representation of the encoded bits
-* The total number of encoded errors, warning or infos
-* The bit encoded as a string
+- As an unsigned integer value with the decimal representation of the encoded bits
+- The total number of encoded errors, warning or infos
+- The bit encoded as a string
Since there can potentially be several errors, warnings or infos, using a simple MAP to display the corresponding message in a UI will not work in all cases. String items with multiple lines will not display properly in the UIs.
Therefore the binding provides actions to retrieve the different messages as an `ArrayList<String>` object which can then be used to e.g. send the messages via email.
-
## Full Example
### Thing Configuration
-```
+```java
Bridge modbus:tcp:modbus-gateway "Modbus TCP/IP Gateway" [ host="192.168.47.11", port=502, id=180, enableDiscovery=true ] {
Thing helios-easycontrols kwl "KWL"
}
### Item Configuration
-```
+```java
// Manual operation
Number KWL_Manual "Manual operation" <fan> (gKWL) ["Control"] {channel="modbus:helios-easycontrols:modbus-gateway:kwl:operation#operatingMode"}
Number KWL_Stage "KWL fan stage" <fan> (gKWL) ["Setpoint", "Level"] {channel="modbus:helios-easycontrols:modbus-gateway:kwl:operation#fanStage"}
### Rule
-```
+```java
import java.util.List
import java.util.Map
### Transformation
-```
+```text
0=no
1=yes
OFF=no
### Sitemap
-```
+```perl
Text label="KWL" icon="fan" {
Frame label="Manual operation" {
Selection item=KWL_Manual mappings=[0=Auto, 1=Manual]
One of the following serial settings need to be configured in the Bridge:
-- 9600 baud, 2 stop bit, no parity
+- 9600 baud, 2 stop bit, no parity
- 9600 baud, 1 stop bit, even parity
- 9600 baud, 1 stop bit, odd parity
### .items
-```
+```java
Number:Energy ALD1_Total_Energy "[%.2f %unit%]" {channel="modbus:ald1Bidirectional:8b6e85623b:total_energy"}
Number:Energy ALD1_Feeding_Back_Energy "[%.2f %unit%]" {channel="modbus:ald1Bidirectional:8b6e85623b:feeding_back_energy"}
Number:ElectricPotential ALD1_Voltage "[%d %unit%]" {channel="modbus:ald1Bidirectional:8b6e85623b:voltage"}
### .sitemap
-```
+```perl
sitemap ald1 label="ALD1 Energy Meter"
{
Default item=ALD1_Total_Energy label="Total Energy"
This extension adds support for the Stiebel Eltron modbus protocol.
-An Internet Service Gateway (ISG) with an installed modbus extension is required in order to run this binding.
-In case the modbus extension is not yet installed on the ISG, the ISG Updater Tool for the update can be found here: https://www.stiebel-eltron.de/de/home/produkte-loesungen/erneuerbare_energien/regelung_energiemanagement/internet_servicegateway/isg_web/downloads.html
+An Internet Service Gateway (ISG) with an installed modbus extension is required in order to run this binding.
+In case the modbus extension is not yet installed on the ISG, the ISG Updater Tool for the update can be found here: <https://www.stiebel-eltron.de/de/home/produkte-loesungen/erneuerbare_energien/regelung_energiemanagement/internet_servicegateway/isg_web/downloads.html>
## Supported Things
A typical bridge configuration would look like this:
-```
+```java
Bridge modbus:tcp:bridge [ host="10.0.0.2", port=502, id=1 ]
```
| is-pumping | Contact | true | OPEN in case the heat pump is currently in pumping mode |
| is-summer | Contact | true | OPEN in case the heat pump is currently in summer mode |
-### System Parameters Group
+### System Parameters Group
This group contains system paramters of the heat pump.
| comfort-temperature-water | Number:Temperature | false | The current water comfort temperature |
| eco-temperature-water | Number:Temperature | false | The current water eco temperature |
-### System Information Group
+### System Information Group
This group contains general operational information about the device.
| water-temperature | Number:Temperature | true | The current water temperature |
| water-temperature-setpoint | Number:Temperature | true | The current water temperature set point |
-### Energy Information Group
+### Energy Information Group
This group contains about the energy consumption and delivery of the heat pump.
### Thing Configuration
-```
+```java
Bridge modbus:tcp:bridge "Stiebel Modbus TCP"[ host="hostname|ip", port=502, id=1 ] {
- Thing heatpump stiebelEltron "StiebelEltron" (modbus:tcp:modbusbridge) @"Room" [ ]
+ Thing heatpump stiebelEltron "StiebelEltron" (modbus:tcp:modbusbridge) @"Room" [ ]
}
```
### Item Configuration
-```
+```java
Number:Temperature stiebel_eltron_temperature_ffk "Temperature FFK [%.1f °C]" <temperature> { channel="modbus:heatpump:stiebelEltron:systemInformation#fek-temperature" }
Number:Temperature stiebel_eltron_setpoint_ffk "Set point FFK [%.1f °C]" <temperature> { channel="modbus:heatpump:stiebelEltron:systemInformation#fek-temperature-setpoint" }
Number:Dimensionless stiebel_eltron_humidity_ffk "Humidity FFK [%.1f %%]" <humidity> { channel="modbus:heatpump:stiebelEltron:systemInformation#fek-humidity" }
### Sitemap Configuration
-```
- Text label="Heat pumpt" icon="temperature" {
- Frame label="Optation Mode" {
- Default item=stiebel_eltron_mode_pump
- Default item=stiebel_eltron_mode_heating
- Default item=stiebel_eltron_mode_water
- Default item=stiebel_eltron_mode_cooling
- Default item=stiebel_eltron_mode_summer
- }
- Frame label= "State" {
- Default item=stiebel_eltron_operation_mode icon="settings"
- Default item=stiebel_eltron_outdoor_temp icon="temperature"
- Default item=stiebel_eltron_temp_hk1 icon="temperature"
- Default item=stiebel_eltron_setpoint_hk1 icon="temperature"
- Default item=stiebel_eltron_vorlauf_temp icon="temperature"
- Default item=stiebel_eltron_ruecklauf_temp icon="temperature"
- Default item=stiebel_eltron_temp_water icon="temperature"
- Default item=stiebel_eltron_setpoint_water icon="temperature"
- Default item=stiebel_eltron_temperature_ffk icon="temperature"
- Default item=stiebel_eltron_setpoint_ffk icon="temperature"
- Default item=stiebel_eltron_humidity_ffk icon="humidity"
- Default item=stiebel_eltron_dewpoint_ffk icon="temperature"
- Default item=stiebel_eltron_source_temp icon="temperature"
- }
- Frame label="Paramters" {
- Setpoint item=stiebel_eltron_heating_comfort_temp icon="temperature" step=1 minValue=5 maxValue=30
- Setpoint item=stiebel_eltron_heating_eco_temp icon="temperature" step=1 minValue=5 maxValue=30
- Setpoint item=stiebel_eltron_water_comfort_temp icon="temperature" step=1 minValue=10 maxValue=60
- Setpoint item=stiebel_eltron_water_eco_temp icon="temperature" step=1 minValue=10 maxValue=60
- }
- Frame label="Energy consumption" {
- Default item=stiebel_eltron_consumption_heat_today icon="energy"
- Default item=stiebel_eltron_consumption_heat_total icon="energy"
- Default item=stiebel_eltron_consumption_water_today icon="energy"
- Default item=stiebel_eltron_consumption_water_total icon="energy"
- }
- Frame label="Heat quantity" {
- Default item=stiebel_eltron_production_heat_today icon="radiator"
- Default item=stiebel_eltron_production_heat_total icon="radiator"
- Default item=stiebel_eltron_production_water_today icon="water"
- Default item=stiebel_eltron_production_water_total icon="water"
- }
-
- }
+```perl
+Text label="Heat pumpt" icon="temperature" {
+ Frame label="Optation Mode" {
+ Default item=stiebel_eltron_mode_pump
+ Default item=stiebel_eltron_mode_heating
+ Default item=stiebel_eltron_mode_water
+ Default item=stiebel_eltron_mode_cooling
+ Default item=stiebel_eltron_mode_summer
+ }
+ Frame label= "State" {
+ Default item=stiebel_eltron_operation_mode icon="settings"
+ Default item=stiebel_eltron_outdoor_temp icon="temperature"
+ Default item=stiebel_eltron_temp_hk1 icon="temperature"
+ Default item=stiebel_eltron_setpoint_hk1 icon="temperature"
+ Default item=stiebel_eltron_vorlauf_temp icon="temperature"
+ Default item=stiebel_eltron_ruecklauf_temp icon="temperature"
+ Default item=stiebel_eltron_temp_water icon="temperature"
+ Default item=stiebel_eltron_setpoint_water icon="temperature"
+ Default item=stiebel_eltron_temperature_ffk icon="temperature"
+ Default item=stiebel_eltron_setpoint_ffk icon="temperature"
+ Default item=stiebel_eltron_humidity_ffk icon="humidity"
+ Default item=stiebel_eltron_dewpoint_ffk icon="temperature"
+ Default item=stiebel_eltron_source_temp icon="temperature"
+ }
+ Frame label="Paramters" {
+ Setpoint item=stiebel_eltron_heating_comfort_temp icon="temperature" step=1 minValue=5 maxValue=30
+ Setpoint item=stiebel_eltron_heating_eco_temp icon="temperature" step=1 minValue=5 maxValue=30
+ Setpoint item=stiebel_eltron_water_comfort_temp icon="temperature" step=1 minValue=10 maxValue=60
+ Setpoint item=stiebel_eltron_water_eco_temp icon="temperature" step=1 minValue=10 maxValue=60
+ }
+ Frame label="Energy consumption" {
+ Default item=stiebel_eltron_consumption_heat_today icon="energy"
+ Default item=stiebel_eltron_consumption_heat_total icon="energy"
+ Default item=stiebel_eltron_consumption_water_today icon="energy"
+ Default item=stiebel_eltron_consumption_water_total icon="energy"
+ }
+ Frame label="Heat quantity" {
+ Default item=stiebel_eltron_production_heat_today icon="radiator"
+ Default item=stiebel_eltron_production_heat_total icon="radiator"
+ Default item=stiebel_eltron_production_water_today icon="water"
+ Default item=stiebel_eltron_production_water_total icon="water"
+ }
+
+}
```
This extension adds support for the Studer protocol.
-Studer Innotec, founded in 1987 by Roland Studer, is an ISO certified company that develops and manufactures inverters, inverter/chargers and MPPT solar charge controllers to communicate over the Modbus protocol entirely in Switzerland
+Studer Innotec, founded in 1987 by Roland Studer, is an ISO certified company that develops and manufactures inverters, inverter/chargers and MPPT solar charge controllers to communicate over the Modbus protocol entirely in Switzerland
-For a list of certified products see this page: https://www.studer-innotec.com/
+For a list of certified products see this page: <https://www.studer-innotec.com/>
## Supported Things
| variotrack | For the VarioTrack models of MPPT solar charge controllers for systems with solar PV capacity from 1 - 75kWp |  |
| variostring | For the VarioString models of MPPT solar charge controllers for systems with solar PV capacity from 4 |  |
-
## Thing Configuration
You need first to set up a Serial Modbus bridge according to the Modbus documentation.
Multicast writes on any devices of given class, but reads only on the first available device (Not Summary!). As currently there are no writes available, 10/20/40 is useless for now.
-
The following parameters are valid for all thing types:
| Parameter | Type | Required | Default if omitted | Description |
The following Channels, and their associated channel types are shown below divided by device.
-#### BSP
+### BSP
All channels read for a BSP device
| stateOfCharge | Number:Dimensionless | State of Charge |
| batteryTemperature | Number:Temperature | Battery temperature |
-#### Xtender
+### Xtender
All channels read for a Xtender device
| operatingState | String | Operating state |
| stateInverter | String | State of the inverter |
-#### VarioTrack
+### VarioTrack
All channels read for a VarioTrack device
| operatingMode | String | Operating mode |
| stateVarioTrack | String | State of the VarioTrack |
-#### VarioString
+### VarioString
All channels read for a VarioString device
### Thing Configuration
-```
+```java
Bridge modbus:serial:bridge [port="/dev/ttyUSB0",baud=9600,dataBits=8,parity="even",stopBits="1.0",encoding="rtu"]
..or..
Bridge modbus:tcp:bridge [host="192.168.178.56", port=502, rtuEncoded=true]
Thing modbus:bsp:bridge:byd "BydBox" (modbus:serial:modbusbridge) [ slaveAddress=61, refresh=5 ]
```
-
Note: Make sure that refresh and slave address are numerical, without quotes.
### Item Configuration
-```
+```java
Number Studer_Xtender_Phase1_InputVoltage "Input Voltage [%.2f V]" {channel="modbus:xtender:bridge:xtender_Phase1:inputVoltage"}
Number Studer_Xtender_Phase1_InputCurrent "Input Current [%.2f A]" {channel="modbus:xtender:bridge:xtender_Phase1:inputCurrent"}
String Studer_Xtender_Phase1_StateInverter "State: [%s]" {channel="modbus:xtender:bridge:xtender_Phase1:stateInverter"}
### Sitemap Configuration
-```
+```perl
Text item=Studer_Xtender_Phase1_InputVoltage
Text item=Studer_Xtender_Phase1_InputCurrent
Text item=Studer_Xtender_Phase1_StateInverter
-## For Developers
+# For Developers
SunSpec is a big specification with many different type of devices.
If you own or have access to an appliance that is not supported at the moment then your help is welcome.
If you want to extend the bundle yourself, you have to do the followings:
- - Define your thing type, channel types and channel groups according to openHAB development practices.
+- Define your thing type, channel types and channel groups according to openHAB development practices.
You can look at the meter and inverter types to get ideas how you can avoid repeating the same configuration over and over.
-
- - Extend the `AbstractSunSpecHandler` and implement the handlePolledData method.
+
+- Extend the `AbstractSunSpecHandler` and implement the handlePolledData method.
This method will be regularly called with the register data read from the appliance.
The method should parse the data and update the channels with them.
- - The preferred way to parse the raw data is to write a parser for you model block type.
+- The preferred way to parse the raw data is to write a parser for you model block type.
Your class should implement the `SunspecParser` class and it is preferred to extend the `AbstractBaseParser` class.
This base class has methods to accurately extract fields from the register array.
- - The parser should only retrieve the data from the register array and return them in a block descriptor class.
+- The parser should only retrieve the data from the register array and return them in a block descriptor class.
Scaling and other higher level transformation should be done by the handler itself.
-
- - To include your block type in auto discovery you have to add its id to the `SUPPORTED_THING_TYPES_UIDS` map in `SunSpecConstants`. This is enough for our discovery process to include your thing type in the results.
+
+- To include your block type in auto discovery you have to add its id to the `SUPPORTED_THING_TYPES_UIDS` map in `SunSpecConstants`. This is enough for our discovery process to include your thing type in the results.
It defines how common parameters like AC/DC voltage and current, lifetime produced energy, device temperature etc can be read from the device.
SunSpec is supported by several manufacturers like ABB, Fronius, LG, SMA, SolarEdge, Schneider Electric.
-For a list of certified products see this page: https://sunspec.org/sunspec-certified-products/
+For a list of certified products see this page: <https://sunspec.org/sunspec-certified-products/>
## Supported Things
A typical bridge configuration would look like this:
-```
+```java
Bridge modbus:tcp:modbusBridgeName [ host="10.0.0.2", port=502, id=1, enableDiscovery=true ]
```
### Thing Configuration
-```
+```java
Bridge modbus:tcp:modbusBridgeName [ host="hostname|ip", port=502, id=1, enableDiscovery=true ]
Thing modbus:inverter-single-phase:bridge:myInverter "SE4000h" (modbus:tcp:modbusBridgeName) [ address=40069, length=52, refresh=15 ]
```
### Item Configuration
-```
+```java
Number Inverter_Temperature "Temperature [%.1f C]" {channel="modbus:inverter-single-phase:bridge:se4000h:deviceInformation#heatsink-temperature"}
Number Inverter_AC_Power "AC Power [%d W]" {channel="modbus:inverter-single-phase:bridge:se4000h:acGeneral#ac-power"}
### Sitemap Configuration
-```
- Text item=Inverter_Temperature
- Text item=Inverter_AC_Current
- Text item=Inverter_AC_Power
- Chart item=Inverter_Temperature period=D refresh=600000
- Chart item=Inverter_AC_Power period=D refresh=30000
+```perl
+Text item=Inverter_Temperature
+Text item=Inverter_AC_Current
+Text item=Inverter_AC_Power
+Chart item=Inverter_Temperature period=D refresh=600000
+Chart item=Inverter_AC_Power period=D refresh=30000
```
### SolarEdge
Newer models of SolarEdge inverters can be monitored over TCP, but you need to enable support in the inverter first.
-Refer to the "Modbus over TCP Configuration" chapter in this documentation: https://www.solaredge.com/sites/default/files/sunspec-implementation-technical-note.pdf
+Refer to the "Modbus over TCP Configuration" chapter in this documentation: <https://www.solaredge.com/sites/default/files/sunspec-implementation-technical-note.pdf>
Modbus connection is limited to a single client at a time, so make sure no other clients are using the port.
## Debugging an addon
-Please follow IDE setup guide at https://www.openhab.org/docs/developer/ide/eclipse.html.
+Please follow IDE setup guide at <https://www.openhab.org/docs/developer/ide/eclipse.html>.
When configuring dependencies in `openhab-distro/launch/app/pom.xml`, add all dependencies, including the transitive dependencies:
You can use test serial slaves without any hardware on Linux using these steps:
1. Set-up virtual null modem emulator using [tty0tty](https://github.com/freemed/tty0tty)
-2. Download [diagslave](https://www.modbusdriver.com/diagslave.html) and start modbus serial slave up using this command:
+1. Download [diagslave](https://www.modbusdriver.com/diagslave.html) and start modbus serial slave up using this command:
-```
+```shell
./diagslave -m rtu -a 1 -b 38400 -d 8 -s 1 -p none -4 10 /dev/pts/7
```
-3. Configure openHAB's modbus slave to connect to `/dev/pts/8`.
+1. Configure openHAB's modbus slave to connect to `/dev/pts/8`.
-4. Modify `start.sh` or `start_debug.sh` to include the unconventional port name by adding the following argument to `java`:
+1. Modify `start.sh` or `start_debug.sh` to include the unconventional port name by adding the following argument to `java`:
-```
+```text
-Dgnu.io.rxtx.SerialPorts=/dev/pts/8
```
1. Download [diagslave](https://www.modbusdriver.com/diagslave.html) and start modbus tcp server (slave) using this command:
-```
-./diagslave -m tcp -a 1 -p 55502
-```
-
-2. Configure openHAB's modbus slave to connect to `127.0.0.1:55502`.
+ ```shell
+ ./diagslave -m tcp -a 1 -p 55502
+ ```
+1. Configure openHAB's modbus slave to connect to `127.0.0.1:55502`.
## Writing Data
You can also use `modpoll` to write data:
-
-```bash
+```shell
# write value=5 to holding register 40001 (index=0 in the binding)
./modpoll -m tcp -a 1 -r 1 -t4 -p 502 127.0.0.1 5
# set coil 00001 (index=0 in the binding) to TRUE
There are two methods you have to implement:
- - `getSupportedThingTypeUIDs` should return a list of the thing type UIDs that are supported by this discovery participant. This is fairly straightforward.
-
- - `startDiscovery` method will be called when a discovery process has began. This method receives two parameters:
-
- - `ModbusEndpointThingHandler` is the endpoint's handler that should be tested if it is known by your bundle. You can start your read requests against this handler.
-
- - `ModbusDiscoveryListener` this listener instance should be used to report any known devices found and to notify the main discovery process when your binding has finished the discovery.
-
+- `getSupportedThingTypeUIDs` should return a list of the thing type UIDs that are supported by this discovery participant. This is fairly straightforward.
+
+- `startDiscovery` method will be called when a discovery process has began. This method receives two parameters:
+
+ - `ModbusEndpointThingHandler` is the endpoint's handler that should be tested if it is known by your bundle. You can start your read requests against this handler.
+
+ - `ModbusDiscoveryListener` this listener instance should be used to report any known devices found and to notify the main discovery process when your binding has finished the discovery.
+
Please try to avoid write requests to the endpoint because it could be some unknown device that write requests could misconfigure.
When a known device is found a `DiscoveryResult` object has to be created then the `thingDiscovered` method has to be called.
When the discovery process is finished either by detecting a device or by realizing it is not supported you should call the `discoveryFinished` method.
This will tear down any resources allocated for the discovery process.
-
### Discovery Architecture
The following diagram shows the concept how discovery is implemented in this binding. (Note that some intermediate classes and interfaces are not shown for clarity.)
The binding can act as
-* Modbus TCP Client (that is, as modbus master), querying data from Modbus TCP servers (that is, modbus slaves)
-* Modbus serial master, querying data from modbus serial slaves
+- Modbus TCP Client (that is, as modbus master), querying data from Modbus TCP servers (that is, modbus slaves)
+- Modbus serial master, querying data from modbus serial slaves
The Modbus binding polls the slave data with a configurable poll period.
openHAB commands are translated to write requests.
- TOC
{:toc}
-
-
## Main Features
-The binding polls (or *reads*) Modbus data using function codes (FC) FC01 (Read coils), FC02 (Read discrete inputs), FC03 (Read multiple holding registers) or FC04 (Read input registers).
+The binding polls (or _reads_) Modbus data using function codes (FC) FC01 (Read coils), FC02 (Read discrete inputs), FC03 (Read multiple holding registers) or FC04 (Read input registers).
This polled data is converted to data suitable for use in openHAB.
Functionality exists to interpret typical number formats (e.g. single precision float).
-The binding can also *write* data to Modbus slaves using FC05 (Write single coil), FC06 (Write single holding register), FC15 (Write multiple coils) or FC16 (Write multiple holding registers).
+The binding can also _write_ data to Modbus slaves using FC05 (Write single coil), FC06 (Write single holding register), FC15 (Write multiple coils) or FC16 (Write multiple holding registers).
## Caveats And Limitations
Please note the following caveats or limitations
-* The binding does *not* act as Modbus slave (e.g. as Modbus TCP server).
-* The binding *does* support Modbus RTU over Modbus TCP, (also known as "Modbus over TCP/IP" or "Modbus over TCP" or "Modbus RTU/IP"), as well as normal "Modbus TCP".
-
+- The binding does _not_ act as Modbus slave (e.g. as Modbus TCP server).
+- The binding _does_ support Modbus RTU over Modbus TCP, (also known as "Modbus over TCP/IP" or "Modbus over TCP" or "Modbus RTU/IP"), as well as normal "Modbus TCP".
## Background Material
Reader of the documentation should understand the basics of Modbus protocol.
Good sources for further information:
-* [Wikipedia article](https://en.wikipedia.org/wiki/Modbus): good read on modbus basics and addressing.
-* [Simplymodbus.ca](https://www.simplymodbus.ca/): good reference as well as excellent tutorial like explanation of the protocol
+- [Wikipedia article](https://en.wikipedia.org/wiki/Modbus): good read on modbus basics and addressing.
+- [Simplymodbus.ca](https://www.simplymodbus.ca/): good reference as well as excellent tutorial like explanation of the protocol
Useful tools
-* [binaryconvert.com](https://www.binaryconvert.com/): tool to convert numbers between different binary presentations
-* [rapidscada.net Modbus parser](https://modbus.rapidscada.net/): tool to parse Modbus requests and responses. Useful for debugging purposes when you want to understand the message sent / received.
-* [JSFiddle tool](https://jsfiddle.net/rgypuuxq/) to test JavaScript (JS) transformations interactively
+- [binaryconvert.com](https://www.binaryconvert.com/): tool to convert numbers between different binary presentations
+- [rapidscada.net Modbus parser](https://modbus.rapidscada.net/): tool to parse Modbus requests and responses. Useful for debugging purposes when you want to understand the message sent / received.
+- [JSFiddle tool](https://jsfiddle.net/rgypuuxq/) to test JavaScript (JS) transformations interactively
## Supported Things
Some examples:
-* `parameter="value"` for `text` parameters
-* `parameter=4` for `integer`
-* `parameter=true` for `boolean`
+- `parameter="value"` for `text` parameters
+- `parameter=4` for `integer`
+- `parameter=true` for `boolean`
Note the differences with quoting.
-Required parameters *must* be specified in the `.things` file.
+Required parameters _must_ be specified in the `.things` file.
When optional parameters are not specified, they default to the values shown in the table below.
### `tcp` Thing
Only the `data` thing has channels.
It has several "data channels", serving the polled data in different formats, and for accepting openHAB commands from different item types.
-Please note that transformations might be *necessary* in order to update some data channels, or to convert some openHAB commands to suitable Modbus data.
+Please note that transformations might be _necessary_ in order to update some data channels, or to convert some openHAB commands to suitable Modbus data.
See [Transformations](#transformations) for more details.
| Channel Type ID | Item Type | Description |
| --------------- | --------------- | ----------------------------------- |
| `number` | `Number` | Data as number |
| `switch` | `Switch` | Data as switch (`ON` / `OFF`) |
-| `contact` | `Contact ` | Data as contact (`OPEN` / `CLOSED`) |
+| `contact` | `Contact` | Data as contact (`OPEN` / `CLOSED`) |
| `dimmer` | `Dimmer` | Data as dimmer |
| `datetime` | `DateTime` | Data as a date time |
| `string` | `String` | Data as string |
For example, in the following example, item `Temperature_Modbus_Livingroom` is bound to channel `number` of thing `modbus:data:siemensplc:holding:livingroom_temperature`.
-```bash
+```java
Number Temperature_Modbus_Livingroom "Temperature Living room [%.1f °C]" <temperature> { channel="modbus:data:siemensplc:holding:livingroom_temperature:number" }
```
Let's go through it step by step
-
```java
// openHAB UI switch changed command is sent
1 [ome.event.ItemCommandEvent] - Item 'Kitchen_Bar_Table_Light' received command ON
Item state has no "fluctuation", it updates from `OFF` to `ON`.
To summarize (credits to [rossko57's community post](https://community.openhab.org/t/rule-to-postupdate-an-item-works-but-item-falls-back-after-some-seconds/19986/2?u=ssalonen)):
-* `autoupdate="false"`: monitor the _actual_ state of device
-* `autoupdate="true"`: (or defaulted) allows faster display of the _expected_ state in a sitemap
+
+- `autoupdate="false"`: monitor the _actual_ state of device
+- `autoupdate="true"`: (or defaulted) allows faster display of the _expected_ state in a sitemap
You can disable `autoupdate` as follows:
-```bash
+```java
Number Temperature_Modbus_Livingroom "Temperature Living room [%.1f °C]" <temperature> { channel="modbus:data:siemensplc:holding:livingroom_temperature:number", autoupdate="false" }
```
When applying command, the calculation goes in reverse.
See examples for concrete use case with value scaling.
+
### Discovery
Device specific modbus bindings can take part in the discovery of things, and detect devices automatically. The discovery is initiated by the `tcp` and `serial` bridges when they have `enableDiscovery` setting enabled.
[Modbus Wikipedia article](https://en.wikipedia.org/wiki/Modbus#Coil.2C_discrete_input.2C_input_register.2C_holding_register_numbers_and_addresses) summarizes this excellently:
> In the traditional standard, [entity] numbers for those entities start with a digit, followed by a number of four digits in range 1–9,999:
-
-> * coils numbers start with a zero and then span from 00001 to 09999
-> * discrete input numbers start with a one and then span from 10001 to 19999
-> * input register numbers start with a three and then span from 30001 to 39999
-> * holding register numbers start with a four and then span from 40001 to 49999
+>
+> - coils numbers start with a zero and then span from 00001 to 09999
+> - discrete input numbers start with a one and then span from 10001 to 19999
+> - input register numbers start with a three and then span from 30001 to 39999
+> - holding register numbers start with a four and then span from 40001 to 49999
>
> This translates into [entity] addresses between 0 and 9,998 in data frames.
If you get strange values using the `int32`, `uint32`, `float32`, `int64`, or `uint64` valuetypes then just try the `int32_swap`, `uint32_swap`, `float32_swap`, `int64_swap`, or `uint64_swap` valuetype, depending upon what your data type is.
-
#### `int32_swap`:
- registers `index` and `(index + 1)` are interpreted as signed 32bit integer
1. Command is converted to string (e.g. `"3.14"`) and passed to the transformation.
Note that in case `readTransform="default"`, a default transformation provided by the binding is used.
See [Transformations](#transformations) section for more details.
-3. We try to convert transformation output to number (`DecimalType`), `OPEN`/`CLOSED` (`OpenClosedType`), and `ON`/`OFF` (`OnOffType`); in this order.
+1. We try to convert transformation output to number (`DecimalType`), `OPEN`/`CLOSED` (`OpenClosedType`), and `ON`/`OFF` (`OnOffType`); in this order.
First successful conversion is stored.
For example, `"3.14"` would convert to number (`DecimalType`), while `"CLOSED"` would convert to `CLOSED` (of `OpenClosedType`).'
In case all conversions fail, the command is discarded and nothing is written to the Modbus slave.
-5. Next step depends on the `writeType`:
- * `writeType="coil"`: the command from the transformation is converted to boolean.
+1. Next step depends on the `writeType`:
+ - `writeType="coil"`: the command from the transformation is converted to boolean.
Non-zero numbers, `ON`, and `OPEN` are considered `true`; and rest as `false`.
- * `writeType="holding"`: First, the command from the transformation is converted `1`/`0` number in case of `OPEN`/`ON` or `CLOSED`/`OFF`. The number is converted to one or more registers using `writeValueType`.
+ - `writeType="holding"`: First, the command from the transformation is converted `1`/`0` number in case of `OPEN`/`ON` or `CLOSED`/`OFF`. The number is converted to one or more registers using `writeValueType`.
For example, number `3.14` would be converted to two registers when `writeValueType="float32"`: [0x4048, 0xF5C3].
-6. Boolean (`writeType="coil"`) or registers (`writeType="holding"`) are written to the Modbus slave using `FC05`, `FC06`, `FC15`, or `FC16`, depending on the value of `writeMultipleEvenWithSingleRegisterOrCoil`.
+1. Boolean (`writeType="coil"`) or registers (`writeType="holding"`) are written to the Modbus slave using `FC05`, `FC06`, `FC15`, or `FC16`, depending on the value of `writeMultipleEvenWithSingleRegisterOrCoil`.
Write address is specified by `writeStart`.
#### Advanced Write Using JSON
Two write requests would be sent to the Modbus slave
1. FC16 (write multiple holding register), with start address 5412, having three registers of data (1, 0, and 5).
-2. FC06 (write single holding register), with start address 555, and single register of data (3).
+1. FC06 (write single holding register), with start address 555, and single register of data (3).
Write is tried maximum of 10 times in case some of the writes fail.
The JSON transformation output can be useful when you need full control how the write goes, for example in case where the write address depends on the incoming command.
Transformations serve two purpose
-* `readTransform`: doing preprocessing transformations to read binary data and to make it more usable in openHAB
-* `writeTransform`: doing preprocessing to openHAB commands before writing them to Modbus slave
+- `readTransform`: doing preprocessing transformations to read binary data and to make it more usable in openHAB
+- `writeTransform`: doing preprocessing to openHAB commands before writing them to Modbus slave
Note that transformation is only one part of the overall process how polled data is converted to openHAB state, or how commands are converted to Modbus writes.
Consult [Read steps](#read-steps) and [Write steps](#write-steps) for more details.
1. String `"default"`, in which case the default transformation is used. The default is to do no conversion to the command.
1. `"SERVICENAME:ARG"` for calling a transformation service. The transformation receives the command as input. This is useful for applying complex arithmetic for commands before the data is written to Modbus. See examples for more details.
1. Any other value is interpreted as static text, in which case the actual command is ignored. Transformation result is always the same.
+
#### Example: Inverting Binary Data On Read And Write
This example transformation is able to invert "boolean" input.
`things/modbus_ex1.things`:
-```
+```java
Bridge modbus:tcp:localhostTCP [ host="127.0.0.1", port=502, id=2 ] {
// read-write for coils. Reading 4 coils, with index 4, and 5.
`items/modbus_ex1.items`:
-```
+```java
Switch DO4 "Digital Output index 4 [%d]" { channel="modbus:data:localhostTCP:coils:do4:switch" }
Switch DO5 "Digital Output index 5 [%d]" { channel="modbus:data:localhostTCP:coils:do5:switch" }
`sitemaps/modbus_ex1.sitemap`:
-```
+```perl
sitemap modbus_ex1 label="modbus_ex1"
{
Frame {
`things/modbus_ex2.things`:
-```
+```java
Bridge modbus:tcp:localhostTCPex2 [ host="127.0.0.1", port=502 ] {
Bridge poller items [ start=4, length=2, refresh=1000, type="discrete" ] {
`items/modbus_ex2.items`:
-```
+```java
Switch ReadDI4WriteDO5 "Coil 4/5 mix [%d]" { channel="modbus:data:localhostTCPex2:items:readDiscrete4WriteCoil5:switch" }
Switch ResetDO5 "Flip to turn Coil 5 OFF [%d]" { channel="modbus:data:localhostTCPex2:items:resetCoil5:switch" }
Switch SetDO5 "Flip to turn Coil 5 ON [%d]" { channel="modbus:data:localhostTCPex2:items:setCoil5:switch" }
`sitemaps/modbus_ex2.sitemap`:
-```
+```perl
sitemap modbus_ex2 label="modbus_ex2"
{
Frame {
`things/modbus_ex_scaling.things`:
-```
+```java
Bridge modbus:tcp:localhostTCP3 [ host="127.0.0.1", port=502 ] {
Bridge poller holdingPoller [ start=5, length=1, refresh=5000, type="holding" ] {
Thing data temperatureDeciCelsius [ readStart="5", readValueType="int16", writeStart="5", writeValueType="int16", writeType="holding" ]
`items/modbus_ex_scaling.items`:
-```
+```java
Number:Temperature TemperatureItem "Temperature [%.1f °C]" { channel="modbus:data:localhostTCP3:holdingPoller:temperatureDeciCelsius:number"[ profile="modbus:gainOffset", gain="0.1 °C", pre-gain-offset="0" ] }
```
`sitemaps/modbus_ex_scaling.sitemap`:
-```
+```perl
sitemap modbus_ex_scaling label="modbus_ex_scaling"
{
Frame {
}
```
-
### Commanding Individual Bits
In Modbus, holding registers represent 16 bits of data. The protocol allow to write the whole register at once.
`things/modbus_ex_command_bit.things`:
-```
+```java
Bridge modbus:tcp:localhostTCP3 [ host="127.0.0.1", port=502 ] {
Bridge poller holdingPoller [ start=5, length=1, refresh=5000, type="holding" ] {
Thing data register5 [ readStart="5.1", readValueType="bit", writeStart="5.1", writeValueType="bit", writeType="holding" ]
`items/modbus_ex_command_bit.items`:
-```
+```java
Switch SecondLeastSignificantBit "2nd least significant bit write switch [%d]" { channel="modbus:data:localhostTCP3:holdingPoller:register5:switch" }
Number SecondLeastSignificantBitAltRead "2nd least significant bit is now [%d]" { channel="modbus:data:localhostTCP3:holdingPoller:register5Bit1:number" }
```
`sitemaps/modbus_ex_command_bit.sitemap`:
-```
+```perl
sitemap modbus_ex_command_bit label="modbus_ex_command_bit"
{
Frame {
`things/modbus_ex_dimmer.things`:
-```
+```java
Bridge modbus:tcp:remoteTCP [ host="192.168.0.10", port=502 ] {
Bridge poller MBDimmer [ start=4700, length=2, refresh=1000, type="holding" ] {
- Thing data DimmerReg [ readStart="4700", readValueType="uint16", readTransform="JS:dimread255.js", writeStart="4700", writeValueType="uint16", writeType="holding", writeTransform="JS:dimwrite255.js" ]
+ Thing data DimmerReg [ readStart="4700", readValueType="uint16", readTransform="JS:dimread255.js", writeStart="4700", writeValueType="uint16", writeType="holding", writeTransform="JS:dimwrite255.js" ]
}
}
```
`items/modbus_ex_dimmer.items`:
-```
+
+```java
Dimmer myDimmer "My Dimmer d2 [%.1f]" { channel="modbus:data:remoteTCP:MBDimmer:DimmerReg:dimmer" }
```
`sitemaps/modbus_ex_dimmer.sitemap`:
-```
+```perl
sitemap modbus_ex_dimmer label="modbus_ex_dimmer"
{
Frame {
```
`transform/dimread255.js`:
+
```javascript
// Wrap everything in a function (no global variable pollution)
// variable "input" contains data string passed by binding
```
`transform/dimwrite255.js`:
+
```javascript
// variable "input" contains command string passed by openHAB
(function(inputData) {
})(input)
```
-
### Rollershutter Example
#### Rollershutter
| `MOVE` | `1` | 2 |
| `STOP` | `0` | 2 |
-
`things/modbus_ex_rollershutter.things`:
-```
+```java
Bridge modbus:tcp:localhostTCPRollerShutter [ host="127.0.0.1", port=502 ] {
Bridge poller holding [ start=0, length=3, refresh=1000, type="holding" ] {
// Since we are using advanced transformation outputting JSON,
`items/modbus_ex_rollershutter.items`:
-```
+```java
// We disable auto-update to make sure that rollershutter position is updated from the slave, not "automatically" via commands
Rollershutter RollershutterItem "Roller shutter position [%.1f]" <temperature> { autoupdate="false", channel="modbus:data:localhostTCPRollerShutter:holding:rollershutterData:rollershutter" }
`sitemaps/modbus_ex_rollershutter.sitemap`:
-```
+```perl
sitemap modbus_ex_rollershutter label="modbus_ex_rollershutter" {
Switch item=RollershutterItem label="Roller shutter [(%d)]" mappings=[UP="up", STOP="X", DOWN="down", MOVE="move"]
Modbus, while simple at its heart, potentially is a complicated standard to use because there's a lot of freedom (and bugs) when it comes to implementations.
There are many device or vendor specific quirks and wrinkles you might stumble across. Here's some:
-* With Modbus TCP devices, there may be multiple network interfaces available, e.g. Wifi and wired Ethernet. However, with some devices the Modbus data is accessible via only one of the interfaces. You need to check the device manufacturer manual, or simply try out which of the IPs are returning valid modbus data.
+- With Modbus TCP devices, there may be multiple network interfaces available, e.g. Wifi and wired Ethernet. However, with some devices the Modbus data is accessible via only one of the interfaces. You need to check the device manufacturer manual, or simply try out which of the IPs are returning valid modbus data.
Attention: a device may have an interface with a port open (502 or other) that it responds to Modbus requests on, but that may have no connection to the real bus hardware, resulting in generic Modbus error responses to _every_ request.
So check ALL interfaces. Usually either the IP on Ethernet will do.
-* some devices do not allow to query a range of registers that is too large or spans reserved registers. Do not poll more than 123 registers.
+- some devices do not allow to query a range of registers that is too large or spans reserved registers. Do not poll more than 123 registers.
Devices may respond with an error or no error but invalid register data so this error can easily go undedetected.
Turn your poller thing into multiple things to cover smaller ranges to work around this problem.
-* there's potentially many more or less weird inconsistencies with some devices.
+- there's potentially many more or less weird inconsistencies with some devices.
If you fail to read a register or you only ever get invalid values (such as 00 or FF bytes), try with various poller lengths such as the exact length of a register in question or twice the amount.
In extreme cases you might even need more than a poller for a single register so you have two or more poller with two or more data things and need to combine these into another item using a rule.
### Absolute Addresses Instead Of Relative
-The new Modbus binding uses *absolute* addresses.
-This means that all parameters referring to addresses of input registers, holding registers, discrete inputs or coils are *entity addresses*.
+The new Modbus binding uses _absolute_ addresses.
+This means that all parameters referring to addresses of input registers, holding registers, discrete inputs or coils are _entity addresses_.
This means that the addresses start from zero (first entity), and can go up to 65 535. See [Wikipedia explanation](https://en.wikipedia.org/wiki/Modbus#Coil.2C_discrete_input.2C_input_register.2C_holding_register_numbers_and_addresses) for more information.
Previous binding sometimes used absolute addresses (`modbus.cfg`), sometimes relative to polled data (items configuration).
`modbus.cfg`
-```
+```text
poll=500
tcp.slave1.connection=192.168.2.9:502
Level one defines a `Bridge` for every modbus device that is to be addressed.
The 1.x configuration in this example only addresses one device, so there will be one top level bridge.
-```
+```java
Bridge modbus:tcp:wago [ host="192.168.2.9", port=502 ] {
}
```
+
Host and Port are taken from the 1.x modbus config.
Within the top level `Bridge` there are one or more second level bridges that replace the former `slave` configurations.
The slave `Bridge` configs go inside the top level config.
For the four `poller`s defined in this example the 2.x configuration looks like this:
-```
+```java
Bridge modbus:tcp:wago [ host="192.168.2.9", port=502, id=1 ] {
Bridge poller wago_slave1 [ start=12288, length=128, refresh=500, type="coil" ] {
The first Item polled with the first `poller` used this configuration (with offset 0):
-```
+```java
Switch FooSwitch "Foo Switch" {modbus="slave1:0"}
```
The `slave1` `poller` uses `12288` as start address.
So we define the first data Thing within the `poller` `wago_slave1` with this address and choose a name that ends with `0`:
-```
+```java
Thing data wago_s1_000 [ readStart="12288", readValueType="bit", writeStart="12288", writeValueType="bit", writeType="coil" ]
```
The second Item of the 1.x binding (offset `1`) is defined as follows.
-```
+```java
Switch BarSwitch "Bar Switch" {modbus="slave1:1"}
```
This leads to the thing definition
-```
+```java
Thing data wago_s1_001 [ readStart="12289", readValueType="bit", writeStart="12289", writeValueType="bit", writeType="coil" ]
```
`wago.things`:
-```
+```java
Bridge modbus:tcp:wago [ host="192.168.2.9", port=502, id=1 ] {
Bridge poller wago_slave1 [ start=12288, length=128, refresh=500, type="coil" ] {
Finally the Item definition has to be changed to refer to the new created `data` `Thing`.
You can copy the names you need for this directly from the `events.log` file:
-```
+```java
Switch FooSwitch "Foo Switch" {modbus="slave1:0"}
Switch BarSwitch "Bar Switch" {modbus="slave1:1"}
```
turn into
-```
+```java
Switch FooSwitch "Foo Switch" {channel="modbus:data:wago:wago_slave1:wago_s1_000:switch", autopudate="false"}
Switch BarSwitch "Bar Switch" {channel="modbus:data:wago:wago_slave1:wago_s1_001:switch", autoupdate="false"}
```
Save your updated item file and check whether updates come in as expected.
-## Troubleshooting
+## Troubleshooting Tips
### Thing Status
Enable `DEBUG` or `TRACE` (even more verbose) logging for the loggers named:
-* `org.openhab.binding.modbus`
-* `org.openhab.core.io.transport.modbus`
-* `net.wimpi.modbus`
+- `org.openhab.binding.modbus`
+- `org.openhab.core.io.transport.modbus`
+- `net.wimpi.modbus`
Consult [openHAB logging documentation](https://www.openhab.org/docs/administration/logging.html#defining-what-to-log) for more information.
The binding supports two different kinds of connections:
-* serial connection,
-* serial over IP connection
+- serial connection,
+- serial over IP connection
For users without a serial port on the server side, you can use a USB to serial adapter.
Some notes:
-* On Linux, you may get an error stating the serial port cannot be opened when the MonopriceAudio binding tries to load.
-* You can get around this by adding the `openhab` user to the `dialout` group like this: `usermod -a -G dialout openhab`.
-* Also on Linux you may have issues with the USB if using two serial USB devices e.g. MonopriceAudio and RFXcom.
-* See the [general documentation about serial port configuration](/docs/administration/serial.html) for more on symlinking the USB ports.
-* Here is an example of ser2net.conf you can use to share your serial port /dev/ttyUSB0 on IP port 8080 using [ser2net Linux tool](https://sourceforge.net/projects/ser2net/):
+- On Linux, you may get an error stating the serial port cannot be opened when the MonopriceAudio binding tries to load.
+- You can get around this by adding the `openhab` user to the `dialout` group like this: `usermod -a -G dialout openhab`.
+- Also on Linux you may have issues with the USB if using two serial USB devices e.g. MonopriceAudio and RFXcom.
+- See the [general documentation about serial port configuration](/docs/administration/serial.html) for more on symlinking the USB ports.
+- Here is an example of ser2net.conf you can use to share your serial port /dev/ttyUSB0 on IP port 8080 using [ser2net Linux tool](https://sourceforge.net/projects/ser2net/):
-```
+```text
8080:raw:0:/dev/ttyUSB0:9600 8DATABITS NONE 1STOPBIT LOCAL
```
monoprice.things:
-```
+```java
// serial port connection
monopriceaudio:amplifier:myamp "Monoprice WHA" [ serialPort="COM5", pollingInterval=15, numZones=6, inputLabel1="Chromecast", inputLabel2="Radio", inputLabel3="CD Player", inputLabel4="Bluetooth Audio", inputLabel5="HTPC", inputLabel6="Phono"]
monoprice.items:
-```
+```java
Switch all_allpower "All Zones Power" { channel="monopriceaudio:amplifier:myamp:all#allpower" }
Number all_source "Source Input [%s]" { channel="monopriceaudio:amplifier:myamp:all#allsource" }
Dimmer all_volume "Volume [%d %%]" { channel="monopriceaudio:amplifier:myamp:all#allvolume" }
monoprice.sitemap:
-```
+```perl
sitemap monoprice label="Audio Control" {
Frame label="All Zones" {
Switch item=all_allpower label="All Zones On" mappings=[ON=" "]
With the openHAB MPD binding you can control Music Player Daemons.
-
## Supported Things
This binding supports one ThingType: mpd
If zeroconf is enabled in the Music Player Daemon, it is discovered. Each Music Player daemon requires a unique zeroconf_name for correct discovery.
-
## Thing Configuration
The ThingType mpd requires the following configuration parameters:
| Port | port | Port number on which the Music Player Daemon is listening. Default: 6600 | yes |
| Password | password | Password to access the Music Player Daemon | no |
-
## Channels
The following channels are currently available:
| currenttitle | String | Current title |
| currenttrack | Number | Current track |
-
## Full Example
-#### Thing
+### Thing
-```
+```java
mpd:mpd:music [ ipAddress="192.168.1.2", port=6600 ]
```
-#### Items
+### Items
-```
+```java
Switch morning_music "Morning music"
Player mpd_music_player "Player" { channel = "mpd:mpd:music:control" }
Number mpd_music_track "Track [%d]" { channel = "mpd:mpd:music:currenttrack" }
```
-#### Sitemap
+### Sitemap
-```
+```perl
Frame label="Music" {
Default item=mpd_music_player
Slider item=mpd_music_volume
}
```
-#### Rule
+### Rule
-```
+```java
rule "turn on morning music"
when
Item morning_music changed to ON
Advantages to using this DIY bridge over the OEM bridge:
-+ Almost unlimited groups to give individual control over an entire house of Milight globes without needing multiple bridges.
-+ If using the Milight remotes to control the globes, this binding can update the openHAB controls the moment a key is pressed on the physical remotes.
-+ Supports auto discovery.
+- Almost unlimited groups to give individual control over an entire house of Milight globes without needing multiple bridges.
+- If using the Milight remotes to control the globes, this binding can update the openHAB controls the moment a key is pressed on the physical remotes.
+- Supports auto discovery.
## Setup the hardware
A quick overview of the steps to get the hardware going are:
-+ Connect a nodemcu/D1 mini/esp8266 to your computer via a USB cable.
-+ Download the latest BIN file from here <https://github.com/sidoh/esp8266_milight_hub/releases>
-+ Download esp8266flasher if you are on windows <https://github.com/nodemcu/nodemcu-flasher>
-+ Check the blog above on more info for Mac or Linux.
-+ Open the flasher tool and make sure the flash size is 4mb or whatever your esp8266 board has.
-+ Flash the bin and press the reset button on the board when it completes.
-+ Connect to the wifi access point of the esp directly with your phone/tablet and setup wifi details.
-+ Login by using the IP address of the esp8266 in a web browser and the control panel will show up.
-+ Connect 7 wires between the two ready made PCBs as shown in the blog.
-+ Setup a MQTT broker as this method uses the faster and lightweight MQTT protocol and not UDP.
+- Connect a nodemcu/D1 mini/esp8266 to your computer via a USB cable.
+- Download the latest BIN file from here <https://github.com/sidoh/esp8266_milight_hub/releases>
+- Download esp8266flasher if you are on windows <https://github.com/nodemcu/nodemcu-flasher>
+- Check the blog above on more info for Mac or Linux.
+- Open the flasher tool and make sure the flash size is 4mb or whatever your esp8266 board has.
+- Flash the bin and press the reset button on the board when it completes.
+- Connect to the wifi access point of the esp directly with your phone/tablet and setup wifi details.
+- Login by using the IP address of the esp8266 in a web browser and the control panel will show up.
+- Connect 7 wires between the two ready made PCBs as shown in the blog.
+- Setup a MQTT broker as this method uses the faster and lightweight MQTT protocol and not UDP.
## Setup the Firmware
**group_state_fields:**
IMPORTANT: Make sure only the following are ticked:
-+ state
-+ level
-+ hue
-+ saturation
-+ mode
-+ color_temp
-+ bulb_mode
+- state
+- level
+- hue
+- saturation
+- mode
+- color_temp
+- bulb_mode
Fill in the MQTT broker fields with the correct details so the hub can connect and then click **save**.
Now when you use any Milight remote control, you will see MQTT topics being created that should include `level` and `hsb` in the messages.
You can use this Linux command to watch all MQTT topics from Milight:
-```
+```shell
mosquitto_sub -u usernamehere -P passwordhere -p 1883 -v -t 'milight/#'
```
To remove a saved state from your MQTT broker that causes an entry in your INBOX you can use this command or use the ignore feature of openHAB.
-```
+```shell
mosquitto_pub -u username -P password -p 1883 -t 'milight/states/0x0/rgb_cct/1' -n -r
```
| `oneTriggersNightMode` | Night mode is a much lower level of light and this feature allows it to be auto selected when your fader/slider moves to 1%. NOTE: Night mode by design locks out some controls of a physical remote, so this feature is disabled by default. | Y | false |
| `powerFailsToMinimum` | If lights loose power from the power switch OR a power outage, they will default to using the lowest brightness if the light was turned off before the power failure occurred. | Y | true |
| `whiteThreshold` | This feature allows you to use a color control to change to using the real white LEDs when the saturation is equal to, or below this threshold. -1 will disable this feature. | Y | 12 |
-| `duvThreshold` | This feature allows you to use a color control to change to using the real warm/cool white LEDs to set a white color temperature if the color is within a certain threshold of the block body curve. 1 will effectively disable this feature. The default settings maps well to Apple's HomeKit that will allow you to choose a color temperature, but sends it as an HSB value. See https://www.waveformlighting.com/tech/calculate-duv-from-cie-1931-xy-coordinates/ for more information. | Y | 0.003 |
+| `duvThreshold` | This feature allows you to use a color control to change to using the real warm/cool white LEDs to set a white color temperature if the color is within a certain threshold of the block body curve. 1 will effectively disable this feature. The default settings maps well to Apple's HomeKit that will allow you to choose a color temperature, but sends it as an HSB value. See <https://www.waveformlighting.com/tech/calculate-duv-from-cie-1931-xy-coordinates/> for more information. | Y | 0.003 |
## Channels
Settings can be found on the radio tab in the esp control panel using your browser.
Suggested settings are as follows:
-+ Packet repeats = 12 (if you only turn 1 globe on or off it uses this value)
-+ Packet repeat throttle threshold = 200
-+ Packet repeat throttle sensitivity = 0
-+ Packet repeat minimum = 8 (When turning multiple globes on and off it will use this value as it throttles the repeats back to reduce latency/delay between each globe)
+- Packet repeats = 12 (if you only turn 1 globe on or off it uses this value)
+- Packet repeat throttle threshold = 200
+- Packet repeat throttle sensitivity = 0
+- Packet repeat minimum = 8 (When turning multiple globes on and off it will use this value as it throttles the repeats back to reduce latency/delay between each globe)
## Important for Textual Configuration
*.things
-```
+```java
Bridge mqtt:broker:myBroker [ host="localhost", secure=false, password="*******", qos=1, username="user"]
Thing mqtt:rgb_cct:myBroker:0xE6C4 "Hallway" (mqtt:broker:myBroker) @ "MQTT"
```
*.items
-```
+```java
Dimmer Hallway_Level "Front Hall" {channel="mqtt:rgb_cct:myBroker:0xE6C4:level"}
Dimmer Hallway_ColourTemperature "White Color Temp" {channel="mqtt:rgb_cct:myBroker:0xE6C4:colourTemperature"}
Color Hallway_Colour "Front Hall" ["Lighting"] {channel="mqtt:rgb_cct:myBroker:0xE6C4:colour"}
*.sitemap
-```
- Text label="Hallway" icon="light"
- {
- Switch item=Hallway_Level
- Slider item=Hallway_Level
- Slider item=Hallway_ColourTemperature
- Colorpicker item=Hallway_Colour
- Selection item=Hallway_DiscoMode
- Text item=Hallway_BulbMode
- Switch item=Hallway_BulbCommand mappings=[next_mode='Mode +', previous_mode='Mode -', mode_speed_up='Speed +', mode_speed_down='Speed -', set_white='White', night_mode='Night' ]
- }
+```perl
+Text label="Hallway" icon="light"
+{
+ Switch item=Hallway_Level
+ Slider item=Hallway_Level
+ Slider item=Hallway_ColourTemperature
+ Colorpicker item=Hallway_Colour
+ Selection item=Hallway_DiscoMode
+ Text item=Hallway_BulbMode
+ Switch item=Hallway_BulbCommand mappings=[next_mode='Mode +', previous_mode='Mode -', mode_speed_up='Speed +', mode_speed_down='Speed -', set_white='White', night_mode='Night' ]
+}
```
MQTT servers are called brokers and the clients are simply the connected devices.
-* When a device (a client) wants to send data to the broker, we call this operation a “publish”.
-* When a device (a client) wants to receive data from the broker, we call this operation a “subscribe”.
+- When a device (a client) wants to send data to the broker, we call this operation a “publish”.
+- When a device (a client) wants to receive data from the broker, we call this operation a “subscribe”.
openHAB itself is not an MQTT Broker and needs to connect to one as a regular client.
-Therefore you must have configured a *Broker Thing* first via the **MQTT Broker Binding**!
+Therefore you must have configured a _Broker Thing_ first via the **MQTT Broker Binding**!
## MQTT Topics
The following optional parameters can be set for the Thing:
-* __availabilityTopic__: The MQTT topic that represents the availability of the thing. This can be the thing's LWT topic.
-* __payloadAvailable__: Payload of the `Availability Topic`, when the device is available. Default: `ON`.
-* __payloadNotAvailable__: Payload of the `Availability Topic`, when the device is *not* available. Default: `OFF`.
-* __transformationPattern__: An optional transformation pattern like [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2) that is applied to the incoming availability payload. Transformations can be chained by separating them with the mathematical intersection character "∩". The result of the transformations is then checked against `payloadAvailable` and `payloadNotAvailable`.
+- **availabilityTopic**: The MQTT topic that represents the availability of the thing. This can be the thing's LWT topic.
+- **payloadAvailable**: Payload of the `Availability Topic`, when the device is available. Default: `ON`.
+- **payloadNotAvailable**: Payload of the `Availability Topic`, when the device is _not_ available. Default: `OFF`.
+- **transformationPattern**: An optional transformation pattern like [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2) that is applied to the incoming availability payload. Transformations can be chained by separating them with the mathematical intersection character "∩". The result of the transformations is then checked against `payloadAvailable` and `payloadNotAvailable`.
## Supported Channels
You can add the following channels:
-* **string**: This channel can show the received text on the given topic and can send text to a given topic.
-* **number**: This channel can show the received number on the given topic and can send a number to a given topic. It can have a min, max and step values.
-* **dimmer**: This channel handles numeric values as percentages. It can have min, max and step values.
-* **contact**: This channel represents an open/close state of a given topic.
-* **switch**: This channel represents an on/off state of a given topic and can send an on/off value to a given topic.
-* **colorRGB**: This channel handles color values in RGB format. (Deprecated)
-* **colorHSB**: This channel handles color values in HSB format. (Deprecated)
-* **color**: This channel handles color values in HSB, RGB or xyY (x,y,brightness) formats.
-* **location**: This channel handles a location.
-* **image**: This channel handles binary images in common java supported formats (bmp,jpg,png).
-* **datetime**: This channel handles date/time values.
-* **rollershutter**: This channel is for rollershutters.
+- **string**: This channel can show the received text on the given topic and can send text to a given topic.
+- **number**: This channel can show the received number on the given topic and can send a number to a given topic. It can have a min, max and step values.
+- **dimmer**: This channel handles numeric values as percentages. It can have min, max and step values.
+- **contact**: This channel represents an open/close state of a given topic.
+- **switch**: This channel represents an on/off state of a given topic and can send an on/off value to a given topic.
+- **colorRGB**: This channel handles color values in RGB format. (Deprecated)
+- **colorHSB**: This channel handles color values in HSB format. (Deprecated)
+- **color**: This channel handles color values in HSB, RGB or xyY (x,y,brightness) formats.
+- **location**: This channel handles a location.
+- **image**: This channel handles binary images in common java supported formats (bmp,jpg,png).
+- **datetime**: This channel handles date/time values.
+- **rollershutter**: This channel is for rollershutters.
## Channel Configuration
-* __stateTopic__: The MQTT topic that represents the state of the thing. This can be empty, the thing channel will be a state-less trigger then. You can use a wildcard topic like "sensors/+/event" to retrieve state from multiple MQTT topics.
-* __transformationPattern__: An optional transformation pattern like [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2) that is applied to all incoming MQTT values.
-* __transformationPatternOut__: An optional transformation pattern like [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2) that is applied before publishing a value to MQTT.
-* __commandTopic__: The MQTT topic that commands are send to. This can be empty, the thing channel will be read-only then. Transformations are not applied for sending data.
-* __formatBeforePublish__: Format a value before it is published to the MQTT broker. The default is to just pass the channel/item state. If you want to apply a prefix, say "MYCOLOR,", you would use "MYCOLOR,%s". Currently only "%s" is supported.
-* __postCommand__: If `true`, the received MQTT value will not only update the state of linked items, but command it.
+- **stateTopic**: The MQTT topic that represents the state of the thing. This can be empty, the thing channel will be a state-less trigger then. You can use a wildcard topic like "sensors/+/event" to retrieve state from multiple MQTT topics.
+- **transformationPattern**: An optional transformation pattern like [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2) that is applied to all incoming MQTT values.
+- **transformationPatternOut**: An optional transformation pattern like [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2) that is applied before publishing a value to MQTT.
+- **commandTopic**: The MQTT topic that commands are send to. This can be empty, the thing channel will be read-only then. Transformations are not applied for sending data.
+- **formatBeforePublish**: Format a value before it is published to the MQTT broker. The default is to just pass the channel/item state. If you want to apply a prefix, say "MYCOLOR,", you would use "MYCOLOR,%s". Currently only "%s" is supported.
+- **postCommand**: If `true`, the received MQTT value will not only update the state of linked items, but command it.
The default is `false`.
You usually need this to be `true` if your item is also linked to another channel, say a KNX actor, and you want a received MQTT payload to command that KNX actor.
-* __retained__: The value will be published to the command topic as retained message. A retained value stays on the broker and can even be seen by MQTT clients that are subscribing at a later point in time.
-* __qos__: QoS of this channel. Overrides the connection QoS (defined in broker connection).
-* __trigger__: If `true`, the state topic will not update a state, but trigger a channel instead.
+- **retained**: The value will be published to the command topic as retained message. A retained value stays on the broker and can even be seen by MQTT clients that are subscribing at a later point in time.
+- **qos**: QoS of this channel. Overrides the connection QoS (defined in broker connection).
+- **trigger**: If `true`, the state topic will not update a state, but trigger a channel instead.
### Channel Type "string"
-* __allowedStates__: An optional comma separated list of allowed states. Example: "ONE,TWO,THREE"
+- **allowedStates**: An optional comma separated list of allowed states. Example: "ONE,TWO,THREE"
You can connect this channel to a String item.
### Channel Type "number"
-* __min__: An optional minimum value.
-* __max__: An optional maximum value.
-* __step__: For decrease, increase commands the step needs to be known
-* __unit__: Unit of measurement (optional). For supported units see [OpenHAB: List of Units](https://www.openhab.org/docs/concepts/units-of-measurement.html#list-of-units). Examples: "°C", "°F"
+- **min**: An optional minimum value.
+- **max**: An optional maximum value.
+- **step**: For decrease, increase commands the step needs to be known
+- **unit**: Unit of measurement (optional). For supported units see [OpenHAB: List of Units](https://www.openhab.org/docs/concepts/units-of-measurement.html#list-of-units). Examples: "°C", "°F"
A decimal value (like 0.2) is send to the MQTT topic if the number has a fractional part.
If you always require an integer, please use the formatter.
### Channel Type "dimmer"
-* __on__: An optional string (like "ON"/"Open") that is recognized as minimum.
-* __off__: An optional string (like "OFF"/"Close") that is recognized as maximum.
-* __min__: A required minimum value.
-* __max__: A required maximum value.
-* __step__: For decrease, increase commands the step needs to be known
+- **on**: An optional string (like "ON"/"Open") that is recognized as minimum.
+- **off**: An optional string (like "OFF"/"Close") that is recognized as maximum.
+- **min**: A required minimum value.
+- **max**: A required maximum value.
+- **step**: For decrease, increase commands the step needs to be known
The value is internally stored as a percentage for a value between **min** and **max**.
### Channel Type "contact", "switch"
-* __on__: An optional number (like 1, 10) or a string (like "ON"/"Open") that is recognized as on/open state.
-* __off__: An optional number (like 0, -10) or a string (like "OFF"/"Close") that is recognized as off/closed state.
+- **on**: An optional number (like 1, 10) or a string (like "ON"/"Open") that is recognized as on/open state.
+- **off**: An optional number (like 0, -10) or a string (like "OFF"/"Close") that is recognized as off/closed state.
The contact channel by default recognizes `"OPEN"` and `"CLOSED"`. You can connect this channel to a Contact item.
The switch channel by default recognizes `"ON"` and `"OFF"`. You can connect this channel to a Switch item.
### Channel Type "color"
-* __colorMode__: An optional string that defines the color representation: `HSB`, `RGB` or `XYY` (x,y,brightness). Defaults to `HSB` when not specified.
-* __on__: An optional string (like "BRIGHT") that is recognized as on state. (ON will always be recognized.)
-* __off__: An optional string (like "DARK") that is recognized as off state. (OFF will always be recognized.)
-* __onBrightness__: If you connect this channel to a Switch item and turn it on,
+- **colorMode**: An optional string that defines the color representation: `HSB`, `RGB` or `XYY` (x,y,brightness). Defaults to `HSB` when not specified.
+- **on**: An optional string (like "BRIGHT") that is recognized as on state. (ON will always be recognized.)
+- **off**: An optional string (like "DARK") that is recognized as off state. (OFF will always be recognized.)
+- **onBrightness**: If you connect this channel to a Switch item and turn it on,
color and saturation are preserved from the last state, but
the brightness will be set to this configured initial brightness (default: 10%).
### Channel Type "colorRGB", "colorHSB" (Deprecated)
-* __on__: An optional string (like "BRIGHT") that is recognized as on state. (ON will always be recognized.)
-* __off__: An optional string (like "DARK") that is recognized as off state. (OFF will always be recognized.)
-* __onBrightness__: If you connect this channel to a Switch item and turn it on,
+- **on**: An optional string (like "BRIGHT") that is recognized as on state. (ON will always be recognized.)
+- **off**: An optional string (like "DARK") that is recognized as off state. (OFF will always be recognized.)
+- **onBrightness**: If you connect this channel to a Switch item and turn it on,
color and saturation are preserved from the last state, but
the brightness will be set to this configured initial brightness (default: 10%).
### Channel Type "rollershutter"
-* __on__: An optional string (like "Open") that is recognized as `UP` state.
-* __off__: An optional string (like "Close") that is recognized as `DOWN` state.
-* __stop__: An optional string (like "Stop") that is recognized as `STOP` state.
+- **on**: An optional string (like "Open") that is recognized as `UP` state.
+- **off**: An optional string (like "Close") that is recognized as `DOWN` state.
+- **stop**: An optional string (like "Stop") that is recognized as `STOP` state.
Internally `UP` is converted to 0%, `DOWN` to 100%.
If strings are defined for these values, they are used for sending commands to the broker, too.
You can connect this channel to a Rollershutter or Dimmer item.
-
## Rule Actions
This binding includes a rule action, which allows one to publish MQTT messages from within rules.
There is a separate instance for each MQTT broker (i.e. bridge), which can be retrieved through
-```
+```java
val mqttActions = getActions("mqtt","mqtt:broker:myBroker")
```
where the first parameter always has to be `mqtt` and the second (`mqtt:broker:myBroker`) is the Thing UID of the broker that should be used.
Once this action instance is retrieved, you can invoke the `publishMQTT(String topic, String value, Boolean retained)` method on it:
-```
+```java
mqttActions.publishMQTT("mytopic","myvalue", true)
```
## Configuration via Text Files
-*broker.things* file:
+_broker.things_ file:
-```
+```java
mqtt:broker:mySecureBroker [ host="192.168.0.41", secure=true, certificatepin=true, publickeypin=true ]
mqtt:broker:myInsecureBroker [ host="192.168.0.42", secure=false ]
mqtt:broker:myAuthenticatedBroker [ host="192.168.0.43",secure=true, username="user", password="password" ]
Files can also be used to create topic things and channels and to combine them with a broker connection:
-*mqtt.things* file:
+_mqtt.things_ file:
-```
+```java
Bridge mqtt:broker:myInsecureBroker [ host="192.168.0.42", secure=false ]
Thing mqtt:topic:mything "mything" (mqtt:broker:myInsecureBroker) {
If the availability status is available, it can be configured to set the Thing status:
-```
+```java
Thing mqtt:topic:bedroom1-switch (mqtt:broker:myInsecureBroker) [ availabilityTopic="tele/bedroom1-switch/LWT", payloadAvailable="Online", payloadNotAvailable="Offline" ] {
Channels:
Type switch : power [ stateTopic="stat/bedroom1-switch/RESULT", transformationPattern="REGEX:(.*POWER.*)∩JSONPATH:$.POWER", commandTopic="cmnd/bedroom1-switch/POWER" ]
}
```
-
+
## Limitations
-* The HomeAssistant Fan Components only support ON/OFF.
-* The HomeAssistant Cover Components only support OPEN/CLOSE/STOP.
-* The HomeAssistant Light Component does not support XY color changes.
-* The HomeAssistant Climate Components is not yet supported.
+- The HomeAssistant Fan Components only support ON/OFF.
+- The HomeAssistant Cover Components only support OPEN/CLOSE/STOP.
+- The HomeAssistant Light Component does not support XY color changes.
+- The HomeAssistant Climate Components is not yet supported.
## Incoming Value Transformation
Here are a few examples:
-* All uppercase: "%S". Just use the upper case letter for the conversion argument.
-* Apply a prefix: "myprefix%s"
-* Apply a suffix: "%s suffix"
-* Number precision: ".4f" for a 4 digit precision. Use the "+" flag to always add a sign: "+.4f".
-* Decimal to Hexadecimal/Octal/Scientific: For example "60" with "%x", "%o", "%e" becomes "3C", "74", "60".
-* Date/Time: To reference the item state multiple times, use "%1$". Use the "tX" conversion where "X" can be any of [h,H,m,M,I,k,l,S,p,B,b,A,a,y,Y,d,e].
- - For an output of *May 23, 1995* use "%1$**tb** %1$**te**,%1$**tY**".
- - For an output of *23.05.1995* use "%1$**td**.%1$**tm**.%1$**tY**".
- - For an output of *23:15* use "%1$**tH**:%1$**tM**".
+- All uppercase: "%S". Just use the upper case letter for the conversion argument.
+- Apply a prefix: "myprefix%s"
+- Apply a suffix: "%s suffix"
+- Number precision: ".4f" for a 4 digit precision. Use the "+" flag to always add a sign: "+.4f".
+- Decimal to Hexadecimal/Octal/Scientific: For example "60" with "%x", "%o", "%e" becomes "3C", "74", "60".
+- Date/Time: To reference the item state multiple times, use "%1$". Use the "tX" conversion where "X" can be any of [h,H,m,M,I,k,l,S,p,B,b,A,a,y,Y,d,e].
+ - For an output of _May 23, 1995_ use "%1$**tb** %1$**te**,%1$**tY**".
+ - For an output of _23.05.1995_ use "%1$**td**.%1$**tm**.%1$**tY**".
+ - For an output of _23:15_ use "%1$**tH**:%1$**tM**".
Default pattern applied for each type:
| Type | Parameter | Pattern | Comment |
| ---------------- | --------------------------------- | ------------------- | ------- |
-| __string__ | String | "%s" |
-| __number__ | BigDecimal | "%f" | The default will remove trailing zeros after the decimal point.
-| __dimmer__ | BigDecimal | "%f" | The default will remove trailing zeros after the decimal point.
-| __contact__ | String | -- | No pattern supported. Always **on** and **off** strings.
-| __switch__ | String | -- | No pattern supported. Always **on** and **off** strings.
-| __colorRGB__ | BigDecimal, BigDecimal, BigDecimal| "%1$d,%2$d,%3$d" | Parameters are **red**, **green** and **blue** components.
-| __colorHSB__ | BigDecimal, BigDecimal, BigDecimal| "%1$d,%2$d,%3$d" | Parameters are **hue**, **saturation** and **brightness** components.
-| __location__ | BigDecimal, BigDecimal | "%2$f,%3$f,%1$f" | Parameters are **altitude**, **latitude** and **longitude**, altitude is only in default pattern, if value is not '0'.
-| __image__ | -- | -- | No publishing supported.
-| __datetime__ | ZonedDateTime | "%1$tY-%1$tm-%1$tdT%1$tH:%1$tM:%1$tS.%1$tN" | Trailing zeros of the nanoseconds are removed.
-| __rollershutter__| String | "%s" | No pattern supported. Always **up**, **down**, **stop** string or integer percent value.
-
-Any outgoing value transformation will **always** result in a __string__ value.
+| **string** | String | "%s" |
+| **number** | BigDecimal | "%f" | The default will remove trailing zeros after the decimal point.
+| **dimmer** | BigDecimal | "%f" | The default will remove trailing zeros after the decimal point.
+| **contact** | String | -- | No pattern supported. Always **on** and **off** strings.
+| **switch** | String | -- | No pattern supported. Always **on** and **off** strings.
+| **colorRGB** | BigDecimal, BigDecimal, BigDecimal| "%1$d,%2$d,%3$d" | Parameters are **red**, **green** and **blue** components.
+| **colorHSB** | BigDecimal, BigDecimal, BigDecimal| "%1$d,%2$d,%3$d" | Parameters are **hue**, **saturation** and **brightness** components.
+| **location** | BigDecimal, BigDecimal | "%2$f,%3$f,%1$f" | Parameters are **altitude**, **latitude** and **longitude**, altitude is only in default pattern, if value is not '0'.
+| **image** | -- | -- | No publishing supported.
+| **datetime** | ZonedDateTime | "%1$tY-%1$tm-%1$tdT%1$tH:%1$tM:%1$tS.%1$tN" | Trailing zeros of the nanoseconds are removed.
+| **rollershutter**| String | "%s" | No pattern supported. Always **up**, **down**, **stop** string or integer percent value.
+
+Any outgoing value transformation will **always** result in a **string** value.
## Troubleshooting
-* If you get the error "No MQTT client": Please update your installation.
-* If you use the Mosquitto broker: Please be aware that there is a relatively low setting for retained messages. If at some point messages stop being delivered change the setting.
+- If you get the error "No MQTT client": Please update your installation.
+- If you use the Mosquitto broker: Please be aware that there is a relatively low setting for retained messages. If at some point messages stop being delivered change the setting.
+# Xtend Examples
## Examples
Have a look at the following textual examples.
-### A broker Thing with a Generic MQTT Thing and a few channels
+### A broker Thing with a Generic MQTT Thing and a few channels
demo1.things:
-```xtend
+```java
Bridge mqtt:broker:myUnsecureBroker [ host="192.168.0.42", secure=false ]
{
Thing topic mything {
demo2.things:
-```xtend
+```java
Bridge mqtt:broker:WorkBroker "Work Broker" [ host="localhost", port="1883", secure=false, username="openhabian", password="ohmqtt", clientID="WORKOPENHAB24" ]
Thing mqtt:topic:WorkBroker:WorkSonoff "Work Sonoff" (mqtt:broker:WorkBroker) @ "Home" {
Type switch : WorkLightTele "Work Tele" [ stateTopic="tele/worklight/STATE", transformationPattern="JSONPATH:$.POWER" ]
}
```
+
tasmota.things: Example of a Tasmota Device with Availablity-Topic state and standard Online/Offline message-payload
-```xtend
+
+```java
Bridge mqtt:broker:mybroker [ host="192.168.0.42", secure=false ]
{
Thing mqtt:topic:SP111 "SP111" [availabilityTopic="tele/tasmota/LWT", payloadAvailable="Online", payloadNotAvailable="Offline"]{
When using .things and .items files for configuration, items and channels follow the format of:
-```xtend
+```java
<ITEM-TYPE> <ITEM-NAME> "<FRIENDLY-NAME>" { channel="mqtt:topic:<BROKER-NAME>:<THING-NAME>:<CHANNEL-NAME>" }
```
demo1.items:
-```xtend
+```java
Switch Kitchen_Light "Kitchen Light" { channel="mqtt:topic:myUnsecureBroker:mything:lamp" }
Rollershutter shutter "Blind" { channel="mqtt:topic:myUnsecureBroker:mything:blind" }
```
demo2.items:
-```xtend
+```java
Switch SW_WorkLight "Work Light Switch" { channel="mqtt:topic:WorkBroker:WorkSonoff:WorkLight", channel="mqtt:topic:WorkBroker:WorkSonoff:WorkLightTele" }
```
An example "demo.rules" rule to publish to `system/started` with the value `true` on every start:
-```xtend
+```java
rule "Send startup message"
when
System started
Define a broker and a trigger channel for your DESTINATION openHAB installation (`thing` file):
-```xtend
+```java
Bridge mqtt:broker:myUnsecureBroker [ host="192.168.0.42", secure=false ]
{
Channels:
The trigger channel will trigger for each received message on the MQTT topic "allItems/".
Now push those changes to your items in a `rules` file:
-```xtend
+```java
rule "Receive all"
when
Channel "mqtt:broker:myUnsecureBroker:myTriggerChannel" triggered
On your SOURCE openHAB installation, you need to define a group `myGroupOfItems` and add all items
to it that you want to synchronize. Then add this rule to a `rule` file:
-```xtend
+```java
rule "Publish all"
when
Member of myGroupOfItems changed
> For mqtt1 make sure you have enabled the Legacy 1.x repository and installed "mqtt1".
-### 1 Command / 1 State topic
+### 1 Command / 1 State topic
Assume you have this item:
-```xtend
+```java
Switch ExampleItem "Heatpump Power" { mqtt=">[mosquitto:heatpump/set:command:*:DEFAULT)],<[mosquitto:heatpump:JSONPATH($.power)]" }
```
This converts to an entry in your *.things file with a **Broker Thing** and a **Generic MQTT Thing** that uses the bridge:
-```xtend
+```java
Bridge mqtt:broker:myUnsecureBroker [ host="192.168.0.42", secure=false ]
{
Thing topic mything "My Thing" {
}
```
-Add as many channels as you have items and add the *stateTopic* and *commandTopic* accordingly.
+Add as many channels as you have items and add the _stateTopic_ and _commandTopic_ accordingly.
Your items change to:
-```xtend
+```java
Switch ExampleItem "Heatpump Power" { channel="mqtt:topic:myUnsecureBroker:mything:heatpumpChannel" }
```
-
-### 1 Command / 2 State topics
+### 1 Command / 2 State topics
If you receive updates from two different topics, you need to create multiple channels now, 1 for each MQTT receive topic.
-```xtend
+```java
Switch ExampleItem "Heatpump Power" { mqtt=">[mosquitto:heatpump/set:command:*:DEFAULT)],<[mosquitto:heatpump/state1:state:*:DEFAULT,<[mosquitto:heatpump/state2:state:*:DEFAULT" }
```
This converts to:
-```xtend
+```java
Bridge mqtt:broker:myUnsecureBroker [ host="192.168.0.42", secure=false ]
{
Thing topic mything "My Thing" {
Link both channels to one item. That item will publish to "heatpump/set" on a change and
receive values from "heatpump/state1" and "heatpump/state2".
-```xtend
+```java
Switch ExampleItem "Heatpump Power" { channel="mqtt:topic:myUnsecureBroker:mything:heatpumpChannel",
channel="mqtt:topic:myUnsecureBroker:mything:heatpumpChannel2" }
```
The HomeAssistant MQTT requires two transformations to be installed:
-* JINJA-Transformations
-* JSONPath-Transformations
+- JINJA-Transformations
+- JSONPath-Transformations
These can be installed under `Settings` → `Addon` → `Transformations`
## Limitations
-* The HomeAssistant Fan Components only support ON/OFF.
-* The HomeAssistant Cover Components only support OPEN/CLOSE/STOP.
-* The HomeAssistant Light Component only support on/off, brightness, and RGB.
+- The HomeAssistant Fan Components only support ON/OFF.
+- The HomeAssistant Cover Components only support OPEN/CLOSE/STOP.
+- The HomeAssistant Light Component only support on/off, brightness, and RGB.
Other color spaces, color temperature, effects, and white channel may work, but are untested.
-* The HomeAssistant Climate Components is not yet supported.
+- The HomeAssistant Climate Components is not yet supported.
## Tasmota auto discovery
To activate HomeAssistant discovery support on your Tasmota device you need to do the following:
-* `Configuration` → `MQTT`: You must have unique `Client` name and `Topic` (should be the default).
-* `Configuration` → `Other`: The `Device Name` will be used to identify the newly found device.
+- `Configuration` → `MQTT`: You must have unique `Client` name and `Topic` (should be the default).
+- `Configuration` → `Other`: The `Device Name` will be used to identify the newly found device.
And you need to enable MQTT, of course.
-* `Console`: Enter `SetOption19 1`.
+- `Console`: Enter `SetOption19 1`.
Your Tasmota device should now show up in your inbox.
Devices that follow the [Homie convention](https://homieiot.github.io/) 3.x and better
are auto-discovered and represented by this binding and the Homie Thing.
-Find the next table to understand the topology mapping from Homie to the Framework:
+Find the next table to understand the topology mapping from Homie to the Framework:
| Homie | Framework | Example MQTT topic |
|----------|---------------|------------------------------------|
| Node | Channel Group | homie/super-car/engine |
| Property | Channel | homie/super-car/engine/temperature |
-System trigger channels are supported using non-retained properties, with *enum* data type and with the following formats:
+System trigger channels are supported using non-retained properties, with _enum_ data type and with the following formats:
-* Format: "PRESSED,RELEASED" -> system.rawbutton
-* Format: "SHORT\_PRESSED,DOUBLE\_PRESSED,LONG\_PRESSED" -> system.button
-* Format: "DIR1\_PRESSED,DIR1\_RELEASED,DIR2\_PRESSED,DIR2\_RELEASED" -> system.rawrocker
+- Format: "PRESSED,RELEASED" -> system.rawbutton
+- Format: "SHORT\_PRESSED,DOUBLE\_PRESSED,LONG\_PRESSED" -> system.button
+- Format: "DIR1\_PRESSED,DIR1\_RELEASED,DIR2\_PRESSED,DIR2\_RELEASED" -> system.rawrocker
## Supported Bridges
-* Broker: This bridge represents an MQTT Broker connection, configured and managed by this binding.
+- Broker: This bridge represents an MQTT Broker connection, configured and managed by this binding.
## Bridge Configuration
-
+
Required configuration parameters are:
-* __host__: The IP/Hostname of the MQTT broker. Be aware that this binding allows only one bridge / one connection per unique host:port.
-* __port__: The optional port of the MQTT broker. If none is provided, the typical ports 1883 and 8883 (SSL) are used. Be aware that this binding allows only one bridge / one connection per unique host:port.
-* __secure__: Uses TLS/SSL to establish a secure connection to the broker. Can be true or false. Defaults to false.
+- **host**: The IP/Hostname of the MQTT broker. Be aware that this binding allows only one bridge / one connection per unique host:port.
+- **port**: The optional port of the MQTT broker. If none is provided, the typical ports 1883 and 8883 (SSL) are used. Be aware that this binding allows only one bridge / one connection per unique host:port.
+- **secure**: Uses TLS/SSL to establish a secure connection to the broker. Can be true or false. Defaults to false.
Additionally the following parameters can be set:
-* __hostnameValidated__: Validate hostname from certificate against server hostname for secure connection. Defaults to true.
-* __protocol__: The protocol used for communicating with the broker (TCP, WEBSOCKETS). Defaults to TCP.
-* __mqttVersion__: The MQTT version used for communicating with the broker (V3, V5). Defaults to V3.
-* __qos__: Quality of Service. Can be 0, 1 or 2. Please read the MQTT specification for details. Defaults to 0.
-* __clientID__: Use a fixed client ID. Defaults to empty which means a user ID is generated for this connection.
+- **hostnameValidated**: Validate hostname from certificate against server hostname for secure connection. Defaults to true.
+- **protocol**: The protocol used for communicating with the broker (TCP, WEBSOCKETS). Defaults to TCP.
+- **mqttVersion**: The MQTT version used for communicating with the broker (V3, V5). Defaults to V3.
+- **qos**: Quality of Service. Can be 0, 1 or 2. Please read the MQTT specification for details. Defaults to 0.
+- **clientID**: Use a fixed client ID. Defaults to empty which means a user ID is generated for this connection.
Reconnect parameters are:
-* __reconnectTime__: Reconnect time in ms. If a connection is lost, the binding will wait this time before it tries to reconnect. Defaults to 60000 (60s).
-* __keepAlive__: Keep alive / heartbeat timer in s. It can take up to this time to determine if a server connection is lost. A lower value may keep the broker unnecessarily busy for no or little additional value. Defaults to 60s.
+- **reconnectTime**: Reconnect time in ms. If a connection is lost, the binding will wait this time before it tries to reconnect. Defaults to 60000 (60s).
+- **keepAlive**: Keep alive / heartbeat timer in s. It can take up to this time to determine if a server connection is lost. A lower value may keep the broker unnecessarily busy for no or little additional value. Defaults to 60s.
An MQTT last will and testament can be configured:
-* __lwtMessage__: An optional last will and testament message. Defaults to empty.
-* __lwtTopic__: The last will topic. Defaults to empty and therefore disables the last will.
-* __lwtQos__: The optional qos of the last will. Defaults to 0.
-* __lwtRetain__: Retain last will message. Defaults to true.
+- **lwtMessage**: An optional last will and testament message. Defaults to empty.
+- **lwtTopic**: The last will topic. Defaults to empty and therefore disables the last will.
+- **lwtQos**: The optional qos of the last will. Defaults to 0.
+- **lwtRetain**: Retain last will message. Defaults to true.
An MQTT message can be published upon a successful connection to the MQTT broker with these parameters:
-* __birthMessage__: An optional message to be published once the bridge established a connection to the MQTT broker. Defaults to empty.
-* __birthTopic__: The birth topic. Defaults to empty and therefore no birth message will be published.
-* __birthRetain__: Retain the birth message. Defaults to true.
+- **birthMessage**: An optional message to be published once the bridge established a connection to the MQTT broker. Defaults to empty.
+- **birthTopic**: The birth topic. Defaults to empty and therefore no birth message will be published.
+- **birthRetain**: Retain the birth message. Defaults to true.
An MQTT message can be published just before disconnecting from the broker with these parameters:
-* __shutdownMessage__: An optional message to be published before the bridge disconnects from the MQTT broker. Defaults to empty.
-* __shutdownTopic__: The shutdown topic. Defaults to empty and therefore no shutdown message will be published.
-* __shutdownRetain__: Retain the shutdown message. Defaults to true.
+- **shutdownMessage**: An optional message to be published before the bridge disconnects from the MQTT broker. Defaults to empty.
+- **shutdownTopic**: The shutdown topic. Defaults to empty and therefore no shutdown message will be published.
+- **shutdownRetain**: Retain the shutdown message. Defaults to true.
For more security, the following optional parameters can be altered:
-* __username__: The MQTT username (since MQTT 3.1). Defaults to empty.
-* __password__: The MQTT password (since MQTT 3.1). Defaults to empty.
-* __certificatepin__: If this is set: After the next connection has been successfully established, the certificate is pinned. The connection will be refused if another certificate is used. Clear **certificate** to allow a new certificate for the next connection attempt. This option will increase security.
-* __publickeypin__: If this is set: After the next connection has been successfully established, the public key of the broker is pinned. The connection will be refused if another public key is used. Clear **publickey** to allow a new public key for the next connection attempt. This option will increase security.
-* __certificate__: The certificate hash. If **certificatepin** is set this hash is used to verify the connection. Clear to allow a new certificate pinning on the next connection attempt. If empty will be filled automatically by the next successful connection. An example input would be `SHA-256:83F9171E06A313118889F7D79302BD1B7A2042EE0CFD029ABF8DD06FFA6CD9D3`.
-* __publickey__: The public key hash. If **publickeypin** is set this hash is used to verify the connection. Clear to allow a new public key pinning on the next connection attempt. If empty will be filled automatically by the next successful connection. An example input would be `SHA-256:83F9171E06A313118889F7D79302BD1B7A2042EE0CFD029ABF8DD06FFA6CD9D3`.
+- **username**: The MQTT username (since MQTT 3.1). Defaults to empty.
+- **password**: The MQTT password (since MQTT 3.1). Defaults to empty.
+- **certificatepin**: If this is set: After the next connection has been successfully established, the certificate is pinned. The connection will be refused if another certificate is used. Clear **certificate** to allow a new certificate for the next connection attempt. This option will increase security.
+- **publickeypin**: If this is set: After the next connection has been successfully established, the public key of the broker is pinned. The connection will be refused if another public key is used. Clear **publickey** to allow a new public key for the next connection attempt. This option will increase security.
+- **certificate**: The certificate hash. If **certificatepin** is set this hash is used to verify the connection. Clear to allow a new certificate pinning on the next connection attempt. If empty will be filled automatically by the next successful connection. An example input would be `SHA-256:83F9171E06A313118889F7D79302BD1B7A2042EE0CFD029ABF8DD06FFA6CD9D3`.
+- **publickey**: The public key hash. If **publickeypin** is set this hash is used to verify the connection. Clear to allow a new public key pinning on the next connection attempt. If empty will be filled automatically by the next successful connection. An example input would be `SHA-256:83F9171E06A313118889F7D79302BD1B7A2042EE0CFD029ABF8DD06FFA6CD9D3`.
By default discovery services (like homie or homeassistant) are enabled on a broker.
This behaviour can be controlled with a configuration parameter.
-* __enableDiscovery__:If set to true, enables discovery on this broker, if set to false, disables discovery services on this broker.
+- **enableDiscovery**:If set to true, enables discovery on this broker, if set to false, disables discovery services on this broker.
## Supported Channels
You can extend your broker connection bridges with a channel:
-* __publishTrigger__: This channel is triggered when a value is published to the configured MQTT topic on this broker connection. The event payload (in `receivedEvent`) will be the received MQTT topic and its value, separated by the hash character (`#`).
+- **publishTrigger**: This channel is triggered when a value is published to the configured MQTT topic on this broker connection. The event payload (in `receivedEvent`) will be the received MQTT topic and its value, separated by the hash character (`#`).
Configuration parameters are:
-* __stateTopic__: This channel will trigger on this MQTT topic. This topic can contain wildcards like + and # for example "all/in/#" or "sensors/+/config".
-* __payload__: An optional condition on the value of the MQTT topic that must match before this channel is triggered.
+- **stateTopic**: This channel will trigger on this MQTT topic. This topic can contain wildcards like + and # for example "all/in/#" or "sensors/+/config".
+- **payload**: An optional condition on the value of the MQTT topic that must match before this channel is triggered.
Note for new users - direct broker Bridge channels are rarely needed. You almost certainly will want to be using one of the binding extensions, or the generic Things and Channels features for most devices or services.
+# Xtend Examples
+
## Secure connection
In a first example a very secure connection to a broker is defined. It pins the returned certificate and public key.
If someone tries a man in the middle attack later on, this broker connection will recognize it and refuse a connection.
-Be aware that if your brokers certificate changes, you need to remove the connection entry and add it again.
+Be aware that if your brokers certificate changes, you need to remove the connection entry and add it again.
`mqttConnections.things`:
-```xtend
+```java
mqtt:broker:mySecureBroker [ host="192.168.0.41", secure=true, certificatepin=true, publickeypin=true ]
```
`mqttConnections.things`:
-```xtend
+```java
mqtt:broker:myUnsecureBroker [ host="192.168.0.42", secure=false ]
```
`mqttConnections.things`:
-```xtend
+```java
mqtt:broker:myAuthentificatedBroker [ host="192.168.0.43", secure=false, username="user", password="password" ]
```
-
## Public key pinning
In a fourth connection, the public key pinning is enabled again.
This time, a public key hash is provided to pin the connection to a specific server.
-It follows the form "hashname:hashvalue". Valid *hashnames* are SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 and all others listed
+It follows the form "hashname:hashvalue". Valid _hashnames_ are SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 and all others listed
in [Java MessageDigest Algorithms](https://docs.oracle.com/javase/9/docs/specs/security/standard-names.html#messagedigest-algorithms).
`mqttConnections.things`:
-```xtend
+```java
mqtt:broker:pinToPublicKey [ host="192.168.0.44", secure=true, publickeypin=true, publickey="SHA-256:9a6f30e67ae9723579da2575c35daf7da3b370b04ac0bde031f5e1f5e4617eb8" ]
```
# MyBMW Binding
The binding provides access like [MyBMW App](https://www.bmw.com/en/footer/mybmw-app.html) to openHAB.
-All vehicles connected to an account will be detected by the discovery with the correct type:
+All vehicles connected to an account will be detected by the discovery with the correct type:
-* Conventional Fuel Vehicle
-* Plugin-Hybrid Electrical Vehicle
-* Battery Electric Vehicle with Range Extender
-* Battery Electric Vehicle
+- Conventional Fuel Vehicle
+- Plugin-Hybrid Electrical Vehicle
+- Battery Electric Vehicle with Range Extender
+- Battery Electric Vehicle
In addition properties are attached with information and services provided by this vehicle.
-The provided data depends on
+The provided data depends on
-1. the [Thing Type](#things) and
-2. the [Properties](#properties) mentioned in Services
+1. the [Thing Type](#things) and
+1. the [Properties](#properties) mentioned in Services
Different channel groups are clustering all information.
Check for each group if it's supported by your vehicle.
-Please note **this isn't a real-time binding**.
-If a door is opened the state isn't transmitted and changed immediately.
-It's not a flaw in the binding itself because the state in BMW's own MyBMW App is also updated with some delay.
+Please note **this isn't a real-time binding**.
+If a door is opened the state isn't transmitted and changed immediately.
+It's not a flaw in the binding itself because the state in BMW's own MyBMW App is also updated with some delay.
## Supported Things
|----------------------------|----------------|------------------------------------------|
| MyBMW Account | `account` | Access to BMW API for a specific user |
-
### Things
-Four different vehicle types are provided.
-They differ in the supported channel groups & channels.
-Conventional Fuel Vehicles don't provide e.g. _Charging Profile_, Electric Vehicles don't provide a _Fuel Range_.
+Four different vehicle types are provided.
+They differ in the supported channel groups & channels.
+Conventional Fuel Vehicles don't provide e.g. _Charging Profile_, Electric Vehicles don't provide a _Fuel Range_.
For hybrid vehicles in addition to _Fuel and Electric Range_ the _Hybrid Range_ is shown.
-
+
| Name | Thing Type ID | Supported Channel Groups |
|-------------------------------------|---------------|---------------------------------------------------------------------|
| BMW Electric Vehicle | `bev` | Vehicle with electric drive train |
| BMW Plug-In-Hybrid Electric Vehicle | `phev` | Vehicle with combustion and electric drive train |
| BMW Conventional Vehicle | `conv` | Vehicle with combustion drive train |
-
#### Properties
<img align="right" src="./doc/vehicle-properties.png" width="500" height="350"/>
-For each vehicle properties are available.
+For each vehicle properties are available.
Basic information is given regarding
-* Vehicle properties like model type, drive train and construction year
-* Which services are available / not available
+- Vehicle properties like model type, drive train and construction year
+- Which services are available / not available
-In the right picture can see in *remoteServicesEnabled* e.g. the *Door Lock* and *Door Unlock* services are mentioned.
+In the right picture can see in _remoteServicesEnabled_ e.g. the _Door Lock_ and _Door Unlock_ services are mentioned.
This ensures channel group [Remote Services](#remote-services) is supporting door lock and unlock remote control.
-In *Services Supported* the entry *ChargingHistory* is mentioned.
+In _Services Supported_ the entry _ChargingHistory_ is mentioned.
So it's valid to connect channel group [Charge Sessions](#charge-sessions) in order to display your last charging sessions.
| Property Key | Property Value | Supported Channel Groups |
| servicesSupported | ChargingHistory | session |
| remoteServicesEnabled | _list of services_ | remote |
-
## Discovery
-Auto discovery is starting after the bridge is created.
+Auto discovery is starting after the bridge is created.
A list of your registered vehicles is queried and all found things are added in the inbox.
-Unique identifier is the *Vehicle Identification Number* (VIN).
+Unique identifier is the _Vehicle Identification Number_ (VIN).
If a thing is already declared in a _.things_ configuration, discovery won't highlight it again.
Properties will be attached to predefined vehicles if the VIN is matching.
### Bridge Configuration
-| Parameter | Type | Description |
+| Parameter | Type | Description |
|-----------------|---------|--------------------------------------------------------------------|
| userName | text | MyBMW Username |
| password | text | MyBMW Password |
The region Configuration has 3 different options
-* _NORTH_AMERICA_
-* _CHINA_
-* _ROW_ (Rest of World)
-
+- _NORTH_AMERICA_
+- _CHINA_
+- _ROW_ (Rest of World)
#### Advanced Configuration
-| Parameter | Type | Description |
+| Parameter | Type | Description |
|-----------------|---------|---------------------------------------------------------|
| language | text | Channel data can be returned in the desired language |
-Language is predefined as *AUTODETECT*.
+Language is predefined as _AUTODETECT_.
Some textual descriptions, date and times are delivered based on your local language.
You can overwrite this setting with lowercase 2-letter [language code reagrding ISO 639](https://www.oracle.com/java/technologies/javase/jdk8-jre8-suported-locales.html)
-So if want your UI in english language place *en* as desired language.
+So if want your UI in english language place _en_ as desired language.
### Thing Configuration
Same configuration is needed for all things
-| Parameter | Type | Description |
+| Parameter | Type | Description |
|-----------------|---------|---------------------------------------|
| vin | text | Vehicle Identification Number (VIN) |
| refreshInterval | integer | Refresh Interval in Minutes |
-
#### Advanced Configuration
-| Parameter | Type | Description |
+| Parameter | Type | Description |
|-----------------|---------|-----------------------------------|
| vehicleBrand | text | Vehicle Brand like BMW or Mini |
The _vehicleBrand_ is automatically obtained by the discovery service and shall not be changed.
If thing is defined manually via *.things file following brands are supported
-* BMW
-* MINI
-
+- BMW
+- MINI
## Channels
-There are many channels available for each vehicle.
+There are many channels available for each vehicle.
For better overview they are clustered in different channel groups.
They differ for each vehicle type, build-in sensors and activated services.
-
-### Thing Channel Groups
+### Thing Channel Groups
| Channel Group ID | Description | conv | phev | bev_rex | bev |
|----------------------------------|---------------------------------------------------|------|------|---------|-----|
| [tires](#tire-pressure) | Current and wanted pressure for all tires | X | X | X | X |
| [image](#image) | Provides an image of your vehicle | X | X | X | X |
-
#### Vehicle Status
Reflects overall status of the vehicle.
-* Channel Group ID is **status**
-* Available for all vehicles
-* Read-only values
+- Channel Group ID is **status**
+- Available for all vehicles
+- Read-only values
| Channel Label | Channel ID | Type | Description | conv | phev | bev_rex | bev |
|---------------------------|---------------------|---------------|------------------------------------------------|------|------|---------|-----|
Overall Door Status values
-* _Closed_ - all doors closed
-* _Open_ - at least one door is open
-* _Undef_ - no door data delivered at all
+- _Closed_ - all doors closed
+- _Open_ - at least one door is open
+- _Undef_ - no door data delivered at all
Overall Windows Status values
-* _Closed_ - all windows closed
-* _Open_ - at least one window is completely open
-* _Intermediate_ - at least one window is partially open
-* _Undef_ - no window data delivered at all
+- _Closed_ - all windows closed
+- _Open_ - at least one window is completely open
+- _Intermediate_ - at least one window is partially open
+- _Undef_ - no window data delivered at all
Check Control values
Localized String of current active warnings.
Examples:
-* No Issues
-* Multiple Issues
+- No Issues
+- Multiple Issues
Charging Status values
-* _Not Charging_
-* _Charging_
-* _Plugged In_
-* _Fully Charged_
+- _Not Charging_
+- _Charging_
+- _Plugged In_
+- _Fully Charged_
Charging Information values
Localized String of current active charging session
Examples
-* 100% at ~00:43
-* Starts at ~09:00
+- 100% at ~00:43
+- Starts at ~09:00
##### Vehicle Status Raw Data
The _raw data channel_ is marked as _advanced_ and isn't shown by default.
Target are advanced users to derive even more data out of BMW API replies.
-As the replies are formatted as JSON use the [JsonPath Transformation Service](https://www.openhab.org/addons/transformations/jsonpath/) to extract data for an item,
+As the replies are formatted as JSON use the [JsonPath Transformation Service](https://www.openhab.org/addons/transformations/jsonpath/) to extract data for an item,
| Channel Label | Channel ID | Type | Description |
|---------------------------|---------------------|---------------|------------------------------------------------|
Examples:
-_Country ISO Code_
+###### Country ISO Code
-```
+```json
$.properties.originCountryISO
```
-_Drivers Guide URL_
+###### Drivers Guide URL
-```
+```json
$.driverGuideInfo.androidStoreUrl
```
#### Range Data
-Based on vehicle type some channels are present or not.
-Conventional fuel vehicles don't provide *Electric Range* and battery electric vehicles don't show *Fuel Range*.
-Hybrid vehicles have both and in addition *Hybrid Range*.
+Based on vehicle type some channels are present or not.
+Conventional fuel vehicles don't provide _Electric Range_ and battery electric vehicles don't show _Fuel Range_.
+Hybrid vehicles have both and in addition _Hybrid Range_.
See description [Range vs Range Radius](#range-vs-range-radius) to get more information.
-* Channel Group ID is **range**
-* Availability according to table
-* Read-only values
+- Channel Group ID is **range**
+- Availability according to table
+- Read-only values
| Channel Label | Channel ID | Type | conv | phev | bev_rex | bev |
|---------------------------|-------------------------|----------------------|------|------|---------|-----|
| Mileage | mileage | Number:Length | X | X | X | X |
| Fuel Range | range-fuel | Number:Length | X | X | X | |
-| Electric Range | range-electric | Number:Length | | X | X | X |
-| Hybrid Range | range-hybrid | Number:Length | | X | X | |
+| Electric Range | range-electric | Number:Length | | X | X | X |
+| Hybrid Range | range-hybrid | Number:Length | | X | X | |
| Battery Charge Level | soc | Number:Dimensionless | | X | X | X |
-| Remaining Fuel | remaining-fuel | Number:Volume | X | X | X | |
-| Fuel Range Radius | range-radius-fuel | Number:Length | X | X | X | |
-| Electric Range Radius | range-radius-electric | Number:Length | | X | X | X |
-| Hybrid Range Radius | range-radius-hybrid | Number:Length | | X | X | |
-
+| Remaining Fuel | remaining-fuel | Number:Volume | X | X | X | |
+| Fuel Range Radius | range-radius-fuel | Number:Length | X | X | X | |
+| Electric Range Radius | range-radius-electric | Number:Length | | X | X | X |
+| Hybrid Range Radius | range-radius-hybrid | Number:Length | | X | X | |
#### Doors Details
Detailed status of all doors and windows.
-* Channel Group ID is **doors**
-* Available for all vehicles if corresponding sensors are built-in
-* Read-only values
-
-| Channel Label | Channel ID | Type |
+- Channel Group ID is **doors**
+- Available for all vehicles if corresponding sensors are built-in
+- Read-only values
+
+| Channel Label | Channel ID | Type |
|----------------------------|-------------------------|---------------|
| Driver Door | driver-front | String |
| Driver Door Rear | driver-rear | String |
Possible states
-* _Undef_ - no status data available
-* _Invalid_ - this door / window isn't applicable for this vehicle
-* _Closed_ - the door / window is closed
-* _Open_ - the door / window is open
-* _Intermediate_ - window in intermediate position, not applicable for doors
-
+- _Undef_ - no status data available
+- _Invalid_ - this door / window isn't applicable for this vehicle
+- _Closed_ - the door / window is closed
+- _Open_ - the door / window is open
+- _Intermediate_ - window in intermediate position, not applicable for doors
#### Check Control
Group for all current active Check Control messages.
If more than one message is active the channel _name_ contains all active messages as options.
-* Channel Group ID is **check**
-* Available for all vehicles
-* Read/Write access
+- Channel Group ID is **check**
+- Available for all vehicles
+- Read/Write access
| Channel Label | Channel ID | Type | Access |
|---------------------------------|---------------------|----------------|------------|
Severity Levels
-* Ok
-* Low
-* Medium
-
+- Ok
+- Low
+- Medium
#### Services
Group for all upcoming services with description, service date and/or service mileage.
If more than one service is scheduled in the future the channel _name_ contains all future services as options.
-* Channel Group ID is **service**
-* Available for all vehicles
-* Read/Write access
+- Channel Group ID is **service**
+- Available for all vehicles
+- Read/Write access
| Channel Label | Channel ID | Type | Access |
|--------------------------------|---------------------|----------------|------------|
| Service Date | date | DateTime | Read |
| Mileage till Service | mileage | Number:Length | Read |
-
#### Location
GPS location and heading of the vehicle.
-* Channel Group ID is **location**
-* Available for all vehicles with built-in GPS sensor. Function can be enabled/disabled in the head unit
-* Read-only values
+- Channel Group ID is **location**
+- Available for all vehicles with built-in GPS sensor. Function can be enabled/disabled in the head unit
+- Read-only values
-| Channel Label | Channel ID | Type |
+| Channel Label | Channel ID | Type |
|---------------------|---------------------|---------------|
-| GPS Coordinates | gps | Location |
-| Heading | heading | Number:Angle |
-| Address | address | String |
-| Distance from Home | home-distance | Number:Length |
+| GPS Coordinates | gps | Location |
+| Heading | heading | Number:Angle |
+| Address | address | String |
+| Distance from Home | home-distance | Number:Length |
#### Remote Services
-Remote control of the vehicle.
-Send a *command* to the vehicle and the *state* is reporting the execution progress.
+Remote control of the vehicle.
+Send a _command_ to the vehicle and the _state_ is reporting the execution progress.
Only one command can be executed each time.
Parallel execution isn't supported.
-* Channel Group ID is **remote**
-* Available for all commands mentioned in *Services Activated*. See [Vehicle Properties](#properties) for further details
-* Read/Write access
-
+- Channel Group ID is **remote**
+- Available for all commands mentioned in _Services Activated_. See [Vehicle Properties](#properties) for further details
+- Read/Write access
| Channel Label | Channel ID | Type | Access |
|-------------------------|---------------------|---------|--------|
The channel _command_ provides options
-* _flash-lights_
-* _vehicle-finder_
-* _door-lock_
-* _door-unlock_
-* _horn-low_
-* _climate-now-start_
-* _climate-now-stop_
+- _flash-lights_
+- _vehicle-finder_
+- _door-lock_
+- _door-unlock_
+- _horn-low_
+- _climate-now-start_
+- _climate-now-stop_
The channel _state_ shows the progress of the command execution in the following order
-1) _initiated_
-2) _pending_
-3) _delivered_
-4) _executed_
-
+1. _initiated_
+1. _pending_
+1. _delivered_
+1. _executed_
#### Charge Profile
Charging options with date and time for preferred time windows and charging modes.
-* Channel Group ID is **profile**
-* Available for electric and hybrid vehicles
-* Read access for UI.
-* There are 4 timers *T1, T2, T3 and T4* available. Replace *X* with number 1,2 or 3 to target the correct timer
-
-| Channel Label | Channel ID | Type |
-|----------------------------|---------------------------|----------|
-| Charge Mode | mode | String |
-| Charge Preferences | prefs | String |
-| Charging Plan | control | String |
-| SoC Target | target | String |
-| Charging Energy Limited | limit | Switch |
-| Window Start Time | window-start | DateTime |
-| Window End Time | window-end | DateTime |
-| A/C at Departure | climate | Switch |
-| T*X* Enabled | timer*X*-enabled | Switch |
-| T*X* Departure Time | timer*X*-departure | DateTime |
-| T*X* Monday | timer*X*-day-mon | Switch |
-| T*X* Tuesday | timer*X*-day-tue | Switch |
-| T*X* Wednesday | timer*X*-day-wed | Switch |
-| T*X* Thursday | timer*X*-day-thu | Switch |
-| T*X* Friday | timer*X*-day-fri | Switch |
-| T*X* Saturday | timer*X*-day-sat | Switch |
-| T*X* Sunday | timer*X*-day-sun | Switch |
+- Channel Group ID is **profile**
+- Available for electric and hybrid vehicles
+- Read access for UI.
+- There are 4 timers _T1, T2, T3 and T4_ available. Replace _X_ with number 1,2 or 3 to target the correct timer
+
+| Channel Label | Channel ID | Type |
+|----------------------------|---------------------------|----------|
+| Charge Mode | mode | String |
+| Charge Preferences | prefs | String |
+| Charging Plan | control | String |
+| SoC Target | target | String |
+| Charging Energy Limited | limit | Switch |
+| Window Start Time | window-start | DateTime |
+| Window End Time | window-end | DateTime |
+| A/C at Departure | climate | Switch |
+| T_X_ Enabled | timer_X_-enabled | Switch |
+| T_X_ Departure Time | timer_X_-departure | DateTime |
+| T_X_ Monday | timer_X_-day-mon | Switch |
+| T_X_ Tuesday | timer_X_-day-tue | Switch |
+| T_X_ Wednesday | timer_X_-day-wed | Switch |
+| T_X_ Thursday | timer_X_-day-thu | Switch |
+| T_X_ Friday | timer_X_-day-fri | Switch |
+| T_X_ Saturday | timer_X_-day-sat | Switch |
+| T_X_ Sunday | timer_X_-day-sun | Switch |
The channel _profile-mode_ supports
-* *immediateCharging*
-* *delayedCharging*
+- _immediateCharging_
+- _delayedCharging_
The channel _profile-prefs_ supports
-* *noPreSelection*
-* *chargingWindow*
-
+- _noPreSelection_
+- _chargingWindow_
#### Charge Statistics
Shows charge statistics of the current month
-* Channel Group ID is **statistic**
-* Available for electric and hybrid vehicles
-* Read-only values
-
-| Channel Label | Channel ID | Type |
+- Channel Group ID is **statistic**
+- Available for electric and hybrid vehicles
+- Read-only values
+
+| Channel Label | Channel ID | Type |
|----------------------------|-------------------------|----------------|
| Charge Statistic Month | title | String |
| Energy Charged | energy | Number:Energy |
| Charge Sessions | sessions | Number |
-
#### Charge Sessions
Group for past charging sessions.
If more than one message is active the channel _name_ contains all active messages as options.
-* Channel Group ID is **session**
-* Available for electric and hybrid vehicles
-* Read-only values
+- Channel Group ID is **session**
+- Available for electric and hybrid vehicles
+- Read-only values
| Channel Label | Channel ID | Type |
|---------------------------------|--------------|----------|
| Issues during Session | issue | String |
| Session Status | status | String |
-
#### Tire Pressure
Current and target tire pressure values
-* Channel Group ID is **tires**
-* Available for all vehicles if corresponding sensors are built-in
-* Read-only values
-
-| Channel Label | Channel ID | Type |
+- Channel Group ID is **tires**
+- Available for all vehicles if corresponding sensors are built-in
+- Read-only values
+
+| Channel Label | Channel ID | Type |
|----------------------------|-------------------------|------------------|
| Front Left | fl-current | Number:Pressure |
| Front Left Target | fl-target | Number:Pressure |
| Rear Right | rr-current | Number:Pressure |
| Rear Right Target | rr-target | Number:Pressure |
-
#### Image
-Image representation of the vehicle.
+Image representation of the vehicle.
-* Channel Group ID is **image**
-* Available for all vehicles
-* Read/Write access
+- Channel Group ID is **image**
+- Available for all vehicles
+- Read/Write access
| Channel Label | Channel ID | Type | Access |
|----------------------------|---------------------|--------|----------|
Possible view ports:
-* _VehicleStatus_ Front Side View
-* _VehicleInfo_ Front View
-* _ChargingHistory_ Side View
-* _Default_ Front Side View
-
+- _VehicleStatus_ Front Side View
+- _VehicleInfo_ Front View
+- _ChargingHistory_ Side View
+- _Default_ Front Side View
## Further Descriptions
There are 3 occurrences of dynamic data delivered
-* Upcoming Services delivered in group [Services](#services)
-* Check Control Messages delivered in group [Check Control](#check-control)
-* Charging Session data delivered in group [Charge Sessions](#charge-sessions)
+- Upcoming Services delivered in group [Services](#services)
+- Check Control Messages delivered in group [Check Control](#check-control)
+- Charging Session data delivered in group [Charge Sessions](#charge-sessions)
-The channel id _name_ shows the first element as default.
-All other possibilities are attached as options.
-The picture on the right shows the _Session Title_ item and 3 possible options.
+The channel id _name_ shows the first element as default.
+All other possibilities are attached as options.
+The picture on the right shows the _Session Title_ item and 3 possible options.
Select the desired service and the corresponding Charge Session with _Energy Charged_, _Session Status_ and _Session Issues_ will be shown.
### TroubleShooting
BMW has a high range of vehicles supported by their API.
-In case of any issues with this binding help to resolve it!
+In case of any issues with this binding help to resolve it!
Please perform the following steps:
-* Can you log into MyBMW App with your credentials?
-* Is the vehicle listed in your account?
-* Is the [MyBMW Brige](#bridge) status _Online_?
+- Can you log into MyBMW App with your credentials?
+- Is the vehicle listed in your account?
+- Is the [MyBMW Brige](#bridge) status _Online_?
-If these preconditions are fulfilled proceed with the fingerprint generation.
+If these preconditions are fulfilled proceed with the fingerprint generation.
#### Generate Debug Fingerprint
<img align="right" src="./doc/DiscoveryScan.png" width="400" height="350"/>
-
First [enable debug logging](https://www.openhab.org/docs/administration/logging.html#defining-what-to-log) for the binding.
-```
+```shell
log:set DEBUG org.openhab.binding.mybmw
```
Personal data is eliminated from the log entries so it should be possible to share them in public.
Data like
-* Vehicle Identification Number (VIN)
-* Location data
+- Vehicle Identification Number (VIN)
+- Location data
are anonymized.
You'll find the fingerprint in the logs with the command
-```
+```shell
grep "Discovery Fingerprint Data" openhab.log
```
After the corresponding fingerprint is generated please [follow the instructions to raise an issue](https://community.openhab.org/t/how-to-file-an-issue/68464) and attach the fingerprint data!
Your feedback is highly appreciated!
-
### Range vs Range Radius
<img align="right" src="./doc/range-radius.png" width="400" height="350"/>
-You will observe differences in the vehicle range and range radius values.
+You will observe differences in the vehicle range and range radius values.
While range is indicating the possible distance to be driven on roads the range radius indicates the reachable range on the map.
-The right picture shows the distance between Kassel and Frankfurt in Germany.
+The right picture shows the distance between Kassel and Frankfurt in Germany.
While the air-line distance is 145 kilometers the route distance is 192 kilometers.
So range value is the normal remaining range while the range radius values can be used e.g. on [Mapview](https://www.openhab.org/docs/ui/sitemaps.html#element-type-mapview) to indicate the reachable range on map.
Please note this is just an indicator of the effective range.
-Especially for electric vehicles it depends on many factors like driving style and usage of electric consumers.
+Especially for electric vehicles it depends on many factors like driving style and usage of electric consumers.
## Full Example
-The example is based on a BMW i3 with range extender (REX).
+The example is based on a BMW i3 with range extender (REX).
Exchange configuration parameters in the Things section
-* 4711 - any id you want
-* YOUR_USERNAME - with your MyBMW login username
-* YOUR_PASSWORD - with your MyBMW password credentials
-* VEHICLE_VIN - the vehicle identification number
+- 4711 - any id you want
+- YOUR_USERNAME - with your MyBMW login username
+- YOUR_PASSWORD - with your MyBMW password credentials
+- VEHICLE_VIN - the vehicle identification number
-In addition search for all occurrences of *i3* and replace it with your Vehicle Identification like *x3* or *535d* and you're ready to go!
+In addition search for all occurrences of _i3_ and replace it with your Vehicle Identification like _x3_ or _535d_ and you're ready to go!
### Things File
-```
+```java
Bridge mybmw:account:4711 "MyBMW Account" [userName="YOUR_USERNAME",password="YOUR_PASSWORD",region="ROW"] {
Thing bev_rex i3 "BMW i3 94h REX" [ vin="VEHICLE_VIN",refreshInterval=5,vehicleBrand="BMW"]
}
### Items File
-```
+```java
Number:Length i3Mileage "Odometer [%d %unit%]" <line> (i3) {channel="mybmw:bev_rex:4711:i3:range#mileage" }
Number:Length i3Range "Range [%d %unit%]" <motion> (i3) {channel="mybmw:bev_rex:4711:i3:range#hybrid"}
Number:Length i3RangeElectric "Electric Range [%d %unit%]" <motion> (i3,long) {channel="mybmw:bev_rex:4711:i3:range#electric"}
### Sitemap File
-```
+```perl
sitemap BMW label="BMW" {
Frame label="BMW i3" {
Image item=i3Image
## Credits
-This work is based on the project of [Bimmer Connected](https://github.com/bimmerconnected/bimmer_connected).
-
+This work is based on the project of [Bimmer Connected](https://github.com/bimmerconnected/bimmer_connected).
- React to all the aforementioned events ...
- ... and send/receive any other kind of messages on the message bus
-
## Supported Things
The only thing managed by this binding is a Mycroft instance
|--------------------|----------------------------------------------------------------------------|
| mycroft | A Mark I/II, a Picroft, or any other variant exposing the message bus |
-
-
## Discovery
There is no discovery service, as Mycroft doesn't announce itself on the network.
-
## Thing Configuration
The configuration is simple, as you just need to give the IP/hostname of the Mycroft instance accessible on the network.
The default port is 8181, which can be changed.
-```
+```java
Thing mycroft:mycroft:myMycroft "Mycroft A.I." @ "Living Room" [host="192.168.X.X"]
```
| port | integer | Port to reach Mycroft (default 8181) | No |
| volume_restoration_level | integer | When unmuted, force Mycroft to restore volume to this value | No |
-
## Channels
A Mycroft thing has the following channels:
-
| channel type id | Item type | description |
|------------------------------|-----------|------------------------------------------------------------------------------------------------|
| listen | Switch | Switch to ON when Mycroft is listening. Can simulate a wake word detection to trigger the STT |
| volume | Dimmer | The volume of the Mycroft speaker. (Note : Value unreliable until a volume change occured) |
| full_message | String | The last message (full json) seen on the Mycroft Bus. Filtered by the messageTypes properties |
-
The channel 'full_message' has the following configuration available:
| property | type | description | mandatory |
|---------------|---------------------------------|-------------------------------------------------------------------------|-----------|
| messageTypes | List of string, comma separated | Only these message types will be forwarded to the Full Message Channel | No |
-
## Full Example
A manual setup through a `things/mycroft.things` file could look like this:
A `demo.sitemap` file:
-```
+```perl
sitemap demo label="myMycroft"
{
Frame label="myMycroft" {
}
```
-
### Ask Mycroft to say something
mycroft.rules
### Thing Configuration
-```xtend
+```java
Bridge myq:account:home "MyQ Account" [ username="foo@bar.com", password="secret", refreshInterval=60 ] {
Thing garagedoor abcd12345 "MyQ Garage Door" [ serialNumber="abcd12345" ]
Thing lamp efgh6789 "MyQ Lamp" [ serialNumber="efgh6789" ]
### Items
-```xtend
+```java
String MyQGarageDoor1Status "Door Status [%s]" {channel = "myq:garagedoor:home:abcd12345:status"}
Switch MyQGarageDoor1Switch "Door Switch [%s]" {channel = "myq:garagedoor:home:abcd12345:switch"}
Switch MyQGarageDoor1CloseError "Door Close Error [%s]" {channel = "myq:garagedoor:home:abcd12345:closeError"}
### Sitemaps
-```xtend
+```perl
sitemap MyQ label="MyQ Demo Sitemap" {
Frame label="Garage Door" {
String item=MyQGarageDoor1Status
This extension does not support autodiscovery. The things need to be added manually.
-
## Thing Configuration
The following parameters are valid for all thing types:
### Thing Configuration
-```
+```java
Thing mystrom:mystromplug:d6217a31 "Plug" [hostname="hostname|ip"]
```
### Item Configuration
-```
-Switch PlugSwitch "Plug" {channel="mystrom:mystromplug:d6217a31:switch"}
+```java
+Switch PlugSwitch "Plug" {channel="mystrom:mystromplug:d6217a31:switch"}
Number:Temperature PlugTemperature "Temperature: [%.1f °C]" {channel="mystrom:mystromplug:d6217a31:temperature"}
Number:Power PlugPower "Power: [%.1f W]" {channel="mystrom:mystromplug:d6217a31:power"}
### Sitemap Configuration
-```
+```perl
Frame label="myStrom Plug" {
Switch item=PlugSwitch
Text item=PlugTemperature
projects / openhab-addons.git / commitdiff