Updated external content (Jenkins build 83)
openHAB Build Server
parent
f09003b787
commit
ae5bd6eed1
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1,154 @@
|
|||
---
|
||||
id: serial
|
||||
label: Serial
|
||||
title: Serial - Bindings
|
||||
type: binding
|
||||
description: "The Serial binding allows openHAB to communicate over serial ports attached to the openHAB server."
|
||||
since: 3x
|
||||
install: auto
|
||||
---
|
||||
|
||||
<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
# Serial Binding
|
||||
|
||||
The Serial binding allows openHAB to communicate over serial ports attached to the openHAB server.
|
||||
|
||||
The binding allows data to be sent and received from a serial port.
|
||||
The binding does not support any particular serial protocols and simply reads what is available and sends what is provided.
|
||||
|
||||
The binding can be used to communicate with simple serial devices for which a dedicated openHAB binding does not exist.
|
||||
|
||||
## Overview
|
||||
|
||||
The Serial binding represents a serial port as a bridge thing and data matching defined patterns as things connected to the bridge.
|
||||
|
||||
### Serial Bridge
|
||||
|
||||
A Serial Bridge thing (`serialBridge`) represents a single serial port.
|
||||
|
||||
The bridge supports a String channel which is set to the currently received data from the serial port.
|
||||
Sending a command to this channel sends the command as a string to the serial port.
|
||||
|
||||
The bridge also supports a String channel which encodes the received data as the string representation of a RawType to handle data that is
|
||||
not supported by the REST interface.
|
||||
A command sent to this channel will only be sent to the serial port if it is encoded as the string representation of a RawType.
|
||||
|
||||
A trigger channel is also provided which triggers when data is received.
|
||||
|
||||
### Serial Device
|
||||
|
||||
A Serial Device thing (`serialDevice`) can be used to represent data matching a defined pattern as a device.
|
||||
The serial port may be providing data for many different devices/sensors, such as a temperature sensor or a doorbell.
|
||||
Usually such devices can be identified by performing a pattern match on the received data.
|
||||
For example, a Serial Device could be configured to represent a temperature sensor.
|
||||
|
||||
The thing will only update its channels if the received data matches the defined pattern.
|
||||
|
||||
The thing supports generic String and Number channels which can apply a transform on the received data to set the channel state.
|
||||
Commands sent to the channels can be formatted and transformed before being sent to the device.
|
||||
|
||||
The thing also supports Switch and Rollershutter channels which provide simple mappings for the ON, OFF, UP, DOWN and STOP commands.
|
||||
|
||||
When using a Serial Device the expectation is that the received data for each device is terminated by a line break.
|
||||
|
||||
## Thing Configuration
|
||||
|
||||
The configuration for the `serialBridge` consists of the following parameters:
|
||||
|
||||
| Parameter | Description |
|
||||
|---------------------|--------------------------------------------------------------------------------------------------------|
|
||||
| serialPort | The serial port to use (e.g. Linux: /dev/ttyUSB0, Windows: COM1) (mandatory) |
|
||||
| baudRate | Set the baud rate. Valid values: 4800, 9600, 19200, 38400, 57600, 115200 (default 9600) |
|
||||
| dataBits | Set the data bits. Valid values: 5, 6, 7, 8 (default 8) |
|
||||
| parity | Set the parity. Valid values: N(one), O(dd), E(even), M(ark), S(pace) (default N) |
|
||||
| stopBits | Set the stop bits. Valid values: 1, 1.5, 2 (default 1) |
|
||||
| charset | The charset to use for converting between bytes and string (e.g. UTF-8,ISO-8859-1) |
|
||||
|
||||
The configuration for the `serialDevice` consists of the following parameters:
|
||||
|
||||
| Parameter | Description |
|
||||
|---------------------|--------------------------------------------------------------------------------------------------------|
|
||||
| patternMatch | Regular expression used to identify device from received data (must match the whole line) (mandatory) |
|
||||
|
||||
## Channels
|
||||
|
||||
The channels supported by the `serialBridge` are:
|
||||
|
||||
| Channel | Type | Description |
|
||||
|----------|------------------|----------------------------------------------------------------------------------------------------------|
|
||||
| `string` | String | Channel for sending/receiving data as a string to/from the serial port. The channel will update its state to a StringType that is the data received from the serial port. A command sent to this channel will be sent out as data through the serial port. |
|
||||
| `binary` | String | Channel for sending/receiving data in Base64 format to/from the serial port. The channel will update its state to a StringType which is the string representation of a RawType that contains the data received from the serial port. A command sent to this channel must be encoded as the string representation of a RawType, e.g. `"data:application/octet-stream;base64 MjA7MDU7Q3Jlc3RhO0lEPTI4MDE7VEVNUD0yNTtIVU09NTU7QkFUPU9LOwo="` |
|
||||
| `data` | system.rawbutton | Trigger which emits `PRESSED` events (no `RELEASED` events) whenever data is available on the serial port |
|
||||
|
||||
|
||||
The channels supported by the `serialDevice` are:
|
||||
|
||||
| Channel Type | Type | Description |
|
||||
|---------------|------------------|----------------------------------------------------------------------------------------------------------|
|
||||
| `string` | String | Channel for receiving string based commands. The channel can be configured to apply a transform on the received data to convert to the channel state. Commands received by the channel can be formatted and transformed before sending to the device. |
|
||||
| `number` | Number | Channel for receiving number based commands. The channel can be configured to apply a transform on the received data to convert to the channel state. Commands received by the channel can be formatted and transformed before sending to the device. |
|
||||
| `dimmer` | Dimmer | Channel for receiving commands from a Dimmer. The channel can be configured to apply a transform on the received data to convert to the channel state. The channel can be configured to apply a simple mapping for the ON, OFF, INCREASE and DECREASE commands. |
|
||||
| `switch` | Switch | Channel for receiving commands from a Switch. The channel can be configured to apply a transform on the received data to convert to the channel state. The channel can be configured to apply a simple mapping for the ON and OFF commands. |
|
||||
| `rollershutter` | Rollershutter | Channel for receiving commands from a Rollershutter. The channel can be configured to apply a transform on the received data to convert to the channel state. The channel can be configured to apply a simple mapping for the UP, DOWN and STOP commands. |
|
||||
|
||||
The configuration for the `serialBridge` channels consists of the following parameters:
|
||||
|
||||
| Parameter | Description | Supported Channels |
|
||||
|------------------|----------------------------------------------------------------------------------------|--------------------|
|
||||
| `stateTransformation` | One or more transformation (concatenated with `∩`) used to convert device data to channel state, e.g. `REGEX:.*?STATE=(.*?);.*` | string, number, dimmer, switch, rollershutter |
|
||||
| `commandTransformation` | One or more transformation (concatenated with `∩`) used to convert command to device data, e.g. `JS:device.js` | string, number, dimmer, switch, rollershutter |
|
||||
| `commandFormat` | Format string applied to the command before transform, e.g. `ID=671;COMMAND=%s` | string, number, dimmer, rollershutter |
|
||||
| `onValue` | Send this value when receiving an ON command | switch, dimmer |
|
||||
| `offValue` | Send this value when receiving an OFF command | switch, dimmer |
|
||||
| `increaseValue` | Send this value when receiving an INCREASE command | dimmer |
|
||||
| `decreaseValue` | Send this value when receiving a DECREASE command | dimmer |
|
||||
| `upValue` | Send this value when receiving an UP command | rollershutter |
|
||||
| `downValue` | Send this value when receiving a DOWN command | rollershutter |
|
||||
| `stopValue` | Send this value when receiving a STOP command | rollershutter |
|
||||
|
||||
|
||||
## Full Example
|
||||
|
||||
The following example is for a device connected to a serial port which provides data for many different sensors and we are interested in the temperature from a particular sensor.
|
||||
|
||||
The data for the sensor of interest is `20;05;Cresta;ID=2801;TEMP=25;HUM=55;BAT=OK;`
|
||||
|
||||
demo.things:
|
||||
|
||||
```
|
||||
Bridge serial:serialBridge:sensors [serialPort="/dev/ttyUSB01", baudRate=57600] {
|
||||
Thing serialDevice temperatureSensor [patternMatch="20;05;Cresta;ID=2801;.*"] {
|
||||
Channels:
|
||||
Type number : temperature [transform="REGEX:.*?TEMP=(.*?);.*"]
|
||||
Type number : humidity [transform="REGEX:.*?HUM=(.*?);.*"]
|
||||
}
|
||||
Thing serialDevice rollershutter [patternMatch=".*"] {
|
||||
Channels:
|
||||
Type rollershutter : serialRollo [transform="REGEX:Position:([0-9.]*)", up="Rollo_UP\n", down="Rollo_DOWN\n", stop="Rollo_STOP\n"]
|
||||
Type switch : roloAt100 [transform="REGEX:s/Position:100/ON/"]
|
||||
}
|
||||
Thing serialDevice relay [patternMatch=".*"] {
|
||||
Channels:
|
||||
Type switch : serialRelay [on="Q1_ON\n", off="Q1_OFF\n"]
|
||||
}
|
||||
Thing serialDevice myDevice [patternMatch="ID=2341;.*"] {
|
||||
Channels:
|
||||
Type string : control [commandTransform="JS:addCheckSum.js", commandFormat="ID=2341;COMMAND=%s;"]
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
demo.items:
|
||||
|
||||
```
|
||||
Number:Temperature myTemp "My Temperature" {channel="serial:serialDevice:sensors:temperatureSensor:temperature"}
|
||||
Number myHum "My Humidity" {channel="serial:serialDevice:sensors:temperatureSensor:humidity"}
|
||||
Switch serialRelay "Relay Q1" (Entrance) {channel="serial:serialDevice:sensors:relay:serialRelay"}
|
||||
Rollershutter serialRollo "Entrance Rollo" (Entrance) {channel="serial:serialDevice:sensors:rollershutter:serialRollo"}
|
||||
Rollershutter roloAt100 "Rolo at 100" (Entrance) {channel="serial:serialDevice:sensors:rollershutter:roloAt100"}
|
||||
String deviceControl {channel="serial:serialDevice:sensors:myDevice:control"}
|
||||
```
|
||||
|
|
@ -116,7 +116,7 @@ This is an optional parameter and multiple values are allowed.
|
|||
| `wanMaxUpstreamRate` | `Number:DataTransferRate` | x | Max. Upstream Rate |
|
||||
| `wanPhysicalLinkStatus` | `String` | x | Link Status |
|
||||
| `wanTotalBytesReceived` | `Number:DataAmount` | x | Total Bytes Received |
|
||||
| `wanTotalBytesSent` | `Number:DataAmount` | x | Total Bytes Send |
|
||||
| `wanTotalBytesSent` | `Number:DataAmount` | x | Total Bytes Sent |
|
||||
| `wifi24GHzEnable` | `Switch` | | Enable/Disable the 2.4 GHz WiFi device. |
|
||||
| `wifi5GHzEnable` | `Switch` | | Enable/Disable the 5.0 GHz WiFi device. |
|
||||
| `wifiGuestEnable` | `Switch` | | Enable/Disable the guest WiFi. |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,245 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<thing:thing-descriptions bindingId="serial"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xmlns:thing="https://openhab.org/schemas/thing-description/v1.0.0"
|
||||
xsi:schemaLocation="https://openhab.org/schemas/thing-description/v1.0.0 https://openhab.org/schemas/thing-description-1.0.0.xsd">
|
||||
|
||||
<!-- Thing Types -->
|
||||
<bridge-type id="serialBridge">
|
||||
<label>Serial Bridge</label>
|
||||
<description>Serial port which can send and receive data</description>
|
||||
|
||||
<channels>
|
||||
<channel id="string" typeId="stringData"/>
|
||||
<channel id="binary" typeId="binaryData"/>
|
||||
<channel id="data" typeId="system.rawbutton"/>
|
||||
</channels>
|
||||
|
||||
<config-description>
|
||||
<parameter name="serialPort" type="text" required="true">
|
||||
<context>serial-port</context>
|
||||
<label>Serial Port</label>
|
||||
<description>The serial port to use (e.g. Linux: /dev/ttyUSB0, Windows: COM1)</description>
|
||||
</parameter>
|
||||
<parameter name="baudRate" type="integer">
|
||||
<advanced>true</advanced>
|
||||
<label>Baud Rate</label>
|
||||
<description>Set the baud rate</description>
|
||||
<default>9600</default>
|
||||
<options>
|
||||
<option value="4800">4800</option>
|
||||
<option value="9600">9600</option>
|
||||
<option value="19200">19200</option>
|
||||
<option value="38400">38400</option>
|
||||
<option value="57600">57600</option>
|
||||
<option value="115200">115200</option>
|
||||
</options>
|
||||
</parameter>
|
||||
<parameter name="dataBits" type="integer">
|
||||
<advanced>true</advanced>
|
||||
<label>Data Bits</label>
|
||||
<description>Set the data bits</description>
|
||||
<default>8</default>
|
||||
<options>
|
||||
<option value="5">5</option>
|
||||
<option value="6">6</option>
|
||||
<option value="7">7</option>
|
||||
<option value="8">8</option>
|
||||
</options>
|
||||
</parameter>
|
||||
<parameter name="parity" type="text">
|
||||
<advanced>true</advanced>
|
||||
<label>Parity</label>
|
||||
<description>Set the parity</description>
|
||||
<default>N</default>
|
||||
<options>
|
||||
<option value="N">N(one)</option>
|
||||
<option value="O">O(dd)</option>
|
||||
<option value="E">E(even)</option>
|
||||
<option value="M">M(ark)</option>
|
||||
<option value="S">S(pace)</option>
|
||||
</options>
|
||||
</parameter>
|
||||
<parameter name="stopBits" type="text">
|
||||
<advanced>true</advanced>
|
||||
<label>Stop Bits</label>
|
||||
<description>Set the stop bits</description>
|
||||
<default>1</default>
|
||||
<options>
|
||||
<option value="1">1</option>
|
||||
<option value="1.5">1.5</option>
|
||||
<option value="2">2</option>
|
||||
</options>
|
||||
</parameter>
|
||||
<parameter name="charset" type="text">
|
||||
<advanced>true</advanced>
|
||||
<label>Charset</label>
|
||||
<description>The charset to use for converting between bytes and string (e.g. UTF-8, ISO-8859-1)</description>
|
||||
</parameter>
|
||||
</config-description>
|
||||
</bridge-type>
|
||||
|
||||
<thing-type id="serialDevice" extensible="string, number, dimmer, switch, rollershutter">
|
||||
<supported-bridge-type-refs>
|
||||
<bridge-type-ref id="serialBridge"/>
|
||||
</supported-bridge-type-refs>
|
||||
|
||||
<label>Serial Device</label>
|
||||
<description>Represents a device</description>
|
||||
|
||||
<config-description>
|
||||
<parameter name="patternMatch" type="text">
|
||||
<label>Patern Match</label>
|
||||
<context>pattern-match</context>
|
||||
<required>true</required>
|
||||
<description>Regular expression used to identify device from received data (must match the whole line)</description>
|
||||
</parameter>
|
||||
</config-description>
|
||||
</thing-type>
|
||||
|
||||
<!-- Channel Types -->
|
||||
<channel-type id="stringData">
|
||||
<item-type>String</item-type>
|
||||
<label>String Data</label>
|
||||
<description>Channel for sending/receiving data as a string to/from the serial port</description>
|
||||
</channel-type>
|
||||
|
||||
<channel-type id="binaryData">
|
||||
<item-type>String</item-type>
|
||||
<label>Binary Data</label>
|
||||
<description>Channel for sending/receiving data encoded as Base64 to/from the serial port</description>
|
||||
</channel-type>
|
||||
|
||||
<channel-type id="string">
|
||||
<item-type>String</item-type>
|
||||
<label>String</label>
|
||||
<description>Channel to receive commands as a string</description>
|
||||
<config-description>
|
||||
<parameter name="stateTransformation" type="text">
|
||||
<label>State Transformation</label>
|
||||
<description>Transform used to convert device data to channel state, e.g. REGEX:.*?STATE=(.*?);.*</description>
|
||||
</parameter>
|
||||
<parameter name="commandFormat" type="text">
|
||||
<label>String Format</label>
|
||||
<description>Format string applied to the command, e.g. ID=671;COMMAND=%s</description>
|
||||
</parameter>
|
||||
<parameter name="commandTransformation" type="text">
|
||||
<label>Command Transformation</label>
|
||||
<description>Transform used to convert command to device data, e.g. JS:device.js</description>
|
||||
</parameter>
|
||||
</config-description>
|
||||
</channel-type>
|
||||
|
||||
<channel-type id="number">
|
||||
<item-type>Number</item-type>
|
||||
<label>Number</label>
|
||||
<description>Channel to receive commands as a number</description>
|
||||
<config-description>
|
||||
<parameter name="stateTransformation" type="text">
|
||||
<label>State Transformation</label>
|
||||
<description>Transform used to convert device data to channel state, e.g. REGEX:.*?STATE=(.*?);.*</description>
|
||||
</parameter>
|
||||
<parameter name="commandFormat" type="text">
|
||||
<label>Number Format</label>
|
||||
<description>Format string applied to the command, e.g. ID=671;VAL=%f</description>
|
||||
</parameter>
|
||||
<parameter name="commandTransformation" type="text">
|
||||
<label>Command Transformation</label>
|
||||
<description>Transform used to convert command to device data, e.g. JS:device.js</description>
|
||||
</parameter>
|
||||
</config-description>
|
||||
</channel-type>
|
||||
|
||||
<channel-type id="dimmer">
|
||||
<item-type>Dimmer</item-type>
|
||||
<label>Dimmer</label>
|
||||
<description>Channel to receive commands from a Dimmer</description>
|
||||
<config-description>
|
||||
<parameter name="stateTransformation" type="text">
|
||||
<label>State Transformation</label>
|
||||
<description>Transform used to convert device data to channel state, e.g. REGEX:.*?STATE=(.*?);.*</description>
|
||||
</parameter>
|
||||
<parameter name="onValue" type="text">
|
||||
<label>On Value</label>
|
||||
<description>Send this value when receiving an ON command</description>
|
||||
</parameter>
|
||||
<parameter name="offValue" type="text">
|
||||
<label>Off Value</label>
|
||||
<description>Send this value when receiving an OFF command</description>
|
||||
</parameter>
|
||||
<parameter name="increaseValue" type="text">
|
||||
<label>Increase Value</label>
|
||||
<description>Send this value when receiving an INCREASE command</description>
|
||||
</parameter>
|
||||
<parameter name="decreaseValue" type="text">
|
||||
<label>Decrease Value</label>
|
||||
<description>Send this value when receiving a DECREASE command</description>
|
||||
</parameter>
|
||||
<parameter name="commandFormat" type="text">
|
||||
<label>Percent Format</label>
|
||||
<description>Format string applied to the percent command, e.g. ID=671;VAL=%d</description>
|
||||
</parameter>
|
||||
<parameter name="commandTransformation" type="text">
|
||||
<label>Command Transformation</label>
|
||||
<description>Transform used to convert command to device data, e.g. JS:device.js</description>
|
||||
</parameter>
|
||||
</config-description>
|
||||
</channel-type>
|
||||
|
||||
<channel-type id="switch">
|
||||
<item-type>Switch</item-type>
|
||||
<label>Switch</label>
|
||||
<description>Channel to receive commands from a Switch</description>
|
||||
<config-description>
|
||||
<parameter name="stateTransformation" type="text">
|
||||
<label>State Transformation</label>
|
||||
<description>Transform used to convert device data to channel state, e.g. REGEX:.*?STATE=(.*?);.*</description>
|
||||
</parameter>
|
||||
<parameter name="onValue" type="text">
|
||||
<label>On Value</label>
|
||||
<description>Send this value when receiving an ON command</description>
|
||||
</parameter>
|
||||
<parameter name="offValue" type="text">
|
||||
<label>Off Value</label>
|
||||
<description>Send this value when receiving an OFF command</description>
|
||||
</parameter>
|
||||
<parameter name="commandTransformation" type="text">
|
||||
<label>Command Transformation</label>
|
||||
<description>Transform used to convert command to device data, e.g. JS:device.js</description>
|
||||
</parameter>
|
||||
</config-description>
|
||||
</channel-type>
|
||||
|
||||
<channel-type id="rollershutter">
|
||||
<item-type>Rollershutter</item-type>
|
||||
<label>Rollershutter</label>
|
||||
<description>Channel to receive commands from a Rollershutter</description>
|
||||
<config-description>
|
||||
<parameter name="stateTransformation" type="text">
|
||||
<label>State Transformation</label>
|
||||
<description>Transform used to convert device data to channel state, e.g. REGEX:.*?STATE=(.*?);.*</description>
|
||||
</parameter>
|
||||
<parameter name="upValue" type="text">
|
||||
<label>Up Value</label>
|
||||
<description>Send this value when receiving an UP command</description>
|
||||
</parameter>
|
||||
<parameter name="downValue" type="text">
|
||||
<label>Down Value</label>
|
||||
<description>Send this value when receiving a DOWN command</description>
|
||||
</parameter>
|
||||
<parameter name="stopValue" type="text">
|
||||
<label>Stop Value</label>
|
||||
<description>Send this value when receiving a STOP command</description>
|
||||
</parameter>
|
||||
<parameter name="commandFormat" type="text">
|
||||
<label>Percent Format</label>
|
||||
<description>Format string applied to the percent command, e.g. ID=671;VAL=%d</description>
|
||||
</parameter>
|
||||
<parameter name="commandTransformation" type="text">
|
||||
<label>Command Transformation</label>
|
||||
<description>Transform used to convert command to device data, e.g. JS:device.js</description>
|
||||
</parameter>
|
||||
</config-description>
|
||||
</channel-type>
|
||||
|
||||
</thing:thing-descriptions>
|
||||
Loading…
Reference in New Issue