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 <cassert>
#include <chrono>
#include <frequency/frequency>
#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
 
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));
    }
 
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;
 
    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;       
        bool addr_10bit = false;        
        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<typename Rep, typename Period>
    void transmit(std::span<const uint8_t> data, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_transmit(data, 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<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);
    }
 
    [[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
    [[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_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;
};
 
 
} // 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