Update things.md to show Channel Definitions (#891)

* Update things.md to show Channel definitios

Added the Channel definition part from Eclipse Smarthome.
Points to be discussed:
-Is it still OK to use YahooWeather as an example?
-ESH described three! possible ways to define a State Channel (with or without "State" and with "Type". I rather show/describe only the last one, since it could be used for all except the Trigger Channels.
-Never worked with Trigger Channels (working at all? / Needed?...)

* Done all requested changes
Signed-off-by: Juergen Baginski opus42@gmx.de (github: JueBag)

* Small newline fixes.
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
pull/894/head
Jürgen Baginski 2019-02-03 19:09:16 +01:00 committed by Jerome Luckenbach
parent 464fb041ce
commit a8162cc878
1 changed files with 84 additions and 0 deletions

View File

@ -127,6 +127,7 @@ Please notice that the UID of the thing also contains the bridge ID as third seg
For the contained notation of things the UID will be inherited and the bridge ID is automatically taken as part of the resulting thing UID.
**Example of a MQTT Bridge with Generic MQTT Things :**
```xtend
Bridge mqtt:broker:MyMQTTBroker [ host="192.168.178.50", secure=false, username="MyUserName", password="MyPassword"] {
Thing topic sonoff_Dual_Thing "Light_Dual" @ "Sonoff" {
@ -145,6 +146,89 @@ Bridge mqtt:broker:MyMQTTBroker [ host="192.168.178.50", secure=false, username=
}
```
### Defining Channels
It is also possible to manually define channels.
Usually this is not needed, as channels will be automatically created by the binding based on the thing type description.
It is also possible to add additional channels to existing things and for bindings that allow to create generic things (for example the [MQTT Generic Thing Binding](/addons/bindings/mqtt.generic/)) all channels can be defined by the user.
#### State channels
```xtend
Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
Channels:
State String : customChannel1 "My Custom Channel" [
configParameter="Value"
]
State Number : customChannel2 []
}
```
Each channel definition must be placed inside the curly braces and begin with the keyword `State` followed by the accepted item type (e.g. `String`).
After this the channel ID follows with the configuration of a channel.
The framework will merge the list of channels coming from the binding and the user-defined list in the DSL.
As state channels are the default channels, you can omit the `State` keyword, the following example creates the same channels as the example above:
```xtend
Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
Channels:
String : customChannel1 "My Custom Channel" [
configParameter="Value"
]
Number : customChannel2 []
}
```
You may optionally give the channel a proper label (like “My Custom Channel” in the example above) so you can distinguish the channels easily.
#### Trigger channels
```xtend
Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
Channels:
Trigger String : customChannel1 [
configParameter="Value"
]
}
```
Trigger channels are defined with the keyword `Trigger` and only support the type `String`.
#### Referencing existing channel types
Many bindings provide standalone channel type definitions like this:
```xtend
<thing:thing-descriptions bindingId="yahooweather" [...]>
<channel-type id="temperature">
<item-type>Number</item-type>
<label>Temperature</label>
<description>Current temperature in degrees celsius</description>
<category>Temperature</category>
<state readOnly="true" pattern="%.1f °C">
</state>
</channel-type>
[...]
</thing:thing-descriptions>
```
They can be referenced within a things channel definition, so that they need to be defined only once and can be reused for many channels.
You may do so in the DSL as well:
```xtend
Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
Channels:
Type temperature : my_yesterday_temperature "Yesterday's Temperature"
}
```
The Type keyword indicates a reference to an existing channel definition.
The channel kind and accepted item types of course are takes from the channel definition, therefore they dont need to be specified here again.
You may optionally give the channel a proper label (like “Yesterdays Temperature” in the example above) so you can distinguish the channels easily.
If you decide not to, then the label from the referenced channel type definition will be used.
### Linking Items
Items can be linked to Channels of discovered or manually defined Things inside Paper UI or inside configuration files.