# idfxx_onewire
1-Wire bus protocol driver.
## Features
- Typed 64-bit device address with family code extraction, ROM byte access and hex formatting
- Bus reset, ROM select, and skip ROM commands
- Single-byte and byte-buffer read/write operations accepting `uint8_t` or `std::byte` buffers,
literal byte lists and fixed-size array reads
- Parasitic power control for battery-less devices
- Device search with optional family code filtering
- Thread-safe bus access (Lockable interface)
- CRC8 and CRC16 utility functions
- Dual API: exception-based and result-based error handling
## Requirements
- ESP-IDF 5.5 or later
- C++23 compiler
## Installation
### ESP-IDF Component Manager
Add to your project's `idf_component.yml`:
```yaml
dependencies:
idfxx_onewire:
version: "^2.0.0"
```
Or add `idfxx_onewire` to the `REQUIRES` list in your component's `CMakeLists.txt`.
## Usage
### Basic Bus Operations
If `CONFIG_COMPILER_CXX_EXCEPTIONS` is enabled:
```cpp
#include <idfxx/onewire>
#include <idfxx/log>
try {
idfxx::onewire::bus bus(idfxx::gpio_4);
if (bus.reset()) {
bus.skip_rom();
bus.write(0x44); // e.g., DS18B20 Convert T command
}
// Read each DS18B20's 9-byte scratchpad and verify its CRC
for (auto addr : bus.search(0x28)) {
if (!bus.reset()) {
continue;
}
bus.select(addr);
bus.write(0xBE); // Read Scratchpad
auto scratchpad = bus.read<9>();
if (idfxx::onewire::crc8({scratchpad.data(), 8}) != scratchpad[8]) {
idfxx::log::warn("OW", "{}: scratchpad CRC mismatch", addr);
}
}
} catch (const std::system_error& e) {
idfxx::log::error("OW", "Error: {}", e.what());
}
```
### Device Search
```cpp
#include <idfxx/onewire>
#include <idfxx/log>
try {
idfxx::onewire::bus bus(idfxx::gpio_4);
// Find all devices
auto devices = bus.search();
idfxx::log::info("OW", "Found {} devices", devices.size());
for (auto& addr : devices) {
idfxx::log::info("OW", " {}", addr);
}
// Find only DS18B20 devices (family code 0x28)
auto sensors = bus.search(0x28);
} catch (const std::system_error& e) {
idfxx::log::error("OW", "Error: {}", e.what());
}
```
### Result-based API
If `CONFIG_COMPILER_CXX_EXCEPTIONS` is *not* enabled, the result-based API must be used:
```cpp
#include <idfxx/onewire>
#include <idfxx/log>
auto bus_result = idfxx::onewire::bus::make(idfxx::gpio_4);
if (!bus_result) {
idfxx::log::error("OW", "Failed to create bus: {}", bus_result.error().message());
return;
}
auto& bus = *bus_result;
if (bus.reset()) {
auto result = bus.try_skip_rom();
if (!result) {
idfxx::log::error("OW", "Skip ROM failed: {}", result.error().message());
return;
}
auto write_result = bus.try_write(0x44);
if (!write_result) {
idfxx::log::error("OW", "Write failed: {}", write_result.error().message());
}
}
```
### Thread-Safe Access
The bus satisfies the C++ Lockable named requirement:
```cpp
#include <idfxx/onewire>
#include <mutex>
idfxx::onewire::bus bus(idfxx::gpio_4);
{
std::lock_guard<idfxx::onewire::bus> lock(bus);
// Exclusive access to the bus
if (bus.reset()) {
bus.skip_rom();
bus.write(0x44);
}
}
```
## API Overview
### Types
- `address` - Typed 64-bit 1-Wire ROM address with family code extraction
- `bus` - 1-Wire bus controller with thread-safe access
### `address`
- `address()` - Default construction (equivalent to `any()`)
- `address(uint64_t)` - Construction from raw 64-bit value
- `address(std::array<uint8_t, 8>)` - Construction from the 8 ROM bytes (family code first)
- `any()` - Wildcard address for single-device buses
- `none()` - Invalid sentinel address
- `raw()` - Underlying 64-bit value
- `bytes()` - The 8 ROM bytes in bus transmit order: family code, serial number, CRC
- `family()` - Family code (low byte)
### `bus`
**Creation:**
- `bus(pin)` - Constructor (exception-based, if enabled)
- `make(pin)` - Create bus (result-based)
**Bus Control:**
- `reset()` - 1-Wire reset cycle (returns true if device present)
**ROM Commands:**
- `select(addr)` / `try_select(addr)` - Select specific device
- `skip_rom()` / `try_skip_rom()` - Select all devices
**Data Transfer:**
- `write(byte)` / `try_write(byte)` - Write a single byte, e.g. `write(0x44)`
- `write(data)` / `try_write(data)` - Write a byte buffer (`uint8_t` or `std::byte` range, or
`{ptr, len}`)
- `write({...})` / `try_write({...})` - Write literal bytes, e.g. `write({0xCC, 0x44})`
- `read()` / `try_read()` - Read a single byte
- `read<N>()` / `try_read<N>()` - Read `N` bytes into a returned `std::array<uint8_t, N>`
- `read(buf)` / `try_read(buf)` - Fill a writable byte buffer
**Power:**
- `power()` / `try_power()` - Drive bus high for parasitic power
- `depower()` - Release bus (always succeeds)
**Search:**
- `search(max)` / `try_search(max)` - Find all devices
- `search(family, max)` / `try_search(family, max)` - Find by family code
### Free Functions
- `crc8(data)` - Compute 8-bit CRC of a byte buffer
- `crc16(data, iv)` - Compute 16-bit CRC of a byte buffer
- `check_crc16(data, crc, iv)` - Verify 16-bit CRC; `crc` is a byte view that must be exactly 2 bytes
## Error Handling
- **Dual API Pattern**: The component provides both result-based and exception-based APIs
- `try_*` methods return `idfxx::result<T>` (always available)
- Methods without `try_` prefix throw `std::system_error` (requires
`CONFIG_COMPILER_CXX_EXCEPTIONS`)
## Important Notes
- **Wiring**: 1-Wire devices require a 4.7k pull-up resistor on the data line
- **Reset first**: Always call `reset()` before issuing ROM commands
- **Single-device buses**: Use `address::any()` or `skip_rom()` to skip ROM matching
- **Parasitic power**: Call `power()` after write commands when devices need extra power; `reset()`
automatically depowers
- **Thread safety**: All bus operations acquire the internal mutex; use `std::lock_guard` for
multi-operation sequences
## License
Apache License 2.0 - see [LICENSE](LICENSE) for details.
57caa7b2aabd577aa3ac24211bda868e980767b0
idf.py add-dependency "cleishm/idfxx_onewire^2.0.0"