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

updated generated content 

Signed-off-by: Kai Kreuzer <kai@openhab.org>
pull/500/head
Kai Kreuzer 2017-09-16 00:07:59 +02:00
parent 2dc0ff08cf
commit cbef9ece2d
No known key found for this signature in database
GPG Key ID: 5110767B6248D3C0
24 changed files with 575 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
_bindings/allplay/readme.md
View File

@ -53,9 +53,10 @@ AllPlay Players are identified by their device ID (e.g. 9fbe37ca-d015-47a2-b76e-
| Parameter Label | Parameter ID | Description | Required | Default |
|-----------------|--------------|-------------|----------|---------|
| Device ID | deviceId | The device identifier identifies one certain speaker| true | |
| Device Name | deviceName | The device name of the speaker| false | |
| Volume step size | volumeStepSize | Step size to use if the volume is changed using the increase/decrease command.| true | 1 |
| Device ID | deviceId | The device identifier identifies one certain speaker | true | |
| Device Name | deviceName | The device name of the speaker | false | |
| Volume step size | volumeStepSize | Step size to use if the volume is changed using the increase/decrease command | true | 1 |
| Zone Member Separator | zoneMemberSeparator | Separator which is used when sending multiple zone members to channel 'zonemembers' | true | , |
## Channels
@ -64,6 +65,7 @@ The devices support the following channels:
| Channel Type ID | Item Type | Description |
|-----------------|--------------|--------------|
| clearzone | Switch | Remove the current speaker from the zone |
| control | Player | Control the speaker, play/pause/next/previous/ffward/rewind |
| coverart | Image | Image data of cover art of the current song |
| coverarturl | String | URL of the cover art of the current song |
@ -74,8 +76,9 @@ The devices support the following channels:
| currenttitle | String | Title of the track currently playing |
| currenturl | String | URL of the track or radio station currently playing |
| currentuserdata | String | Custom user data (e.g. name of radio station) of the track currently playing |
| input | String | Input of the speaker, e.g. Line-In (not supported by all speakers) |
| loopmode | String | Loop mode of the speaker (ONE, ALL, NONE) |
| mute | Switch | Set or get the mute state of the master volume of the speaker |
| mute | Switch | Set or get the mute state of the master volume of the speaker (not supported by all speakers) |
| playstate | String | State of the Speaker, e.g. PLAYING, STOPPED,.. |
| shufflemode | Switch | Toggle the shuffle mode of the speaker |
| stop | Switch | Stop the playback |
@ -83,6 +86,7 @@ The devices support the following channels:
| volume | Dimmer | Get and set the volume of the speaker |
| volumecontrol | Switch | Flag if the volume control is enabled (might be disabled if speaker is not master of the zone) |
| zoneid | String | Id of the Zone the speaker belongs to |
| zonemembers | String | Set the zone members by providing a comma-separated list of device names. (This channel is currently only for setting the zone members. It does not update automatically if the zone members are changed from another source) |
## Audio Support

2
_bindings/astro/readme.md
View File

@ -65,7 +65,7 @@ Optionally, a refresh `interval` (in seconds) can be defined to also calculate p
* `total, partial, ring` (DateTime)
* **group** `phase`
* **channel**
* `name` (String), values: `SUN_RISE, ASTRO_DAWN, NAUTIC_DAWN, CIVIL_DAWN, CIVIL_DUSK, NAUTIC_DUSK, ASTRO_DUSK, SUN_SET, DAYLIGHT, NOON, NIGHT`
* `name` (String), values: `SUN_RISE, ASTRO_DAWN, NAUTIC_DAWN, CIVIL_DAWN, CIVIL_DUSK, NAUTIC_DUSK, ASTRO_DUSK, SUN_SET, DAYLIGHT, NIGHT`
* **thing** `moon`
* **group** `rise, set`
* **channel**

2
_bindings/avmfritz/readme.md
View File

@ -34,7 +34,7 @@ This [DECT repeater](https://avm.de/produkte/fritzdect/fritzdect-repeater-100/)
### FRITZ!Powerline 546E
This [powerline adapter](http://avm.de/produkte/fritzpowerline/fritzpowerline-546e/) can be used via the bridge or in standalone mode. It supports switching the outlet and current power and energy consumption readings. This device does not contain a temperature sensor.
This [powerline adapter](http://avm.de/produkte/fritzpowerline/fritzpowerline-546e/) can be used via the bridge or in stand-alone mode. It supports switching the outlet and current power and energy consumption readings. This device does not contain a temperature sensor.
### FRITZ!DECT 300 / Comet DECT

138
_bindings/dmx/readme.md Normal file
View File

@ -0,0 +1,138 @@
---
id: dmx
label: DMX
title: DMX - Bindings
type: binding
description: "The DMX binding integrates DMX devices. There are different output devices supported as well as Dimmers and Chasers."
since: 2x
install: auto
---
<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->
{% include base.html %}
# DMX Binding
The DMX binding integrates DMX devices. There are different output devices supported as well as Dimmers and Chasers.
Each output device (bridges) is representing exactly one universe, each thing is bound to a bridge. At least one bridge and one thing is needed for the binding to work properly.
## Supported Things
### Bridges
Two DMX over Ethernet devices are supported as DMX output: ArtNet and sACN/E1.31. The ArtNet bridge can only be operated in unicast mode (broadcast mode is not supported as the specification recommends using it if more than 40 nodes are connected, which is unlikely in the case of a smarthome). The sACN bridge supports both, unicast and multicast.
Additionally Lib485 devices are supported via the Lib485 bridge.
### Things
The most generic thing is a dimmer. A dimmer can contain one or more DMX channels and be bound to Switch, Dimmer and Color items (Color item is supported if at least three DMX channels are defined). If more than one DMX channel is defined, the item will be updated according to the state of the first DMX channel (or the first three, in case of the Color item).
The second supported thing is a chaser. It can contain one or more DMX channels and bound to Switch items only. If the thing receives an ON command all running fades in all channels are either suspended (if resumeAfter is set to true) or cleared and replaced with the fades defined in this thing. An OFF command stops the fades and either restores the previously suspended fades (if resumeAfter is set to true) or just holds the current values. If any of the DMX channels in a chaser receives a command from another thing, the status of the chaser is updated to OFF. Chaser things define a control channel that can be used to dynamically change the chasers fade configuration.
## Discovery
Discovery is not supported at the moment. You have to add all bridges and things manually.
## Thing Configuration
Since the brightness perception of the human eye is not linear, all bridges support `applycurve`, a list of channels `applycurve` that have a CIE 1931 lightness correction (cf. [Poynton, C.A.: “Gamma” and its Disguises: The Nonlinear Mappings of Intensity in Perception, CRTs, Film and Video, SMPTE Journal Dec. 1993, pp. 1099 - 1108](http://www.poynton.com/PDFs/SMPTE93_Gamma.pdf)) applied. This list follows the format of the thing channel definition. This is used regardless of the thing(s) that are associated to the channel.
All bridges can make use of the `refreshrate` option. It determines at what frequency the DMX output is refreshed. The achievable refresh rate depends on the number of channels and the output type. A value of `0` disables the output, the default value is 30 Hz.
### ArtNet Bridge (`artnet-bridge`)
The ArtNet bridge has one mandatory configuration value: network address (`address`). The network address defines the IP address of the receiving node, it is also allowed to use a FQDN if DNS resolution is available. If necessary the default port 6454 can be changed by adding `:<port>` to the address. Multiple receivers can be added, separated by a comma.
The universe (`universe`) can range from 0-32767, this value defaults to 0.
There are two more configuration values that usually don't need to be touched. The address and port of the sender will be automatically selected by the kernel, if they need to be set to a fixed value, this can be done with `localaddress`. The format is identical to the receiver address. Unlike DMX512-A (E1.11), the ArtNet standard allows to suppress repeated transmissions of unchanged universes for a certain time. This is enabled by default and will re-transmit unchanged data with a fixed refresh rate of 800ms. If for some reason continuous transmission is needed, the `refreshmode` can be set to `always`, opposed to the default `standard`.
### Lib485 Bridge (`lib485-bridge`)
The Lib385 bridge has one mandatory configuration value: network address (`address`). This is the host/port where lib485 is running. This can be an IP address but it is also allowed to use a FQDN if DNS resolution is available. If necessary the default port 9020 can be changed by adding `:<port>` to the address. The default address is localhost. Multiple receivers can be added, separated by a comma.
### sACN/E1.31 Bridge (`sacn-bridge`)
The sACN bridge has one mandatory configuration value: transmission mode (`mode`). The transmission mode can be set to either `unicast` or `multicast`, where the later one is the default value. If unicast mode is selected, it is mandatory to define the network address (`address`) of the receiving node. This can be an IP address but it is also allowed to use a FQDN if DNS resolution is available. If necessary the default port 5568 can be changed by adding `:<port>` to the address. Multiple receivers can be added, separated by a comma.
The universe (`universe`) can range from 1-63999, this value defaults to 1.
There are some more configuration values that usually don't need to be touched. The address and port of the sender will be automatically selected by the kernel, if they need to be set to a fixed value, this can be done with `localaddress`. The format is identical to the receiver address.
Unlike DMX512-A (E1.11), the E1.31 standard allows to suppress repeated transmissions of unchanged universes for a certain time. This is enabled by default and will re-transmit unchanged data with a fixed refresh rate of 800ms. If for some reason continuous transmission is needed, the `refreshmode` can be set to `always`, opposed to the default `standard`.
### Chaser Thing (`chaser`)
There are two mandatory configuration values for a chaser thing: the `dmxid` and `steps`.
The `dmxid` is a list of DMX channels that are associated with this thing. There are several possible formats: `channel,channel,channel,...` or `channel/width` or a combination of both.
The `steps` value is a list of steps that shall be run by the chaser. The format of a single step is `fadetime:value,value2, ...:holdtime`, two or more steps are concatenated by `step1|step2|...`. In textual configuration line-breaks, spaces and tabs are allowed for readability. The fadetime is used for fading from the current value to the new value. In contrast to the dimmer thing, this is an absolute value. The hold time defines how long this step shall wait before advancing to the next step. A value of -1 is used to hold forever. Both times are in ms.
An optional configuration value is `resumeafter`. It defaults to false but if set to true, the original state of the channel (including running fades) will be suspended until the chaser receives an OFF command.
### Dimmer Thing (`dimmer`)
The only mandatory configuration value for a dimmer thing is the `dmxid`, a list of DMX channels that are associated with this thing. There are several possible formats: `channel1,channel2,channel3,...` or `channel/width` or a combination of both.
The `fadetime` option allows a smooth fading from the current to the new value. The time unit is ms and the interval is for a fade from 0-100%. If the current value is 25% and the new value is 75% the time needed for this change is half of `fadetime`. Related is the `dimtime` option. It defines the time in ms from 0-100% if incremental dimmming is used.
Advanced options are the `turnonvalue`and the `turnoffvalue`. They default to 255 (equals 100%) and 0 (equals 0%) respectively. This value can be set individually for all DMX channels, the format is `value1,value2, ...` with values from 0 to 255. If less values than DMX channels are defined, the values will be re-used from the beginning (i.e. if two values are defined, value1 will be used for channel1, channel3, ... and value2 will be used for channel2, channel4, ...). These values will be used if the thing receives an ON or OFF command.
## Channels
| Type-ID | Thing | Item | Description |
|-------------|--------------|---------------|------------------------------------------|
|brightness |dimmer |Switch, Dimmer | controls the brightness of the channels |
|color |dimmer |Color | allows to set the color of the dimmer |
|control |chaser |String | allows to change the chaser steps |
|switch |dimmer,chaser |Switch | turns the channel/chaser ON or OFF |
|mute |(all bridges) |Switch | mutes the DMX output of the bridge |
*Note:* the string send to the control channel of chaser things has to be formatted like the `steps` configuration of the chaser thing. If the new string is invalid, the old configuration will be used.
*Note*: the `color`channel is only available on dimmer things that have a channel count of three or a multiple of three.
## Full Example
This example defines a sACN/E1.31 bridge in unicast mode which transmits universe 2 and three things: a three channel dimmer used to control a RGB light, a single channel dimmer which will turn on only to 90% if it receives a ON command and a chaser which changes the colors like a traffic light.
### demo.things:
```
Bridge dmx:sacn-bridge:mybridge [ mode="unicast", address="192.168.0.60", universe=2] {
dimmer rgb [ dmxid="5/3", fade=1000]
dimmer single [dmxid="50", fade=1000, turnonvalue="230" ]
chaser ampel [dmxid="10,12,13", steps="100:255,0,0:1000|100:255,255,0:500|100:0,0,255:1000|100:0,255,0:500]"]
}
```
### demo.items:
```
Color MyColorItem "My Color Item" { channel="dmx:dimmer:rgb:color" }
Dimmer MyDimmerItem "My Dimmer Item" { channel="dmx:dimmer:single:brightness" }
Switch MyChaserItem "My Chaser Item" { channel="dmx:dimmer:chaser:ampel" }
```
### demo.sitemap:
```
sitemap demo label="Main Menu"
{
Frame {
// Color
Colorpicker item=MyColorItem
// Dimmer
Switch item=MyDimmerItem
Slider item=1MyDimmerItem
// Chaser
Switch item=MyChaserItem
}
}
```

3
_bindings/fritzboxtr0641/readme.md
View File

@ -60,7 +60,10 @@ This binding can be configured in the file `services/fritzboxtr064.cfg`.
```
String fboxName "FBox Model [%s]" {fritzboxtr064="modelName"}
# get wan ip if FritzBox establishes the internet connection (e. g. via DSL)
String fboxWanIP "FBox WAN IP [%s]" {fritzboxtr064="wanip"}
# get wan ip if FritzBox uses internet connection of external router
String fboxWanIPExternal "FBox external WAN IP [%s]" {fritzboxtr064="externalWanip"}
Switch fboxWifi24 "2,4GHz Wifi" {fritzboxtr064="wifi24Switch"}
Switch fboxWifi50 "5,0GHz Wifi" {fritzboxtr064="wifi50Switch"}
Switch fboxGuestWifi "Guest Wifi" {fritzboxtr064="wifiGuestSwitch"}

36
_bindings/harmonyhub/readme.md
View File

@ -82,6 +82,42 @@ Devices can send button presses
String HarmonyGreatRoomDenon "Denon Button Press" (gMain) { channel="harmonyhub:device:GreatRoom:29529817:buttonPress" }
```
Hubs can also trigger events when a new activity is starting (activityStarting channel) and after it is started (activityStarted channel).
The name of the event is equal to the activity name, with all non-alphanumeric characters replaced with underscore.
rules:
```
rule "Starting TV"
when
Channel "harmonyhub:hub:GreatRoom:activityStarting" triggered Watch_TV
then
logInfo("Harmony", "TV is starting...")
end
rule "TV started"
when
Channel "harmonyhub:hub:GreatRoom:activityStarted" triggered Watch_TV
then
logInfo("Harmony", "TV is started")
end
rule "Going off"
when
Channel "harmonyhub:hub:GreatRoom:activityStarting" triggered PowerOff
then
logInfo("Harmony", "Hub is going off...")
end
rule "Hub off"
when
Channel "harmonyhub:hub:GreatRoom:activityStarted" triggered PowerOff
then
logInfo("Harmony", "Hub is off - no activity")
end
```
## Example Sitemap
Using the above things channels and items

4
_bindings/homematic/readme.md
View File

@ -88,10 +88,10 @@ Callback port of the XML-RPC openHAB server, default is 9125 and counts up for e
- **binCallbackPort**
Callback port of the BIN-RPC openHAB server, default is 9126 and counts up for each additional bridge
- **aliveInterval**
- **aliveInterval DEPRECATED, not necessary anymore**
The interval in seconds to check if the communication with the Homematic gateway is still alive. If no message receives from the Homematic gateway, the RPC server restarts (default = 300)
- **reconnectInterval**
- **reconnectInterval DEPRECATED, not necessary anymore**
The interval in seconds to force a reconnect to the Homematic gateway, disables aliveInterval! (0 = disabled, default = disabled)
If you have no sensors which sends messages in regular intervals and/or you have low communication, the aliveInterval may restart the connection to the Homematic gateway to often. The reconnectInterval disables the aliveInterval and reconnects after a fixed period of time.
Think in hours when configuring (one hour = 3600)

2
_bindings/hue/readme.md
View File

@ -25,7 +25,7 @@ The integration happens through the Hue bridge, which acts as an IP gateway to t
The Hue bridge is required as a "bridge" for accessing any other Hue devices.
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 like e.g. the [GE bulb](http://gelinkbulbs.com/). Please note that the devices need to be registered with the Hue bridge before it is possible for this binding to use them.
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. Please note that the devices need to be registered with the Hue bridge before it is possible for this binding to use them.
The Hue binding supports all seven types of lighting devices defined for ZigBee LightLink ([see page 24, table 2](https://www.nxp.com/documents/user_manual/JN-UG-3091.pdf). These are:

21
_bindings/kodi/readme.md
View File

@ -26,17 +26,20 @@ The Kodi binding is the successor to the openHAB 1.x xbmc binding.
## Preparation
In order to allow control of Kodi by this binding, you need to enable the Kodi application remote control feature.
Please enable "Allow remote control form applications" in the Kodi Setting menu under:
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/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
## Supported Things
This binding provides only one thing type: The Kodi media center.
Create one Kodi thing per Kodi instance available in your home automation system.
All Kodi devices are registered as an audio sink in the ESH/openHAB 2 framework.
All Kodi devices are registered as an audio sink in the ESH/openHAB2 framework.
## Discovery
@ -52,9 +55,9 @@ org.openhab.kodi:enableAutoDiscovery=false
The following configuration options are available for the Kodi binding:
| Parameter | Name | Description | Required |
|-----------|------|-------------|----------|
| `callbackUrl` | Callback URL | URL to use for playing notification sounds, e.g. `http://192.168.0.2:8080` | no |
| Parameter | Name | Description | Required |
|---------------|--------------|----------------------------------------------------------------------------|----------|
| `callbackUrl` | Callback URL | URL to use for playing notification sounds, e.g. `http://192.168.0.2:8080` | no |
### Thing Configuration
@ -65,7 +68,7 @@ These parameters will be found by the auto-discovery feature.
A manual setup through a `things/kodi.things` file could look like this:
```
kodi:kodi:myKodi [ipAddress="192.168.1.100", port="9090"]
Thing kodi:kodi:myKodi "Kodi" @ "Living Room" [ipAddress="192.168.1.100", port="9090"]
```
## Channels
@ -99,9 +102,9 @@ The Kodi thing supports the following channels:
A manual setup through a `things/kodi.things` file could look like this:
```
kodi:kodi:myKodi [ipAddress="192.168.1.100", port="9090"] {
Thing kodi:kodi:myKodi "Kodi" @ "Living Room" [ipAddress="192.168.1.100", port="9090"] {
Channels:
Type pvropentv : pvr-open-tv [
Type pvr-open-tv : pvr-open-tv [
group="All channels"
]
}

20
_bindings/meteostick/readme.md
View File

@ -37,11 +37,21 @@ Next add the sensor and configure the channel number.
### meteostick_bridge Configuration Options
| Option | Description |
|--------|----------------------------------------------------------------------------|
| port | Sets the serial port to be used for the stick |
| mode | Sets the operating mode 0 = USA, 1 = Europe, 2 = Australia. 3 = FineOffset |
| Option | Description |
|--------|----------------------------------------------------|
| port | Sets the serial port to be used for the stick |
| mode | Sets the mode (frequency band) |
Set mode to one of the following depending on your device and region:
| Mode | Device | Region |Frequency |
|-------|--------------|------------------|-----------|
| 0 | Davis | North America | 915 Mhz |
| 1 | Davis | Australia | 915 Mhz |
| 2 | Davis | Europe | 868 Mhz |
| 3 | Fine Offset | North America | 915 Mhz |
| 4 | Fine Offset | Europe | 868 Mhz |
| 5 | Davis | New Zealand | 931.5 Mhz |
### meteostick_davis_iss Configuration Options
@ -84,6 +94,6 @@ in the previous hour is the rainfall for each hour of the day and is updated on
Things can be defined in the .thing file as follows
```
meteostick:meteostick_bridge:receiver [ port="/dev/tty.usbserial-AI02XA60" mode="1" ]
meteostick:meteostick_bridge:receiver [ port="/dev/tty.usbserial-AI02XA60", mode=1 ]
meteostick:meteostick_davis_iss:iss (meteostick:meteostick_bridge:receiver) [ channel=1 ]
```

6
_bindings/mihome/readme.md
View File

@ -32,15 +32,17 @@ from the [Google Play](https://play.google.com/store/apps/details?id=com.xiaomi.
* Xiaomi Aqara ZigBee Wired Wall Switch (1 and 2 buttons)
* Xiaomi Aqara ZigBee Wireless Wall Switch (1 and 2 buttons)
* Xiaomi Aqara Smart Curtain
* Xiaomi Aqara Water Leak Sensor
* Xiaomi Aqara Wireless Switch (square one)
* Xiaomi Aqara Temperature, Humidity and Pressure Sensor (square one)
* Xiaomi Aqara Door/Window Sensor (square one)
* Xiaomi Aqara Motion Sensor (with light intensity support)
* Xiaomi Mijia Honeywell Gas Alarm Detector
* Xiaomi Mijia Honeywell Fire Alarm Detector
(not yet confirmed)
* Xiaomi Aqara Neutral Wall Switch (1 and 2 buttons)
* Xiaomi Mijia Honeywell Gas Alarm Detector
* Xiaomi Mijia Honeywell Fire Alarm Detector
## Setup

33
_bindings/netatmo/readme.md
View File

@ -44,9 +44,10 @@ Once you'll get needed informations from the Netatmo API, you'll be able to conf
E.g.
```
Bridge netatmo:netatmoapi:home [ clientId="<CLIENT_ID>", clientSecret="<CLIENT_SECRET>", username = "<USERNAME>", password = "<PASSWORD>", readStation=true|false, readThermostat=true|false] {
Bridge netatmo:netatmoapi:home [ clientId="<CLIENT_ID>", clientSecret="<CLIENT_SECRET>", username = "<USERNAME>", password = "<PASSWORD>", readStation=true|false, readHealthyHomeCoach=true|false, readThermostat=true|false] {
Thing NAMain inside [ equipmentId="aa:aa:aa:aa:aa:aa", [refreshInterval=60000] ]
Thing NAModule1 outside [ equipmentId="yy:yy:yy:yy:yy:yy", parentId="aa:aa:aa:aa:aa:aa" ]
Thing NHC homecoach [ equipmentId="cc:cc:cc:cc:cc:cc", [refreshInterval=60000] ]
Thing NAPlug plugtherm [ equipmentId="bb:bb:bb:bb:bb:bb", [refreshInterval=60000] ]
Thing NATherm1 thermostat [ equipmentId="xx:xx:xx:xx:xx:xx", parentId="bb:bb:bb:bb:bb:bb" ]
...
@ -204,6 +205,34 @@ Number Netatmo_Wind_Strength "Wind Strength [%.0f KPH]" { channel = "netatmo:NAM
* RfStatus
* BatteryVP
### Healthy Home Coach Device
Example item for the **Healthy Home Coach**:
```
String Netatmo_LivingRoom_HomeCoach_HealthIndex "Climate" { channel = "netatmo:NHC:home:livingroom:HealthIndex" }
```
**Supported types for the healthy home coach device:**
* HealthIndex
* Temperature
* TemperatureTrend
* Humidity
* Co2
* Pressure
* PressureTrend
* AbsolutePressure
* Noise
* WifiStatus
* Location
* TimeStamp
* LastStatusStore
* MinTemp
* MaxTemp
* DateMinTemp
* DateMaxTemp
### Thermostat Relay Device
**Supported types for the thermostat relay device:**
@ -278,7 +307,7 @@ Number Netatmo_Indoor_Co2 "Co2 [%.0f ppm]" <carb
Number Netatmo_Indoor_Pressure "Pressure [%.1f mbar]" <pressure> { channel = "netatmo:NAMain:home:inside:Pressure" }
Number Netatmo_Indoor_AbsolutePressure "AbsolutePressure [%.1f mbar]" <pressure> { channel = "netatmo:NAMain:home:inside:AbsolutePressure" }
Number Netatmo_Indoor_Noise "Noise [%.0f db]" <soundvolume> { channel = "netatmo:NAMain:home:inside:Noise" }
Number Netatmo_Indoor_WifiStatus "WifiStatus [%d]" <signal> { channel = "netatmo:NAMain:home:inside:WifiStatus" }
Number Netatmo_Indoor_WifiStatus "WifiStatus [%s]" <signal> { channel = "netatmo:NAMain:home:inside:WifiStatus" }
DateTime Netatmo_Indoor_TimeStamp "TimeStamp [%1$td.%1$tm.%1$tY %1$tH:%1$tM]" <calendar> { channel = "netatmo:NAMain:home:inside:TimeStamp" }
Location Netatmo_Indoor_Location "Location" <movecontrol> { channel = "netatmo:NAMain:home:inside:Location" }
DateTime Netatmo_Indoor_LastStatusStore "LastStatusStore [%1$td.%1$tm.%1$tY %1$tH:%1$tM]" <text> { channel = "netatmo:NAMain:home:inside:LastStatusStore" }

48
_bindings/network/readme.md
View File

@ -21,15 +21,15 @@ This happens by either using [ping](https://en.wikipedia.org/wiki/Ping_%28networ
You can use the following configuration options:
- **allow\_system\_pings:** Use the external ICMP ping program of the operating system, instead of the Java ping. Useful if the devices cannot be reached by Java ping. Default is true.
- **allow\_dhcp\_listen:** If devices leave and reenter a network, they usually request their last IPv4 address by using DHCP requests. If we listen for those messages, we can make the status update more "real-time" and do not have to wait for the next refresh cycle. Default is true.
- **arp\_ping\_tool\_path:** If your arp ping tool is not called arping and cannot be found in the PATH environment, you can configure the absolute path here. Default is "arpping".
- **cache\_device\_state:** The result of a device presence detection is cached for a small amount of time. Set this time here in milliseconds. Be aware that no new pings will be issued within this time frame, even if explicitly requested. Default is 2000.
- **allowSystemPings:** Use the external ICMP ping program of the operating system, instead of the Java ping. Useful if the devices cannot be reached by Java ping. Default is true.
- **allowDHCPlisten:** If devices leave and reenter a network, they usually request their last IPv4 address by using DHCP requests. If we listen for those messages, we can make the status update more "real-time" and do not have to wait for the next refresh cycle. Default is true.
- **arpPingToolPath:** If your arp ping tool is not called arping and cannot be found in the PATH environment, you can configure the absolute path here. Default is "arping".
- **cacheDeviceStateTimeInMS:** The result of a device presence detection is cached for a small amount of time. Set this time here in milliseconds. Be aware that no new pings will be issued within this time frame, even if explicitly requested. Default is 2000.
Create a file *network.cfg* in your openhab/etc directory and use the above options like this:
Create a file *org.openHAB.binding.network.cfg* in your openHAB/etc directory and use the above options like this:
```
org.openhab.binding.network:allow_system_pings=false
allowSystemPings=false
```
## Supported Things
@ -46,7 +46,7 @@ Auto discovery can be used to scan the local network for **pingdevice** things b
```
network:pingdevice:one_device [ hostname="192.168.0.64" ]
network:pingdevice:second_device [ hostname="192.168.0.65", retry=1, timeout=5000, refresh_interval=60000 ]
network:pingdevice:second_device [ hostname="192.168.0.65", retry=1, timeout=5000, refreshInterval=60000 ]
network:servicedevice:important_server [ hostname="192.168.0.62", port=1234 ]
```
@ -56,11 +56,11 @@ Use the following options for a **network:pingdevice**:
- **hostname:** IP address or hostname of the device
- **retry:** After how many refresh interval cycles shall the device be assumed as offline. Default is 1.
- **timeout:** How long shall the ping wait for an answer (in milliseconds. Default: `5000` = 5 seconds)
- **refresh_interval:** How often shall the device be checked (in milliseconds. Default: `60000` = one minute)
- **refreshInterval:** How often shall the device be checked (in milliseconds. Default: `60000` = one minute)
Use the following additional options for a **network:servicedevice**:
- **port:** Must be not 0. The destination port needs to be a TCP service.
- **port:** Must not be 0. The destination port needs to be a TCP service.
## Presence detection - Configure target device
@ -72,11 +72,11 @@ Pings on windows 10 are usually blocked by the internal firewall. You need to al
### Android and iOS devices
Because mobile devices put themself in a deep sleep mode after some inactivity, they do not react to normal ICMP pings. Configure ARP ping to realize presence detection for those devices. This only works if your devices have WIFI enabled, have been configured to use your home WIFI network, and have the option "Disable wifi in standby" disabled (default).
Because mobile devices put themselves in a deep sleep mode after some inactivity, they do not react to normal ICMP pings. Configure ARP ping to realize presence detection for those devices. This only works if your devices have WIFI enabled, have been configured to use your home WIFI network, and have the option "Disable wifi in standby" disabled (default). An almost immediate presence detection for phones and tables, if they (re)join the home Wifi network, is to use DHCP listen.
### iPhones, iPads
Apple iOS devices are usually in a deep sleep mode and do not respond to ARP pings under all conditions, but to Bonjour service discovery messages (UDP port 5353). Therefore first a Bonjour message is send, before the ARP presence detection is performed. The binding automatically figures out if the target device is an iOS device. You can check if the binding has correctly recognised your device by having a look at the *uses_ios_wakeup* property of your thing.
Apple iOS devices are usually in a deep sleep mode and do not respond to ARP pings under all conditions, but to Bonjour service discovery messages (UDP port 5353). Therefore first a Bonjour message is send, before the ARP presence detection is performed. The binding automatically figures out if the target device is an iOS device. You can check if the binding has correctly recognised your device by having a look at the *uses_ios_wakeup* property of your thing. An almost immediate presence detection for phones and tables, if they (re)join the home Wifi network, is to use DHCP listen.
### Use open TCP ports
@ -103,13 +103,35 @@ In this example, there are four suitable ports to use.
The port 554 (Windows network file sharing service) is open on most Windows PCs and Windows compatible Linux systems.
Port 1025 (MS RPC) is open on XBox systems. Port 548 (Apple Filing Protocol (AFP)) is open on Mac OS X systems.
## DHCP Listen
Please don't forget to open the required ports in your firewall setup.
## Presence detection - Configure your openHAB installation
Because we use external tools for some of the presence detection mechanism or need elevated permissions for others, your OpenHAB installation needs to be altered.
### Arping
For arp pings to work, you need a separate tool, called "arping".
On Linux there exists three different tools:
* arp-scan (not yet supported by this binding)
* arping of the ip-utils (Ubuntu/Debian: `apt-get install iputils-arping`)
* arping by Thomas Habets (Ubuntu/Debian: `apt-get install arping`)
arping by Thomas Habets runs on Windows and MacOS as well.
Make sure the tool is available in $PATH (%PATH% respectively on Windows) or in the same path as the openHAB executable.
On Linux and MacOS you might need elevated access permissions, for instance by making the executable a suid executable (`chmod u+s /usr/sbin/arping`). Just test the executable on the command line, if `sudo` is required, you need to grant elevated permissions.
### DHCP Listen
If devices leave and reenter a network, they usually request their last IPv4 address by using DHCP requests. If we listen for those messages, we can make the status update more "real-time" and do not have to wait for the next refresh cycle.
Some operating systems such as Linux restrict applications to only use ports >= 1024 without elevated privileges.
If the binding is not able to use port 67 (DHCP), because of such a restriction or because the same system is used
as a DHCP server, port 6767 will be used instead. Check the property *uses_dhcp_listen* on your thing for such a hint. You need to establish a port forwarding in this case:
as a DHCP server, port 6767 will be used instead. Check the property *dhcp_state* on your thing for such a hint. You need to establish a port forwarding in this case:
```shell
sysctl -w net.ipv4.ip_forward=1

5
_bindings/oh2/org.openhab.binding.nest.test/README.md Normal file
View File

@ -0,0 +1,5 @@
# Nest Binding Tests
[Nest Labs](https://nest.com/) developed/acquired the Wi-Fi enabled Nest Learning Thermostat, the Nest Protect Smoke+CO detector, and the Nest Cam. These devices are supported by this binding, which communicates with the Nest API over a secure, RESTful API to Nest's servers. Monitoring ambient temperature and humidity, changing HVAC mode, changing heat or cool setpoints, monitoring and changing your "home/away" status, and monitoring your Nest Protects and Nest Cams can be accomplished through this binding.
This binding is to test and verify the nest binding.

21
_bindings/rfxcom/readme.md
View File

@ -225,6 +225,7 @@ Switch Switch {channel="rfxcom:lighting2:usb0:100001_1:command"}
This binding currently supports the following things / message types:
* [bbqtemperature - RFXCOM BBQ Temperature Sensor](#bbqtemperature---rfxcom-bbq-temperature-sensor)
* [blinds1 - RFXCOM Blinds1 Actuator](#blinds1---rfxcom-blinds1-actuator)
* [chime - RFXCOM Chime](#chime---rfxcom-chime)
* [currentenergy - RFXCOM CurrentEnergy Actuator](#currentenergy---rfxcom-currentenergy-actuator)
@ -249,6 +250,26 @@ This binding currently supports the following things / message types:
* [uv - RFXCOM UV/Temperature Sensor](#uv---rfxcom-uvtemperature-sensor)
* [wind - RFXCOM Wind Sensor](#wind---rfxcom-wind-sensor)
### bbqtemperature - RFXCOM BBQ Temperature Sensor
A BBQ Temperature device.
#### Channels
| Name | Channel Type | Item Type | Remarks |
|-----------------|-------------------------------------|-----------|----------|
| foodTemperature | [temperature](#channels) | Number | |
| bbqTemperature | [temperature](#channels) | Number | |
| signalLevel | [system.signal-strength](#channels) | Number | |
| batteryLevel | [system.battery-level](#channels) | Number | |
| lowBattery | [system.low-battery](#channels) | Switch | |
#### Configuration Options
* deviceId - Device Id
* Sensor Id. Example 56923
### blinds1 - RFXCOM Blinds1 Actuator
A Blinds1 device.

7
_bindings/samsungtv/readme.md
View File

@ -19,13 +19,14 @@ This binding integrates the [Samsung TV's](http://www.samsung.com).
## Supported Things
Samsung TV C (2010), D (2011) and E (2012) models should be supported. Because Samsung haven't publish any documentation about the TV's UPnP interface, there could be differences between different TV models, which could lead to mismatch problems.
Samsung TV C (2010), D (2011), E (2012) and F (2013) models should be supported. Because Samsung does not publish any documentation about the TV's UPnP interface, there could be differences between different TV models, which could lead to mismatch problems.
Tested TV models:
| Model | State | Notes |
|-----------|-------|--------------------------------------------------------------------|
| UE46E5505 | OK | Initial contribution is done by this model |
| UE40F6500 | OK | All channels except `colorTemperature`, `programTitle` and `channelName` are working |
## Discovery
@ -34,7 +35,7 @@ The TV's are discovered through UPnP protocol in the local network and all devic
## Binding Configuration
The binding does not require any special configuration
The binding does not require any special configuration.
## Thing Configuration
@ -43,7 +44,7 @@ The Samsung TV Thing requires the host name and port address as a configuration
E.g.
```
Thing samsungtv:tv:livingroom [ hostName="192.168.1.10", port=55000, refreshInterval=1000]
Thing samsungtv:tv:livingroom [ hostName="192.168.1.10", port=55000, refreshInterval=1000 ]
```
## Channels

2
_bindings/sonance1/readme.md
View File

@ -6,7 +6,7 @@ type: binding
description: "This binding integrates with [Sonance DSP Amplifiers](http://www.sonance.com/electronics/amplifiers/dsp). It supports all three models (DSP 2-150, DSP 8-130 and DSP 2-750) but for now it's only tested with the DSP 8-130. For each group you can enable or disable sound (toggle mute) or set the volume."
source: https://github.com/openhab/openhab1-addons/blob/master/bundles/binding/org.openhab.binding.sonance/README.md
since: 1x
install: manual
install: auto
---
<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->

10
_bindings/tradfri/readme.md
View File

@ -28,6 +28,14 @@ The thing type ids are defined according to the lighting devices defined for Zig
| Dimmable Light | 0x0100 | 0100 |
| Colour Temperature Light | 0x0220 | 0220 |
The following matrix lists the capabilities (channels) for each of the supported lighting device types:
| Thing type | On/Off | Brightness | Color | Color Temperature |
|-------------|:------:|:----------:|:-----:|:-----------------:|
| 0100 | X | X | | |
| 0220 | X | X | | X |
## Thing Configuration
The gateway requires a `host` parameter for the hostname or IP address and a `code`, which is the security code that is printed on the bottom of the gateway. Optionally, a `port` can be configured, but any standard gateway uses the default port 5684.
@ -36,7 +44,7 @@ The devices require only a single (integer) parameter, which is their instance i
## Channels
All devices support the `brightness` channel, while the white spectrum bulbs additionally also support the `color_temperature` channel.
All devices support the `brightness` channel, while the white spectrum bulbs additionally also support the `color_temperature` channel (refer to the matrix above).
| Channel Type ID | Item Type | Description |
|-------------------|-----------|---------------------------------------------|

2
_bindings/weatherunderground/readme.md
View File

@ -146,7 +146,7 @@ demo.items:
String Conditions "Conditions [%s]" {channel="weatherunderground:weather:CDG:current#conditions"}
Image Icon "Icon" {channel="weatherunderground:weather:CDG:current#icon"}
DateTime ObservationTime "Observation time [%1$tH:%1$tM]" <clock> {channel="weatherunderground:weather:CDG:current#observationTime"}
String Location "Location [%s]" {channel="weatherunderground:weather:CDG:current#location"}
String ObservationLocation "Location [%s]" {channel="weatherunderground:weather:CDG:current#location"}
String Station "Station [%s]" {channel="weatherunderground:weather:CDG:current#stationId"}
Number Temperature "Current temperature [%.1f °C]" <temperature> {channel="weatherunderground:weather:CDG:current#temperature"}

118
_bindings/withings1/readme.md
View File

@ -15,90 +15,124 @@ install: manual
# Withings Binding
The Withings binding allows openHAB to synchronize data from the official Withings API to items. The following body measure types are supported: diastolic blood pressure, fat free mass, fat mass weight, fat ratio, heart pulse, height, systolic blood pressure, weight.
The Withings binding allows openHAB to synchronize data from the official
Withings API to items. The following body measure types are supported: diastolic
blood pressure, fat free mass, fat mass weight, fat ratio, heart pulse, height,
systolic blood pressure, and weight.
## Binding Configuration
The binding can be configured in the file `services/withings.cfg`.
| Property | Default | Required | Description |
|----------|---------|:--------:|-------------|
| refresh | 360000 | No | The rate, in milliseconds, at which the binding requests Withings data. By default the Withings data is requested every 60 minutes (360000 milliseconds). |
| consumerKey | | Yes | your consumer key |
| consumerSecret | | Yes | your consumer secret |
| redirectUrl | | Yes | your redirect url |
| Property | Default | Required | Description |
|----------------|---------|:--------:|-------------|
| refresh | 360000 | No | The periodicity, in milliseconds, at which the binding requests Withings data. By default the Withings data is requested every 60 minutes (360000 milliseconds). |
| consumerkey | | Yes | your consumer key |
| consumersecret | | Yes | your consumer secret |
| redirectUrl | | Yes | your redirect url |
To access Withings data, the user needs to authenticate via an OAuth 1.0 flow. The binding implements the flow through the command line interface. The first time the binding is started, it prints the following messages to the console:
### Configuration for multiple accounts
```
If using multiple withings accounts, the following properties are required
for each account.
| Property | Description |
|----------------------------|-------------|
| `<accountId>`.userid | The userid for this account |
| `<accountId>`.token | The token for this account |
| `<accountId>`.tokensecret | The token secret for this account |
To access Withings data, the user needs to authenticate via an OAuth 1.0 flow.
The binding implements this flow through the command line interface. The first
time the binding is started, it prints the following messages to the console:
````
#########################################################################################
# Withings Binding needs authentication.
# Execute 'withings:startAuthentication "<accountId>"' on OSGi console.
#########################################################################################
```
````
In order to start the authentication process, the user needs to execute `withings:startAuthentication <accountId>` on the OSGi console where `<accountId>` is an arbitrary key also used in the `services/withings-oauth.cfg` in order to differentiate between the different credentials per Withings account.
In order to start the authentication process, the user needs to execute
`withings:startAuthentication <accountId>` on the OSGi console where
`<accountId>` is an arbitrary key also used in the `services/withings.cfg`
file in order to differentiate between the different credentials per Withings
account.
The binding will print the following lines to the console:
```
````
#########################################################################################
# Withings Binding Setup:
# 1. Open URL 'http://<auth-url>//' in your webbrowser
# 2. Login, choose your user and allow openHAB to access your Withings data
# 3. Execute 'withings:finishAuthentication "<accountId>" "<verifier>" "<user-id>"' on OSGi console
#########################################################################################
```
````
So the user needs to open the shown URL in a web browser, login with his Withings credentials, confirm that openHAB is allowed to access his data and at the end he is redirected to a page on github. There the user finds the command `withings:finishAuthentication "<accountId>" "<verifier>" "<user-id>"` with filled parameters that is needed to finish the authentication.
The user needs to open the given URL in a web browser, log in with his Withings
credentials, and confirm that openHAB is allowed to access the user's data. At
the end of this process, the user will be redirected to a page on github. There
the user finds the command `withings:finishAuthentication "<accountId>" "<verifier>" "<user-id>"`
with pre-filled parameters that is needed to finish the authentication.
The binding stores the OAuth tokens, so that the user does not need to login again. From this point the binding is successfully configured.
The binding stores the OAuth tokens so that the user does not need to log in
again. From this point, the binding is successfully configured.
### Advanced OAuth Configuration
The Withings Binding uses a default application registration to request an OAuth token. The application belongs to the binding developer. If the user wants to use his own application, the binding can be configured to use another OAuth consumer key and consumer secret. Please read the Withings documentation how to register an application (http://oauth.withings.com/en/partner/dashboard). After the application was created, Withings will generate a consumer key and secret. The redirect url must be configured, too. To change the OAuth parameters for the Withings binding the user can specify the following values in the `services/withings.cfg`:
The Withings Binding uses a default application registration to request an OAuth
token. The application belongs to the binding developer. If the user wants to
use his own application, the binding can be configured to use another OAuth
consumer key and consumer secret. Please read the [Withings documentation](http://oauth.withings.com/en/partner/dashboard)
on how to register an application. After the application is created, Withings
will generate a consumer key and secret. The redirect URL must be configured,
too.
The OAuth configuration must be stored in the file `services/withings-oauth.cfg`.
### Multiple accounts
If one owns multiple withings accounts these accounts must be configured specifically. In addition to the above mentioned `services/withings.cfg` configuration, an `accountId` can be specified.
```
thomas.token=74c0e77021ef5be1ec8dcb4dd88c1xckusadwe92f9541c86799dcbbfcb8fc8b236
thomas.tokensecret=25f1098209xns511711b3287288f90740ff45532cef91658c5043db0b0e0c851c
peter.token=74c0e77021ef5be1ec8dcb4dd88c1xckusadwe92f9541c86799dcbbfcb8fc8b236
peter.tokensecret=25f1098209xns511711b3287288f90740ff45532cef91658c5043db0b0e0c851c
```
## Item Configuration
To bind a measure value to an item, the measure type has to be defined in the item binding config. Withings data can be bound to `Number` items only. The syntax for a Withings binding is
To bind a measure value to an item, the measure type has to be defined in the
item binding config. Withings data can be bound to `Number` items only. The
syntax for a Withings item binding is:
```
````
withings="<measure type>"
```
````
The following table shows the measure types and units, that are supported by the binding:
The following table shows the measure types and units that are supported by the binding:
| Measure type | Binding Config | Unit |
|--------------|----------------|------|
| Weight | weight | kg |
| Height | height | meter |
| Fat Free Mass | fat_free_mass | kg |
| Fat Ratio | fat_ratio | % |
| Measure Type | Binding Config | Unit |
|-----------------|----------------|------|
| Weight | weight | kg |
| Height | height | meter |
| Fat Free Mass | fat_free_mass | kg |
| Fat Ratio | fat_ratio | % |
| Fat Mass Weight | fat_mass_weight | kg |
| Diastolic Blood Pressure | diastolic_blood_pressure | mmHg |
| Systolic Blood Pressure | systolic_blood_pressure | mmHg |
| Heart Pulse | heart_pulse | bpm |
| Heart Pulse | heart_pulse | bpm |
## Examples
The following snippet shows some sample bindings:
### Examples of multiple account configuration
```
````
thomas.userid=ImThomas
thomas.token=74c0e77021ef5be1ec8dcb4dd88c1xckusadwe92f9541c86799dcbbfcb8fc8b236
thomas.tokensecret=25f1098209xns511711b3287288f90740ff45532cef91658c5043db0b0e0c851c
peter.userid=PeterPeter
peter.token=74c0e77021ef5be1ec8dcb4dd88c1xckusadwe92f9541c86799dcbbfcb8fc8b236
peter.tokensecret=25f1098209xns511711b3287288f90740ff45532cef91658c5043db0b0e0c851c
````
### Item configuration examples
````
Number Weight "Weight [%.1f kg]" { withings = "weight" }
Number FatRatio "FatRatio [%.1f %%]" { withings = "fat_ratio" }
Number HeartPulse "HeartPulse [%d bpm]" { withings = "heart_pulse" }
```
Number PHeight "Height [%d in]" { withings = "peter:height" }
````

121
_bindings/yamahareceiver/readme.md
View File

@ -3,7 +3,7 @@ id: yamahareceiver
label: Yamahareceiver
title: Yamahareceiver - Bindings
type: binding
description: "This binding connects openHAB with Yamaha Receivers of product line CX-A5000, RX-A30xx, RX-A20xx, RX-A10xx, RX-Vxxx, RX-Z7, DSP-Z7, RX-S600, HTR-xxxx."
description: "This binding connects openHAB with Yamaha Receivers of product line CX-A5000, RX-A30xx, RX-A20xx, RX-A10xx, RX-Vxxx, RX-Z7, DSP-Z7, RX-S600, RX-S601D, HTR-xxxx."
since: 2x
logo: images/addons/yamahareceiver.png
install: auto
@ -15,7 +15,7 @@ install: auto
# Yamahareceiver Binding
This binding connects openHAB with Yamaha Receivers of product line CX-A5000, RX-A30xx, RX-A20xx, RX-A10xx, RX-Vxxx, RX-Z7, DSP-Z7, RX-S600, HTR-xxxx.
This binding connects openHAB with Yamaha Receivers of product line CX-A5000, RX-A30xx, RX-A20xx, RX-A10xx, RX-Vxxx, RX-Z7, DSP-Z7, RX-S600, RX-S601D, HTR-xxxx.
If your hardware is on the list but still does not work, please fill a bug report!
@ -48,13 +48,15 @@ Zone control channels are:
Playback control channels are:
* `preset#playback_channels`: Set a preset.
* `preset#playback_channels`: Set a preset. Not supported by Spotify.
* `playback#playback_channels`: Set a play mode or get the current play mode.
* `playback_station#playback_channels`: Get the current played station (radio).
* `playback_artist#playback_channels`: Get the current played artist.
* `playback_album#playback_channels`: Get the current played album.
* `playback_song#playback_channels`: Get the current played song.
* `playback_song_image_url#playback_channels`: Get the current played song image URL (currently Spotify input only). openHAB Type `String`.
* `tuner_band#playback_channels`: Set the band (FM or DAB) for tuner input when device supports DAB (e.g. RX-S601D). openHAB Type `String`.
Navigation control channels are:
* `navigation_menu#navigation_channels`: Select or display the full or relative path to an item.
@ -67,39 +69,114 @@ Navigation control channels are:
* `navigation_back#navigation_channels`: Navigate to the parent menu.
* `navigation_backtoroot#navigation_channels`: Navigate back to the root menu.
Navigation is not supported by Spotify input.
## Example
### For auto linking with Paper UI.
### Basic Setup
Link the items to the channels of your preferred zone in paperui after you've saved your items file.
##### For auto linking with Paper UI
Link the items to the channels of your preferred zone (here `Main_Zone`) in PaperUI after you've saved your items file.
Items:
```
Switch Yamaha_Power "Power [%s]" <tv>
Dimmer Yamaha_Volume "Volume [%.1f %%]"
Switch Yamaha_Mute "Mute [%s]"
String Yamaha_Input "Input [%s]"
String Yamaha_Surround "surround [%s]"
Switch Yamaha_Power "Power [%s]" <switch>
Dimmer Yamaha_Volume "Volume [%.1f %%]" <soundvolume>
Switch Yamaha_Mute "Mute [%s]" <soundvolume_mute>
String Yamaha_Input "Input [%s]" <video>
String Yamaha_Surround "Surround [%s]" <video>
```
### Manually linking
##### For manually linking
Replace the UPNP UDN (here: 9ab0c000_f668_11de_9976_00a0de88ee65) with the real UDN provided by your UPNP discovery.
Replace the UPNP UDN (here: `9ab0c000_f668_11de_9976_00a0ded41bb7`) with the real UDN provided by your UPNP discovery.
Also replace the zone name with your preferred zone (here `Main_Zone`).
Items:
```
Switch Yamaha_Power "Power [%s]" <tv> {channel="yamahareceiver:yamahaAV:9ab0c000_f668_11de_9976_00a0de88ee65:MAIN_ZONE:power"}
Dimmer Yamaha_Volume "Volume [%.1f %%]" {channel="yamahareceiver:yamahaAV:9ab0c000_f668_11de_9976_00a0de88ee65:MAIN_ZONE:volume"}
Switch Yamaha_Mute "Mute [%s]" {channel="yamahareceiver:yamahaAV:9ab0c000_f668_11de_9976_00a0de88ee65:MAIN_ZONE:mute"}
String Yamaha_Input "Input [%s]" {channel="yamahareceiver:yamahaAV:9ab0c000_f668_11de_9976_00a0de88ee65:MAIN_ZONE:input"}
String Yamaha_Surround "surround [%s]" {channel="yamahareceiver:yamahaAV:9ab0c000_f668_11de_9976_00a0de88ee65:MAIN_ZONE:surroundProgram"}
Switch Yamaha_Power "Power [%s]" <switch> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:zone_channels#power" }
Dimmer Yamaha_Volume "Volume [%.1f %%]" <soundvolume> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:zone_channels#volume" }
Switch Yamaha_Mute "Mute [%s]" <soundvolume_mute> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:zone_channels#mute" }
String Yamaha_Input "Input [%s]" <video> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:zone_channels#input" }
String Yamaha_Surround "Surround [%s]" <video> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:zone_channels#surroundProgram" }
```
Sitemap:
```
Selection item=Yamaha_Input mappings=[HDMI1="BlueRay",HDMI2="Satellite",NET_RADIO="NetRadio",TUNER="Tuner"]
Selection item=Yamaha_Surround label="Surround Mode" mappings=["2ch Stereo"="2ch","7ch Stereo"="7ch"]
Switch item=Yamaha_Power
Switch item=Yamaha_Mute
Slider item=Yamaha_Volume
Selection item=Yamaha_Input mappings=[HDMI1="Kodi",HDMI2="PC",AUDIO1="TV",TUNER="Tuner",Spotify="Spotify",Bluetooth="Bluetooth","NET RADIO"="NetRadio"]
Selection item=Yamaha_Surround mappings=["2ch Stereo"="2ch Stereo","5ch Stereo"="5ch Stereo","Chamber"="Chamber","Sci-Fi"="Sci-Fi","Adventure"="Adventure"]
```
### Playback
Items:
```
String Yamaha_Playback "[]" <video> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:playback_channels#playback" }
String Yamaha_Playback_Station "Station [%s]" <video> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:playback_channels#playback_station" }
String Yamaha_Playback_Artist "Artist [%s]" <video> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:playback_channels#playback_artist" }
String Yamaha_Playback_Album "Album [%s]" <video> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:playback_channels#playback_album" }
String Yamaha_Playback_Song "Song [%s]" <video> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:playback_channels#playback_song" }
String Yamaha_Playback_Song_Image "[]" <videp> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:playback_channels#playback_song_image_url" }
```
Sitemap:
```
Switch item=Yamaha_Playback mappings=["Previous"="⏮", "Play"="►", "Pause"="⏸", "Stop"="⏹", "Next"="⏭"] visibility=[Yamaha_Input=="Spotify", Yamaha_Input=="Bluetooth"]
Text item=Yamaha_Playback_Station visibility=[Yamaha_Input=="TUNER"]
Text item=Yamaha_Playback_Artist
Text item=Yamaha_Playback_Album
Text item=Yamaha_Playback_Song
Image item=Yamaha_Playback_Song_Image visibility=[Yamaha_Input=="Spotify"]
```
Note the `visiblility` rules - you may need to adjust to your particular AVR model supported inputs and features.
### DAB Tuner (dual band)
Items:
```
Number Yamaha_Preset "Preset [%d]" <video> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:playback_channels#preset"}
String Yamaha_Tuner_Band "Band [%s]" <video> { channel="yamahareceiver:zone:9ab0c000_f668_11de_9976_00a0ded41bb7:Main_Zone:playback_channels#tuner_band" }
String Yamaha_Input_Ex
```
The synthetic `Yamaha_Input_Ex` will be calculated by a rule (see below) and will drive sitemap visibility (see below).
Rules:
```
rule "Yamaha_Input_Ex"
when
Item Yamaha_Input changed or
Item Yamaha_Tuner_Band changed
then
var input = Yamaha_Input.state
if (input != NULL) {
if (Yamaha_Input.state == "TUNER" && Yamaha_Tuner_Band.state != NULL) {
input = "TUNER_" + Yamaha_Tuner_Band.state
}
}
Yamaha_Input_Ex.postUpdate(new StringType(input))
end
```
When the input is `TUNER` the `Yamaha_Input_Ex` item will have a value of either `TUNER_FM` or `TUNER_DAB` depending on the chosen tuner band,
otherwise it will be same as input (`Yamaha_Input`).
Sitemap:
```
Selection item=Yamaha_Tuner_Band mappings=[FM="FM",DAB="DAB+"] visibility=[Yamaha_Input=="TUNER"]
Selection item=Yamaha_Preset mappings=[2="Radio Krakow",3="PR Trojka",5="RadioZet",8="Radio Chillizet",12="RMF Classic",13="RMF MAXXX"] visibility=[Yamaha_Input_Ex=="TUNER_FM"]
Selection item=Yamaha_Preset mappings=[1="FM-1",2="FM-2",3="FM-3"] visibility=[Yamaha_Input_Ex=="TUNER_DAB"]
```
Notice how we have two preset mappings that each is meant for FM and DAB+ bands respectively. This enables to have different channel names per band.

39
concepts/categories.md Normal file
View File

@ -0,0 +1,39 @@
---
layout: documentation
---
{% include base.html %}
# Categories
Categories in Eclipse SmartHome are used to provide meta information about things channels, etc. UIs can use this information to render specific icons or provide a search functionality to for example filter all things for a certain category.
## Differences between categories
We seperate the categories into `functional` and `visual`. Therefore we treat `thing categories` as how the physical device **looks like** and `channel categories` as something that describes the **functional purpose** of the channel.
## Thing Categories
The thing type definition allows to specify a category. User interfaces can parse this category to get an idea how to render this thing. A binding can classify each thing into one of the existing categories. The list of all predefined categories can be found in our categories overview:
| Category | Description | Icon Example |
|-----------------|-------------|{% for category in site.data.categories_thing %}
|{{category.name}}|{{category.description}}|![{{category.icon}}](../features/ui/iconset/classic/icons/{{category.icon}}){:height="36px" width="36px"}|{% endfor %}
## Channel Categories
The channel type definition allows to specify a category. Together with the definition of the `readOnly` attribute in the state description, user interfaces get an idea how to render an item for this channel. A binding should classify each channel into one of the existing categories. This is a list of all predefined categories with their usual accessible mode and the according item type:
| Category | Accessible Mode | Item Type | Icon Example |
|-----------------|-------------|{% for category in site.data.categories_channel %}
|{{category.name}}|{{category.access}}|{{category.itemType}}|![{{category.icon}}](../features/ui/iconset/classic/icons/{{category.icon}}){:height="36px" width="36px"}|{% endfor %}
R=Read, RW=Read/Write
The accessible mode indicates whether a category could have `read only` flag configured to true or not. For example the `Motion` category can be used for sensors only, so `read only` can not be false. Temperature can be either measured or adjusted, so the accessible mode is R and RW, which means the read only flag can be `true` or `false`. In addition categories are related to specific item types. For example the 'Energy' category can only be used for `Number` items. But `Rain` could be either expressed as Switch item, where it only indicates if it rains or not, or as `Number`, which gives information about the rain intensity.
The list of categories may not be complete and not every device will fit into one of these categories. It is possible to define own categories. If the category is widely used, the list of predefined categories can be extended. Moreover, not all user interfaces will support all categories. It is more important to specify the `read only` information and state information, so that default controls can be rendered, even if the category is not supported.
## Group Channel Categories
Channel groups can be seen as a kind of `sub-device` as they combine certain (physical) abilities of a `thing` into one. For such `group channels` one can set a category from the `channel` category list.

8
concepts/guidelines.md
View File

@ -68,3 +68,11 @@ Note that this list also serves as a checklist for code reviews on pull requests
- ```error``` logging should only be used to inform the user that something is tremendously wrong in his setup, the system cannot function normally anymore, and there is a need for immediate action. It should also be used if some code fails irrecoverably and the user should report it as a severe bug.
1. For bindings, you should NOT log errors, if e.g. connections are dropped - this is considered to be an external problem and from a system perspective to be a normal and expected situation. The correct way to inform users about such events is to update the Thing status accordingly. Note that all events (including Thing status events) are anyhow already logged.
1. Likewise, bundles that accept external requests (such as servlets) must not log errors or warnings if incoming requests are incorrect. Instead, appropriate error responses should be returned to the caller.
## Static code analysis
The Eclipse SmartHome Maven build includes [tooling for static code analysis](https://github.com/openhab/static-code-analysis) that will validate your code against the Coding Guidelines and some additional best practices. Information about the checks can be found [here](https://github.com/openhab/static-code-analysis/blob/master/docs/included-checks.md).
The tool will generate an individual report for each bundle that you can find in `path/to/bundle/target/code-analysis/report.html` file and a report for the whole build that contains links to the individual reports in the `target/summary_report.html`. The tool categorizes the found issues by priority: 1(error),2(warning) or 3(info). If any error is found within your code the Maven build will end with failure. You will receive detailed information (path to the file, line and message) listing all problems with Priority 1 on the console.
Please fix all the Priority 1 issues and all issues with Priority 2 and 3 that are relevant (if you have any doubt don't hesitate to ask). Re-run the build to confirm that the checks are passing.

25
concepts/profiles.md Normal file
View File

@ -0,0 +1,25 @@
---
layout: documentation
---
# Profiles
The communication between the framework and the thing handlers is managed by the "Communication Manager", which in turn uses "Profiles" to determined what exactly needs to be done. This provides some flexibility to influence these communication paths.
By their nature, profiles are correlated to links between items and channels (i.e. `ItemChannelLinks`). So if one channel is linked to several items it also will have several profile instances, each handling the communication to exactly one of these items. The same applies for the situation where one item is linked to multiple channels.
Profiles are created by ProfileFactories and are retained for the lifetime of their link. This means that they are allowed to retain a transient state, like e.g. the timestamp of the the last event or the last state. With this, it is possible to take into account the temporal dimension when calculating the appropriate action in any situation.
There exist two different kinds of profiles: state and trigger profiles.
### State Profiles
State profiles are responsible for communication between items and their corresponding state channels (`ChannelKind.STATE`). Their purpose is to forward state updates and commands to and from the thing handlers.
### Trigger Profiles
Trigger channels (`ChannelKind.TRIGGER`) by themselves do not maintain a state (as by their nature they only fire events). With the help of trigger profiles they can be linked to items anyway. Hence the main purpose of a trigger profile is to calculate a state based on the fired events. This state then is forwarded to the linked item by sending `ItemStateEvents`.
Trigger profiles are powerful means to implement some immediate, straight-forward logic without the need to write any rules.
Apart from that, they do not pass any commands or state updates to and from the thing handler as by their nature trigger channels are not capable of handling these.