master.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/error>
#include <idfxx/gpio>
#include <idfxx/intr_alloc>
 
#include <array>
#include <cassert>
#include <chrono>
#include <concepts>
#include <frequency/frequency>
#include <functional>
#include <initializer_list>
#include <memory>
#include <mutex>
#include <optional>
#include <span>
#include <string>
#include <vector>
 
typedef struct i2c_master_bus_t* i2c_master_bus_handle_t;
typedef struct i2c_master_dev_t* i2c_master_dev_handle_t;
 
namespace idfxx::i2c {
 
static constexpr auto DEFAULT_TIMEOUT = std::chrono::milliseconds(50);
 
enum class port : int {
    i2c0 = 0, 
#if SOC_HP_I2C_NUM >= 2
    i2c1 = 1, 
#endif
#if SOC_LP_I2C_NUM >= 1
    lp_i2c0 = 2, 
#endif
};
 
// Clock source enums use sequential values rather than matching the ESP-IDF
// constants directly, since the underlying SOC_MOD_CLK_* values differ per
// target. Conversion to ESP-IDF types is done in the implementation.
 
enum class clk_source : int {
    default_source = 0, 
#if SOC_I2C_SUPPORT_APB
    apb, 
#endif
#if SOC_I2C_SUPPORT_REF_TICK
    ref_tick, 
#endif
#if SOC_I2C_SUPPORT_XTAL
    xtal, 
#endif
#if SOC_I2C_SUPPORT_RTC
    rc_fast, 
#endif
};
 
#if SOC_LP_I2C_SUPPORTED
enum class lp_clk_source : int {
    default_source = 0, 
    lp_fast,            
    xtal_d2,            
};
#endif
 
enum class operation_command : int {
    start = 0, 
    write = 1, 
    read = 2,  
    stop = 3,  
};
 
enum class ack_value : uint8_t {
    ack = 0,  
    nack = 1, 
};
 
struct operation {
    operation_command command;           
    bool ack_check = true;               
    std::span<const uint8_t> write_data; 
    std::span<uint8_t> read_data;        
    ack_value ack_type = ack_value::ack; 
};
 
class master_bus {
public:
    struct config {
        idfxx::gpio sda = gpio::nc();                            
        idfxx::gpio scl = gpio::nc();                            
        freq::hertz frequency{0};                                
        enum clk_source clk_source = clk_source::default_source; 
#if SOC_LP_I2C_SUPPORTED
        enum lp_clk_source lp_source_clk = lp_clk_source::default_source; 
#endif
        uint8_t glitch_ignore_cnt = 7; 
        std::optional<idfxx::intr_level> intr_level = {}; 
        size_t trans_queue_depth = 0;       
        bool enable_internal_pullup = true; 
        bool allow_pd = false;              
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit master_bus(enum port port, const struct config& config);
 
    [[nodiscard]] explicit master_bus(enum port port, gpio sda, gpio scl, freq::hertz frequency);
#endif
 
    [[nodiscard]] static result<master_bus> make(enum port port, const struct config& config);
 
    [[nodiscard]] static result<master_bus> make(enum port port, gpio sda, gpio scl, freq::hertz frequency);
 
    ~master_bus();
 
    master_bus(const master_bus&) = delete;
    master_bus& operator=(const master_bus&) = delete;
    master_bus(master_bus&& other) noexcept;
    master_bus& operator=(master_bus&& other) noexcept;
 
    void lock() const {
        if (!_mux) {
            return;
        }
        _mux->lock();
    }
 
    [[nodiscard]] bool try_lock() const noexcept {
        if (!_mux) {
            return false;
        }
        return _mux->try_lock();
    }
 
    void unlock() const {
        if (!_mux) {
            return;
        }
        _mux->unlock();
    }
 
    [[nodiscard]] i2c_master_bus_handle_t handle() const { return _handle; }
 
    [[nodiscard]] enum port port() const { return _port; }
 
    [[nodiscard]] freq::hertz frequency() const { return _frequency; }
 
    [[nodiscard]] std::vector<uint8_t> scan_devices() const { return scan_devices(DEFAULT_TIMEOUT); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] std::vector<uint8_t> scan_devices(const std::chrono::duration<Rep, Period>& timeout) const {
        return _scan_devices(std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void probe(uint16_t address) const { probe(address, DEFAULT_TIMEOUT); }
 
    template<typename Rep, typename Period>
    void probe(uint16_t address, const std::chrono::duration<Rep, Period>& timeout) const {
        unwrap(_probe(address, std::chrono::ceil<std::chrono::milliseconds>(timeout)));
    }
#endif
 
    [[nodiscard]] result<void> try_probe(uint16_t address) const { return try_probe(address, DEFAULT_TIMEOUT); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_probe(uint16_t address, const std::chrono::duration<Rep, Period>& timeout) const {
        return _probe(address, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename Rep, typename Period>
    void wait_all_done(const std::chrono::duration<Rep, Period>& timeout) const {
        unwrap(try_wait_all_done(timeout));
    }
#endif
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_wait_all_done(const std::chrono::duration<Rep, Period>& timeout) const {
        return _try_wait_all_done(std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
private:
    explicit master_bus(i2c_master_bus_handle_t handle, enum port port, freq::hertz frequency);
 
    void _delete() noexcept;
 
    [[nodiscard]] std::vector<uint8_t> _scan_devices(std::chrono::milliseconds timeout) const;
    [[nodiscard]] result<void> _probe(uint16_t address, std::chrono::milliseconds timeout) const;
    [[nodiscard]] result<void> _try_wait_all_done(std::chrono::milliseconds timeout) const;
 
    mutable std::unique_ptr<std::recursive_mutex> _mux;
    i2c_master_bus_handle_t _handle = nullptr;
    enum port _port;
    freq::hertz _frequency;
};
 
class master_device {
public:
    struct config {
        freq::hertz scl_speed{0}; 
        uint32_t scl_wait_us = 0; 
#if SOC_I2C_SUPPORT_10BIT_ADDR
        bool addr_10bit = false; 
#endif
        bool disable_ack_check = false; 
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit master_device(master_bus& bus, uint16_t address, const struct config& config);
 
    [[nodiscard]] explicit master_device(master_bus& bus, uint16_t address);
#endif
 
    [[nodiscard]] static result<master_device> make(master_bus& bus, uint16_t address, const struct config& config);
 
    [[nodiscard]] static result<master_device> make(master_bus& bus, uint16_t address);
 
    ~master_device();
 
    master_device(const master_device&) = delete;
    master_device& operator=(const master_device&) = delete;
    master_device(master_device&& other) noexcept;
    master_device& operator=(master_device&& other) noexcept;
 
    [[nodiscard]] master_bus& bus() const {
        assert(_bus != nullptr);
        return *_bus;
    }
 
    [[nodiscard]] i2c_master_dev_handle_t handle() const { return _handle; }
 
    [[nodiscard]] uint16_t address() const { return _address; }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void probe() const { probe(DEFAULT_TIMEOUT); }
 
    template<typename Rep, typename Period>
    void probe(const std::chrono::duration<Rep, Period>& timeout) const {
        unwrap(try_probe(timeout));
    }
#endif
 
    [[nodiscard]] result<void> try_probe() const { return try_probe(DEFAULT_TIMEOUT); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_probe(const std::chrono::duration<Rep, Period>& timeout) const {
        if (_handle == nullptr) {
            return error(errc::invalid_state);
        }
        return _bus->try_probe(_address, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void transmit(std::span<const uint8_t> data) { unwrap(try_transmit(data)); }
 
    template<std::convertible_to<std::span<const uint8_t>>... Buffers>
        requires(sizeof...(Buffers) > 1)
    void transmit(Buffers... buffers) {
        unwrap(try_transmit(buffers...));
    }
 
    void transmit(std::span<const std::span<const uint8_t>> buffers) { unwrap(try_transmit(buffers)); }
 
    template<typename Rep, typename Period>
    void transmit(std::span<const uint8_t> data, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_transmit(data, timeout));
    }
 
    template<typename Rep, typename Period>
    void
    transmit(std::span<const std::span<const uint8_t>> buffers, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_transmit(buffers, timeout));
    }
 
    void transmit(const uint8_t* buf, size_t size) { unwrap(try_transmit(buf, size)); }
 
    template<typename Rep, typename Period>
    void transmit(const uint8_t* buf, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_transmit(buf, size, timeout));
    }
#endif
 
    [[nodiscard]] result<void> try_transmit(std::span<const uint8_t> data) {
        return try_transmit(data, DEFAULT_TIMEOUT);
    }
 
    template<std::convertible_to<std::span<const uint8_t>>... Buffers>
        requires(sizeof...(Buffers) > 1)
    [[nodiscard]] result<void> try_transmit(Buffers... buffers) {
        std::array<std::span<const uint8_t>, sizeof...(Buffers)> arr{buffers...};
        return try_transmit(std::span<const std::span<const uint8_t>>{arr});
    }
 
    [[nodiscard]] result<void> try_transmit(std::span<const std::span<const uint8_t>> buffers) {
        return try_transmit(buffers, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_transmit(std::span<const uint8_t> data, const std::chrono::duration<Rep, Period>& timeout) {
        return try_transmit(data.data(), data.size(), timeout);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_transmit(std::span<const std::span<const uint8_t>> buffers, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_multi_buffer_transmit(buffers, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
    [[nodiscard]] result<void> try_transmit(const uint8_t* buf, size_t size) {
        return try_transmit(buf, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_transmit(const uint8_t* buf, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_transmit(buf, size, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void change_address(uint16_t new_address) { unwrap(try_change_address(new_address)); }
 
    template<typename Rep, typename Period>
    void change_address(uint16_t new_address, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_change_address(new_address, timeout));
    }
#endif
 
    [[nodiscard]] result<void> try_change_address(uint16_t new_address) {
        return try_change_address(new_address, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_change_address(uint16_t new_address, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_change_address(new_address, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void register_event_callbacks(std::move_only_function<bool() const> on_trans_done) {
        unwrap(try_register_event_callbacks(std::move(on_trans_done)));
    }
#endif
 
    [[nodiscard]] result<void> try_register_event_callbacks(std::move_only_function<bool() const> on_trans_done);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void execute_operations(std::span<const operation> ops) { unwrap(try_execute_operations(ops)); }
 
    template<typename Rep, typename Period>
    void execute_operations(std::span<const operation> ops, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_execute_operations(ops, timeout));
    }
#endif
 
    [[nodiscard]] result<void> try_execute_operations(std::span<const operation> ops) {
        return try_execute_operations(ops, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_execute_operations(std::span<const operation> ops, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_execute_operations(ops, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] std::vector<uint8_t> receive(size_t size) { return unwrap(try_receive(size)); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] std::vector<uint8_t> receive(size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_receive(size, timeout));
    }
 
    void receive(uint8_t* buf, size_t size) { unwrap(try_receive(buf, size)); }
 
    template<typename Rep, typename Period>
    void receive(uint8_t* buf, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_receive(buf, size, timeout));
    }
 
    void receive(std::span<uint8_t> buf) { unwrap(try_receive(buf)); }
 
    template<typename Rep, typename Period>
    void receive(std::span<uint8_t> buf, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_receive(buf, timeout));
    }
#endif
 
    [[nodiscard]] result<std::vector<uint8_t>> try_receive(size_t size) { return try_receive(size, DEFAULT_TIMEOUT); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<std::vector<uint8_t>>
    try_receive(size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        std::vector<uint8_t> buf(size);
        return try_receive(buf, timeout).transform([&]() { return buf; });
    }
 
    [[nodiscard]] result<void> try_receive(uint8_t* buf, size_t size) {
        return try_receive(buf, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_receive(uint8_t* buf, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_receive(buf, size, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
    [[nodiscard]] result<void> try_receive(std::span<uint8_t> buf) { return try_receive(buf, DEFAULT_TIMEOUT); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_receive(std::span<uint8_t> buf, const std::chrono::duration<Rep, Period>& timeout) {
        return try_receive(buf.data(), buf.size(), timeout);
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void write_register(uint16_t reg, std::span<const uint8_t> buf) { unwrap(try_write_register(reg, buf)); }
 
    template<typename Rep, typename Period>
    void write_register(uint16_t reg, std::span<const uint8_t> buf, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_write_register(reg, buf, timeout));
    }
 
    void write_register(uint16_t reg, const uint8_t* buf, size_t size) { unwrap(try_write_register(reg, buf, size)); }
 
    template<typename Rep, typename Period>
    void
    write_register(uint16_t reg, const uint8_t* buf, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_write_register(reg, buf, size, timeout));
    }
#endif
 
    [[nodiscard]] result<void> try_write_register(uint16_t reg, std::span<const uint8_t> buf) {
        return try_write_register(reg, buf.data(), buf.size(), DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_write_register(uint16_t reg, std::span<const uint8_t> buf, const std::chrono::duration<Rep, Period>& timeout) {
        return try_write_register(reg, buf.data(), buf.size(), timeout);
    }
 
    [[nodiscard]] result<void> try_write_register(uint16_t reg, const uint8_t* buf, size_t size) {
        return try_write_register(reg, buf, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_write_register(
        uint16_t reg,
        const uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return _try_write_register(reg, buf, size, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void write_register(uint8_t high, uint8_t low, std::span<const uint8_t> buf) {
        unwrap(try_write_register(high, low, buf));
    }
 
    template<typename Rep, typename Period>
    void write_register(
        uint8_t high,
        uint8_t low,
        std::span<const uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        unwrap(try_write_register(high, low, buf, timeout));
    }
 
    void write_register(uint8_t high, uint8_t low, const uint8_t* buf, size_t size) {
        unwrap(try_write_register(high, low, buf, size));
    }
 
    template<typename Rep, typename Period>
    void write_register(
        uint8_t high,
        uint8_t low,
        const uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        unwrap(try_write_register(high, low, buf, size, timeout));
    }
#endif
 
    [[nodiscard]] result<void> try_write_register(uint8_t high, uint8_t low, std::span<const uint8_t> buf) {
        return try_write_register(high, low, buf, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_write_register(
        uint8_t high,
        uint8_t low,
        std::span<const uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return try_write_register(high, low, buf.data(), buf.size(), timeout);
    }
 
    [[nodiscard]] result<void> try_write_register(uint8_t high, uint8_t low, const uint8_t* buf, size_t size) {
        return try_write_register(high, low, buf, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_write_register(
        uint8_t high,
        uint8_t low,
        const uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return _try_write_register(high, low, buf, size, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void write_registers(std::span<const uint16_t> registers, std::span<const uint8_t> buf) {
        unwrap(try_write_registers(registers, buf));
    }
 
    template<typename Rep, typename Period>
    void write_registers(
        std::span<const uint16_t> registers,
        std::span<const uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        unwrap(try_write_registers(registers, buf, timeout));
    }
 
    void write_registers(std::span<const uint16_t> registers, const uint8_t* buf, size_t size) {
        unwrap(try_write_registers(registers, buf, size));
    }
 
    template<typename Rep, typename Period>
    void write_registers(
        std::span<const uint16_t> registers,
        const uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        unwrap(try_write_registers(registers, buf, size, timeout));
    }
 
    // C++23: std::span cannot be constructed from a braced initializer list until C++26 (P2447).
    // Remove these overloads when C++26 becomes the minimum standard.
 
    void write_registers(std::initializer_list<uint16_t> registers, std::span<const uint8_t> buf) {
        write_registers(std::span<const uint16_t>{registers.begin(), registers.size()}, buf);
    }
 
    template<typename Rep, typename Period>
    void write_registers(
        std::initializer_list<uint16_t> registers,
        std::span<const uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        write_registers(std::span<const uint16_t>{registers.begin(), registers.size()}, buf, timeout);
    }
 
    void write_registers(std::initializer_list<uint16_t> registers, const uint8_t* buf, size_t size) {
        write_registers(std::span<const uint16_t>{registers.begin(), registers.size()}, buf, size);
    }
 
    template<typename Rep, typename Period>
    void write_registers(
        std::initializer_list<uint16_t> registers,
        const uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        write_registers(std::span<const uint16_t>{registers.begin(), registers.size()}, buf, size, timeout);
    }
#endif
 
    [[nodiscard]] result<void> try_write_registers(std::span<const uint16_t> registers, std::span<const uint8_t> buf) {
        return try_write_registers(registers, buf, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_write_registers(
        std::span<const uint16_t> registers,
        std::span<const uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return try_write_registers(registers, buf.data(), buf.size(), timeout);
    }
 
    [[nodiscard]] result<void>
    try_write_registers(std::span<const uint16_t> registers, const uint8_t* buf, size_t size) {
        return try_write_registers(registers, buf, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_write_registers(
        std::span<const uint16_t> registers,
        const uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return _try_write_registers(registers, buf, size, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
    // C++23: std::span cannot be constructed from a braced initializer list until C++26 (P2447).
    // Remove these overloads when C++26 becomes the minimum standard.
 
    [[nodiscard]] result<void>
    try_write_registers(std::initializer_list<uint16_t> registers, std::span<const uint8_t> buf) {
        return try_write_registers(std::span<const uint16_t>{registers.begin(), registers.size()}, buf);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_write_registers(
        std::initializer_list<uint16_t> registers,
        std::span<const uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return try_write_registers(std::span<const uint16_t>{registers.begin(), registers.size()}, buf, timeout);
    }
 
    [[nodiscard]] result<void>
    try_write_registers(std::initializer_list<uint16_t> registers, const uint8_t* buf, size_t size) {
        return try_write_registers(std::span<const uint16_t>{registers.begin(), registers.size()}, buf, size);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_write_registers(
        std::initializer_list<uint16_t> registers,
        const uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return try_write_registers(std::span<const uint16_t>{registers.begin(), registers.size()}, buf, size, timeout);
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] std::vector<uint8_t> read_register(uint16_t reg, size_t size) {
        return unwrap(try_read_register(reg, size));
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] std::vector<uint8_t>
    read_register(uint16_t reg, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_read_register(reg, size, timeout));
    }
 
    void read_register(uint16_t reg, std::span<uint8_t> buf) { unwrap(try_read_register(reg, buf)); }
 
    template<typename Rep, typename Period>
    void read_register(uint16_t reg, std::span<uint8_t> buf, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_read_register(reg, buf, timeout));
    }
 
    void read_register(uint16_t reg, uint8_t* buf, size_t size) { unwrap(try_read_register(reg, buf, size)); }
 
    template<typename Rep, typename Period>
    void read_register(uint16_t reg, uint8_t* buf, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_read_register(reg, buf, size, timeout));
    }
#endif
 
    [[nodiscard]] result<std::vector<uint8_t>> try_read_register(uint16_t reg, size_t size) {
        return try_read_register(reg, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<std::vector<uint8_t>>
    try_read_register(uint16_t reg, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        std::vector<uint8_t> buf(size);
        return try_read_register(reg, buf, timeout).transform([&]() { return buf; });
    }
 
    [[nodiscard]] result<void> try_read_register(uint16_t reg, std::span<uint8_t> buf) {
        return try_read_register(reg, buf, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_read_register(uint16_t reg, std::span<uint8_t> buf, const std::chrono::duration<Rep, Period>& timeout) {
        return try_read_register(reg, buf.data(), buf.size(), timeout);
    }
 
    [[nodiscard]] result<void> try_read_register(uint16_t reg, uint8_t* buf, size_t size) {
        return try_read_register(reg, buf, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_read_register(uint16_t reg, uint8_t* buf, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_read_register(reg, buf, size, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] std::vector<uint8_t> read_register(uint8_t high, uint8_t low, size_t size) {
        return unwrap(try_read_register(high, low, size));
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] std::vector<uint8_t>
    read_register(uint8_t high, uint8_t low, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_read_register(high, low, size, timeout));
    }
 
    void read_register(uint8_t high, uint8_t low, uint8_t* buf, size_t size) {
        unwrap(try_read_register(high, low, buf, size));
    }
 
    template<typename Rep, typename Period>
    void read_register(
        uint8_t high,
        uint8_t low,
        uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        unwrap(try_read_register(high, low, buf, size, timeout));
    }
#endif
 
    [[nodiscard]] result<std::vector<uint8_t>> try_read_register(uint8_t high, uint8_t low, size_t size) {
        return try_read_register(high, low, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<std::vector<uint8_t>>
    try_read_register(uint8_t high, uint8_t low, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        std::vector<uint8_t> buf(size);
        return try_read_register(high, low, buf, timeout).transform([&]() { return buf; });
    }
 
    [[nodiscard]] result<void> try_read_register(uint8_t high, uint8_t low, std::span<uint8_t> buf) {
        return try_read_register(high, low, buf, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_read_register(
        uint8_t high,
        uint8_t low,
        std::span<uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return try_read_register(high, low, buf.data(), buf.size(), timeout);
    }
 
    [[nodiscard]] result<void> try_read_register(uint8_t high, uint8_t low, uint8_t* buf, size_t size) {
        return try_read_register(high, low, buf, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_read_register(
        uint8_t high,
        uint8_t low,
        uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return _try_read_register(high, low, buf, size, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
private:
    explicit master_device(master_bus* bus, i2c_master_dev_handle_t handle, uint16_t address);
 
    void _delete() noexcept;
 
    [[nodiscard]] result<void> _try_transmit(const uint8_t* buf, size_t size, std::chrono::milliseconds timeout);
    [[nodiscard]] result<void>
    _try_multi_buffer_transmit(std::span<const std::span<const uint8_t>> buffers, std::chrono::milliseconds timeout);
    [[nodiscard]] result<void> _try_change_address(uint16_t new_address, std::chrono::milliseconds timeout);
    [[nodiscard]] result<void>
    _try_execute_operations(std::span<const operation> ops, std::chrono::milliseconds timeout);
    [[nodiscard]] result<void> _try_receive(uint8_t* buf, size_t size, std::chrono::milliseconds timeout);
 
    [[nodiscard]] result<void>
    _try_write_register(uint16_t reg, const uint8_t* buf, size_t size, std::chrono::milliseconds timeout);
    [[nodiscard]] result<void>
    _try_write_register(uint8_t high, uint8_t low, const uint8_t* buf, size_t size, std::chrono::milliseconds timeout);
    [[nodiscard]] result<void> _try_write_registers(
        std::span<const uint16_t> registers,
        const uint8_t* buf,
        size_t size,
        std::chrono::milliseconds timeout
    );
    [[nodiscard]] result<void>
    _try_read_register(uint16_t reg, uint8_t* buf, size_t size, std::chrono::milliseconds timeout);
    [[nodiscard]] result<void>
    _try_read_register(uint8_t high, uint8_t low, uint8_t* buf, size_t size, std::chrono::milliseconds timeout);
 
    master_bus* _bus = nullptr;
    i2c_master_dev_handle_t _handle = nullptr;
    uint16_t _address = 0;
    std::unique_ptr<std::move_only_function<bool() const>> _on_trans_done;
};
 
 
} // namespace idfxx::i2c
 
namespace idfxx {
 
[[nodiscard]] inline std::string to_string(i2c::port p) {
    switch (p) {
    case i2c::port::i2c0:
        return "I2C0";
#if SOC_HP_I2C_NUM >= 2
    case i2c::port::i2c1:
        return "I2C1";
#endif
#if SOC_LP_I2C_NUM >= 1
    case i2c::port::lp_i2c0:
        return "LP_I2C0";
#endif
    default:
        return "unknown(" + std::to_string(static_cast<int>(p)) + ")";
    }
}
 
} // namespace idfxx
 
#include "sdkconfig.h"
#ifdef CONFIG_IDFXX_STD_FORMAT
#include <algorithm>
#include <format>
namespace std {
template<>
struct formatter<idfxx::i2c::port> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::i2c::port p, FormatContext& ctx) const {
        auto s = idfxx::to_string(p);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
} // namespace std
#endif // CONFIG_IDFXX_STD_FORMAT