Add initial documentation for profiles (#798)
* Add initial documentation for profiles (WIP) Signed-off-by: Patrick Fink <mail@pfink.de> * Style guide compliance Signed-off-by: Patrick Fink <mail@pfink.de> * Convert profile descriptions into a table and add `rawbutton-toggle-switch` Profile Signed-off-by: Patrick Fink <mail@pfink.de> * Add missing profiles Signed-off-by: Patrick Fink <mail@pfink.de> * Proofread Signed-off-by: Patrick Fink <mail@pfink.de> * Add profile usage example Signed-off-by: Patrick Fink <mail@pfink.de> * Style improvements Signed-off-by: Patrick Fink <mail@pfink.de> * Improve offset description Signed-off-by: Patrick Fink <mail@pfink.de> * Improve syntax scheme Signed-off-by: Patrick Fink <mail@pfink.de> * Removed double sentence Signed-off-by: Jerome Luckenbach <github@luckenba.ch>pull/827/head
Patrick Fink
Jerome Luckenbach
parent
484cd53e30
commit
7d271b8d8f
|
|
@ -592,6 +592,14 @@ These are all in plain text, so be careful who you share these with if some data
|
|||
openHAB2 introduces the concept of [Things and Channels]({{base}}/concepts/things.html).
|
||||
Unlike 1.x version Bindings which each define their own format for the Binding config that is defined on the Item itself, 2.x Bindings define those parameters in a Thing.
|
||||
Each Thing has one or more Channels, and Items are linked to one or more Channels.
|
||||
There are two different kinds of channels:
|
||||
|
||||
- State Channels will, as soon as linked to the Item, update the state of it and/or listen for Commands you send to it.
|
||||
For example, if you have a `Player` Item, a State Channel could be responsible for propagating the state of an audio player (`PLAYING`, `PAUSED`) to your Item as well as listening for proper Commands (`PLAY`, `PAUSE`, `PREVIOUS`, `NEXT`)
|
||||
- Trigger Channels will only send events that won't have any effect on the Item unless you treat them with Rules or use a Trigger Profile to do state changes or commands based on your event.
|
||||
For example, when you use a Binding that integrates buttons or wall switches, a Trigger Channel could be responsible for sending a `PRESSED` event when someone is pressing the button of the device.
|
||||
This event on it's own won't change anything on the Item, but you could use, for example, the Trigger Profile "rawbutton-toggle-switch" to toggle a lamp on or off when the button is clicked.
|
||||
Also, you could e.g. define a Rule that is triggered by this event and calculates the color of the lamp based on the sun position.
|
||||
|
||||
Some Bindings support automatic discovery of Things, in which case discovered Things will appear in the Inbox in the Paper UI.
|
||||
Once accepted, the new Thing will appear under Configuration > Things.
|
||||
|
|
@ -653,3 +661,53 @@ Example:
|
|||
```java
|
||||
Switch Garage_Gate {binding="xxx", autoupdate="false"}
|
||||
```
|
||||
|
||||
#### Profiles
|
||||
|
||||
With Profiles, you're able to change the behavior how Channels interact with your Items. You can use *State Profiles* which on State Channels and *Trigger Profiles* on Trigger Channels.
|
||||
|
||||
Profiles can be specified as a parameter for a given Channel on the Item configuration:
|
||||
|
||||
```java
|
||||
<item-type> MyItem { channel="<bindingID>:<thing-typeID>:MyThing:myChannel"[profile="<profileID>", <profile-parameterID>="MyValue", ...]}
|
||||
```
|
||||
|
||||
There are some built-in Profiles available which are described in the table below.
|
||||
Some Bindings will may offer additional Profiles for Binding-specific use cases.
|
||||
If this is the case, you'll find those within the documentation of the Binding.
|
||||
Also, all [Transformation Services]({{base}}/configuration/transformations.html) provide a State Profile which allows you to do the transformation already on item-level instead doing it with a [Sitemap]({{base}}/configuration/sitemaps.html).
|
||||
You can find the documentation of these Profiles within the [Add-On documentation of the Transformation Service](/addons/#transform) you'd like to use.
|
||||
|
||||
|
||||
|
||||
| ID | Type | Supported Item Types | Description |
|
||||
|---------------|---------|----------------------|------------------------------------|
|
||||
| `default` | State | All | If you don't specify any Profile, this Profile will be used. For State Channels, this means that states and commands are just propagated from the Channel to the Item and vice-versia without any changes. For Trigger Channels, the Default Profile won't change anything on the Item. |
|
||||
| `follow` | State | All | If one device should "follow" the actions of another device, this can be used. The term "follow" in this case means that any state that is sent to an Item will be forwarded from this Item to any linked Channel with the `follow` Profile. It takes state updates on an Item and sends them as a command onto the Channel. In the direction from the ThingHandler towards the Item, this Profile ignores state updates.
|
||||
| `offset` | State | Number | An offset can be specified via the parameter `offset` which has to be a `QuantityType` or `DecimalType`. The specificed offset will be added to the value from the device before it arrives at the item.|
|
||||
| `rawbutton-toggle-switch` | Trigger | Color, Dimmer, Switch | This Profile can only be used on Channels of the type `system.rawbutton`. On those channels, it will toggle the Item state when `PRESSED` events arrive. This Profile can e.g. be used to add button channels to a lighting item which will enable you to turn the lighting on and off with your button.
|
||||
| `rawrocker-to-on-off` | Trigger | Dimmer, Switch | This Profile can only be used on Channels of the type `system.rawrocker`. On those channels, it will convert a press on the first rocker button to an `ON` command while the second one will be converted to an `OFF` command.
|
||||
| `rawrocker-to-dimmer` | Trigger | Dimmer | Same as `rawrocker-to-on-off`, but additionally it allows to dim by holding the respective button. Technically, this Profile sends an `INCREASE` or `DECREASE` Command every 500 milliseconds while you hold.
|
||||
Example: You have an Item called `Bedroom_Light` that is connected to a Hue lamp
|
||||
```java
|
||||
Item Bedroom_Light { channel="hue:0210:1:bulb1:color" }
|
||||
```
|
||||
and a [Rule]({{base}}/configuration/rules-dsl.html) to toggle this light with a serial button:
|
||||
```java
|
||||
when
|
||||
Channel "serialbutton:button:mybutton:button" triggered PRESSED
|
||||
then
|
||||
if (Light_Bedroom.getStateAs(OnOffType) != ON)
|
||||
Light_Bedroom.sendCommand(ON)
|
||||
else
|
||||
Light_Bedroom.sendCommand(OFF)
|
||||
end
|
||||
```
|
||||
|
||||
Instead of using this Rule, you can also use the `rawbutton-toggle-switch` Profile in combination with [Multi-Channel Linking](#multi-binding-channel-linkage):
|
||||
|
||||
```java
|
||||
Item Bedroom_Light { channel="hue:0210:1:bulb1:color", channel="serialbutton:button:mybutton:button" [profile="rawbutton-toggle-switch"] }
|
||||
```
|
||||
|
||||
This will make your Rule obsolete. So with Profiles, you can significantly reduce the amount of Rules you need for your Smart Home which helps you to keep your configuration short and clear.
|
||||
|
|
|
|||
Loading…
Reference in New Issue