= OneWire Bridge

Serial bridge for temperature and sensor devices using the OneWire protocol.

== Overview

The OneWire Bridge provides direct communication with 1-Wire (OneWire) devices such as temperature sensors, humidity monitors, and smart battery controllers. OneWire is a low-speed, single-wire protocol (plus ground) designed by Maxim Integrated for simple sensor networks.

The bridge communicates directly with a OneWire busmaster device (e.g., DS9490R USB dongle) without requiring the OneWire File System (OWFS). It accesses the native Maxim Integrated C library via Java JNI for optimal performance.

Common use cases:

* Temperature monitoring (thermometers at different locations)
* Humidity and environmental sensors
* Battery voltage and current monitoring via smart battery controllers

== Components

[[_bridge_onewire]]
=== Bridge OneWire

*Name*: Bridge OneWire

*Factory-PID*: `Bridge.Onewire`

*Purpose*: Master bridge for 1-Wire communication with temperature and sensor devices.

.*Configuration*:

* `id` (String): Unique bridge identifier; default: `"onewire0"`
* `alias` (String): Human-readable name; default: same as id
* `enabled` (Boolean): Enable/disable this component; default: `true`
* `port` (String): OneWire adapter port identifier; default: `"USB1"`

== Supported Devices

.Common OneWire Sensors
* **DS18B20** - Digital thermometer (-55°C to +125°C)
* **DS18S20** - Digital thermometer (older model)
* **DS2438** - Smart Battery Monitor (voltage, current, temperature)
* **DS2450** - Quad A/D converter for analog inputs
* **DS2413** - Dual addressable switch
* **DS1923** - Temperature and humidity logger

For complete device list, query the bridge via getDevices() JSON-RPC method (see "Identifying Devices" section).

== Hardware Setup

=== OneWire Adapter

Supported adapters:

* **DS9490R** - USB dongle (recommended, most common)
* **DS9481** - Serial adapter
* Compatible third-party 1-Wire adapters

### USB Adapter Setup

1. **Connect adapter** to USB port on OpenEMS system
2. **Verify detection**: `lsusb | grep Maxim`
3. **Configure port** in OpenEMS config (typically `USB1`, `USB2`, etc.)

### Serial Adapter Setup

1. **Connect adapter** to serial port (`/dev/ttyS0`, `/dev/ttyUSB0`, etc.)
2. **Configure permissions**: `sudo chmod 666 /dev/ttyS0`
3. **Set port** in OpenEMS config (e.g., `"/dev/ttyUSB0"`)

== Native Library Installation

The bridge requires the native 1-Wire library from Maxim Integrated compiled for your system.

=== Linux Installation

1. **Download OneWireViewer**:
   ```bash
   wget https://www.maximintegrated.com/.../OneWireViewer-Linux.zip
   unzip OneWireViewer-Linux.zip
   ```

2. **Install build dependencies**:
   ```bash
   sudo apt-get install libusb-dev build-essential
   sudo apt-get install openjdk-11-jdk  # or appropriate version
   ```

3. **Compile native library**:
   ```bash
   cd OneWireViewer-Linux/PDKAdapterUSB
   make
   sudo make install
   ```

4. **Configure exclusive access** (DS9490R USB only):
   ```bash
   # Unload default Linux driver
   sudo rmmod ds2490
   
   # Block driver from loading on boot
   echo "blacklist ds2490" | sudo tee /etc/modprobe.d/ds2490.conf
   
   # Reboot or apply immediately
   sudo update-initramfs -u
   ```

=== Verification

Test native library loading:
```bash
cd /usr/local/lib
ls -la *1Wire*
java -Djava.library.path=/usr/local/lib YourOpenEMSApp
```

If library not found, check LD_LIBRARY_PATH includes `/usr/local/lib`.

== Device Discovery & Configuration

=== Discovering Connected Devices

Use the getDevices() JSON-RPC method to identify all connected 1-Wire devices:

**Request via OpenEMS Backend**:
```json
{
  "method": "edgeRpc",
  "params": {
    "edgeId": "edge0",
    "payload": {
      "method": "componentJsonApi",
      "params": {
        "componentId": "onewire0",
        "payload": {
          "method": "getDevices",
          "params": {}
        }
      }
    }
  }
}
```

**Response Example**:
```json
{
  "devices": [
    {
      "address": "4D0000094xxxxxxx",
      "name": "DS18B20",
      "description": "Digital thermometer ...",
      "details": {
        "type": "TemperatureContainer",
        "temperature": 17.5625
      }
    },
    {
      "address": "6F0000022xxxxxxx",
      "name": "DS2438",
      "description": "Smart Battery Monitor ...",
      "details": {
        "type": "TemperatureContainer",
        "temperature": 19.3125
      }
    }
  ]
}
```

Use the **address** field to configure individual thermometer components (see `io.openems.edge.onewire.thermometer`).

=== Device Addresses

Each 1-Wire device has a unique 64-bit address in hexadecimal format:

* Example: `4D0000094xxxxxxx`
* Format: `FFXXXXXXXXXXXXXXXXXX` where FF is family code, X is unique serial

Store these addresses for configuring thermometer components.

https://github.com/OpenEMS/openems/tree/develop/io.openems.edge.bridge.onewire[Source Code icon:github[]]