This page is part of archived documentation for openHAB 3.3. Go to the current stable version
# OneWire Binding
The OneWire binding integrates OneWire (also spelled 1-Wire) devices. OneWire is a serial bus developed by Dallas Semiconductor. It provides cheap sensors for temperature, humidity, digital I/O and more.
# Getting Started
The OneWire File System (OWFS, https://owfs.org (opens new window)) provides an abstraction layer between the OneWire bus and this binding. It is assumed that you already have a working OWFS installation. Besides your sensors, you need a busmaster device (e.g. DS9490R).
# Supported Things
# Bridges
Currently only one bridge is supported.
The owserver
is the bridge that connects to an existing OWFS installation.
# Things
There are different types of things: the simple one (basic
), multisensors built around the DS1923/DS2438 chip (ms-tx
) and more advanced sensors from Elaborated Networks (www.wiregate.de (opens new window)) (ams
, bms
), Embedded Data System (www.embeddeddatasystems.com (opens new window))(edsenv
) and Brain4Home (bae091x
).
# Discovery
Discovery is supported for things. You have to add the bridges manually.
# Thing Configuration
It is strongly recommended to add things using discovery and configure them using the UI. Please note that:
- All things need a bridge.
- The sensor id parameter supports only the dotted format, including the family id (e.g.
28.7AA256050000
). DS2409 MicroLAN couplers (hubs) are supported by adding their id and the branch (main
oraux
) in a directory-like format in front of the sensor id (e.g.1F.EDC601000000/main/28.945042000000
). - Refresh time is the minimum time in seconds between two checks of that thing. It defaults to 300s for analog channels and 10s for digital channels.
- Some thing channels need additional configuration, please see below in the channels section.
# OWFS Bridge (owserver
)
There are no configuration options for the owserver besides the network address.
It consists of two parts: address
and port
.
The address
parameter is used to denote the location of the owserver instance.
It supports both, a hostname or an IP address.
The port
parameter is used to adjust non-standard OWFS installations.
It defaults to 4304
, which is the default of each OWFS installation.
Bridges of type owserver
are extensible with channels of type owfs-number
and owfs-string
.
# Generic (basic
)
The basic
thing supports iButton-like chips (DS1420, DS2401/DS1990A), temperature sensors (DS18B20, DS18S20, DS1822), digital i/o chips (DS2405, DS2406, DS2408, DS2413) and counter chips (DS2423).
It has two parameters: sensor id id
and refresh time refresh
.
Depending on the chip, either present
, temperature
, digitalX
or counterX
channel(s) are added.
X
is the number of the channel, starting from 0
.
# Multisensor (ms-tx
)
The multisensor is build around the DS2438 or DS1923 chipset.
It always provides a temperature
channel.
Depnding on the actual sensor, additional channels (current
, humidity
, light
, voltage
, supplyvoltage
) are added.
If the voltage input of the DS2438 is connected to a humidity sensor, several common types are supported (see below).
It has three parameters: sensor id id
, refresh time refresh
and manualsensor
(advanced option).
Known DS2438-base sensors are iButtonLink (https://www.ibuttonlink.com/ (opens new window)) MS-T (recognized as generic DS2438), MS-TH, MS-TC, MS-TL, MS-TV.
Unknown multisensors are added as generic DS2438 and have temperature
, current
, voltage
and supplyvoltage
channels.
In case the sensor is not properly detected (e.g. because it is a self-made sensor), check if it is compatible with one of the sensors listed above.
You can use manualsensor
to override the auto-detected sensortype by setting DS2438
, MS_TH
, MS_TV
, MS_TL
or MS_TC
.
# Elaborated Networks Multisensors (ams
, bms
)
These things are complex devices from Elaborated networks. They consist of a DS2438 and a DS18B20 with additional circuitry on one PCB. The AMS additionally has a second DS2438 and a DS2413 for digital I/O on-board. Analog light sensors can optionally be attached to both sensors.
These sensors provide temperature
, humidity
and supplyvoltage
channels.
If the light sensor is attached and configured, a light
channel is provided, otherwise a current
channel.
The AMS has an additional voltage
and two digitalX
channels.
It has two (bms
) or four (ams
) sensors.
The id parameter (id
) has to be configured with the sensor id of the humidity sensor.
Additionally the refresh time refresh
can be configured.
The AMS supports a digitalrefresh
parameter for the refresh time of the digital channels.
Since both multisensors have two temperature sensors on-board, the temperaturesensor
parameter allows to select DS18B20
or DS2438
to be used for temperature measurement.
This parameter has a default of DS18B20
as this is considered more accurate.
The temperature
channel is of type temperature
if the internal sensor is used and of type temperature-por-res
for the external DS18B20.
The last parameter is the lightsensor
option to configure if an ambient light sensor is attached.
It defaults to false
.
In that mode, a current
channel is provided.
If set to true
, a light
channel is added to the thing.
The correct formula for the ambient light is automatically determined from the sensor version.
# Embedded Data System Environmental sensors (edsenv
)
This thing supports EDS0064, EDS0065, EDS0066 or EDS0067 sensors.
It has two parameters: sensor id id
and refresh time refresh
.
All things have a temperature
channel.
Additional channels (light
, pressure
, humidity
, dewpoint
, abshumidity
) will be added if available from the sensor automatically.
# Brain4Home BAE091x (bae091x
)
Currently this thing only supports BAE0910 sensors.
All functional pins of this sensor have multiple functions which can be configured individually.
For detailed information of each mode, please see the official documentation.
Each pin has the can be configured as disabled
.
The necessary channels are automatically added.
Pin 1 (pin1
) has only one function counter
(channel counter
).
Pin 2 (pin2
) can be configured as digital output (output
, channel digital2
) or pulse width modulated output (pwm
, software PWM 4, channels freq2
, duty4
).
Pin 6 (pin6
) can be configured as digital in-/output (pio
, channel digital6
) or pulse width modulated output (pwm
, software PWM 3, channels freq1
, duty3
).
Pin 7 (pin7
) can be configured as analog input (analog
), digital output (output
, channel digital7
) or pulse width modulated output (pwm
, hardware PWM 2, channels freq2
, duty2
).
Pin 8 (pin8
) can be configured as digital input (input
, channel digital8
), digital output (output
, channel digital8
) or pulse width modulated output (pwm
, hardware PWM 1, channels freq1
, duty1
).
Please note: support for this sensor is considered experimental.
# Channels
Type-ID | Thing | Item | readonly | Description |
---|---|---|---|---|
absolutehumidity | ms-tx, ams, bms, edsenv | Number:Density | yes | absolute humidity |
current | ms-tx, ams | Number:ElectricCurrent | yes | current |
counter | counter2 | Number | yes | countervalue |
dewpoint | ms-tx, ams, bms, edsenv | Number:Temperature | yes | dewpoint |
dio | digitalX, ams | Switch | no | digital I/O, can be configured as input or output |
humidity | ms-tx, ams, bms, edsenv | Number:Dimensionless | yes | relative humidity |
humidityconf | ms-tx | Number:Dimensionless | yes | relative humidity |
light | ams, bms, edsenv | Number:Illuminance | yes | lightness |
owfs-number | owserver | Number | yes | direct access to OWFS nodes |
owfs-string | owserver | String | yes | direct access to OWFS nodes |
present | all | Switch | yes | sensor found on bus (yes = ON) |
pressure | edsenv | Number:Pressure | yes | environmental pressure |
supplyvoltage | ms-tx | Number:ElectricPotential | yes | sensor supplyvoltage |
temperature | temperature, ms-tx, edsenv | Number:Temperature | yes | environmental temperature |
temperature-por | temperature | Number:Temperature | yes | environmental temperature |
temperature-por-res | temperature, ams, bms | Number:Temperature | yes | environmental temperature |
voltage | ms-tx, ams | Number:ElectricPotential | yes | voltage input |
bae-pwm-frequency | bae091x | Number:Frequency | no | frequency for PWM output |
bae-pwm-duty | bae091x | Number:Dimensionless | no | duty cycle (0-100%) for PWM output |
bae-di | bae091x | Switch | yes | digital input |
bae-do | bae091x | Switch | no | digital output |
bae-pio | bae091x | Switch | yes | digital in-/output |
bae-analog | bae091x | Number:ElectricPotential | yes | analog input |
bae-counter | bae091x | Number | yes | countervalue |
# Digital I/O (dio
)
Channels of type dio
channels each have two parameters: mode
and logic
.
The mode
parameter is used to configure this channels as input
or output
.
The logic
parameter can be used to invert the channel.
In normal
mode the channel is considered ON
for logic high, and OFF
for logic low.
In inverted
mode ON
is logic low and OFF
is logic high.
# Humidity (humidity
, humidityconf
, abshumidity
, dewpoint
)
Depending on the sensor, a humidity
or humidityconf
channel may be added.
This is only relevant for DS2438-based sensors of thing-type ms-tx
.
humidityconf
-type channels have the humiditytype
parameter.
Possible options are /humidity
for HIH-3610 sensors, /HIH4000/humidity
for HIH-4000 sensors, /HTM1735/humidity
for HTM-1735 sensors and /DATANAB/humidity
for sensors from Datanab.
All humidity sensors also support absolutehumidity
and dewpoint
.
# OWFS Direct Access (owfs-number
, owfs-string
)
These channels allow direct access to OWFS nodes.
They have two configuration parameters: path
and refresh
.
The path
parameter is mandatory and contains a full path inside the OWFS (e.g. statistics/errors/CRC8_errors
).
The refresh
parameter is the number of seconds between two consecutive (successful) reads of the node.
It defaults to 300s.
# Temperature (temperature
, temperature-por
, temperature-por-res
)
There are three temperature channel types: temperature
, temperature-por
and temperature-por-res
.
The correct channel-type is selected automatically by the thing handler depending on the sensor type.
If the channel-type is temperature
, there is nothing else to configure.
Some sensors (e.g. DS18x20) report 85 °C as Power-On-Reset value.
In some installations this leads to errorneous temperature readings.
If the ignorepor
parameter is set to true
85 °C values will be filtered.
The default is false
as correct reading of 85 °C will otherwise be filtered, too.
Please note that the parameter value must not be set in quotation marks (see example below).
A channel of type temperature-por-res
has one parameter: resolution
.
OneWire temperature sensors are capable of different resolutions: 9
, 10
, 11
and 12
bits.
This corresponds to 0.5 °C, 0.25 °C, 0.125 °C, 0.0625 °C respectively.
The conversion time is inverse to that and ranges from 95 ms to 750 ms.
For best performance it is recommended to set the resolution only as high as needed.
# BAE PWM (bae-pwm-frequency
, bae-pwm-duty
)
PWM output 1 and 3 (2 and 4) share a frequency channel pwmfreq1
(pwmfreq2
).
Each PWM output has its own duty cycle (pwmduty1
to pwmduty4
).
The frequency channel has two configuration options (prescaler
, reversePolarity
).
The prescaler
sets the frequency range which can be used.
Valid values are 0
to 7
(0
=> 245 Hz - 8 MHz, 1
=> 123 Hz - 4 MHz, 2
=> 62 Hz - 2 MHz, 3
=> 31 Hz - 1 MHz, 4
=> 16 Hz - 500 kHz, 5
=> 8 Hz - 250 kHz, 6
=> 4 Hz - 125 kHz, 7
=> 2 Hz - 62.5 kHz).
The default value is 0
.
The reversePolarity
option is used to invert the output.
It can be true
or false
.
The default value is false
.
The duty cycle can be set from 0-100%.
# BAE PIO (bae-pio
)
The PIO channel (programmable I/O channel) has two configuration options: mode
and pulldevice
.
The mode
can be set to input
or output
.
The default is input
.
The pulldevice
is only relevant for input
mode.
It can be configured as disabled
, pullup
, pulldown
.
The default is disabled.
# Full Example
** Attention: Adding channels with UIDs different from the ones mentioned in the thing description will not work and may cause problems. Please use the pre-defined channel names only. **
This is the configuration for a OneWire network consisting of an owserver as bridge (onewire:owserver:mybridge
) as well as a temperature sensor, a BMS and a 2-port Digital I/O as things (onewire:basic:mybridge:mysensor
, onewire:bms:mybridge:mybms
, onewire:basic:mybridge:mydio
).
# demo.things:
Bridge onewire:owserver:mybridge [
network-address="192.168.0.51"
] {
Thing basic mysensor [
id="28.505AF0020000",
refresh=60
] {
Channels:
Type temperature-por-res : temperature [
ignorepor=true,
resolution="11"
]
}
Thing bms mybms [
id="26.CD497C010000",
refresh=60,
lightsensor=true,
temperaturesensor="DS18B20"
] {
Channels:
Type temperature-por-res : temperature [
ignorepor=false,
resolution="9"
]
}
Thing basic mydio [
id="3A.67F113000000"
] {
Channels:
Type dio : digital0 [
mode="input"
]
Type dio : digital1 [
mode="output"
]
}
Channels:
Type owfs-number : crc8errors [
path="statistics/errors/CRC8_errors"
]
}
# demo.items:
Number:Temperature MySensor "MySensor [%.1f °C]" { channel="onewire:basic:mybridge:mysensor:temperature" }
Number:Temperature MyBMS_T "MyBMS Temperature [%.1f °F]" { channel="onewire:bms:mybridge:mybms:temperature" }
Number:Dimensionless MyBMS_H "MyBMS Humidity [%.1f %unit%]" { channel="onewire:bms:mybridge:mybms:humidity" }
Switch Digital0 "Digital 0" { channel="onewire:basic:mybridge:mydio:digital0" }
Switch Digital1 "Digital 1" { channel="onewire:basic:mybridge:mydio:digital1" }
Number CRC8Errors "Bus-Errors [%d]" { channel="onewire:owserver:mybridge:crc8errors" }
# demo.sitemap:
sitemap demo label="Main Menu"
{
Frame {
Text item=MySensor
Text item=MyBMS_T
Text item=MyBMS_H
Text item=CRC8Errors
Text item=Digital0
Switch item=Digital1
}
}