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

Updated external content (Jenkins build 14)

pull/764/head
CloudBees DEV@Cloud 2018-07-17 21:44:40 +02:00
parent ac85c4a3ed
commit 32ee74eb91
10 changed files with 304 additions and 226 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
_addons_bindings/ekey1/readme.md
View File

@ -3,7 +3,7 @@ id: ekey
label: ekey
title: ekey - Bindings
type: binding
description: "[ekey](http://ekey.net/) is an Austrian company that provides biometric access-control solutions, more precisely fingerprint readers and corresponding controllers. This binding extends the functionality of the products [ekey home](http://ekey.net/ekey-home-en) and [ekey multi](http://ekey.net/ekey-multi-en)."
description: "[ekey](http://ekey.net/) is an Austrian company that provides biometric"
source: https://github.com/openhab/openhab1-addons/blob/master/bundles/binding/org.openhab.binding.ekey/README.md
since: 1x
logo: images/addons/ekey.png
@ -16,74 +16,64 @@ install: auto
# ekey Binding
[ekey](http://ekey.net/) is an Austrian company that provides biometric access-control solutions, more precisely fingerprint readers and corresponding controllers. This binding extends the functionality of the products [ekey home](http://ekey.net/ekey-home-en) and [ekey multi](http://ekey.net/ekey-multi-en).
[ekey](http://ekey.net/) is an Austrian company that provides biometric
access-control solutions, more precisely fingerprint readers and
corresponding controllers. This binding extends the functionality of the
products [ekey home](http://ekey.net/ekey-home-en) and
[ekey multi](http://ekey.net/ekey-multi-en).
To use this binding, one needs to have either the _home_ or the _multi_ solution of ekey. Note that the _multi_ version provides much more functionality than the _home_ version.
## Setup
Additionally the _ekey UDP converter_ is needed. This module provides an interface by converting the internal RS485 signals to Ethernet. Connecting this to the local network enables ekey to communicate to the ekey binding.
To use this binding, one needs to have either the _home_ or the _multi_
solution of ekey. Note that the _multi_ version provides much more
functionality than the _home_ version.
Additionally the _ekey UDP converter_ is needed. This module provides an
interface by converting the internal RS485 signals to Ethernet. Connecting
this to the local network enables ekey to communicate to the ekey binding.
![example](http://ekey.net/media/W/720/bilder/automatisierung/example_E.jpg)
The ekey binding translates information that comes from the ekey controller and makes it usable to openHAB. Usually ekey sends packets with information on each user input. This might be every time a person pulls their finger over the terminal or if a digital input occurs.
The ekey binding translates information that comes from the ekey controller and
makes it usable to openHAB. Usually ekey sends packets with information on
each user input. This might be every time a person pulls their finger over the
terminal or if a digital input occurs.
The information consists at least of these types:
**userID** - the index of the detected user that is stored on the controller
* **userID** - the index of the detected user that is stored on the controller
* **fingerID** - the finger that the person used
* **terminalID** - the serial number of the fingerprint reader that was used
* **action** - this tells whether the user was recognized successfully and
access was granted or access was denied
**fingerID** - the finger that the person used
The amount of information depends on whether _ekey home_ or _ekey multi_ is
used and which protocol is used by the converter. But the previously mentioned
4 are supported in any case.
**terminalID** - the serial number of the fingerprint reader that was used
The converter knows up to three different protocols. The _RARE_ protocol that
is enabled by default, the _HOME_ protocol which is very similar to the _RARE_,
and finally the _MULTI_ protocol which is fairly powerful compared to the other
ones. The binding uses the term "mode" instead of "protocol".
**action** - this tells whether the user was recognized successfully and access was granted or access was denied
The type of protocol that is used by the converter can be changed with a small
tool which is only available for Windows systems. This tool is called
_ConfigConverterUDP_ and can be downloaded from the [ekey website](https://www.ekey.net/en/media_center/).
The amount of information depends on whether _ekey home_ or _ekey multi_ is used and which protocol is used by the converter. But the previously mentioned 4 are supported in any case.
The converter knows up to three different protocols. The _RARE_ protocol that is enabled by default, the _HOME_ protocol which is very similar to the _RARE_ and finally the _MULTI_ protocol which is fairly powerful compared to the other ones. The binding uses the term "mode" instead of "protocol".
The type of protocol that is used by the converter can be changed with a small tool (unfortunately Windows only). This tool is called _ConfigConverterUDP_ and can be downloaded from the [ekey website](http://www.ekey.net/downloads-en/cat/Software).
### Available Types of Information
**Action** This indicates whether access was granted (Value: 0) or denied (Value: -1). According to the ekey documentation there are six more values possible as you can see in the .map file below. (Item Type Number, Modes: R/H/M)
**Finger ID** This indicates the finger that was used by a person. The value consists of 2 digits. The first one specifies the hand (left hand: 1, right hand: 2) and the second digit specifies the finger from left to right. To get a feeling see the .map file below. (Item Type Number, Modes: R/H/M)
**Input ID** This indicates which of the four digital inputs was triggered. Value is number of Input. "-1" tells that no input was triggered. (Item Type Number, Modes: M)
**Key ID** This indicates which of the four keys was used. See ekey documentation on "keys". (Item Type Number, Modes: M)
**Mode** This simply returns the mode that was used 1=RARE, 2=MULTI, 3=HOME (Item Type Number, Modes: R/H/M)
**Relay ID** This indicates which relay has been switched. (Item Type Number, Modes: R/H)
**Terminal ID** This provides the serial number of the packet source. The source can be a fingerprint terminal or the controller (in case of digital inputs). The Serial number has a length of 13. When using RARE mode, only the tailing 8 digits can be returned.(Item Type Number, Modes: R/H/M)
**Terminal name** This returns the 4 characters long name that was specified on the controller for the specific terminals. (Item Type String, Modes: M)
**User ID** This indicates which user has been detected on the terminal. The value is the numerical order of the user as it was specified on the controller. Mapping the numbers to names make sense. (Item Type Number, Modes: R/H/M)
**Username** This returns the ten characters long name of the person that has been recognized on the terminal. The name that is returned must have been specified on the controller before. (Item Type String, Modes: M)
**User status** This indicates the status of the user: -1 = undefined, 1 = enabled, 0 = disabled (Item Number, Modes: M)
As you can see, in many cases it makes sense to map the number values to some more meaningful strings.
See the mapping examples on the bottom.
## Binding Configuration
This binding can be configured in the file `services/ekey.cfg`.
| Property | Default | Required | Description |
|----------|---------|:--------:|-------------|
| ip | | No | IPv4 address of the eKey udp converter. A static IP address is recommended. |
| port | | Yes | port as you configured during the UDP Converter configuration. For example, 51000 |
| mode | RARE | No | can be RARE, MULTI or HOME depending on what your system supports |
| delimiter | ` ` (space) | No | the delimiter is also defined on the eKey UDP converter - use the eKey configuration software to determine which delimiter is used or to change it. Another option is `_` (underscore) |
| Property | Default | Required | Description |
|-----------|---------|:--------:|-------------|
| ip | | No | IPv4 address of the eKey udp converter. A static IP address is recommended. |
| port | | Yes | The port as configured during the UDP Converter configuration. e.g. 51000 |
| mode | RARE | No | Can be RARE, MULTI or HOME depending on what the system supports |
| delimiter | ` ` (space) | No | The delimiter is also defined on the ekey UDP converter - use the ekey configuration software to determine which delimiter is used or to change it. Another option is `_` (underscore) |
## Items Configuration
This is quite simple. It depends on the type of information someone is interested in.
## Item Configuration
The syntax is:
@ -91,23 +81,74 @@ The syntax is:
ekey="<interestname>"
```
Where `<interestname>` is one of the following:
where `<interestname>` is one of the following:
* action
* username
* userid
* userstatus
* fingerid
* inputid
* keyid
* mode
* relayid
* terminalid
* terminalname
* fingerid
* keyid
* inputid
* mode
* relay
* userid
* username
* userstatus
## Full Example
Here is an example that demonstrates a simple rule that feeds the openHAB TTS-engine and welcomes the user when he or she enters the house.
### interestname Definitions
* **Action**
This indicates whether access was granted (value=0) or denied (value=-1).
According to the ekey documentation there are six more values possible as you
can see in the .map file below. (Item Type: Number, Modes: R/H/M)
* **Finger ID**
This indicates the finger that was used by a person. The value consists of 2
digits. The first one specifies the hand (left hand=1, right hand=2) and
the second digit specifies the finger from left to right. (see the .map file
below). (Item Type: Number, Modes: R/H/M)
* **Input ID**
This indicates which of the four digital inputs was triggered. Value is
number of Input. "-1" indicates that no input was triggered. (Item Type:
Number, Modes: M)
* **Key ID**
This indicates which of the four keys was used. See ekey documentation on
"keys". (Item Type: Number, Modes: M)
* **Mode**
This simply returns the mode that was used (1=RARE, 2=MULTI, 3=HOME) (Item
Type: Number, Modes: R/H/M)
* **Relay ID**
This indicates which relay has been switched. (Item Type: Number, Modes: R/H)
* **Terminal ID**
This provides the serial number of the packet source. The source can be a
fingerprint terminal or the controller (in case of digital inputs). The
Serial number has a length of 13. When using RARE mode, only the trailing 8
digits can be returned. (Item Type: Number, Modes: R/H/M)
* **Terminal name**
This returns the 4-character-long name that was specified on the controller
for the specific terminals. (Item Type: String, Modes: M)
* **User ID**
This indicates which user has been detected on the terminal. The value is the
numerical order of the user as it was specified on the controller. (Item
Type: Number, Modes: R/H/M)
* **Username**
This returns the ten-character-long name of the person that has been
recognized on the terminal. The name that is returned must have been
previously specified on the controller. (Item Type String, Modes: M)
* **User status**
This indicates the status of the user (-1=undefined, 1=enabled, 0= disabled)
(Item Type: Number, Modes: M)
In many cases it makes sense to map the number values to more meaningful
strings. See the mapping examples below.
## Examples
### Full Example
Here is an example that demonstrates a simple rule that feeds the openHAB
TTS-engine and welcomes the user when he or she enters the house.
items/ekey.items
@ -121,7 +162,7 @@ Number Action "Last action [MAP(ekey_action.map):%d]" {
rules/ekey.rules
```
```java
rule Welcome
when
Item Action received update
@ -140,7 +181,7 @@ end
transform/ekey_finger.map
```
```javascript
11=leftlittle
12=leftring
13=leftmiddle
@ -156,7 +197,8 @@ transform/ekey_finger.map
transform/ekey_names.map
```
```javascript
-1=Unspecified
1=John Doe
2=Jane Doe
@ -164,14 +206,14 @@ transform/ekey_names.map
transform/ekey_terminal.map
```
```javascript
80156839130911=frontdoor
80156839130914=backdoor
```
transform/ekey_action.map
```
```javascript
0=granted
-1=rejected
1=timeoutA
@ -182,7 +224,6 @@ transform/ekey_action.map
6=digitalinput
```
## Further Examples
* eKey binding demo config (may be specific to openHAB 1.x)(http://pastebin.com/fjXkFbiq)
### Further Examples
* [ekey binding demo config](http://pastebin.com/fjXkFbiq) (may be specific to openHAB 1.x)

106
_addons_bindings/homematic/readme.md
View File

@ -16,7 +16,7 @@ install: auto
# Homematic Binding
This is the binding for the [eQ-3 Homematic Solution](http://www.eq-3.de/).
This binding allows you to integrate, view, control and configure all Homematic devices in the openHAB environment.
This binding allows you to integrate, view, control and configure all Homematic devices in Eclipse Smarthome.
## Supported Bridges
@ -47,7 +47,7 @@ These ports are used by the binding by default to communicate **TO** the gateway
- TclRegaScript: 8181
- Groups: 9292
And **FROM** the gateway to openHab:
And **FROM** the gateway to the binding:
- XML-RPC: 9125
- BIN-RPC: 9126
@ -73,7 +73,7 @@ CCU Autodiscovery:
## Supported Things
All devices connected to a Homematic gateway.
All required openHAB metadata are generated during device discovery.
All required metadata are generated during device discovery.
With Homegear or a CCU, variables and scripts are supported too.
## Discovery
@ -84,10 +84,10 @@ Gateway discovery is available:
* Homegear >= 0.6.x
* piVCCU
For all other gateways you have to manually add a bridge in a things file. Device discovery is supported for all gateways.
For all other gateways you have to manually add a bridge in a things file. Device discovery is supported for all gateways.
The binding has a gateway type autodetection, but sometimes a gateway does not clearly notify the type.
If you are using a YAHM for example, you have to manually set the gateway type in the bride configuration to CCU.
If you are using a YAHM for example, you have to manually set the gateway type in the bride configuration to CCU.
If autodetection can not identify the gateway, the binding uses the default gateway implementation.
The difference is, that variables, scripts and device names are not supported, everything else is the same.
@ -104,52 +104,52 @@ Besides discovering devices that are already known by the gateway, it may be des
There are several settings for a bridge:
- **gatewayAddress** (required)
- **gatewayAddress** (required)
Network address of the Homematic gateway
- **gatewayType**
- **gatewayType**
Hint for the binding to identify the gateway type (auto|ccu|noccu) (default = auto).
- **callbackHost**
Callback network address of the openHAB server, default is auto-discovery
- **callbackHost**
Callback network address of the system runtime, default is auto-discovery
- **callbackPort DEPRECATED, use binCallbackPort and xmlCallbackPort**
Callback port of the openHAB server, default is 9125 and counts up for each additional bridge
- **callbackPort DEPRECATED, use binCallbackPort and xmlCallbackPort**
Callback port of the binding's server, default is 9125 and counts up for each additional bridge
- **xmlCallbackPort**
Callback port of the XML-RPC openHAB server, default is 9125 and counts up for each additional bridge
- **xmlCallbackPort**
Callback port of the binding's XML-RPC server, default is 9125 and counts up for each additional bridge
- **binCallbackPort**
Callback port of the BIN-RPC openHAB server, default is 9126 and counts up for each additional bridge
- **binCallbackPort**
Callback port of the binding's BIN-RPC server, default is 9126 and counts up for each additional bridge
- **aliveInterval DEPRECATED, not necessary anymore**
- **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 DEPRECATED, not necessary anymore**
- **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)
- **timeout**
- **timeout**
The timeout in seconds for connections to a Homematic gateway (default = 15)
- **discoveryTimeToLive**
- **discoveryTimeToLive**
The time to live in seconds for discovery results of a Homematic gateway (default = -1, which means infinite)
- **socketMaxAlive**
- **socketMaxAlive**
The maximum lifetime of a pooled socket connection to the Homematic gateway in seconds (default = 900)
- **rfPort**
- **rfPort**
The port number of the RF daemon (default = 2001)
- **wiredPort**
- **wiredPort**
The port number of the HS485 daemon (default = 2000)
- **hmIpPort**
- **hmIpPort**
The port number of the HMIP server (default = 2010)
- **cuxdPort**
- **cuxdPort**
The port number of the CUxD daemon (default = 8701)
- **installModeDuration**
@ -191,7 +191,7 @@ Bridge homematic:bridge:occu [ gatewayAddress="..."]
## Thing Configuration
Things are all discovered automatically, you can handle them in PaperUI.
Things are all discovered automatically, you can handle them in PaperUI.
If you really like to manually configure a thing:
@ -224,7 +224,7 @@ All channels have two configs:
The receiveDelay is handy for dimmers and rollershutters for example.
If you have a slider in a UI and you move this slider to a new position, it jumps around because the gateway sends multiple events with different positions until the final has been reached.
If you set the ```receiveDelay``` to some seconds, these events are filtered out and only the last position is distributed to openHab.
If you set the ```receiveDelay``` to some seconds, these events are filtered out and only the last position is distributed to the binding.
The disadvantage is of course, that all events for this channel are delayed.
```java
@ -247,10 +247,10 @@ In the items file, you can map the datapoints, the syntax is:
homematic:TYPE:BRIDGE:SERIAL:CHANNELNUMBER#DATAPOINTNAME
```
- **homematic:** the binding id, fixed
- **type:** the type of the Homematic device
- **bridge:** the name of the bridge
- **serial:** the serial number of the Homematic device
- **homematic:** the binding id, fixed
- **type:** the type of the Homematic device
- **bridge:** the name of the bridge
- **serial:** the serial number of the Homematic device
- **channelnumber:** the channel number of the Homematic datapoint
- **datapointname:** the name of the Homematic datapoint
@ -271,7 +271,7 @@ Virtual datapoints are generated by the binding and provides special functionali
The GATEWAY-EXTRAS is a virtual device which contains a switch to reload all values from all devices and also a switch to put the gateway in the install mode to add new devices.
If the gateway supports variables and scripts, you can handle them with this device too.
The type is generated: GATEWAY-EXTRAS-&lsqb;BRIDGE_ID&rsqb;.
Example: bridgeId=ccu, type=GATEWAY-EXTRAS-CCU
Example: bridgeId=ccu, type=GATEWAY-EXTRAS-CCU
Address: fixed GWE00000000
### RELOAD_ALL_FROM_GATEWAY
@ -311,14 +311,14 @@ A virtual datapoint (Enum) to configure the device deletion with DELETE_MODE, av
### ON_TIME_AUTOMATIC
A virtual datapoint (Number) to automatically set the ON_TIME datapoint before the STATE or LEVEL datapoint is sent to the gateway, available for all devices which supports the ON_TIME datapoint.
A virtual datapoint (Number) to automatically set the ON_TIME datapoint before the STATE or LEVEL datapoint is sent to the gateway, available for all devices which supports the ON_TIME datapoint.
This is usefull to automatically turn off the datapoint after the specified time.
### DISPLAY_OPTIONS
A virtual datapoint (String) to control the display of a 19 button Homematic remote control (HM-RC-19), available on channel 18
A virtual datapoint (String) to control the display of a 19 button Homematic remote control (HM-RC-19), available on channel 18
The remote control display is limited to five characters, a longer text is truncated.
The remote control display is limited to five characters, a longer text is truncated.
You have several additional options to control the display.
@ -330,9 +330,9 @@ You have several additional options to control the display.
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.
**Examples:**
**Examples:**
Assumed you mapped the virtual datapoint to a String item called Display_Options
Assumed you mapped the virtual datapoint to a String item called Display_Options
```java
String Display_Options "Display_Options" { channel="homematic:HM-RC-19-B:ccu:KEQ0099999:18#DISPLAY_OPTIONS" }
@ -418,7 +418,7 @@ end
### PRESS
A virtual datapoint (String) to simulate a key press, available on all channels that contains PRESS_ datapoints.
A virtual datapoint (String) to simulate a key press, available on all channels that contains PRESS_ datapoints.
Available values: SHORT, LONG, LONG_RELEASE, CONT
Example: to capture a key press on the 19 button remote control in a rule
@ -434,7 +434,7 @@ end
## 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.
@ -442,32 +442,32 @@ As the HM-PB-2-WM55 for instance has two channels, it is enough to mention the S
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 (loglevel 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've tested pretty much but i did not found the reason. The HM-ES-TX-WM device for example always returns this failure, it's impossible with the current CCU2 firmware (2.17.15) to fetch the values.
I've implemented two workarounds, if a device returns the failure, workaround one is executed, if the device still returns the failure, workaround two is executed.
This always works in my tests, but you may see a OFFLINE, ONLINE cycle for the device.
Fetching values is only done at startup or if you trigger a REFRESH. I hope this will be fixed in one of the next CCU firmwares.
This always works in my tests, but you may see a OFFLINE, ONLINE cycle for the device.
Fetching values is only done at startup or if you trigger a REFRESH. 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 a event if a datapoint of a device has changed.
There is (currently) no way to receive a event automatically when a variable has changed.
To reload all variable values, send a REFRESH command to any variable.
e.g you have a item linked to a variable with the name Var_1
To reload all variable values, send a REFRESH command to any variable.
e.g you have a item linked to a variable with the name Var_1
In the console:
```shell
@ -489,25 +489,25 @@ sendCommand(Var_1, RefreshType.REFRESH)
If you want to see what's going on in the binding, switch the loglevel to DEBUG in the Karaf console
```shell
log:set DEBUG org.openhab.binding.homematic
log:set DEBUG org.eclipse.smarthome.binding.homematic
```
If you want to see even more, switch to TRACE to also see the gateway request/response data
```shell
log:set TRACE org.openhab.binding.homematic
log:set TRACE org.eclipse.smarthome.binding.homematic
```
Set the logging back to normal
```shell
log:set INFO org.openhab.binding.homematic
log:set INFO org.eclipse.smarthome.binding.homematic
```
To identify problems, i need a full startup TRACE log
```shell
stop org.openhab.binding.homematic
log:set TRACE org.openhab.binding.homematic
start org.openhab.binding.homematic
stop org.eclipse.smarthome.binding.homematic
log:set TRACE org.eclipse.smarthome.binding.homematic
start org.eclipse.smarthome.binding.homematic
```

7
_addons_ios/dropbox/readme.md
View File

@ -3,7 +3,7 @@ id: dropbox
label: Dropbox Synchronization
title: Dropbox Synchronization - System Integrations
type: io
description: "This service will synchronize files on the openHAB server, such as configuration and log files, to and/or from a Dropbox account."
description: "This service no longer exists. It was written to work with the original Dropbox API, which is now retired."
source: https://github.com/openhab/openhab1-addons/blob/master/bundles/io/org.openhab.io.dropbox/README.md
since: 1x
logo: images/addons/dropbox.png
@ -16,6 +16,11 @@ install: auto
# Dropbox Synchronization Service
This service no longer exists. It was written to work with the original Dropbox API, which is now retired.
An update for OH2/ESH is in progress but not completed.
<hr>
This service will synchronize files on the openHAB server, such as configuration and log files, to and/or from a Dropbox account.
The main use case is backing up openHAB configuration and log files

29
concepts/audio.md
View File

@ -8,21 +8,34 @@ layout: documentation
Audio and voice features are an important aspect of any smart home solution as it is a very natural way to interact with the user.
Eclipse SmartHome comes with a very modular architecture that enables all kinds of different use cases. At its core, there is the notion of an *audio stream*. Audio streams are provided by *audio sources* and consumed by *audio sinks*.
Eclipse SmartHome comes with a very modular architecture that enables all kinds of different use cases.
At its core, there is the notion of an *audio stream*.
Audio streams are provided by *audio sources* and consumed by *audio sinks*.
![](images/audio.png)
- *Audio Streams* are essentially a byte stream with a given *audio format*. They do not need to be limited in size, i.e. it is also allowed to have continuous streams, e.g. the input from a microphone or from an Internet radio station.
- *Audio Streams* are essentially a byte stream with a given *audio format*.
They do not need to be limited in size, i.e. it is also allowed to have continuous streams, e.g. the input from a microphone or from an Internet radio station.
- *Audio Formats* define the container (e.g. WAV), encoding, bit rate, sample frequency and depth and the bit order (little or big endian).
- *Audio Sources* are services that are capable of producing audio streams. They can support different formats and provide a stream in a requested format upon request. Typical audio source services are microphones. Typically, a continuous stream is expected from them.
- *Audio Sinks* are services that accept audio streams of certain formats. Typically, these are expected to play the audio stream, i.e. they are some kind of speaker or media device.
- *Text-to-Speech* (TTS) services are similar to audio sources with respect to the ability to create audio streams. The difference is that they take a string as an input and will synthesize this string to a spoken text using a given voice. TTS services can provide information about the voices that they support and the locale that those voices are associated with. Each voice supports exactly one locale.
- *Speech-to-Text* (STT) services are similar to audio sinks, but they do not simply play back the stream, but convert it to a plain string. They provide information about supported formats and locales.
- *Audio Sources* are services that are capable of producing audio streams.
They can support different formats and provide a stream in a requested format upon request.
Typical audio source services are microphones. Typically, a continuous stream is expected from them.
- *Audio Sinks* are services that accept audio streams of certain formats.
Typically, these are expected to play the audio stream, i.e. they are some kind of speaker or media device.
- *Text-to-Speech* (TTS) services are similar to audio sources with respect to the ability to create audio streams.
The difference is that they take a string as an input and will synthesize this string to a spoken text using a given voice.
TTS services can provide information about the voices that they support and the locale that those voices are associated with.
Each voice supports exactly one locale.
- *Speech-to-Text* (STT) services are similar to audio sinks, but they do not simply play back the stream, but convert it to a plain string.
They provide information about supported formats and locales.
As plain text from an STT service is often not very useful, there is additionally the concept of a *human language interpreter*:
![](images/hli.png)
A *Human Language Interpreter* takes a string as an input. It then derives actions from it (like sending commands to devices) and/or replies with a string, which opens the possibility to realize conversations. As such an interpreter is not directly linked to audio streams, but operates on strings only, this can be the basis for any kind of assistant, e.g. for chat bots using the console, XMPP, Twitter or other messaging services.
A *Human Language Interpreter* takes a string as an input.
It then derives actions from it (like sending commands to devices) and/or replies with a string, which opens the possibility to realize conversations.
As such an interpreter is not directly linked to audio streams, but operates on strings only, this can be the basis for any kind of assistant, e.g. for chat bots using the console, XMPP, Twitter or other messaging services.
Applications can dynamically choose which services to use, so that different sinks can be used for different use cases. Defaults can be set as a configuration for all those services in case an application does not ask for any specific service.
Applications can dynamically choose which services to use, so that different sinks can be used for different use cases.
Defaults can be set as a configuration for all those services in case an application does not ask for any specific service.

16
concepts/categories.md
View File

@ -6,15 +6,19 @@ layout: documentation
# 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.
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.
We separate 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:
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 %}
@ -22,11 +26,13 @@ The thing type definition allows to specify a category. User interfaces can pars
### Channel Group 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 `thing` category list.
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 `Thing` category list.
## Channel Categories
The channel type definition allows to specify a category. A binding should classify each channel into one of the existing categories or leave the category blank, if there is no good match. There are different types of categories for channels, which are listed below.
The Channel type definition allows to specify a category.
A Binding should classify each Channel into one of the existing categories or leave the category blank, if there is no good match.
There are different types of categories for Channels, which are listed below.
{% for category in site.data.categories %}
{% assign typesStr = typesStr | append: category.type | append: ',' %}

17
concepts/discovery.md
View File

@ -8,7 +8,7 @@ layout: documentation
Many devices, technologies and systems can be automatically discovered on the network or browsed through some API. It therefore makes a lot of sense to use these features for a smart home solution.
In Eclipse SmartHome bindings therefore implement _Discovery Services_ for things, which provide _Discovery Results_. All _Discovery Results_ are regarded as suggestions to the user and are put into the _inbox_.
In Eclipse SmartHome bindings therefore implement _Discovery Services_ for Things, which provide _Discovery Results_. All _Discovery Results_ are regarded as suggestions to the user and are put into the _inbox_.
### Background Discovery
@ -18,16 +18,21 @@ It is possible to override this setting and deactivate background discovery for
## Inbox
The inbox holds a list of all discovered things (`DiscoveryResult`) from all active discovery services. A discovery result represents a discovered thing of a specific thing type, that could be instantiated as a thing. The result usually contains properties that identify the discovered things further like IP address or a serial number. Each discovery result also has a timestamp when it was added to or updated in the inbox and it may also contain a time to live, indicating the time after which it is be automatically removed from the inbox.
The inbox holds a list of all discovered Things (`DiscoveryResult`) from all active discovery services.
A discovery result represents a discovered Thing of a specific Thing type, that could be instantiated as a Thing.
The result usually contains properties that identify the discovered Things further like IP address or a serial number.
Each discovery result also has a timestamp when it was added to or updated in the inbox and it may also contain a time to live, indicating the time after which it is be automatically removed from the inbox.
Discovery results can either be ignored or approved, where in the latter case a thing is created for them and they become available in the application. If an entry is ignored, it will be hidden in the inbox without creating a thing for it.
Discovery results can either be ignored or approved, where in the latter case a Thing is created for them and they become available in the application.
If an entry is ignored, it will be hidden in the inbox without creating a Thing for it.
Eclipse SmartHome offers a service to automatically ignore discovery results in the inbox, whenever a thing is created manually, that represents the same thing, as the respective discovery result would create.
This thing would either have the same thing UID or the value of its representation property is equal to the representation property's value in the discovery result. This service is enabled by default but can be disabled by setting `org.eclipse.smarthome.inbox:autoIgnore=false`.
Eclipse SmartHome offers a service to automatically ignore discovery results in the inbox, whenever a Thing is created manually, that represents the same Thing, as the respective discovery result would create.
This Thing would either have the same Thing UID or the value of its representation property is equal to the representation property's value in the discovery result.
This service is enabled by default but can be disabled by setting `org.eclipse.smarthome.inbox:autoIgnore=false`.
### Auto Approve
If the manual acceptence of discovery results by the user is not wished, it is possible to turn on the auto-approval feature of the inbox.
If the manual acceptance of discovery results by the user is not wished, it is possible to turn on the auto-approval feature of the inbox.
In this case, every new entry gets automatically approved immediately (unless it has been marked as ignored as a duplicate).
The auto approval can be enabled by the setting `org.eclipse.smarthome.inbox:autoApprove=true`; the default is false.

76
concepts/items.md
View File

@ -6,12 +6,12 @@ layout: documentation
# Items
Eclipse SmartHome has a strict separation between the physical world (the "things", see below) and the application, which is built around the notion of "items" (also called the virtual layer).
Eclipse SmartHome has a strict separation between the physical world (the "Things", see below) and the application, which is built around the notion of "Items" (also called the virtual layer).
Items represent functionality that is used by the application (mainly user interfaces or automation logic).
Items have a state and are used through events.
The following item types are currently available (alphabetical order):
The following Item types are currently available (alphabetical order):
| Item Name | Description | Command Types |
|--------------------|-------------|---------------|
@ -19,7 +19,7 @@ The following item types are currently available (alphabetical order):
| Contact | Item storing status of e.g. door/window contacts | OpenClose |
| DateTime | Stores date and time | - |
| Dimmer | Item carrying a percentage value for dimmers | OnOff, IncreaseDecrease, Percent |
| Group | Item to nest other items / collect them in groups | - |
| Group | Item to nest other Items / collect them in Groups | - |
| Image | Holds the binary data of an image | - |
| Location | Stores GPS coordinates | Point |
| Number | Stores values in number format, takes an optional dimension suffix | Decimal |
@ -31,12 +31,12 @@ The following item types are currently available (alphabetical order):
## Group Items
Group items collect other items into groups.
Group items can themselves be members of other group items.
Group Items collect other Items into Groups.
Group Items can themselves be members of other Group Items.
Cyclic membership is not forbidden but strongly not recommended.
User interfaces might display group items as single entries and provide navigation to its members.
User interfaces might display Group Items as single entries and provide navigation to its members.
Example for a Group item as a simple collection of other items:
Example for a Group Item as a simple collection of other Items:
```
Group groundFloor
Switch kitchenLight (groundFloor)
@ -45,29 +45,29 @@ Example for a Group item as a simple collection of other items:
### Derive Group State from Member Items
Group items can derive their own state from their member items.
To derive a state the group item must be constructed using a base item and a group function.
When calculating the state, group functions recursively traverse the group's members and also take members of subgroups into account.
If a subgroup however defines a state on its own (having base item & group function set) traversal stops and the state of the subgroup member is taken.
Group Items can derive their own state from their member Items.
To derive a state the Group Item must be constructed using a base Item and a Group function.
When calculating the state, Group functions recursively traverse the Group's members and also take members of subgroups into account.
If a subgroup however defines a state on its own (having base Item & Group function set) traversal stops and the state of the subgroup member is taken.
Available group functions:
Available Group functions:
| Function | Parameters | Base Item | Description |
|--------------------|-------------------------------|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| EQUALITY | - | \<all\> | Sets the state of the members if all have equal state. Otherwise UNDEF is set. |
| AND, OR, NAND, NOR | <activeState>, <passiveState> | \<all\> (must match active & passive state) | Sets the \<activeState\>, if the member state \<activeState\> evaluates to `true` under the boolean term. Otherwise the \<passiveState\> is set.|
| SUM, AVG, MIN, MAX | - | Number | Sets the state according to the arithmetic function over all member states. |
| COUNT | <regular expression> | Number | Sets the state to the number of members matching the given regular expression with their states. |
| LATEST, EARLIEST | - | DateTime | Sets the state to the latest/earliest date from all member states
| Function | Parameters | Base Item | Description |
|--------------------|-------------------------------|---------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| EQUALITY | - | \<all\> | Sets the state of the members if all have equal state. Otherwise UNDEF is set. |
| AND, OR, NAND, NOR | <activeState>, <passiveState> | \<all\> (must match active & passive state) | Sets the \<activeState\>, if the member state \<activeState\> evaluates to `true` under the boolean term. Otherwise the \<passiveState\> is set. |
| SUM, AVG, MIN, MAX | - | Number | Sets the state according to the arithmetic function over all member states. |
| COUNT | <regular expression> | Number | Sets the state to the number of members matching the given regular expression with their states. |
| LATEST, EARLIEST | - | DateTime | Sets the state to the latest/earliest date from all member states |
Examples for derived states on group items when declared in the item DSL:
Examples for derived states on Group Items when declared in the Item DSL:
- `Group:Number:COUNT(".*")` counts all members of the group matching the given regular expression, here any character or state (simply count all members).
- `Group:Number:COUNT(".*")` counts all members of the Group matching the given regular expression, here any character or state (simply count all members).
- `Group:Number:AVG` calculates the average value over all member states which can be interpreted as `DecimalTypes`.
- `Group:Switch:OR(ON,OFF)` sets the group state to `ON` if any of its members has the state `ON`, `OFF` if all are off.
- `Group:Switch:AND(ON,OFF)` sets the group state to `ON` if all of its members have the state `ON`, `OFF` if any of the group members has a different state than `ON`.
- `Group:DateTime:LATEST` sets the group state to the latest date from all its members states.
- `Group:Switch:OR(ON,OFF)` sets the Group state to `ON` if any of its members has the state `ON`, `OFF` if all are off.
- `Group:Switch:AND(ON,OFF)` sets the Group state to `ON` if all of its members have the state `ON`, `OFF` if any of the Group members has a different state than `ON`.
- `Group:DateTime:LATEST` sets the Group state to the latest date from all its members states.
## State and Command Type Formatting
@ -123,29 +123,29 @@ HSB string values consist of three comma-separated values for hue (0-360°), sat
| StopMoveType | `STOP`, `MOVE` |
| UpDownType | `UP`, `DOWN` |
## A note on items which accept multiple state data types
## A note on Items which accept multiple state data types
There are a number of items which accept multiple state data types, for example `DimmerItem`, which accepts `OnOffType` and `PercentType`, `RollershutterItem`, which accepts `PercentType` and `UpDownType`, or `ColorItem`, which accepts `HSBType`, `OnOffType` and `PercentType`.
Since an item has a SINGLE state, these multiple data types can be considered different views to this state.
The data type carrying the most information about the state is usually used to keep the internal state for the item, and other datatypes are converted from this main data type.
There are a number of Items which accept multiple state data types, for example `DimmerItem`, which accepts `OnOffType` and `PercentType`, `RollershutterItem`, which accepts `PercentType` and `UpDownType`, or `ColorItem`, which accepts `HSBType`, `OnOffType` and `PercentType`.
Since an Item has a SINGLE state, these multiple data types can be considered different views to this state.
The data type carrying the most information about the state is usually used to keep the internal state for the Item, and other datatypes are converted from this main data type.
This main data type is normally the first element in the list returned by `Item.getAcceptedDataTypes()`.
Here is a short table demonstrating conversions for the examples above:
| Item Name | Main Data Type | Additional Data Types Conversions |
|---------------|----------------|-----------------------------------|
| Item Name | Main Data Type | Additional Data Types Conversions |
|---------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Color | `HSBType` | &bull; `OnOffType` - `OFF` if the brightness level in the `HSBType` equals 0, `ON` otherwise <br/> &bull; `PercentType` - the value for the brightness level in the `HSBType` |
| Dimmer | `PercentType` | `OnOffType` - `OFF` if the brightness level indicated by the percent type equals 0, `ON` otherwise |
| Rollershutter | `PercentType` | `UpDownType` - `UP` if the shutter level indicated by the percent type equals 0, `DOWN` if it equals 100, and `UnDefType.UNDEF` for any other value|
| Dimmer | `PercentType` | `OnOffType` - `OFF` if the brightness level indicated by the percent type equals 0, `ON` otherwise |
| Rollershutter | `PercentType` | `UpDownType` - `UP` if the shutter level indicated by the percent type equals 0, `DOWN` if it equals 100, and `UnDefType.UNDEF` for any other value |
## Item Metadata
Sometimes additional information is required to be attached to items for certain use-cases.
This could be e.g. an application which needs some hints in order to render the items in a generic way or an integration with voice controlled assistants or any other services which access the items and need to understand their "meaning".
Sometimes additional information is required to be attached to Items for certain use-cases.
This could be e.g. an application which needs some hints in order to render the Items in a generic way or an integration with voice controlled assistants or any other services which access the Items and need to understand their "meaning".
For this purpose, such meta-information can be attached to items using disjunct namespaces so they won't conflict with each other.
For this purpose, such meta-information can be attached to Items using disjunct namespaces so they won't conflict with each other.
Each metadata entry has a main value and optionally additional key/value pairs.
There can be metadata attached to an item for as many namespaces as desired, like in the following example:
There can be metadata attached to an Item for as many namespaces as desired, like in the following example:
Switch "My Fan" { homekit="Fan.v2", alexa="Fan" [ type="oscillating", speedSteps=3 ] }
@ -155,5 +155,5 @@ Extensions which can infer some metadata automatically need to implement an regi
They may provision them from any source they like and also dynamically remove or add data.
They are also not restricted to a single namespace.
The `MetadataRegistry` provides access for all extensions which need to read the item metadata programmatically.
It is the central place where additional information about items is kept.
The `MetadataRegistry` provides access for all extensions which need to read the Item metadata programmatically.
It is the central place where additional information about Items is kept.

20
concepts/profiles.md
View File

@ -4,22 +4,30 @@ 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.
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.
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.
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.
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 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.
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.

74
concepts/things.md
View File

@ -5,7 +5,7 @@ layout: documentation
# Things
Things are the entities that can physically be added to a system and which can potentially provide many functionalities in one.
It is important to note that things do not have to be devices, but they can also represent a web service or any other manageable source of information and functionality.
It is important to note that Things do not have to be devices, but they can also represent a web service or any other manageable source of information and functionality.
From a user perspective, they are relevant for the setup and configuration process, but not for the operation.
Things can have configuration properties, which can be optional or mandatory.
@ -13,44 +13,44 @@ Such properties can be basic information like an IP address, an access token for
### Channels
Things provide "channels", which represent the different functions the thing provides.
Where the thing is the physical entity or source of information, the channel is a concrete function from this thing.
A physical light bulb might have a color temperature channel and a color channel, both providing functionality of the one light bulb thing to the system.
For sources of information the thing might be the local weather with information from a web service with different channels like temperature, pressure and humidity.
Things provide "Channels", which represent the different functions the Thing provides.
Where the Thing is the physical entity or source of information, the Channel is a concrete function from this Thing.
A physical light bulb might have a color temperature Channel and a color Channel, both providing functionality of the one light bulb Thing to the system.
For sources of information the Thing might be the local weather with information from a web service with different Channels like temperature, pressure and humidity.
Channels are linked to items, where such links are the glue between the virtual and the physical layer.
Once such a link is established, a thing reacts on events sent for an item that is linked to one of its channels.
Likewise, it actively sends out events for items linked to its channels.
Channels are linked to Items, where such links are the glue between the virtual and the physical layer.
Once such a link is established, a Thing reacts on events sent for an item that is linked to one of its Channels.
Likewise, it actively sends out events for Items linked to its Channels.
### Bridges
A special type of thing is a "bridge".
Bridges are things that need to be added to the system in order to gain access to other things.
A typical example of a bridge is an IP gateway for some non-IP based home automation system or a web service configuration with authentication information which every thing from this web service might need.
A special type of Thing is a "bridge".
Bridges are Things that need to be added to the system in order to gain access to other Things.
A typical example of a bridge is an IP gateway for some non-IP based home automation system or a web service configuration with authentication information which every Thing from this web service might need.
### Discovery
As many things can be automatically discovered, there are special mechanisms available that deal with the handling of [automatically discovered things](discovery.html).
As many Things can be automatically discovered, there are special mechanisms available that deal with the handling of [automatically discovered Things](discovery.html).
## Thing Status
Each thing has a status object, which helps to identify possible problems with the device or service.
Each Thing has a status object, which helps to identify possible problems with the device or service.
The following table provides an overview of the different statuses:
| Status | Description |
|---------------|-------------|
| UNINITIALIZED | This is the initial status of a thing, when it is added or the framework is being started. This status is also assigned, if the initializing process failed or the binding is not available. Commands, which are sent to channels will not be processed. |
| INITIALIZING | This state is assigned while the binding initializes the thing. It depends on the binding how long the initializing process takes. Commands, which are sent to channels will not be processed. |
| UNKNOWN | The handler is fully initialized but due to the nature of the represented device/service it cannot really tell yet whether the thing is ONLINE or OFFLINE. Therefore the thing potentially might be working correctly already and may or may not process commands. But the framework is allowed to send commands, because some radio-based devices may go ONLINE if a command is sent to them. The handler should take care to switch the thing to ONLINE or OFFLINE as soon as possible. |
| ONLINE | The device/service represented by a thing is assumed to be working correctly and can process commands. |
| OFFLINE | The device/service represented by a thing is assumed to be not working correctly and may not process commands. But the framework is allowed to send commands, because some radio-based devices may go back to ONLINE, if a command is sent to them. |
| REMOVING | The device/service represented by a thing should be removed, but the binding did not confirm the deletion yet. Some bindings need to communicate with the device to unpair it from the system. Thing is probably not working and commands can not be processed. |
| REMOVED | This status indicates that the device/service represented by a thing was removed from the external system after the REMOVING was initiated by the framework. Usually this status is an intermediate status because the thing gets removed from the database after this status was assigned. |
| Status | Description |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| UNINITIALIZED | This is the initial status of a Thing, when it is added or the framework is being started. This status is also assigned, if the initializing process failed or the binding is not available. Commands, which are sent to Channels will not be processed. |
| INITIALIZING | This state is assigned while the binding initializes the Thing. It depends on the binding how long the initializing process takes. Commands, which are sent to Channels will not be processed. |
| UNKNOWN | The handler is fully initialized but due to the nature of the represented device/service it cannot really tell yet whether the Thing is ONLINE or OFFLINE. Therefore the Thing potentially might be working correctly already and may or may not process commands. But the framework is allowed to send commands, because some radio-based devices may go ONLINE if a command is sent to them. The handler should take care to switch the Thing to ONLINE or OFFLINE as soon as possible. |
| ONLINE | The device/service represented by a Thing is assumed to be working correctly and can process commands. |
| OFFLINE | The device/service represented by a Thing is assumed to be not working correctly and may not process commands. But the framework is allowed to send commands, because some radio-based devices may go back to ONLINE, if a command is sent to them. |
| REMOVING | The device/service represented by a Thing should be removed, but the binding did not confirm the deletion yet. Some bindings need to communicate with the device to unpair it from the system. Thing is probably not working and commands can not be processed. |
| REMOVED | This status indicates that the device/service represented by a Thing was removed from the external system after the REMOVING was initiated by the framework. Usually this status is an intermediate status because the Thing gets removed from the database after this status was assigned. |
The statuses UNINITIALIZED, INITIALIZING and REMOVING are set by the framework, where as the statuses UNKNOWN, ONLINE and OFFLINE are assigned from a binding.
Additionally, the REMOVED state is set by the binding to indicate that the removal process has been completed, i.e. the thing must have been in REMOVING state before.
Additionally, the REMOVED state is set by the binding to indicate that the removal process has been completed, i.e. the Thing must have been in REMOVING state before.
### Status Transitions
@ -58,11 +58,11 @@ The following diagram shows the allowed status transitions:
![Status Transitions](diagrams/status_transitions.png)
The initial state of a thing is UNINITIALIZED.
From UNINITIALIZED the thing goes into INITIALIZING.
If the initialization fails, the thing goes back to UNINITIALIZED.
If the initialization succeeds, the binding sets the status of the thing to UNKNOWN, ONLINE or OFFLINE, which all mean that the thing handler is fully initialized.
From one of this states the thing can go back into UNINITIALIZED, REMOVING or REMOVED.
The initial state of a Thing is UNINITIALIZED.
From UNINITIALIZED the Thing goes into INITIALIZING.
If the initialization fails, the Thing goes back to UNINITIALIZED.
If the initialization succeeds, the binding sets the status of the Thing to UNKNOWN, ONLINE or OFFLINE, which all mean that the Thing handler is fully initialized.
From one of this states the Thing can go back into UNINITIALIZED, REMOVING or REMOVED.
The statuses REMOVING and REMOVED can also be reached from any of the other states.
## Status Details
@ -76,18 +76,18 @@ The following table lists the different status details for each status:
<tr valign="top"> <td>HANDLER_REGISTERING_ERROR</td><td>The handler failed in the service registration phase.</td></tr>
<tr valign="top"> <td>HANDLER_CONFIGURATION_PENDING</td><td>The handler is registered but can not be initialized caused by missing configuration parameters.</td></tr>
<tr valign="top"> <td>HANDLER_INITIALIZING_ERROR</td><td>The handler failed in the initialization phase.</td></tr>
<tr valign="top"> <td>BRIDGE_UNINITIALIZED</td><td>The bridge associated with this thing is not initialized.</td></tr>
<tr valign="top"> <td>BRIDGE_UNINITIALIZED</td><td>The bridge associated with this Thing is not initialized.</td></tr>
<tr valign="top"><td>INITIALIZING</td> <td>NONE</td><td>No further status details available.</td></tr>
<tr valign="top"><td>UNKNOWN</td> <td>NONE</td><td>No further status details available.</td></tr>
<tr valign="top"><td rowspan="2">ONLINE</td> <td>NONE</td><td>No further status details available.</td></tr>
<tr valign="top"> <td>CONFIGURATION_PENDING</td><td>The thing is waiting to transfer configuration information to a device. Some bindings need to communicate with the device to make sure the configuration is accepted.</td></tr>
<tr valign="top"> <td>CONFIGURATION_PENDING</td><td>The Thing is waiting to transfer configuration information to a device. Some bindings need to communicate with the device to make sure the configuration is accepted.</td></tr>
<tr valign="top"><td rowspan="7">OFFLINE</td> <td>NONE</td><td>No further status details available.</td></tr>
<tr valign="top"> <td>COMMUNICATION_ERROR</td><td>Error in communication with the device. This may also be only a temporary error.</td></tr>
<tr valign="top"> <td>CONFIGURATION_ERROR</td><td>An issue with the configuration of a thing prevents the communication with the represented device or service. This issue might be solved by reconfiguring the thing.</td></tr>
<tr valign="top"> <td>BRIDGE_OFFLINE</td><td>Assuming the thing to be offline because the corresponding bridge is offline.</td></tr>
<tr valign="top"> <td>FIRMWARE_UPDATING</td><td>The thing is currently operating a firmware update.</td></tr>
<tr valign="top"> <td>DUTY_CYCLE</td><td>The thing is currently in DUTY_CYCLE state, which means it is blocked for further usage.</td></tr>
<tr valign="top"> <td>GONE</td><td>The thing has been removed from the bridge or the network to which it belongs and is no longer available for use. The user can now remove the thing from the system.</td></tr>
<tr valign="top"> <td>CONFIGURATION_ERROR</td><td>An issue with the configuration of a Thing prevents the communication with the represented device or service. This issue might be solved by reconfiguring the Thing.</td></tr>
<tr valign="top"> <td>BRIDGE_OFFLINE</td><td>Assuming the Thing to be offline because the corresponding bridge is offline.</td></tr>
<tr valign="top"> <td>FIRMWARE_UPDATING</td><td>The Thing is currently operating a firmware update.</td></tr>
<tr valign="top"> <td>DUTY_CYCLE</td><td>The Thing is currently in DUTY_CYCLE state, which means it is blocked for further usage.</td></tr>
<tr valign="top"> <td>GONE</td><td>The Thing has been removed from the bridge or the network to which it belongs and is no longer available for use. The user can now remove the Thing from the system.</td></tr>
<tr valign="top"><td>REMOVING</td> <td>NONE</td><td>No further status details available.</td></tr>
<tr valign="top"><td>REMOVED</td> <td>NONE</td><td>No further status details available.</td></tr>
</table>
@ -100,8 +100,8 @@ This description can be used for debugging purposes and should not be presented
### Thing Status API
The Thing interface defines a method `getStatusInfo()` to retrieve the current status of the thing.
The following code shows how to print the status of each thing into the console:
The Thing interface defines a method `getStatusInfo()` to retrieve the current status of the Thing.
The following code shows how to print the status of each Thing into the console:
```java
Collection<Thing> things = thingRegistry.getAll();

6
concepts/units-of-measurement.md
View File

@ -35,14 +35,14 @@ This is:
## NumberItem linked to QuantityType Channel
In addition to the automated conversion the `NumberItem` linked to a channel delivering `QuantityTypes` can be configured to always have state updates converted to a specific unit.
In addition to the automated conversion the `NumberItem` linked to a Channel delivering `QuantityTypes` can be configured to always have state updates converted to a specific unit.
The unit given in the state description is parsed and then used for conversion (if necessary).
The framework assumes that the unit to parse is always the last token in the state description.
If the parsing failed the locale based default conversion takes place.
Number:Temperature temperature "Outside [%.2f °F]" { channel="...:current#temperature" }
In the example the `NumberItem` is specified to bind to channels which offer values from the dimension `Temperature`.
In the example the `NumberItem` is specified to bind to Channels which offer values from the dimension `Temperature`.
Without the dimension information the `NumberItem` only will receive updates of type `DecimalType` without a unit and any conversion.
The state description defines two decimal places for the value and the fix unit °F.
In case the state description should display the unit the binding delivers or the framework calculates through locale based conversion the pattern will look like this:
@ -54,7 +54,7 @@ In addition the placeholder `%unit%` can be placed anywhere in the state descrip
#### Defining ChannelTypes
In order to match `NumberItems` and channels and define a default state description with unit placeholder the channel also has to provide an item type which includes the dimension information:
In order to match `NumberItems` and Channels and define a default state description with unit placeholder the Channel also has to provide an Item type which includes the dimension information:
<channel-type id="temperature">