[Documentation] Markdown improvements for bindings a to e (#13859)
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
This commit is contained in:
Jerome Luckenbach
committed by
GitHub
GitHub
parent
72efc1cfed
commit
caf71f72e6
@@ -1,35 +1,35 @@
|
||||
# DMX Binding
|
||||
|
||||
The DMX binding integrates DMX devices. There are different output devices supported as well as Dimmers and Chasers.
|
||||
The DMX binding integrates DMX devices. There are different output devices supported as well as Dimmers and Chasers.
|
||||
|
||||
Each output device (bridges) is representing exactly one universe, each thing is bound to a bridge.
|
||||
At least one bridge and one thing is needed for the binding to work properly.
|
||||
Each output device (bridges) is representing exactly one universe, each thing is bound to a bridge.
|
||||
At least one bridge and one thing is needed for the binding to work properly.
|
||||
|
||||
## Supported Things
|
||||
|
||||
### Bridges
|
||||
|
||||
Two DMX over Ethernet devices are supported as DMX output: ArtNet and sACN/E1.31.
|
||||
The ArtNet bridge can only be operated in unicast mode (broadcast mode is not supported as the specification recommends using it if more than 40 nodes are connected, which is unlikely in the case of a smarthome).
|
||||
The sACN bridge supports both, unicast and multicast.
|
||||
Two DMX over Ethernet devices are supported as DMX output: ArtNet and sACN/E1.31.
|
||||
The ArtNet bridge can only be operated in unicast mode (broadcast mode is not supported as the specification recommends using it if more than 40 nodes are connected, which is unlikely in the case of a smarthome).
|
||||
The sACN bridge supports both, unicast and multicast.
|
||||
|
||||
Additionally Lib485 devices are supported via the Lib485 bridge.
|
||||
|
||||
### Things
|
||||
|
||||
The most generic thing is a dimmer.
|
||||
A dimmer can contain one or more DMX channels.
|
||||
It can be bound to Switch and Dimmer items.
|
||||
If more than one DMX channel is defined, the item will be updated according to the state of the first DMX channel.
|
||||
There are two other things similar to the dimmer thing.
|
||||
One is the color thing, it can be bound to Switch, Dimmer or Color Items and is best used for RGB lamps.
|
||||
The most generic thing is a dimmer.
|
||||
A dimmer can contain one or more DMX channels.
|
||||
It can be bound to Switch and Dimmer items.
|
||||
If more than one DMX channel is defined, the item will be updated according to the state of the first DMX channel.
|
||||
There are two other things similar to the dimmer thing.
|
||||
One is the color thing, it can be bound to Switch, Dimmer or Color Items and is best used for RGB lamps.
|
||||
The second one is the tunable white thing, it allows to control the color temperature of lamps with seperate DMX channels for cool white and warm white.
|
||||
|
||||
The last supported thing is a chaser.
|
||||
It can contain one or more DMX channels and binds to Switch items only.
|
||||
If the thing receives an ON command all running fades in all channels are either suspended (if resumeAfter is set to true) or cleared and replaced with the fades defined in this thing.
|
||||
An OFF command stops the fades and either restores the previously suspended fades (if resumeAfter is set to true) or just holds the current values.
|
||||
If any of the DMX channels in a chaser receives a command from another thing, the status of the chaser is updated to OFF.
|
||||
The last supported thing is a chaser.
|
||||
It can contain one or more DMX channels and binds to Switch items only.
|
||||
If the thing receives an ON command all running fades in all channels are either suspended (if resumeAfter is set to true) or cleared and replaced with the fades defined in this thing.
|
||||
An OFF command stops the fades and either restores the previously suspended fades (if resumeAfter is set to true) or just holds the current values.
|
||||
If any of the DMX channels in a chaser receives a command from another thing, the status of the chaser is updated to OFF.
|
||||
Chaser things define a control channel that can be used to dynamically change the chasers fade configuration.
|
||||
|
||||
## Discovery
|
||||
@@ -39,27 +39,27 @@ You have to add all bridges and things manually.
|
||||
|
||||
## Thing Configuration
|
||||
|
||||
Since the brightness perception of the human eye is not linear, all bridges support `applycurve`, a list of channels `applycurve` that have a CIE 1931 lightness correction (cf. [Poynton, C.A.: “Gamma” and its Disguises: The Nonlinear Mappings of Intensity in Perception, CRTs, Film and Video, SMPTE Journal Dec. 1993, pp. 1099 - 1108](https://www.poynton.com/PDFs/SMPTE93_Gamma.pdf)) applied.
|
||||
This list follows the format of the thing channel definition.
|
||||
Since the brightness perception of the human eye is not linear, all bridges support `applycurve`, a list of channels `applycurve` that have a CIE 1931 lightness correction (cf. [Poynton, C.A.: “Gamma” and its Disguises: The Nonlinear Mappings of Intensity in Perception, CRTs, Film and Video, SMPTE Journal Dec. 1993, pp. 1099 - 1108](https://www.poynton.com/PDFs/SMPTE93_Gamma.pdf)) applied.
|
||||
This list follows the format of the thing channel definition.
|
||||
This is used regardless of the thing(s) that are associated to the channel.
|
||||
|
||||
All bridges can make use of the `refreshrate` option.
|
||||
It determines at what frequency the DMX output is refreshed.
|
||||
The achievable refresh rate depends on the number of channels and the output type.
|
||||
All bridges can make use of the `refreshrate` option.
|
||||
It determines at what frequency the DMX output is refreshed.
|
||||
The achievable refresh rate depends on the number of channels and the output type.
|
||||
A value of `0` disables the output, the default value is 30 Hz.
|
||||
|
||||
### ArtNet Bridge (`artnet-bridge`)
|
||||
|
||||
The ArtNet bridge has one mandatory configuration value: network address (`address`).
|
||||
The ArtNet bridge has one mandatory configuration value: network address (`address`).
|
||||
The network address defines the IP address of the receiving node, it is also allowed to use a FQDN if DNS resolution is available.
|
||||
If necessary the default port 6454 can be changed by adding `:<port>` to the address.
|
||||
Multiple receivers can be added, separated by a comma.
|
||||
|
||||
The universe (`universe`) can range from 0-32767, this value defaults to 0.
|
||||
The universe (`universe`) can range from 0-32767, this value defaults to 0.
|
||||
|
||||
There are two more configuration values that usually don't need to be touched.
|
||||
The address and port of the sender will be automatically selected by the kernel, if they need to be set to a fixed value, this can be done with `localaddress`.
|
||||
The format is identical to the receiver address.
|
||||
There are two more configuration values that usually don't need to be touched.
|
||||
The address and port of the sender will be automatically selected by the kernel, if they need to be set to a fixed value, this can be done with `localaddress`.
|
||||
The format is identical to the receiver address.
|
||||
Unlike DMX512-A (E1.11), the ArtNet standard allows to suppress repeated transmissions of unchanged universes for a certain time.
|
||||
This is enabled by default and will re-transmit unchanged data with a fixed refresh rate of 800ms.
|
||||
If for some reason continuous transmission is needed, the `refreshmode` can be set to `always`, opposed to the default `standard`.
|
||||
@@ -76,17 +76,17 @@ Multiple receivers can be added, separated by a comma.
|
||||
### sACN/E1.31 Bridge (`sacn-bridge`)
|
||||
|
||||
The sACN bridge has one mandatory configuration value: transmission mode (`mode`).
|
||||
The transmission mode can be set to either `unicast` or `multicast`, where the later one is the default value.
|
||||
The transmission mode can be set to either `unicast` or `multicast`, where the later one is the default value.
|
||||
If unicast mode is selected, it is mandatory to define the network address (`address`) of the receiving node.
|
||||
This can be an IP address but it is also allowed to use a FQDN if DNS resolution is available.
|
||||
If necessary the default port 5568 can be changed by adding `:<port>` to the address.
|
||||
Multiple receivers can be added, separated by a comma.
|
||||
|
||||
The universe (`universe`) can range from 1-63999, this value defaults to 1.
|
||||
The universe (`universe`) can range from 1-63999, this value defaults to 1.
|
||||
|
||||
There are some more configuration values that usually don't need to be touched.
|
||||
The address and port of the sender will be automatically selected by the kernel, if they need to be set to a fixed value, this can be done with `localaddress`.
|
||||
The format is identical to the receiver address.
|
||||
The format is identical to the receiver address.
|
||||
|
||||
Unlike DMX512-A (E1.11), the E1.31 standard allows to suppress repeated transmissions of unchanged universes for a certain time.
|
||||
This is enabled by default and will re-transmit unchanged data with a fixed refresh rate of 800ms.
|
||||
@@ -94,10 +94,10 @@ If for some reason continuous transmission is needed, the `refreshmode` can be s
|
||||
|
||||
### Chaser Thing (`chaser`)
|
||||
|
||||
There are two mandatory configuration values for a chaser thing: the `dmxid` and `steps`.
|
||||
There are two mandatory configuration values for a chaser thing: the `dmxid` and `steps`.
|
||||
|
||||
The `dmxid` is a list of DMX channels that are associated with this thing.
|
||||
There are several possible formats: `channel,channel,channel,...` or `channel/width` or a combination of both.
|
||||
There are several possible formats: `channel,channel,channel,...` or `channel/width` or a combination of both.
|
||||
|
||||
The `steps` value is a list of steps that shall be run by the chaser.
|
||||
The format of a single step is `fadetime:value,value2, ...:holdtime`, two or more steps are concatenated by `step1|step2|...`.
|
||||
@@ -115,37 +115,37 @@ It defaults to false but if set to true, the original state of the channel (incl
|
||||
|
||||
There is one mandatory configuration value for a dimmer thing.
|
||||
It is the `dmxid`, a list of DMX channels that are associated with this thing.
|
||||
There are several possible formats: `channel1,channel2,channel3,...` or `channel/width` or a combination of both.
|
||||
There are several possible formats: `channel1,channel2,channel3,...` or `channel/width` or a combination of both.
|
||||
|
||||
The `fadetime` option allows a smooth transition from the current to the new value.
|
||||
The time unit is ms and the interval is for a fade from 0-100%.
|
||||
If the current value is 25% and the new value is 75% the time needed for this change is half of `fadetime`.
|
||||
`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel.
|
||||
`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel.
|
||||
Related is the `dimtime` option: it defines the time in ms from 0-100% if incremental dimming (`INCREASE`/`DECREASE`) is used.
|
||||
For convenient use `dimtime` usually is set to a larger value than `fadetime`.
|
||||
Typical values are 500-1000 ms for `fadetime` and 2000-5000 ms for `dimtime`.
|
||||
Typical values are 500-1000 ms for `fadetime` and 2000-5000 ms for `dimtime`.
|
||||
|
||||
Advanced options are the `turnonvalue`and the `turnoffvalue`.
|
||||
Advanced options are the `turnonvalue`and the `turnoffvalue`.
|
||||
They default to 255 (equals 100%) and 0 (equals 0%) respectively.
|
||||
This value can be set individually for all DMX channels, the format is `value1,value2, ...` with values from 0 to 255.
|
||||
If less values than DMX channels are defined, the values will be re-used from the beginning (i.e. if two values are defined, value1 will be used for channel1, channel3, ... and value2 will be used for channel2, channel4, ...).
|
||||
These values will be used if the thing receives an ON or OFF command.
|
||||
These values will be used if the thing receives an ON or OFF command.
|
||||
|
||||
The `dynamicturnonvalue` can be set to `true` or `false` (default).
|
||||
If enabled, thing overwrites the previous turn-on value with the current channel values.
|
||||
The next `ON` command uses these values instead of the default (or configuration supplied) values.
|
||||
The next `ON` command uses these values instead of the default (or configuration supplied) values.
|
||||
|
||||
### Color Thing (`color`)
|
||||
|
||||
There is one mandatory configuration value for a dimmer thing.
|
||||
It is the `dmxid`, a list of DMX channels that are associated with this thing.
|
||||
There are several possible formats: `channel1,channel2,channel3,...` or `channel/width` or a combination of both.
|
||||
The number of channels has to be a multiple of three.
|
||||
The number of channels has to be a multiple of three.
|
||||
|
||||
The `fadetime` option allows a smooth transition from the current to the new value.
|
||||
The time unit is ms and the interval is for a fade from 0-100%.
|
||||
If the current value is 25% and the new value is 75% the time needed for this change is half of `fadetime`.
|
||||
`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel.
|
||||
`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel.
|
||||
Related is the `dimtime` option: it defines the time in ms from 0-100% if incremental dimming (`INCREASE`/`DECREASE`) is used.
|
||||
For convenient use `dimtime` usually is set to a larger value than `fadetime`.
|
||||
Typical values are 500-1000 ms for `fadetime` and 2000-5000 ms for `dimtime`.
|
||||
@@ -155,24 +155,24 @@ They default to 255 (equals 100%) and 0 (equals 0%) respectively.
|
||||
This value can be set individually for all DMX channels, the format is `value1,value2, ...` with values from 0 to 255.
|
||||
If less values than DMX channels are defined, the values will be re-used from the beginning (i.e. if two values are defined, value1 will be used for channel1, channel3, ... and value2 will be used for channel2, channel4, ...).
|
||||
For color things the number of values has to be a multiple of three.
|
||||
These values will be used if the thing receives an ON or OFF command.
|
||||
These values will be used if the thing receives an ON or OFF command.
|
||||
|
||||
The `dynamicturnonvalue` can be set to `true` or `false` (default).
|
||||
If enabled, thing overwrites the previous turn-on value with the current channel values.
|
||||
The next `ON` command uses these values instead of the default (or configuration supplied) values.
|
||||
The next `ON` command uses these values instead of the default (or configuration supplied) values.
|
||||
|
||||
### Tunable White Thing (`tunablewhite`)
|
||||
|
||||
There is one mandatory configuration value for a dimmer thing.
|
||||
There is one mandatory configuration value for a dimmer thing.
|
||||
It is the `dmxid`, a list of DMX channels that are associated with this thing.
|
||||
There are several possible formats: `channel1,channel2,channel3,...` or `channel/width` or a combination of both.
|
||||
The number of channels has to be even. In the order "cool white, warm white".
|
||||
Additionally a channel for cool and warm white brightness as well as color temperature (`0` being the coolest, `100` being the warmest) will be provided.
|
||||
Additionally a channel for cool and warm white brightness as well as color temperature (`0` being the coolest, `100` being the warmest) will be provided.
|
||||
|
||||
The `fadetime` option allows a smooth transition from the current to the new value.
|
||||
The time unit is ms and the interval is for a fade from 0-100%.
|
||||
If the current value is 25% and the new value is 75% the time needed for this change is half of `fadetime`.
|
||||
`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel.
|
||||
`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel.
|
||||
Related is the `dimtime` option: it defines the time in ms from 0-100% if incremental dimming (`INCREASE`/`DECREASE`) is used.
|
||||
For convenient use `dimtime` usually is set to a larger value than `fadetime`.
|
||||
Typical values are 500-1000 ms for `fadetime` and 2000-5000 ms for `dimtime`.
|
||||
@@ -180,15 +180,14 @@ Typical values are 500-1000 ms for `fadetime` and 2000-5000 ms for `dimtime`.
|
||||
Advanced options are the `turnonvalue`and the `turnoffvalue`.
|
||||
They default to 255 (equals 100%) and 0 (equals 0%) respectively.
|
||||
This value can be set individually for all DMX channels, the format is `value1,value2, ...` with values from 0 to 255.
|
||||
If less values than DMX channels are defined, the values will be re-used from the beginning (i.e. if two values are defined, value1 will be used for channel1, channel3, ... and value2 will be used for channel2, channel4, ...).
|
||||
If less values than DMX channels are defined, the values will be re-used from the beginning (i.e. if two values are defined, value1 will be used for channel1, channel3, ... and value2 will be used for channel2, channel4, ...).
|
||||
For tunable white things the number of values has to be a multiple of two.
|
||||
These values will be used if the thing receives an ON or OFF command.
|
||||
|
||||
These values will be used if the thing receives an ON or OFF command.
|
||||
|
||||
The `dynamicturnonvalue` can be set to `true` or `false` (default).
|
||||
If enabled, thing overwrites the previous turn-on value with the current channel values.
|
||||
The next `ON` command uses these values instead of the default (or configuration supplied) values.
|
||||
|
||||
|
||||
The next `ON` command uses these values instead of the default (or configuration supplied) values.
|
||||
|
||||
## Channels
|
||||
|
||||
| Type-ID | Thing | Item | Description |
|
||||
@@ -205,7 +204,7 @@ The next `ON` command uses these values instead of the default (or configuration
|
||||
|switch |chaser |Switch | turns the chaser ON or OFF |
|
||||
|mute |(all bridges) |Switch | mutes the DMX output of the bridge |
|
||||
|
||||
*Note:* the string send to the control channel of chaser things has to be formatted like the `steps` configuration of the chaser thing.
|
||||
_Note:_ the string send to the control channel of chaser things has to be formatted like the `steps` configuration of the chaser thing.
|
||||
If the new string is invalid, the old configuration will be used.
|
||||
|
||||
## Rule Actions
|
||||
@@ -254,7 +253,7 @@ This example defines a sACN/E1.31 bridge in unicast mode which transmits univers
|
||||
|
||||
### demo.things:
|
||||
|
||||
```
|
||||
```java
|
||||
Bridge dmx:sacn-bridge:mybridge [ mode="unicast", address="192.168.0.60", universe=2 ] {
|
||||
color rgb [dmxid="5/3", fadetime=1000, dimtime=10000 ]
|
||||
dimmer single [dmxid="50", fadetime=1000, turnonvalue="230", turnoffvalue="25" ]
|
||||
@@ -264,7 +263,7 @@ Bridge dmx:sacn-bridge:mybridge [ mode="unicast", address="192.168.0.60", univer
|
||||
|
||||
### demo.items:
|
||||
|
||||
```
|
||||
```java
|
||||
Color MyColorItem "My Color Item" { channel="dmx:color:mybridge:rgb:color" }
|
||||
Dimmer MyDimmerItem "My Dimmer Item" { channel="dmx:dimmer:mybridge:single:brightness" }
|
||||
Switch MyChaserItem "My Chaser Item" { channel="dmx:chaser:mybridge:ampel:switch" }
|
||||
@@ -272,7 +271,7 @@ Switch MyChaserItem "My Chaser Item" { channel="dmx:chaser:mybridge:ampel:switch
|
||||
|
||||
### demo.sitemap:
|
||||
|
||||
```
|
||||
```perl
|
||||
sitemap demo label="Main Menu"
|
||||
{
|
||||
Frame {
|
||||
|
||||
Reference in New Issue
Block a user