# 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>) 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>) (`ams`, `bms`), Embedded Data System (<www.embeddeddatasystems.com>)(`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` or `aux`) 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 built around the DS2438 or DS1923 chipset.
It always provides a `temperature` channel.

Depending 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/>) 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 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 erroneous 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` Example

```java
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` Example

```java
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` Example

```perl
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
    }
}
```
