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 and added imperihome integration 

Signed-off-by: Kai Kreuzer <kai@openhab.org>
pull/133/head
Kai Kreuzer 2016-11-11 09:30:30 +01:00
parent 9fa75699fc
commit 5a14eef01d
No known key found for this signature in database
GPG Key ID: 5110767B6248D3C0
11 changed files with 487 additions and 355 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_data/oh1addons.csv
View File

@ -27,6 +27,7 @@ binding,EnOcean Binding
binding,Enphase Energy Binding
binding,Epson Projector Binding
binding,Exec Binding
binding,Fatek PLC Binding
binding,Freeswitch Binding
binding,FS20 Binding
binding,Garadget Binding
@ -39,6 +40,7 @@ binding,InsteonPLM Binding
binding,Intertechno Binding
binding,IPX800 Binding
binding,IRTrans Binding
binding,jointSPACE Binding
binding,KNX Binding
binding,Koubachi Binding
binding,LCN Binding

1 category label
27 binding Enphase Energy Binding
28 binding Epson Projector Binding
29 binding Exec Binding
30 binding Fatek PLC Binding
31 binding Freeswitch Binding
32 binding FS20 Binding
33 binding Garadget Binding
40 binding Intertechno Binding
41 binding IPX800 Binding
42 binding IRTrans Binding
43 binding jointSPACE Binding
44 binding KNX Binding
45 binding Koubachi Binding
46 binding LCN Binding

2
_includes/user-menu.html
View File

@ -8,6 +8,7 @@
<li><a href="{{docu}}/concepts/items.html">Items</a></li>
<li><a href="{{docu}}/concepts/things.html">Things</a></li>
<li><a href="{{docu}}/concepts/discovery.html">Inbox &amp; Discovery</a></li>
<li><a href="{{docu}}/concepts/audio.html">Audio &amp; Voice</a></li>
</ul>
</li>
<li><a href="{{docu}}/installation/index.html">Installation</a>
@ -65,6 +66,7 @@
<ul>
<li><a href="{{docu}}/addons/io/homekit/readme.html">HomeKit</a></li>
<li><a href="{{docu}}/addons/io/hueemulation/readme.html">Amazon Echo</a></li>
<li><a href="{{docu}}/addons/io/imperihome/readme.html">ImperiHome</a></li>
</ul>
</li>
<li><a href="{{docu}}/addons/uis.html">User Interfaces</a>

25
addons/bindings/onkyo/readme.md
View File

@ -22,6 +22,7 @@ This binding supports only one thing: The Onkyo AV Receiver
This binding can discover the supported Onkyo AV Receivers. At the moment only the following models are supported:
* TX-NR535
* TX-NR646
## Binding Configuration
@ -48,16 +49,20 @@ The Onkyo AVR supports the following channels:
| Channel Type ID | Item Type | Description |
|-------------------------|--------------|--------------|
| power | Switch | Power on/off your device |
| mute | Switch | Mute/unmute your device |
| input | Number | The input for the AVR |
| volume | Dimmer | Volume of your device |
| control | Player | Control the Zone Player, e.g. play/pause/next/previous/ffward/rewind (available if playing from Network or USB)|
| title | String | Title of the current song (available if playing from Network or USB)|
| album | String | Album name of the current song (available if playing from Network or USB)|
| artist | String | Artist name of the current song (available if playing from Network or USB)|
| currentPlayingTime | String | Current playing time of the current song (available if playing from Network or USB)|
| listenmode | Number | Current listening mode e.g. Stero, 5.1ch Surround,..|
| zone1#power | Switch | Power on/off your device |
| zone1#mute | Switch | Mute/unmute zone 1 |
| zone1#input | Number | The input for zone 1 |
| zone1#volume | Dimmer | Volume of zone 1 |
| zone2#power | Switch | Power on/off zone 2 |
| zone2#mute | Switch | Mute/unmute zone 2 |
| zone2#input | Number | The input for zone 2 |
| zone2#volume | Dimmer | Volume of zone 2 |
| player#control | Player | Control the Zone Player, e.g. play/pause/next/previous/ffward/rewind (available if playing from Network or USB)|
| player#title | String | Title of the current song (available if playing from Network or USB)|
| player#album | String | Album name of the current song (available if playing from Network or USB)|
| player#artist | String | Artist name of the current song (available if playing from Network or USB)|
| player#currentPlayingTime | String | Current playing time of the current song (available if playing from Network or USB)|
| player#listenmode | Number | Current listening mode e.g. Stero, 5.1ch Surround,..|
##Input Source Mapping

1
addons/io.md
View File

@ -12,3 +12,4 @@ layout: documentation
|-------|----------------------|
| [HomeKit]({{docu}}/addons/io/homekit/readme.html) | Exposes openHAB items to HomeKit, so that it can be used with Siri on iOS. |
| [Amazon Echo]({{docu}}/addons/io/hueemulation/readme.html) | Emulates a Philips hue bridge, so that devices like Amazon Echo can discover and use it. |
| [ImperiHome]({{docu}}/addons/io/imperihome/readme.html) | Allows the integration of openHAB into the Evertygo ImperiHome dashboard app |

434
addons/io/imperihome/readme.md Normal file
View File

@ -0,0 +1,434 @@
---
layout: documentation
---
{% include base.html %}
# ImperiHome integration service
This IO service exposes openHAB Items to the Evertygo [ImperiHome](http://www.evertygo.com/imperihome) dashboard app for Android and iOS.
It creates a REST service at _/imperihome/iss_ that implements the [ImperiHome Standard System API](http://dev.evertygo.com/api/iss) (ISS).
## Installation
The ImperiHome integration service can be installed through the Paper UI. Navigate to Extensions &gt; Misc and click Install.
## Configuration
The service itself has no configuration. ImperiHome on the other hand must be configured to connect to your openHAB instance.
Start ImperiHome, open the menu and go to My Systems. Add a new system (+) and choose 'ImperiHome Standard System' as the object type. Now enter the URL to your openHAB instance
as Local URL, followed by _/imperihome/iss_. For example, if your OH instance is running at _http://192.168.1.10:8080/_, the Local URL would be _http://192.168.1.10:8080/imperihome/iss_.
If you have port forwarding or similar set up to access your OH form the internet, you can also fill the Remote URL in the same way. For example:
_http://my-openhab-url.dyndns.org:8080/imperihome/iss_. Please be aware that this service provides no authentication mechanism, so anyone could use the API to control your
system when accessible from the internet.
Click Next to let ImperiHome validate the URL. After validation succeeded the system is added and you can continue to configure your Items for use in ImperiHome.
## Device Tagging
This service uses Item tags to determine how to expose your Items to ImperiHome. All tags are formatted like this:
```
iss:<tagtype>:<value>
```
For example:
```
iss:room:Kitchen
```
If you've defined your Items in _.items_ files, tags can be added using the
```
[ "mytag" ]
```
syntax (after the _(Groups)_ and before the _{channel}_).
If you created your items another way, e.g. using the Paper UI, [HABmin](https://github.com/openhab/org.openhab.ui.habmin) allows you to modify the tags.
### Tag: _type_
Specifies the device type to expose to ImperiHome. Take a look at [Device types](#deviceTypes) below for the supported device types and how to configure them.
If no type is specified, this service will try to auto-detect the type from the Item, based on supported value types (OnOff for a switch, HSB for color light) and Item name.
_Required_: no<br>
_Default_: auto-detect<br>
Example:
```
iss:type:DevSwitch
```
### Tag: _room_
Specifies the room the device will show up in in ImperiHome.
_Required_: no<br>
_Default_: 'No Room'<br>
_Example_:
```
iss:room:Kitchen
```
### Tag: _label_
Sets the device label in ImperiHome. If no label is specified, the Item label is used if available. Otherwise the Item name will be used.
_Required_: no<br>
_Default_: Item label or name<br>
_Example_:
```
iss:label:Kitchen light
```
### Tag: _mapping_
Sets the mapping for a ImperiHome MultiSwitch device, just like an openHAB sitemap mapping does.
In the example below, 'All off', 'Relax' and 'Reading' will be visible in ImperiHome. Clicking one of the options will send
a 0, 1 or 2 value command to the openHAB item.
_Required_: only for MultiSwitch device<br>
_Default_: none<br>
_Example_:
```
iss:mapping:0=All off,1=Relax,2=Reading
```
### Tag: _link_
Links two devices together, using the value from the linked device as an additional value in the device containing the link tag.
See [Device links](#deviceLinks) for details.
_Required_: no<br>
_Default_: none<br>
_Example_:
```
iss:link:energy:Kitchen_Current_Consumption
```
### Tag: _unit_
Sets the unit for devices with a numeric value, such as _DevTemperature_ and _DevGenericSensor_.
The unit is only used to tell ImperiHome what to display; no conversion is performed.
_Required_: no<br>
_Default_: none<br>
_Example_:
```
iss:unit:°C
```
### Tag: _invert_
Inverts the state of on/off devices such as switches and dimmers.
_Required_: no<br>
_Default_: false<br>
_Example_:
```
iss:invert:true
```
<a name="deviceTypes"></a>
## Device types
The following table lists the ImperiHome API device types that you can use in a _iss:type_ tag. Not all device types are currently supported. For those that are supported,
the Item types you can use them on are listed.
<table>
<tr>
<th>Device</th>
<th>Description</th>
<th>Supported</th>
<th>Item types</th>
<th>Link types</th>
</tr>
<tr>
<td>DevCamera</td>
<td>MJPEG IP Camera</td>
<td>No</td>
<td></td>
<td>-</td>
</tr>
<tr>
<td>DevCO2</td>
<td>CO2 sensor</td>
<td>Yes</td>
<td>Number</td>
<td>-</td>
</tr>
<tr>
<td>DevCO2Alert</td>
<td>CO2 Alert sensor</td>
<td>Yes</td>
<td>Contact, Number, String<sup>(1)</sup>, Switch</td>
<td>-</td>
</tr>
<tr>
<td>DevDimmer</td>
<td>Dimmable light</td>
<td>Yes</td>
<td>Dimmer</td>
<td>energy</td>
</tr>
<tr>
<td>DevDoor</td>
<td>Door / window security sensor</td>
<td>Yes</td>
<td>Contact, Number, String<sup>(1)</sup>, Switch</td>
<td>-</td>
</tr>
<tr>
<td>DevElectricity</td>
<td>Electricity consumption sensor</td>
<td>Yes</td>
<td>Number</td>
<td>kwh, watt</td>
</tr>
<tr>
<td>DevFlood</td>
<td>Flood security sensor</td>
<td>Yes</td>
<td>Contact, Number, String<sup>(1)</sup>, Switch</td>
<td>-</td>
</tr>
<tr>
<td>DevGenericSensor</td>
<td>Generic sensor (any value)</td>
<td>Yes</td>
<td>Number, String</td>
<td>-</td>
</tr>
<tr>
<td>DevHygrometry</td>
<td>Hygro sensor</td>
<td>Yes</td>
<td>Number</td>
<td>-</td>
</tr>
<tr>
<td>DevLock</td>
<td>Door lock</td>
<td>Yes</td>
<td>Contact, Switch</td>
<td>-</td>
</tr>
<tr>
<td>DevLuminosity</td>
<td>Luminance sensor</td>
<td>Yes</td>
<td>Number</td>
<td>-</td>
</tr>
<tr>
<td>DevMotion</td>
<td>Motion security sensor</td>
<td>Yes</td>
<td>Contact, Number, String<sup>(1)</sup>, Switch</td>
<td>-</td>
</tr>
<tr>
<td>DevMultiSwitch</td>
<td>Multiple choice actuator</td>
<td>Yes</td>
<td>Number</td>
<td>-</td>
</tr>
<tr>
<td>DevNoise</td>
<td>Noise sensor</td>
<td>Yes</td>
<td>Number</td>
<td>-</td>
</tr>
<tr>
<td>DevPlayer</td>
<td>Audio/Video player</td>
<td>No</td>
<td></td>
<td>-</td>
</tr>
<tr>
<td>DevPlaylist</td>
<td>Audio/Video playlist</td>
<td>No</td>
<td></td>
<td>-</td>
</tr>
<tr>
<td>DevPressure</td>
<td>Pressure sensor</td>
<td>Yes</td>
<td>Number</td>
<td>-</td>
</tr>
<tr>
<td>DevRain</td>
<td>Rain sensor</td>
<td>Yes</td>
<td>Number</td>
<td>accum</td>
</tr>
<tr>
<td>DevRGBLight</td>
<td>RGB(W) Light (dimmable)</td>
<td>Yes</td>
<td>Color</td>
<td>energy</td>
</tr>
<tr>
<td>DevScene</td>
<td>Scene (launchable)</td>
<td>Yes</td>
<td>Switch, Number</td>
<td>-</td>
</tr>
<tr>
<td>DevShutter</td>
<td>Shutter actuator</td>
<td>No</td>
<td></td>
<td>-</td>
</tr>
<tr>
<td>DevSmoke</td>
<td>Smoke security sensor</td>
<td>Yes</td>
<td>Contact, Number, String<sup>(1)</sup>, Switch</td>
<td>-</td>
</tr>
<tr>
<td>DevSwitch</td>
<td>Standard on/off switch</td>
<td>Yes</td>
<td>Switch</td>
<td>energy</td>
</tr>
<tr>
<td>DevTemperature</td>
<td>Temperature sensor</td>
<td>Yes</td>
<td>Number</td>
<td>-</td>
</tr>
<tr>
<td>DevTempHygro</td>
<td>Temperature and Hygrometry combined sensor</td>
<td>Yes</td>
<td>Number</td>
<td>hygro, temp</td>
</tr>
<tr>
<td>DevThermostat</td>
<td>Thermostat</td>
<td>No</td>
<td></td>
<td>-</td>
</tr>
<tr>
<td>DevUV</td>
<td>UV sensor</td>
<td>Yes</td>
<td>Number</td>
<td>-</td>
</tr>
<tr>
<td>DevWind</td>
<td>Wind sensor</td>
<td>Yes</td>
<td>Number</td>
<td>direction</td>
</tr>
</table>
<sup>(1)</sup> When using a String Item for trippable devices, any non-empty value other than 'ok' will set the device to tripped. This makes it compatible with the Nest Protect binding.
<a name="deviceLinks"></a>
## Device links
Some devices can be linked to another device. This allows you to create combined devices reporting multiple values, or reporting the energy consumption with a switch device.
The _link_ tag refers to the name of the Item it should link to. The item must be an ImperiHome device itself, so it must have at least one _iss_ tag.
### Switch energy consumption
ImperiHome allows you to show the current energy consumption for a _DevDimmer_, _DevRGBLight_ and _DevSwitch_.
This example links the _MyLightEnergy_ Number Item to the _MyLight_ Switch Item,
so the _DevSwitch_ device will also report the energy consumption value to ImperiHome:
```
Switch MyLight "My Light" ["iss:type:DevSwitch", "iss:link:energy:MyLight_Energy"] { channel="zwave:device:1:node14:switch_binary1" }
Number MyLightEnergy "My Light Usage [%.1f W]" ["iss:type:DevElectricity"] { channel="zwave:device:1:node14:meter_watts1" }
```
### Total energy consumption
The _DevElectricity_ devices main value is the current consumption in Watts. To add the total consumption in KWh, link your electricity device to
a generic sensor device containing the total energy consumption value:
```
Number MyLight_Energy "My Light Usage [%.1f W]" ["iss:type:DevElectricity", "iss:link:kwh:MyLight_Total_Energy"] { channel="zwave:device:1:node14:meter_watts1" }
Number MyLight_Total_Energy "My Light Total usage [%.1f KWh]" ["iss:type:DevGenericSensor", "iss:unit:KWh"] { channel="zwave:device:1:node14:sensor_power1" }
```
### TempHygro
ImperiHome recognizes the special _DevTempHygro_ device, combining a temperature and hydrometry sensor. You can create such a device by linking either from a temperature Item to a hygro Item:
```
Number MyTemp "Temperature [%.1f °C]" ["iss:type:DevTempHygro", "iss:link:hygro:MyHum"] { channel="zwave:device:1:node8:sensor_temperature" }
Number MyHum "Humidity [%d%%]" ["iss:type:DevHygrometry"] { channel="zwave:device:1:node8:sensor_relhumidity" }
```
or vise versa:
```
Number MyTemp "Temperature [%.1f °C]" ["iss:type:DevTemperature"] { channel="zwave:device:1:node8:sensor_temperature" }
Number MyHum "Humidity [%d%%]" ["iss:type:DevTempHygro", "iss:link:temp:MyTemp"] { channel="zwave:device:1:node8:sensor_relhumidity" }
```
### Rain accumulation
The _DevRain_ devices main value is the current instant rain value (default in mm per hour). To add the total rain accumulation value, link your rain device to
a generic sensor device:
```
Number RainCurrent "Rain current [%.1f mm/h]" ["iss:type:DevRain", "iss:link:accum:RainAccumulation"] { channel="..." }
Number RainAccumulation "Rain accumulation [%.1f mm]" ["iss:type:DevGenericSensor", "iss:unit:mm"] { channel="..." }
```
### Wind direction
The _DevWind_ devices main value is the current wind speed (default in km per hour). To add the wind direction value (default in degrees), link your wind device to
a generic sensor device:
```
Number WindSpeed "Wind speed [%.1f km/h]" ["iss:type:DevWind", "iss:link:direction:WindDirection"] { channel="..." }
Number WindDirection "Wind direction [%d deg]" ["iss:type:DevGenericSensor", "iss:unit:deg"] { channel="..." }
```
## Items example
```
Color LVR_Billy "Billy" <colorlight> (Lights) ["iss:room:Living room", "iss:type:DevRGBLight"] { channel="hue:0210:001122334455:bulb1:color" }
Switch LVR_TallLamp "Tall lamp" (Lights) ["iss:room:Living room", "iss:type:DevSwitch", "iss:invert:true"] { channel="zwave:device:1:node3:switch_binary" }
Dimmer LVR_DinnerTable "Dinner table" (Lights) ["iss:room:Living room", "iss:type:DevDimmer"] { channel="zwave:device:1:node13:switch_dimmer" }
Number ENT_Entrance_Current "Entrance usage [%.1f W]" (Wattage) ["iss:room:Entrance", "iss:type:DevElectricity", "iss:unit:Watt"] { channel="zwave:device:1:node14:meter_watts1" }
Number ENT_Temperature "Entrance temperature [%.1f °C]" (Temperature) ["iss:room:Entrance", "iss:type:DevTempHygro", "iss:link:hygro:ENT_Humidity"] { channel="zwave:device:1:node8:sensor_temperature" }
Number ENT_Luminance "Entrance light [%d lm]" (Luminance) ["iss:room:Entrance", "iss:type:DevLuminosity", "iss:unit:lux"] { channel="zwave:device:1:node8:sensor_luminance" }
Number ENT_Humidity "Entrance humidity [%d%%]" (Humidity) ["iss:room:Entrance", "iss:type:DevHygrometry"] { channel="zwave:device:1:node8:sensor_relhumidity" }
```

28
concepts/audio.md Normal file
View File

@ -0,0 +1,28 @@
---
layout: documentation
---
{% include base.html %}
# Audio & Voice
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*.
![](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 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.
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.
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.

49
concepts/discovery.md
View File

@ -4,53 +4,14 @@ layout: documentation
{% include base.html %}
# Thing Discovery and Inbox
# Thing Discovery
Many 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.
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 can therefore implement _Discovery Services_ for things. As a solution might not want to make everything that is found on the network immediately available to the user and his applications, all _Discovery Results_ are regarded as suggestions that are first put into an _inbox_.
## Glossary
- _Discovery_: Search for available things in the smart home environment.
- _Discovery Result_: Result of a _Discovery_ stored in the _Inbox_.
- _Discovery Service_: Implements a service to discover things, typically based on a specialized protocol (e.g. UPnP).
- _Inbox_: List of all discovered things, constantly updated by all running discoveries.
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_.
## Inbox
The inbox represents a list of all discovered things (`DiscoveryResult`) from all known discovery services. Bindings can register new discovery services to discover new thing types (e.g. the Hue binding registers a new discovery service to search for Hue lights). Technically the inbox is an OSGi service which manages the discovery results. Notification about new things added to or things removed from the inbox will be sent as events.
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 Result
A discovery result represents a discovered thing of a specific thing type, that could be instantiated as things in Eclipse SmartHome. 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 will be automatically removed from the inbox.
The following table gives an overview about the main parts of a `DiscoveryResult`:
| Field | Description |
|-------|-------------|
| `thingUID` | The `thingUID` is the unique identifier of the specific discovered thing (e.g. a device's serial number). It *must not* be constructed out of properties, that can change (e.g. IP addresses). A typical `thingUID` could look like this: `hue:bridge:001788141f1a`
| `thingTypeUID` | Contrary to the `thingUID` is the `thingTypeUID` that specifies the type the discovered thing belongs to. It could be constructed from e.g. a product number. A typical `thingTypeUID` could be the following: `hue:bridge`.
| `bridgeUID` | If the discovered thing belongs to a bridge, the `bridgeUID` contains the UID of that bridge.
| `properties` | The `properties` of a `DiscoveryResult` contain the configuration for the newly created thing.
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. The configuration of that created thing contains the values from the `properties`of the approved `DiscoveryResult`. If an entry is ignored, it will be hidden in the inbox without creating a thing for it.
### Active Scan vs. Background Discovery
There are different ways how a thing can be discovered:
- In protocols like UPnP or Bonjour/mDNS devices send announcements on the network that can be listened to. In Eclipse SmartHome we refer to such mechanisms as "background discovery", i.e. passive mechanisms where events come in and can be processed. Things can be therefore found any time and put into the inbox.
- There might be an API, which can be accessed to actively query all available things. In Eclipse SmartHome, this is called an "active scan" and thus configuration UIs must provide a way to trigger such a scan for a certain thing type. In general, it is not recommended to do any active discovery by the binding in the background as it can negatively impact the system performance. The only exception is that a scan can be triggered once at startup and if a bridge has been added, so that its attached things are directly discovered.
## Available Discovery Services
Eclipse SmartHome already comes with some discovery services. These are:
- `UPnPDiscoveryService`: This discovery service discovers all IP devices using the UPnP protocol. The bindings must implement a `UpnpDiscoveryParticipant` to support this discovery service. The [UPnP discovery service documentation](../development/bindings/discovery-services.html#upnp-discovery) explains in detail, how to do that.
- `MDNSDiscoveryService`: All devices supporting the mDNS protocol are discovered by this service.
Bindings implement more discovery services, e.g. the search for Hue lights in the Hue binding or the search for the local weather in the Yahoo weather binding.
The [Implement Discovery Service](../development/bindings/discovery-services.html) chapter describes how to implement DiscoveryServices in a binding.
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.

96
concepts/event-type-definition.md
View File

@ -1,96 +0,0 @@
---
layout: documentation
---
{% include base.html %}
# Event Type Definition
Eclipse SmartHome provides the possibility to easily implement new event types and event factories.
## Define new Event Type
Events can be added by implementing the `Event` interface or the `AbstractEvent` class which offers a default implementation. Both classes are located in the Eclipse SmartHome core bundle.
The following Java snippet shows a new event type extending the class `AbstractEvent`.
```java
public class SunriseEvent extends AbstractEvent {
public final static String TYPE = SunriseEvent.class.getSimpleName();
private final SunriseDTO sunriseDTO;
SunriseEvent(String topic, String payload, SunriseDTO sunriseDTO) {
super(topic, payload, null);
this.sunriseDTO = sunriseDTO;
}
@Override
public String getType() {
return TYPE;
}
public SunriseDTO getSunriseDTO() {
return sunriseDTO;
}
@Override
public String toString() {
return "Sunrise at '" + getSunriseDTO.getTime() + "'.";
}
}
```
The listing below summarizes some coding guidelines as illustrated in the example above:
- Events should only be created by event factories. Constructors do not have any access specifier in order to make the class package private.
- The serialization of the payload into a data transfer object (e.g. `SunriseDTO`) should be part of the event factory and will be assigned to a class member via the constructor.
- A public member `TYPE` represents the event type as string representation and is usually the name of the class.
- The `toString()` method should deliver a meaningful string since it is used for event logging.
- The source of an event can be null if not required.
For more information about implementing an event, please refer to the Java documentation.
## Define new Event Factory
Event factories can be added by implementing the `EventFactory` interface or the `AbstractEventFactory` class. The `AbstractEventFactory` provides some useful utility for parameter validation and payload serialization & deserialization with JSON. The classes are located in the Eclipse SmartHome core bundle.
```java
public class SunEventFactory extends AbstractEventFactory {
private static final String SUNRISE_EVENT_TOPIC = "smarthome/sun/{time}/sunrise";
public SunEventFactory() {
super(Sets.newHashSet(SunriseEvent.TYPE);
}
@Override
protected Event createEventByType(String eventType, String topic, String payload, String source) throws Exception {
Event event = null;
if (eventType.equals(SunriseEvent.TYPE)) {
createSunriseEvent(topic, payload);
}
return event;
}
private createSunriseEvent(String topic, String payload) {
SunriseDTO sunriseDTO = deserializePayload(payload, SunriseDTO.class);
return new SunriseEvent(topic, payload, sunriseDTO);
}
public static SunriseEvent createSunriseEvent(Sunrise sunrise) {
String topic = buildTopic(SUNRISE_EVENT_TOPIC, sunrise.getTime());
SunriseDTO sunriseDTO = map(sunrise);
String payload = serializePayload(sunriseDTO);
return new SunriseEvent(topic, payload, sunriseDTO);
}
}
```
The listing below summarizes some guidelines as illustrated in the example above:
- Provide the supported event types (`SunriseEvent.TYPE`) via an `AbstractEventFactory` constructor call. The supported event types will be returned by the `AbstractEventFactory.getSupportedEventTypes()` method.
- The event factory defines the topic (`SUNRISE_EVENT_TOPIC`) of the supported event types. Please ensure that the topic format follows the topic structure of the Eclipse SmartHome core events, similar to a REST URI (`{namespace}/{entityType}/{entity}/{sub-entity-1}/.../{sub-entity-n}/{action}`). The namespace must be `smarthome`.
- Implement the method `createEventByType(String eventType, String topic, String payload, String source)` to create a new event based on the topic and the payload, determined by the event type. This method will be called by the framework in order to dispatch received events to the corresponding event subscribers. If the payload is serialized with JSON, the method `deserializePayload(String payload, Class<T> classOfPayload)`can be used to deserialize the payload into a data transfer object.
- Provide a static method to create event instances based on a domain object (Item, Thing, or in the example above `Sunrise`). This method can be used by components in order to create events based on domain objects which should be sent by the EventPublisher. If the data transfer object should be serialized into a JSON payload, the method `serializePayload(Object payloadObject)` can be used.
For more information about implementing an event factory, please refer to the Java documentation.

205
concepts/events.md
View File

@ -1,205 +0,0 @@
---
layout: documentation
---
{% include base.html %}
# Events
The Eclipse SmartHome framework provides an event bus for inter-component communication. The communication is based on events which can be sent and received through the event bus in an asynchronous way. Examples of Eclipse SmartHome event types are _ItemCommandEvent_, _ItemStateEvent_, _ItemAddedEvent_, _ThingStatusInfoEvent_, etc.
This section gives a short overview about the event API and illustrates how to receive such events. Furthermore, the sending of events and the implementation of new event types will be described.
A code snippet about receiving events can be found in chapter "Receive Events". In particular, receiving _ItemStateEvents_ and _ItemCommandEvents_ is described in chapter "Receive ItemStateEvents and ItemCommandEvents".
## API Introduction
### The Interfaces
![Event Interfaces](diagrams/event_interfaces.png)
The `EventPublisher` posts `Event`s through the Eclipse SmartHome event bus in an asynchronous way. The `EventSubscriber` defines the callback interface to receive events of specific types to which the event subscriber is subscribed. The EventPublisher and the EventSubscribers are registered as OSGi services. An event subscriber can provide an `EventFilter` in order to filter events based on the topic or the content. If there is no filter all subscribed event types are received. The event itself will be subclassed for each event type, which exists in the System (e.g. ItemCommandEvent, ItemUpdatedEvent, ThingStatusInfoEvent).
### The Core Events
This section lists the core events provided by Eclipse SmartHome which can be divided into the categories _Item Events_, _Thing Events_ and _Inbox Events_.
An event consists of a `topic`, a `type`, a `payload` and a `source`. The payload can be serialized with any String representation and is determined by its concrete event type implementation (e.g. ItemCommandEvent, ItemUpdatedEvent). The payloads of the Eclipse SmartHome core events are serialized with JSON. Each event implementation provides the payload as high level methods as well, usually presented by a data transfer object (DTO).
A topic clearly defines the target of the event and its structure is similar to a REST URI, except the last part, the action. The topics of Eclipse SmartHome events are divided into the following four parts: `{namespace}/{entityType}/{entity}/{action}`, e.g. `smarthome/items/{itemName}/command`.
The type of an event is represented by a string, usually the name of the concrete event implementation class, e.g. ItemCommandEvent, ItemUpdatedEvent. This string type presentation is used by event subscribers for event subscription (see chapter "Receive Events") and by the framework for the creation of concrete event instances.
The event source is optional and represents the name of the source identifying the sender.
#### Item Events
| Event |Description |Topic |
|-----------------------|-------------------------------------------------|----------------------------------------|
| ItemAddedEvent |An item has been added to the item registry. |smarthome/items/{itemName}/added |
| ItemRemovedEvent |An item has been removed from the item registry. |smarthome/items/{itemName}/removed |
| ItemUpdatedEvent |An item has been updated in the item registry. |smarthome/items/{itemName}/updated |
| ItemCommandEvent |A command is sent to an item via a channel. |smarthome/items/{itemName}/command |
| ItemStateEvent |The state of an item is updated. |smarthome/items/{itemName}/state |
| ItemStateChangedEvent |The state of an item has changed. |smarthome/items/{itemName}/statechanged |
**Note:** The ItemStateEvent is always sent if the state of an item is updated, even if the state did not change. ItemStateChangedEvent is sent only if the state of an item was really changed. It contains the old and the new state of the item.
#### Thing Events
| Event |Description |Topic |
|-----------------------|-------------------------------------------------|-----------------------------------|
| ThingAddedEvent |A thing has been added to the thing registry. |smarthome/things/{thingUID}/added |
| ThingRemovedEvent |A thing has been removed from the thing registry.|smarthome/things/{thingUID}/removed|
| ThingUpdatedEvent |A thing has been updated in the thing registry. |smarthome/things/{thingUID}/updated|
| ThingStatusInfoEvent |The status of a thing is updated. |smarthome/things/{thingUID}/status |
| ThingStatusInfoChangedEvent |The status of a thing changed. |smarthome/things/{thingUID}/statuschanged |
**Note:** The ThingStatusInfoEvent is always sent if the status info of a thing is updated, even if the status did not change. ThingStatusInfoChangedEvent is sent only if the status of a thing was really changed. It contains the old and the new status of the thing.
#### Inbox Events
| Event |Description |Topic |
|-----------------------|---------------------------------------------------|-----------------------------------|
| InboxAddedEvent |A discovery result has been added to the inbox. |smarthome/inbox/{thingUID}/added |
| InboxRemovedEvent |A discovery result has been removed from the inbox. |smarthome/inbox/{thingUID}/removed |
| InboxUpdateEvent |A discovery result has been updated in the inbox. |smarthome/inbox/{thingUID}/updated |
#### Link Events
| Event |Description |Topic |
|-----------------------------|---------------------------------------------------------|------------------------------------------------|
| ItemChannelLinkAddedEvent |An item channel link has been added to the registry. |smarthome/links/{itemName}-{channelUID}/added |
| ItemChannelLinkRemovedEvent |An item channel link has been removed from the registry. |smarthome/links/{itemName}-{channelUID}/removed |
| ItemThingLinkAddedEvent |An item thing link has been added to the registry. |smarthome/links/{itemName}-{thingUID}/added |
| ItemThingLinkRemovedEvent |An item thing link has been removed from the registry. |smarthome/links/{itemName}-{thingUID}/removed |
#### Channel Events
| Event |Description |Topic |
|-----------------------------|---------------------------------------------------------|------------------------------------------------|
| ChannelTriggeredEvent |A channel has been triggered. |smarthome/channels/{channelUID}/triggered |
## Receive Events
This section describes how to receive Eclipse SmartHome events in Java. If you want to receive events "outside" Eclipse SmartHome, e.g. with JavaScript, please refer to the [Server Sent Events section](../features/rest.html).
An event subscriber defines the callback interface for receiving events from the Eclipse SmartHome event bus. The following Java snippet shows how to receive `ItemStateEvent`s and `ItemCommandEvent`s from the event bus. Therefore, the `EventSubscriber` interface must be implemented.
```java
public class SomeItemEventSubscriber implements EventSubscriber {
private final Set<String> subscribedEventTypes = ImmutableSet.of(ItemStateEvent.TYPE, ItemCommandEvent.TYPE);
private final EventFilter eventFiter = new TopicEventFilter("smarthome/items/ItemX/.*");
@Override
public Set<String> getSubscribedEventTypes() {
return subscribedEventTypes;
}
@Override
public EventFilter getEventFilter() {
return eventFilter;
}
@Override
public void receive(Event event) {
String topic = event.getTopic();
String type = event.getType();
String payload = event.getPayload();
if (event instanceof ItemCommandEvent) {
ItemCommandEvent itemCommandEvent = (ItemCommandEvent) event;
String itemName = itemCommandEvent.getItemName();
Command command = itemCommandEvent.getItemCommand();
// ...
} else if (event instanceof ItemStateEvent) {
ItemStateEvent itemStateEvent = (ItemStateEvent) event;
// ...
}
}
}
```
The `SomeItemEventSubscriber` is subscribed to the event types `ItemStateEvent` and `ItemCommandEvent`, provided by the method `getSubscribedEventTypes()`. A string representation of an event type can be found by a public member `TYPE` which usually presents the name of the class. To subscribe to all available event types, use the public member `ALL_EVENT_TYPES` of the event subscriber interface.
The event subscriber provides a `TopicEventFilter` which is a default Eclipse SmartHome `EventFilter` implementation that ensures filtering of events based on a topic. The argument of the filter is a [Java regular expression](http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html). The filter method `EventFilter.apply()` will be called for each event on the event bus to which the event subscriber is subscribed (in the example above ItemStateEvent and ItemCommandEvent). If the filter applies (in the given example for all item events with the item name "ItemX"), the event will be received by the `EventSubscriber.receive()` method. Received events can be cast to the event implementation class for further processing.
Each event subscriber must be registered via OSGi Declarative Services (DS) under the `org.eclipse.smarthome.event.EventSubscriber` interface.
```xml
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" immediate="true" name="SomeItemEventSubscriber">
<implementation class="org.eclipse.smarthome.core.items.events.SomeItemEventSubscriber"/>
<service>
<provide interface="org.eclipse.smarthome.core.events.EventSubscriber"/>
</service>
</scr:component>
```
The listing below summarizes some best practices in order to implement event subscribers:
- To subscribe to only one event type Eclipse SmartHome provides the `org.eclipse.smarthome.core.events.AbstractTypedEventSubscriber` implementation. To receive an already cast event the `receiveTypedEvent(T)` method must be implemented. To provide an event filter the method `getEventFilter()` can be overridden.
- Eclipse SmartHome provides an `AbstractItemEventSubscriber` class in order to receive ItemStateEvents and ItemCommandEvents (more information can be obtained in the next chapter).
- To filter events based on a topic the `org.eclipse.smarthome.core.events.TopicEventFilter` implementation from the Eclipse SmartHome core bundle can be used. The filtering is based on [Java regular expression](http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html).
- The subscribed event types and the filter should be stored as class members (see example above) due to performance reasons.
- If the subscribed event types are sufficient in order to receive all interested events, do not return any filter (in that case the method getFilter() returns null) due to performance reasons.
- Avoid the creation of too many event subscribers. Similar event types can be received in one event subscriber.
- Handle exceptions in event subscriber implementation and throw only serious exceptions. Thrown exceptions will be handled in the framework by logging an error message with the cause.
- The receive method should terminate quickly, since it blocks other event subscribers. Create a thread for long running operations.
### Receive ItemStateEvents and ItemCommandEvents
Due to the fact that receiving ItemStateEvents and ItemCommandEvents is a common use case, Eclipse SmartHome provides an abstract event subscriber implementation via the core bundle. The class `org.eclipse.smarthome.core.items.events.AbstractItemEventSubscriber` provides two methods `receiveUpdate(ItemStateEvent)` and `receiveCommand(ItemCommandEvent)` which can be implemented in order to receive and handle such events.
```java
public class SomeItemEventSubscriber extends AbstractItemEventSubscriber {
private final EventFilter eventFiter = new TopicEventFilter("smarthome/items/ItemX/.*");
@Override
public EventFilter getEventFilter() {
return eventFilter;
}
@Override
protected void receiveCommand(ItemCommandEvent commandEvent) {
// do something
}
@Override
protected void receiveUpdate(ItemStateEvent stateEvent) {
// do something
}
}
```
## Send Events
Usually the core events are only sent by the Eclipse SmartHome framework. However, it is possible to sent events explicitly, e.g. ItemCommandEvents and ItemStateEvents. The Java snippet below illustrates how to send events via the EventPublisher. The Eclipse SmartHome core events can only be created via the corresponding event factory.
```java
public class SomeComponentWantsToPost {
private EventPublisher eventPublisher;
public void postSomething() {
ItemCommandEvent itemCommandEvent = ItemEventFactory.createCommandEvent("ItemX", OnOffType.ON);
eventPublisher.post(itemCommandEvent);
}
protected void setEventPublisher(EventPublisher eventPublisher) {
this.eventPublisher = eventPublisher;
}
protected void unsetEventPublisher(EventPublisher eventPublisher) {
this.eventPublisher = null;
}
}
```
The EventPublisher will be injected via OSGi Declarative Services.
```xml
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" immediate="true" name="SomeComponentWantsToPost">
<!-- ... -->
<reference bind="setEventPublisher" cardinality="1..1" interface="org.eclipse.smarthome.core.events.EventPublisher"
name="EventPublisher" policy="static" unbind="unsetEventPublisher"/>
</scr:component>
```
## Define new Event Types
It is possible to create and provide new event types. For a detailed description please refer to the [Event Type Definition section](./event-type-definition.html).

BIN
concepts/images/audio.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 74 KiB

BIN
concepts/images/hli.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB