Updated external content (Jenkins build 234)

pull/1569/head
openHAB Build Server 2021-02-03 04:46:55 +00:00
parent 67d224afde
commit 01f8d00250
5 changed files with 219 additions and 29 deletions

File diff suppressed because one or more lines are too long

View File

@ -0,0 +1,88 @@
---
id: modbus.sbc
label: Modbus Saia Burgess Controls
title: Modbus Saia Burgess Controls - Bindings
type: binding
description: "This binding interfaces the energy meter series ALD1 by Saia Burgess Controls (SBC) via Modbus."
since: 3x
install: manual
---
<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->
{% include base.html %}
# Modbus Saia Burgess Controls Binding
This binding interfaces the energy meter series ALD1 by Saia Burgess Controls (SBC) via Modbus.
## Supported Things
The following Things are supported:
- `ald1Unidirectional`: 1-phase 32A one-way energy meter ALD1D5FD00A3A00
- `ald1Bidirectional`: 1-phase 32A two-way energy meter ALD1B5FD00A3A00
## Discovery
This binding does not support discovery.
## Thing Configuration
The following configuration parameter applys to `ald1Unidirectional` and `ald1Bidirectional`.
| Name | Description | Type | Required |
|---------------|------------------------------------------|---------|----------|
| pollInterval | Time between polling the data in ms | Integer | yes |
The Thing needs a Modbus serial slave Bridge to operate.
One of the following serial settings need to be configured in the Bridge:
- 9600 baud, 2 stop bit, no parity
- 9600 baud, 1 stop bit, even parity
- 9600 baud, 1 stop bit, odd parity
## Channels
The following Channels apply to `ald1Unidirectional` and `ald1Bidirectional` if not stated otherwise.
| Name | Type | Description |
|---------------------|--------------------------|---------------------------------------------------------------|
| total_energy | Number:Energy | Energy Total |
| partial_energy | Number:Energy | Energy Counter Resettable (only unidirectional meter) |
| feeding_back_energy | Number:Energy | Energy Feeding Back (only bidirectional meter) |
| voltage | Number:ElectricPotential | Effective Voltage |
| current | Number:ElectricCurrent | Effective Current |
| active_power | Number:Power | Effective Active Power (negative numbers mean feeding back) |
| reactive_power | Number:Power | Effective Reactive Power (negative numbers mean feeding back) |
| power_factor | Number:Dimensionless | Power Factor |
## Full Example
### .items
```
Number:Energy ALD1_Total_Energy "[%.2f %unit%]" {channel="modbus:ald1Bidirectional:8b6e85623b:total_energy"}
Number:Energy ALD1_Feeding_Back_Energy "[%.2f %unit%]" {channel="modbus:ald1Bidirectional:8b6e85623b:feeding_back_energy"}
Number:ElectricPotential ALD1_Voltage "[%d %unit%]" {channel="modbus:ald1Bidirectional:8b6e85623b:voltage"}
Number:ElectricCurrent ALD1_Current "[%.1f %unit%]" {channel="modbus:ald1Bidirectional:8b6e85623b:current"}
Number:Power ALD1_Active_Power "[%.2f %unit%]" {channel="modbus:ald1Bidirectional:8b6e85623b:active_power"}
Number:Power ALD1_Reactive_Power "[%.2f %unit%]" {channel="modbus:ald1Bidirectional:8b6e85623b:reactive_power"}
Number:Dimensionless ALD1_Power_Factor "[%.2f]" {channel="modbus:ald1Bidirectional:8b6e85623b:power_factor"}
```
### .sitemap
```
sitemap ald1 label="ALD1 Energy Meter"
{
Default item=ALD1_Total_Energy label="Total Energy"
Default item=ALD1_Feeding_Back_Energy label="Feeding Back Energy"
Default item=ALD1_Voltage label="Voltage"
Default item=ALD1_Current label="Current"
Default item=ALD1_Active_Power label="Active Power"
Default item=ALD1_Reactive_Power label="Reactive Power"
Default item=ALD1_Power_Factor label="Power Factor"
}
```

View File

@ -217,12 +217,12 @@ You must give each of your data Things a reference (thing ID) that is unique for
| ------------------------------------------- | ------- | -------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `readValueType` | text | | (empty) | How data is read from modbus. Use empty for write-only things.<br /><br />Bit value type must be used with coils and discrete inputs. With registers all value types are applicable. Valid values are: `"int64"`, `"int64_swap"`, `"uint64"`, `"uint64_swap"`, `"float32"`, `"float32_swap"`, `"int32"`, `"int32_swap"`, `"uint32"`, `"uint32_swap"`, `"int16"`, `"uint16"`, `"int8"`, `"uint8"`, or `"bit"`. See also [Value types on read and write](#value-types-on-read-and-write). |
| `readStart` | text | | (empty) | Start address to start reading the value. Use empty for write-only things. <br /><br />Input as zero-based index number, e.g. in place of `400001` (first holding register), use the address `"0"`. Must be between (poller start) and (poller start + poller length - 1) (inclusive).<br /><br />With registers and value type less than 16 bits, you must use `"X.Y"` format where `Y` specifies the sub-element to read from the 16 bit register:<ul> <li>For example, `"3.1"` would mean pick second bit from register index `3` with bit value type. </li><li>With int8 valuetype, it would pick the high byte of register index `3`.</li></ul> |
| `readTransform` | text | | `"default"` | Transformation to apply to polled data, after it has been converted to number using `readValueType`. <br /><br />Use "default" to communicate that no transformation is done and value should be passed as is.<br />Use `"SERVICENAME(ARG)"` to use transformation service `SERVICENAME` with argument `ARG`. <br />Any other value than the above types will be interpreted as static text, in which case the actual content of the polled value is ignored. |
| `readTransform` | text | | `"default"` | Transformation to apply to polled data, after it has been converted to number using `readValueType`. <br /><br />Use "default" to communicate that no transformation is done and value should be passed as is.<br />Use `"SERVICENAME:ARG"` or `"SERVICENAME(ARG)"` (old syntax) to use transformation service `SERVICENAME` with argument `ARG`. <br />Any other value than the above types will be interpreted as static text, in which case the actual content of the polled value is ignored. ou can chain many transformations with ∩, for example `"SERVICE1:ARG1∩SERVICE2:ARG2"`. |
| `writeValueType` | text | | (empty) | How data is written to modbus. Only applicable to registers. Valid values are: `"int64"`, `"int64_swap"`, `"float32"`, `"float32_swap"`, `"int32"`, `"int32_swap"`, `"int16"`. See also [Value types on read and write](#value-types-on-read-and-write). |
| `writeStart` | text | | (empty) | Start address of the first holding register or coil in the write. Use empty for read-only things. <br />Use zero based address, e.g. in place of `400001` (first holding register), use the address `"0"`. This address is passed to data frame as is. |
| `writeType` | text | | (empty) | Type of data to write. Use empty for read-only things. Valid values: `"coil"` or `"holding"`.<br /><br /> Coil uses function code (FC) FC05 or FC15. Holding register uses FC06 or FC16. See `writeMultipleEvenWithSingleRegisterOrCoil` parameter. |
| `writeTransform` | text | | `"default"` | Transformation to apply to received commands.<br /><br />Use `"default"` to communicate that no transformation is done and value should be passed as is. <br />Use `"SERVICENAME(ARG)"` to use transformation service `SERVICENAME` with argument `ARG`. <br />Any other value than the above types will be interpreted as static text, in which case the actual content of the command value is ignored. |
| `writeMultipleEvenWithSingleRegisterOrCoil` | boolean | | `false` | Controls how single register / coil of data is written.<br /> By default, or when 'false, FC06 ("Write single holding register") / FC05 ("Write single coil"). Or when 'true', using FC16 ("Write Multiple Holding Registers") / FC15 ("Write Multiple Coils"). |
| `writeTransform` | text | | `"default"` | Transformation to apply to received commands.<br /><br />Use `"default"` to communicate that no transformation is done and value should be passed as is. <br />Use `"SERVICENAME:ARG"` or `"SERVICENAME(ARG)"` (old syntax) to use transformation service `SERVICENAME` with argument `ARG`. <br />Any other value than the above types will be interpreted as static text, in which case the actual content of the command value is ignored. You can chain many transformations with ∩, for example `"SERVICE1:ARG1∩SERVICE2:ARG2"`. |
| `writeMultipleEvenWithSingleRegisterOrCoil` | boolean | | `false` | Controls how single register / coil of data is written.<br /> By default, or when 'false, FC06 ("Write single holding register") / FC05 ("Write single coil"). Or when 'true', using FC16 ("Write Multiple Holding Registers") / FC15 ("Write Multiple Coils"). |
| `writeMaxTries` | integer | | `3` | Maximum tries when writing <br /><br />Number of tries when writing data, if some of the writes fail. For single try, enter `1`. |
| `updateUnchangedValuesEveryMillis` | integer | | `1000` | Interval to update unchanged values. <br /><br />Modbus binding by default is not updating the item and channel state every time new data is polled from a slave, for performance reasons. Instead, the state is updated whenever it differs from previously updated state, or when enough time has passed since the last update. The time interval can be adjusted using this parameter. Use value of `0` if you like to update state with every poll, even though the value has not changed. In milliseconds. |
@ -566,7 +566,7 @@ For example, `openhab-transformation-javascript` feature provides the javascript
There are three different format to specify the configuration:
1. String `"default"`, in which case the default transformation is used. The default is to convert non-zero numbers to `ON`/`OPEN`, and zero numbers to `OFF`/`CLOSED`, respectively. If the item linked to the data channel does not accept these states, the number is converted to best-effort-basis to the states accepted by the item. For example, the extracted number is passed as-is for `Number` items, while `ON`/`OFF` would be used with `DimmerItem`.
1. `"SERVICENAME(ARG)"` for calling a transformation service. The transformation receives the extracted number as input. This is useful for example scaling (divide by x) the polled data before it is used in openHAB. See examples for more details.
1. `"SERVICENAME:ARG"` for calling a transformation service. The transformation receives the extracted number as input. This is useful for example scaling (divide by x) the polled data before it is used in openHAB. See examples for more details.
1. Any other value is interpreted as static text, in which case the actual content of the polled value is ignored. Transformation result is always the same. The transformation output is converted to best-effort-basis to the states accepted by the item.
Consult [background documentation on items](https://www.openhab.org/docs/concepts/items.html) to understand accepted data types (state) by each item.
@ -578,7 +578,7 @@ Consult [background documentation on items](https://www.openhab.org/docs/concept
There are three different format to specify the configuration:
1. String `"default"`, in which case the default transformation is used. The default is to do no conversion to the command.
1. `"SERVICENAME(ARG)"` for calling a transformation service. The transformation receives the command as input. This is useful for example scaling ("multiply by x") commands before the data is written to Modbus. See examples for more details.
1. `"SERVICENAME:ARG"` for calling a transformation service. The transformation receives the command as input. This is useful for example scaling ("multiply by x") commands before the data is written to Modbus. See examples for more details.
1. Any other value is interpreted as static text, in which case the actual command is ignored. Transformation result is always the same.
#### Transformation Example: Scaling
@ -792,7 +792,7 @@ This example divides value on read, and multiplies them on write, using JS trans
```xtend
Bridge modbus:tcp:localhostTCP3 [ host="127.0.0.1", port=502 ] {
Bridge poller holdingPoller [ start=5, length=1, refresh=5000, type="holding" ] {
Thing data holding5Scaled [ readStart="5", readValueType="int16", readTransform="JS(divide10.js)", writeStart="5", writeValueType="int16", writeType="holding", writeTransform="JS(multiply10.js)" ]
Thing data holding5Scaled [ readStart="5", readValueType="int16", readTransform="JS:divide10.js", writeStart="5", writeValueType="int16", writeType="holding", writeTransform="JS:multiply10.js" ]
}
}
```
@ -830,7 +830,7 @@ Example for a dimmer device where 255 register value = 100% for fully ON:
```xtend
Bridge modbus:tcp:remoteTCP [ host="192.168.0.10", port=502 ] {
Bridge poller MBDimmer [ start=4700, length=2, refresh=1000, type="holding" ] {
Thing data DimmerReg [ readStart="4700", readValueType="uint16", readTransform="JS(dimread255.js)", writeStart="4700", writeValueType="uint16", writeType="holding", writeTransform="JS(dimwrite255.js)" ]
Thing data DimmerReg [ readStart="4700", readValueType="uint16", readTransform="JS:dimread255.js", writeStart="4700", writeValueType="uint16", writeType="holding", writeTransform="JS:dimwrite255.js" ]
}
}
```
@ -910,7 +910,7 @@ Bridge modbus:tcp:localhostTCPRollerShutter [ host="127.0.0.1", port=502 ] {
Bridge poller holding [ start=0, length=3, refresh=1000, type="holding" ] {
// Since we are using advanced transformation outputting JSON,
// other write parameters (writeValueType, writeStart, writeType) can be omitted
Thing data rollershutterData [ readStart="0", readValueType="int16", writeTransform="JS(rollershutter.js)" ]
Thing data rollershutterData [ readStart="0", readValueType="int16", writeTransform="JS:rollershutter.js" ]
// For diagnostics
Thing data rollershutterDebug0 [ readStart="0", readValueType="int16", writeStart="0", writeValueType="int16", writeType="holding" ]
@ -1084,7 +1084,7 @@ The new binding supports 32 and 64 bit values types when writing.
### How to manually migrate
Here is a step by step example for a migration from a 1.x configuration to an equivalent 2.x configuration.
Here is a step by step example for a migration from a 1.x configuration to an equivalent 2.x configuration.
It does not cover all features the 1.x configuration offers, but it should serve as an example on how to get it done.
The 1.x modbus configuration to be updated defined 4 slaves:
@ -1122,8 +1122,8 @@ The 1.x modbus configuration to be updated defined 4 slaves:
As you can see, all the slaves poll the same modbus device (actually a Wago 750-841 controller).
We now have to create `Things` for this slaves.
The 2.x modbus binding uses a three-level definition.
Level one defines a `Bridge` for every modbus device that is to be addressed.
The 2.x modbus binding uses a three-level definition.
Level one defines a `Bridge` for every modbus device that is to be addressed.
The 1.x configuration in this example only addresses one device, so there will be one top level bridge.
```
@ -1160,7 +1160,7 @@ Address, length and type can be directly taken over from the 1.x config.
The third (and most complex) part is the definition of data `Thing` objects for every `Item` bound to modbus.
This definitions go into the corresponding 2nd level `Bridge` definitions.
Here it is especially important that the modbus binding now uses absolute addresses all over the place, while the addresses in the item definition for the 1.x binding were relative to the start address of the slave definition before.
For less work in the following final step, the update of the `Item` configuration, the naming of the `data` things in this example uses the offset of the modbus value within the `poller` as suffix, starting with 0(!).
For less work in the following final step, the update of the `Item` configuration, the naming of the `data` things in this example uses the offset of the modbus value within the `poller` as suffix, starting with 0(!).
See below for details.
Here a few examples of the Item configuration from the 1.x binding:
@ -1168,12 +1168,12 @@ Here a few examples of the Item configuration from the 1.x binding:
The first Item polled with the first `poller` used this configuration (with offset 0):
```
Switch FooSwitch "Foo Switch" {modbus="slave1:0"}
Switch FooSwitch "Foo Switch" {modbus="slave1:0"}
```
Now we have to define a `Thing` that can later be bound to that Item.
The `slave1` `poller` uses `12288` as start address.
The `slave1` `poller` uses `12288` as start address.
So we define the first data Thing within the `poller` `wago_slave1` with this address and choose a name that ends with `0`:
```
@ -1217,32 +1217,32 @@ Bridge modbus:tcp:wago [ host="192.168.2.9", port=502, id=1 ] {
}
```
Save this in the `things` folder.
Watch the file `events.log` as it lists your new added `data` `Things`.
Given that there are no config errors, they quickly change from `INITIALIZING` to `ONLINE`.
Save this in the `things` folder.
Watch the file `events.log` as it lists your new added `data` `Things`.
Given that there are no config errors, they quickly change from `INITIALIZING` to `ONLINE`.
Finally the Item definition has to be changed to refer to the new created `data` `Thing`.
Finally the Item definition has to be changed to refer to the new created `data` `Thing`.
You can copy the names you need for this directly from the `events.log` file:
```
Switch FooSwitch "Foo Switch" {modbus="slave1:0"}
Switch FooSwitch "Foo Switch" {modbus="slave1:0"}
Switch BarSwitch "Bar Switch" {modbus="slave1:1"}
```
turn into
```
Switch FooSwitch "Foo Switch" {channel="modbus:data:wago:wago_slave1:wago_s1_000:switch", autopudate="false"}
Switch FooSwitch "Foo Switch" {channel="modbus:data:wago:wago_slave1:wago_s1_000:switch", autopudate="false"}
Switch BarSwitch "Bar Switch" {channel="modbus:data:wago:wago_slave1:wago_s1_001:switch", autoupdate="false"}
```
If you have many Items to change and used the naming scheme recommended above, you can now use the following search-and-replace expressions in your editor:
Replace
Replace
`{modbus="slave1:`
by
by
`{channel="modbus:data:wago:wago_slave1:wago_s1_00`
@ -1250,11 +1250,11 @@ in all lines which used single digits for the address in the 1.x config.
Instead of `wago`, `wago_slave1` and `wago_s1_00` you have to use the names you have chosen for your `Bridge`, `poller` and `data` things.
Similar expressions are to be used for two-digit and three-digit relative addresses.
Replace
Replace
`"}`
by
by
`:switch"}`
@ -1268,7 +1268,7 @@ The definition of `autoupdate` is optional; please refer to [`autoupdate`](#auto
Continue to add `data` `Thing`s for all your other Items the same way and link them to your Items.
Save your updated item file and check whether updates come in as expected.
## Troubleshooting
### Thing Status

View File

@ -0,0 +1,100 @@
<?xml version="1.0" encoding="UTF-8"?>
<thing:thing-descriptions bindingId="modbus"
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-type id="ald1Unidirectional">
<supported-bridge-type-refs>
<bridge-type-ref id="serial"/>
<bridge-type-ref id="tcp"/>
</supported-bridge-type-refs>
<label>ALD1 Energy Meter (Unid.)</label>
<description>Unidirectional one-phase energy meter connected via Modbus.</description>
<channels>
<channel id="total_energy" typeId="total_energy"/>
<channel id="partial_energy" typeId="partial_energy"/>
<channel id="voltage" typeId="voltage"/>
<channel id="current" typeId="current"/>
<channel id="active_power" typeId="active_power"/>
<channel id="reactive_power" typeId="reactive_power"/>
<channel id="power_factor" typeId="power_factor"/>
</channels>
<config-description-ref uri="thing-type:modbus-sbc:ald1"/>
</thing-type>
<thing-type id="ald1Bidirectional">
<supported-bridge-type-refs>
<bridge-type-ref id="serial"/>
<bridge-type-ref id="tcp"/>
</supported-bridge-type-refs>
<label>ALD1 Energy Meter (Bidi.)</label>
<description>Bidirectional one-phase energy meter connected via Modbus.</description>
<channels>
<channel id="total_energy" typeId="total_energy"/>
<channel id="feeding_back_energy" typeId="feeding_back_energy"/>
<channel id="voltage" typeId="voltage"/>
<channel id="current" typeId="current"/>
<channel id="active_power" typeId="active_power"/>
<channel id="reactive_power" typeId="reactive_power"/>
<channel id="power_factor" typeId="power_factor"/>
</channels>
<config-description-ref uri="thing-type:modbus-sbc:ald1"/>
</thing-type>
<channel-type id="total_energy">
<item-type>Number:Energy</item-type>
<label>Energy Total</label>
<state pattern="%.2f %unit%" readOnly="true"/>
</channel-type>
<channel-type id="partial_energy">
<item-type>Number:Energy</item-type>
<label>Energy Counter Resettable</label>
<state pattern="%.2f %unit%" readOnly="true"/>
</channel-type>
<channel-type id="feeding_back_energy">
<item-type>Number:Energy</item-type>
<label>Energy Feeding Back</label>
<state pattern="%.2f %unit%" readOnly="true"/>
</channel-type>
<channel-type id="voltage">
<item-type>Number:ElectricPotential</item-type>
<label>Effective Voltage</label>
<state pattern="%.0f %unit%" readOnly="true"/>
</channel-type>
<channel-type id="current">
<item-type>Number:ElectricCurrent</item-type>
<label>Effective Current</label>
<state pattern="%.1f %unit%" readOnly="true"/>
</channel-type>
<channel-type id="active_power">
<item-type>Number:Power</item-type>
<label>Effective Active Power</label>
<description>Negative numbers mean feeding back</description>
<state pattern="%.2f %unit%" readOnly="true"/>
</channel-type>
<channel-type id="reactive_power">
<item-type>Number:Power</item-type>
<label>Effective Reactive Power</label>
<description>Negative numbers mean feeding back</description>
<state pattern="%.2f %unit%" readOnly="true"/>
</channel-type>
<channel-type id="power_factor">
<item-type>Number:Dimensionless</item-type>
<label>Power Factor</label>
<state pattern="%.2f %unit%" readOnly="true"/>
</channel-type>
</thing:thing-descriptions>

View File

@ -44,9 +44,10 @@
<label>Read Transform</label>
<description><![CDATA[Transformation to apply to polled data, after it has been converted to number using readValueType
<br /><br />Use "default" to communicate that no transformation is done and value should be passed as is.
<br />Use SERVICENAME(ARG) to use transformation service.
<br />Use SERVICENAME(ARG) or SERVICENAME:ARG to use transformation service.
<br />Any other value than the above types will be interpreted as static text, in which case the actual content of the polled
value is ignored.]]></description>
value is ignored.
<br />You can chain many transformations with ∩, for example SERVICE1:ARG1∩SERVICE2:ARG2]]></description>
<default>default</default>
</parameter>
<parameter name="readValueType" type="text">
@ -97,8 +98,9 @@
<label>Write Transform</label>
<description><![CDATA[Transformation to apply to received commands.
<br /><br />Use "default" to communicate that no transformation is done and value should be passed as is.
<br />Use SERVICENAME(ARG) to use transformation service.
<br />Use SERVICENAME(ARG) or SERVICENAME:ARG to use transformation service.
<br />Any other value than the above types will be interpreted as static text, in which case the actual content of the command
<br />You can chain many transformations with ∩, for example SERVICE1:ARG1∩SERVICE2:ARG2
value is ignored.]]></description>
<default>default</default>
</parameter>