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 <chrono>
#include <frequency/frequency>
#include <memory>
#include <mutex>
#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
};
 
class master_bus {
public:
    [[nodiscard]] static result<std::unique_ptr<master_bus>>
    make(enum port port, gpio sda, gpio scl, freq::hertz frequency);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit master_bus(enum port port, gpio sda, gpio scl, freq::hertz frequency);
#endif
 
    ~master_bus();
 
    master_bus(const master_bus&) = delete;
    master_bus& operator=(const master_bus&) = delete;
    master_bus(master_bus&&) = delete;
    master_bus& operator=(master_bus&&) = delete;
 
    void lock() const { _mux.lock(); }
 
    [[nodiscard]] bool try_lock() const noexcept { return _mux.try_lock(); }
 
    void unlock() const { _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(uint8_t address) const { probe(address, DEFAULT_TIMEOUT); }
 
    template<typename Rep, typename Period>
    void probe(uint8_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(uint8_t address) const { return try_probe(address, DEFAULT_TIMEOUT); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_probe(uint8_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);
 
    [[nodiscard]] std::vector<uint8_t> _scan_devices(std::chrono::milliseconds timeout) const;
    [[nodiscard]] result<void> _probe(uint8_t address, std::chrono::milliseconds timeout) const;
 
    mutable std::recursive_mutex _mux;
    i2c_master_bus_handle_t _handle;
    enum port _port;
    freq::hertz _frequency;
};
 
class master_device {
public:
    [[nodiscard]] static result<std::unique_ptr<master_device>> make(std::shared_ptr<master_bus> bus, uint8_t address);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit master_device(std::shared_ptr<master_bus> bus, uint8_t address);
#endif
 
    ~master_device();
 
    master_device(const master_device&) = delete;
    master_device& operator=(const master_device&) = delete;
    master_device(master_device&&) = delete;
    master_device& operator=(master_device&&) = delete;
 
    [[nodiscard]] const std::shared_ptr<master_bus>& bus() const { return _bus; }
 
    [[nodiscard]] i2c_master_dev_handle_t handle() const { return _handle; }
 
    [[nodiscard]] uint8_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 {
        _bus->probe(_address, std::chrono::ceil<std::chrono::milliseconds>(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 {
        return _bus->try_probe(_address, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void transmit(const std::vector<uint8_t> data) { unwrap(try_transmit(data)); }
 
    template<typename Rep, typename Period>
    void transmit(const std::vector<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(const std::vector<uint8_t> data) {
        return try_transmit(data, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_transmit(const std::vector<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::vector<uint8_t> buf) { unwrap(try_receive(buf)); }
 
    template<typename Rep, typename Period>
    void receive(std::vector<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::vector<uint8_t> buf) { return try_receive(buf, DEFAULT_TIMEOUT); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void>
    try_receive(std::vector<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, const std::vector<uint8_t> buf) { unwrap(try_write_register(reg, buf)); }
 
    template<typename Rep, typename Period>
    void
    write_register(uint16_t reg, const std::vector<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, const std::vector<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,
        const std::vector<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 regHigh, uint8_t regLow, const std::vector<uint8_t> buf) {
        unwrap(try_write_register(regHigh, regLow, buf));
    }
 
    template<typename Rep, typename Period>
    void write_register(
        uint8_t regHigh,
        uint8_t regLow,
        const std::vector<uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        unwrap(try_write_register(regHigh, regLow, buf, timeout));
    }
 
    void write_register(uint8_t regHigh, uint8_t regLow, const uint8_t* buf, size_t size) {
        unwrap(try_write_register(regHigh, regLow, buf, size));
    }
 
    template<typename Rep, typename Period>
    void write_register(
        uint8_t regHigh,
        uint8_t regLow,
        const uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        unwrap(try_write_register(regHigh, regLow, buf, size, timeout));
    }
#endif
 
    [[nodiscard]] result<void> try_write_register(uint8_t regHigh, uint8_t regLow, const std::vector<uint8_t> buf) {
        return try_write_register(regHigh, regLow, buf, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_write_register(
        uint8_t regHigh,
        uint8_t regLow,
        const std::vector<uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return try_write_register(regHigh, regLow, buf.data(), buf.size(), timeout);
    }
 
    [[nodiscard]] result<void> try_write_register(uint8_t regHigh, uint8_t regLow, const uint8_t* buf, size_t size) {
        return try_write_register(regHigh, regLow, buf, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_write_register(
        uint8_t regHigh,
        uint8_t regLow,
        const uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return _try_write_register(regHigh, regLow, buf, size, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void write_registers(std::vector<uint16_t> registers, const std::vector<uint8_t> buf) {
        unwrap(try_write_registers(registers, buf));
    }
 
    template<typename Rep, typename Period>
    void write_registers(
        std::vector<uint16_t> registers,
        const std::vector<uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        unwrap(try_write_registers(registers, buf, timeout));
    }
 
    void write_registers(std::vector<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::vector<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));
    }
#endif
 
    [[nodiscard]] result<void> try_write_registers(std::vector<uint16_t> registers, const std::vector<uint8_t> buf) {
        return try_write_registers(registers, buf, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_write_registers(
        std::vector<uint16_t> registers,
        const std::vector<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::vector<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::vector<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));
    }
 
#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::vector<uint8_t> buf) { unwrap(try_read_register(reg, buf)); }
 
    template<typename Rep, typename Period>
    void read_register(uint16_t reg, std::vector<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::vector<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::vector<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 regHigh, uint8_t regLow, size_t size) {
        return unwrap(try_read_register(regHigh, regLow, size));
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] std::vector<uint8_t>
    read_register(uint8_t regHigh, uint8_t regLow, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_read_register(regHigh, regLow, size, timeout));
    }
 
    void read_register(uint8_t regHigh, uint8_t regLow, uint8_t* buf, size_t size) {
        unwrap(try_read_register(regHigh, regLow, buf, size));
    }
 
    template<typename Rep, typename Period>
    void read_register(
        uint8_t regHigh,
        uint8_t regLow,
        uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        unwrap(try_read_register(regHigh, regLow, buf, size, timeout));
    }
#endif
 
    [[nodiscard]] result<std::vector<uint8_t>> try_read_register(uint8_t regHigh, uint8_t regLow, size_t size) {
        return try_read_register(regHigh, regLow, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<std::vector<uint8_t>>
    try_read_register(uint8_t regHigh, uint8_t regLow, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        std::vector<uint8_t> buf(size);
        return try_read_register(regHigh, regLow, buf, timeout).transform([&]() { return buf; });
    }
 
    [[nodiscard]] result<void> try_read_register(uint8_t regHigh, uint8_t regLow, std::vector<uint8_t> buf) {
        return try_read_register(regHigh, regLow, buf, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_read_register(
        uint8_t regHigh,
        uint8_t regLow,
        std::vector<uint8_t> buf,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return try_read_register(regHigh, regLow, buf.data(), buf.size(), timeout);
    }
 
    [[nodiscard]] result<void> try_read_register(uint8_t regHigh, uint8_t regLow, uint8_t* buf, size_t size) {
        return try_read_register(regHigh, regLow, buf, size, DEFAULT_TIMEOUT);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_read_register(
        uint8_t regHigh,
        uint8_t regLow,
        uint8_t* buf,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return _try_read_register(regHigh, regLow, buf, size, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
private:
    explicit master_device(std::shared_ptr<master_bus> bus, i2c_master_dev_handle_t handle, uint8_t address);
 
    [[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 regHigh,
        uint8_t regLow,
        const uint8_t* buf,
        size_t size,
        std::chrono::milliseconds timeout
    );
    [[nodiscard]] result<void> _try_write_registers(
        std::vector<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 regHigh, uint8_t regLow, uint8_t* buf, size_t size, std::chrono::milliseconds timeout);
 
    std::shared_ptr<master_bus> _bus;
    i2c_master_dev_handle_t _handle;
    uint8_t _address;
};
 
 
} // 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