m5_unit_unified_wiring.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2024 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_UNIFIED_WIRING_HPP
#define M5_UNIT_UNIFIED_WIRING_HPP
 
#include "../M5UnitUnified.hpp"  // core (UnitUnified / Component, brings in M5HAL)
#if defined(ARDUINO)
#include <Wire.h>
#include <SPI.h>
#include <HardwareSerial.h>
#elif defined(ESP_PLATFORM)  // ESP-IDF native
// driver/i2c_master.h (new I2C master driver) exists only on IDF >= 5.2. On IDF 5.0/5.1 fall back to
// the legacy driver/i2c.h so the I2C wiring helpers keep working across the whole IDF >= 5.0 range.
#if __has_include(<driver/i2c_master.h>)
#include <driver/i2c_master.h>
#else
#include <driver/i2c.h>
#endif
#include <driver/uart.h>
#include <driver/spi_master.h>
#include <hal/gpio_types.h>
#include <soc/soc_caps.h>
#endif
// NOTE: M5Unified.h / M5GFX are NOT included; caller must include them BEFORE this header.
 
#if defined(ESP_PLATFORM)
#include <esp_idf_version.h>
// Number of HP I2C controllers. SOC_HP_I2C_NUM exists from ESP-IDF 5.3; before that SOC_I2C_NUM counts HP only.
#if defined(SOC_HP_I2C_NUM)
#define M5_UNIT_UNIFIED_WIRING_HP_I2C_NUM SOC_HP_I2C_NUM
#else
#define M5_UNIT_UNIFIED_WIRING_HP_I2C_NUM SOC_I2C_NUM
#endif
// Whether Arduino-ESP32 declares Wire1 (mirrors its Wire.h):
//   2.x / 3.0: SOC_I2C_NUM > 1, 3.1: SOC_HP_I2C_NUM > 1, 3.2+ on ESP-IDF >= 5.4: SOC_I2C_NUM > 1 (LP I2C included)
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 4, 0)
#define M5_UNIT_UNIFIED_WIRING_HAS_WIRE1 (SOC_I2C_NUM > 1)
#else
#define M5_UNIT_UNIFIED_WIRING_HAS_WIRE1 (M5_UNIT_UNIFIED_WIRING_HP_I2C_NUM > 1)
#endif
// Number of HP UARTs. SOC_UART_HP_NUM exists from ESP-IDF 5.2; before that SOC_UART_NUM counts HP only.
// (SOC_UART_NUM includes the LP UART on C6 / C5 / P4, which cannot be routed to the GROVE ports.)
#if defined(SOC_UART_HP_NUM)
#define M5_UNIT_UNIFIED_WIRING_HP_UART_NUM SOC_UART_HP_NUM
#else
#define M5_UNIT_UNIFIED_WIRING_HP_UART_NUM SOC_UART_NUM
#endif
#endif
 
namespace m5 {
namespace unit {
namespace wiring {
 
enum class NessoPort { PortB, PortA };
 
enum class GpioRole {
    Both,    
    InOnly,  
    OutOnly  
};
 
enum class UartConfig : uint32_t {
    Default = 0,  
    _8N1    = 1,
    _8N2    = 2,
    _8E1    = 3,
    _8O1    = 4,
    _7N1    = 5,
    _7E1    = 6,
    _7O1    = 7,
};
 
struct I2CPins {
    int8_t sda;
    int8_t scl;
    enum class Backend : uint8_t {
        Wire,         
        SoftwareI2C,  
        ExI2C         
    } backend;
};
 
struct GpioPinPair {
    int8_t rx;
    int8_t tx;
    bool fallback_a;  
};
 
struct UartPinPair {
    int8_t rx;
    int8_t tx;
    bool fallback_a;  
};
 
struct SpiPins {
    int8_t sclk;
    int8_t miso;
    int8_t mosi;
};
 
struct HatI2CPins {
    int8_t sda;
    int8_t scl;
    bool useWire1;  
};
 
struct HatPinPair {
    int8_t rx;
    int8_t tx;
};
 
#if defined(__M5UNIFIED_HPP__)  // M5Unified.h must be included before this header
inline I2CPins i2cPins(const NessoPort nesso = NessoPort::PortB)
{
    const auto board = M5.getBoard();
    if (board == m5::board_t::board_ArduinoNessoN1) {
        if (nesso == NessoPort::PortB) {
            return {static_cast<int8_t>(M5.getPin(m5::pin_name_t::port_b_out)),
                    static_cast<int8_t>(M5.getPin(m5::pin_name_t::port_b_in)), I2CPins::Backend::SoftwareI2C};
        }
        return {static_cast<int8_t>(M5.getPin(m5::pin_name_t::port_a_sda)),
                static_cast<int8_t>(M5.getPin(m5::pin_name_t::port_a_scl)), I2CPins::Backend::Wire};
    }
    if (board == m5::board_t::board_M5NanoC6 || board == m5::board_t::board_M5NanoH2) {
        return {static_cast<int8_t>(M5.getPin(m5::pin_name_t::ex_i2c_sda)),
                static_cast<int8_t>(M5.getPin(m5::pin_name_t::ex_i2c_scl)), I2CPins::Backend::ExI2C};
    }
    // In_I2C and Ex_I2C on the same pins are one bus that M5.begin() already installed via In_I2C
    // (Core Basic/Gray/Go/Fire, ToughC5, CoreMatrix, PaperDIY...). Opening a new Wire / native master bus
    // on it would collide, so borrow M5.Ex_I2C instead (ExI2C backend -> i2cClass).
    const int8_t ex_sda = M5.getPin(m5::pin_name_t::ex_i2c_sda);
    const int8_t ex_scl = M5.getPin(m5::pin_name_t::ex_i2c_scl);
    if (ex_sda >= 0 && ex_scl >= 0 && ex_sda == M5.getPin(m5::pin_name_t::in_i2c_sda) &&
        ex_scl == M5.getPin(m5::pin_name_t::in_i2c_scl)) {
        return {ex_sda, ex_scl, I2CPins::Backend::ExI2C};
    }
    return {static_cast<int8_t>(M5.getPin(m5::pin_name_t::port_a_sda)),
            static_cast<int8_t>(M5.getPin(m5::pin_name_t::port_a_scl)), I2CPins::Backend::Wire};
}
 
inline GpioPinPair gpioPins(const GpioRole role = GpioRole::Both)
{
    int rx                = (role == GpioRole::OutOnly) ? -1 : M5.getPin(m5::pin_name_t::port_b_in);
    int tx                = (role == GpioRole::InOnly) ? -1 : M5.getPin(m5::pin_name_t::port_b_out);
    const bool need_rx_fb = (role != GpioRole::OutOnly && rx < 0);
    const bool need_tx_fb = (role != GpioRole::InOnly && tx < 0);
    bool fb               = false;
    if (need_rx_fb || need_tx_fb) {
        fb = true;
        rx = (role == GpioRole::OutOnly) ? -1 : M5.getPin(m5::pin_name_t::port_a_pin1);
        tx = (role == GpioRole::InOnly) ? -1 : M5.getPin(m5::pin_name_t::port_a_pin2);
    }
    return {static_cast<int8_t>(rx), static_cast<int8_t>(tx), fb};
}
 
inline UartPinPair uartPins()
{
    int rx  = M5.getPin(m5::pin_name_t::port_c_rxd);
    int tx  = M5.getPin(m5::pin_name_t::port_c_txd);
    bool fb = false;
    if (rx < 0 || tx < 0) {
        fb = true;
        rx = M5.getPin(m5::pin_name_t::port_a_pin1);
        tx = M5.getPin(m5::pin_name_t::port_a_pin2);
    }
    return {static_cast<int8_t>(rx), static_cast<int8_t>(tx), fb};
}
 
inline SpiPins spiPins()
{
    return {static_cast<int8_t>(M5.getPin(m5::pin_name_t::sd_spi_sclk)),
            static_cast<int8_t>(M5.getPin(m5::pin_name_t::sd_spi_miso)),
            static_cast<int8_t>(M5.getPin(m5::pin_name_t::sd_spi_mosi))};
}
 
inline HatI2CPins hatI2CPins()
{
    const auto board = M5.getBoard();
    switch (board) {
        case m5::board_t::board_M5StickC:
        case m5::board_t::board_M5StickCPlus:
        case m5::board_t::board_M5StickCPlus2:
            return {0, 26, false};
        case m5::board_t::board_M5StickS3:
            // SCL is GPIO0 (strapping pin): a Hat that pulls it to its own unpowered supply at power-on (e.g. Hat DAC)
            // makes the board boot into download mode
            return {8, 0, false};
        case m5::board_t::board_M5StackCoreInk:
            return {25, 26, false};
        case m5::board_t::board_ArduinoNessoN1:
            return {6, 7, true};  // useWire1
        default:
            return {-1, -1, false};
    }
}
 
inline HatPinPair hatGPIOPins()
{
    const auto board = M5.getBoard();
    switch (board) {
        case m5::board_t::board_M5StickC:
        case m5::board_t::board_M5StickCPlus:
        case m5::board_t::board_M5StickCPlus2:
            return {26, 0};
        case m5::board_t::board_M5StickS3:
            return {0, 8};
        case m5::board_t::board_M5StackCoreInk:
            return {26, 25};
        case m5::board_t::board_ArduinoNessoN1:
            return {7, 6};
        default:
            return {-1, -1};
    }
}
 
inline HatPinPair hatUARTPins()
{
    const auto board = M5.getBoard();
    switch (board) {
        case m5::board_t::board_M5StickCPlus:
        case m5::board_t::board_M5StickCPlus2:
            return {26, 0};
        case m5::board_t::board_M5StickS3:
            return {0, 8};
        case m5::board_t::board_M5StackCoreInk:
            return {26, 25};
        case m5::board_t::board_ArduinoNessoN1:
            return {7, 6};
        default:
            return {-1, -1};
    }
}
#endif  // __M5UNIFIED_HPP__
 
#if defined(ARDUINO)
inline bool i2cWire(UnitUnified& units, Component& unit, TwoWire& wire, const int sda, const int scl,
                    const uint32_t clock)
{
    M5_LIB_LOGI("wiring: I2C(Wire) sda=%d scl=%d clock=%lu", sda, scl, (unsigned long)clock);
    wire.end();
    wire.begin(sda, scl, clock);
    return units.add(unit, wire);
}
#endif
 
#if defined(__M5_I2C_CLASS_H__)
inline bool i2cClass(UnitUnified& units, Component& unit, m5::I2C_Class& i2c)
{
    M5_LIB_LOGI("wiring: I2C(I2C_Class)");
    i2c.begin();
    return units.add(unit, i2c);
}
#endif
 
#if defined(M5_HAL_HPP) && defined(ESP_PLATFORM)
inline bool i2cSoftware(UnitUnified& units, Component& unit, const int sda, const int scl)
{
    M5_LIB_LOGI("wiring: I2C(Software/M5HAL) sda=%d scl=%d", sda, scl);
    m5::hal::bus::I2CBusConfig cfg;
    cfg.pin_sda = m5::hal::gpio::getPin(sda);
    cfg.pin_scl = m5::hal::gpio::getPin(scl);
    auto bus    = m5::hal::bus::i2c::getBus(cfg);
    return units.add(unit, bus ? bus.value() : nullptr);
}
#endif
 
#if defined(ARDUINO)
inline bool addI2C(UnitUnified& units, Component& unit, const uint32_t clock = 0,
                   const NessoPort nesso = NessoPort::PortB)
{
    // clock == 0: use the unit's own configured clock; clock > 0: override it. Either way the unit's
    // component_config().clock is the single source of truth applied per transaction by every backend.
    if (clock != 0) {
        auto cfg  = unit.component_config();
        cfg.clock = clock;
        unit.component_config(cfg);
    }
    const uint32_t eff_clock = unit.component_config().clock;
    const auto p             = i2cPins(nesso);
    M5_LIB_LOGI("wiring: addI2C board=0x%02x nesso=%d backend=%d sda=%d scl=%d clock=%lu", (int)M5.getBoard(),
                (int)nesso, (int)p.backend, (int)p.sda, (int)p.scl, (unsigned long)eff_clock);
    switch (p.backend) {
        case I2CPins::Backend::SoftwareI2C:
            return i2cSoftware(units, unit, p.sda, p.scl);
        case I2CPins::Backend::Wire:
            return i2cWire(units, unit, Wire, p.sda, p.scl, eff_clock);
        case I2CPins::Backend::ExI2C:
            return i2cClass(units, unit, M5.Ex_I2C);
    }
    return false;
}
 
inline bool addGPIO(UnitUnified& units, Component& unit, const GpioRole role = GpioRole::Both)
{
    const auto p = gpioPins(role);
    if (p.fallback_a) {
        Wire.end();
    }
    M5_LIB_LOGI("wiring: GPIO rx=%d tx=%d role=%d fallback_a=%d", (int)p.rx, (int)p.tx, (int)role, (int)p.fallback_a);
    return units.add(unit, p.rx, p.tx);
}
 
inline uint32_t toArduinoSerialConfig(const UartConfig c)
{
    switch (c) {
        case UartConfig::_8N2:
            return SERIAL_8N2;
        case UartConfig::_8E1:
            return SERIAL_8E1;
        case UartConfig::_8O1:
            return SERIAL_8O1;
        case UartConfig::_7N1:
            return SERIAL_7N1;
        case UartConfig::_7E1:
            return SERIAL_7E1;
        case UartConfig::_7O1:
            return SERIAL_7O1;
        case UartConfig::Default:
        case UartConfig::_8N1:
        default:
            return SERIAL_8N1;
    }
}
 
inline HardwareSerial& defaultUartSerial()
{
#if M5_UNIT_UNIFIED_WIRING_HP_UART_NUM > 2
    return Serial2;
#elif M5_UNIT_UNIFIED_WIRING_HP_UART_NUM > 1
    return Serial1;
#else
#error "Not enough Serial"
#endif
}
 
inline bool addUART(UnitUnified& units, Component& unit, const uint32_t baud = 115200,
                    const UartConfig config = UartConfig::Default)
{
    HardwareSerial& serial = defaultUartSerial();
    const uint32_t cfg     = toArduinoSerialConfig(config);
    const auto p           = uartPins();
    if (p.fallback_a) {
        const auto b = M5.getBoard();
        if (b == m5::board_t::board_M5NanoC6 || b == m5::board_t::board_M5NanoH2) {
            // M5.begin() calls Ex_I2C.setPort() but NOT begin(). m5gfx::i2c::release() is gated
            // by the internal `initialized` flag, so release() alone is a no-op. Workaround:
            // begin() flips initialized=true, then release() actually detaches + restores pins.
            M5.Ex_I2C.begin();
            M5.Ex_I2C.release();
        }
    }
    M5_LIB_LOGI("wiring: UART rx=%d tx=%d baud=%lu config=0x%lx fallback_a=%d", (int)p.rx, (int)p.tx,
                (unsigned long)baud, (unsigned long)cfg, (int)p.fallback_a);
    serial.end();
    serial.begin(baud, cfg, p.rx, p.tx);
    return units.add(unit, serial);
}
 
inline bool spiBus(UnitUnified& units, Component& unit, SPIClass& spi, const SPISettings& settings)
{
    M5_LIB_LOGI("wiring: SPI");
    return units.add(unit, spi, settings);
}
 
inline bool addSPI(UnitUnified& units, Component& unit, const uint32_t clock_hz, const uint8_t mode = 0,
                   const uint8_t bit_order = 0)
{
    SPISettings settings{clock_hz, static_cast<uint8_t>((bit_order == 0) ? MSBFIRST : LSBFIRST), mode};
    const auto p = spiPins();
    M5_LIB_LOGI("wiring: addSPI sclk=%d miso=%d mosi=%d clock=%lu mode=%u bit_order=%u", (int)p.sclk, (int)p.miso,
                (int)p.mosi, (unsigned long)clock_hz, (unsigned)mode, (unsigned)bit_order);
    if (!SPI.bus()) {
        SPI.begin(p.sclk, p.miso, p.mosi);
    }
    return spiBus(units, unit, SPI, settings);
}
 
 
inline bool addHatI2C(UnitUnified& units, Component& unit, const uint32_t clock = 0)
{
    const auto p = hatI2CPins();
    if (p.sda < 0 || p.scl < 0) {
        M5_LIB_LOGE("wiring: Hat I2C unsupported board=0x%02x", (int)M5.getBoard());
        return false;
    }
    // clock == 0: use the unit's own configured clock; clock > 0: override it.
    if (clock != 0) {
        auto cfg  = unit.component_config();
        cfg.clock = clock;
        unit.component_config(cfg);
    }
    const uint32_t eff_clock = unit.component_config().clock;
#if M5_UNIT_UNIFIED_WIRING_HAS_WIRE1
    TwoWire& wire = p.useWire1 ? Wire1 : Wire;
#else
    // Arduino-ESP32 declares Wire only (e.g. ESP32-C3); Wire1 is absent.
    if (p.useWire1) {
        M5_LIB_LOGE("wiring: addHatI2C NessoN1 Hat needs Wire1, but Wire1 is not available");
        return false;
    }
    TwoWire& wire = Wire;
#endif
    M5_LIB_LOGI("wiring: addHatI2C board=0x%02x sda=%d scl=%d clock=%lu wire=%s", (int)M5.getBoard(), (int)p.sda,
                (int)p.scl, (unsigned long)eff_clock, p.useWire1 ? "Wire1" : "Wire");
    return i2cWire(units, unit, wire, p.sda, p.scl, eff_clock);
}
 
inline bool addHatGPIO(UnitUnified& units, Component& unit, const GpioRole role = GpioRole::Both)
{
    auto p = hatGPIOPins();
    if (p.rx < 0 || p.tx < 0) {
        M5_LIB_LOGE("wiring: Hat GPIO unsupported board=0x%02x", (int)M5.getBoard());
        return false;
    }
    if (role == GpioRole::OutOnly) p.rx = -1;
    if (role == GpioRole::InOnly) p.tx = -1;
    M5_LIB_LOGI("wiring: addHatGPIO board=0x%02x rx=%d tx=%d role=%d", (int)M5.getBoard(), (int)p.rx, (int)p.tx,
                (int)role);
    return units.add(unit, p.rx, p.tx);
}
 
inline bool addHatUART(UnitUnified& units, Component& unit, const uint32_t baud = 115200,
                       const UartConfig config = UartConfig::Default)
{
    HardwareSerial& serial = defaultUartSerial();
    const uint32_t cfg     = toArduinoSerialConfig(config);
    const auto p           = hatUARTPins();
    if (p.rx < 0 || p.tx < 0) {
        M5_LIB_LOGE("wiring: Hat UART unsupported board=0x%02x", (int)M5.getBoard());
        return false;
    }
    M5_LIB_LOGI("wiring: addHatUART board=0x%02x rx=%d tx=%d baud=%lu config=0x%lx", (int)M5.getBoard(), (int)p.rx,
                (int)p.tx, (unsigned long)baud, (unsigned long)cfg);
    serial.end();
    serial.begin(baud, cfg, p.rx, p.tx);
    return units.add(unit, serial);
}
#endif  // ARDUINO
 
#if !defined(ARDUINO) && defined(ESP_PLATFORM)
 
inline uart_port_t defaultUartPort()
{
#if M5_UNIT_UNIFIED_WIRING_HP_UART_NUM > 2
    return UART_NUM_2;
#elif M5_UNIT_UNIFIED_WIRING_HP_UART_NUM > 1
    return UART_NUM_1;
#else
#error "Not enough UART"
#endif
}
 
struct IdfUartParams {
    uart_word_length_t word_length;
    uart_parity_t parity;
    uart_stop_bits_t stop_bits;
};
inline IdfUartParams toIdfUartParams(const UartConfig c)
{
    switch (c) {
        case UartConfig::_8N2:
            return {UART_DATA_8_BITS, UART_PARITY_DISABLE, UART_STOP_BITS_2};
        case UartConfig::_8E1:
            return {UART_DATA_8_BITS, UART_PARITY_EVEN, UART_STOP_BITS_1};
        case UartConfig::_8O1:
            return {UART_DATA_8_BITS, UART_PARITY_ODD, UART_STOP_BITS_1};
        case UartConfig::_7N1:
            return {UART_DATA_7_BITS, UART_PARITY_DISABLE, UART_STOP_BITS_1};
        case UartConfig::_7E1:
            return {UART_DATA_7_BITS, UART_PARITY_EVEN, UART_STOP_BITS_1};
        case UartConfig::_7O1:
            return {UART_DATA_7_BITS, UART_PARITY_ODD, UART_STOP_BITS_1};
        case UartConfig::Default:
        case UartConfig::_8N1:
        default:
            return {UART_DATA_8_BITS, UART_PARITY_DISABLE, UART_STOP_BITS_1};
    }
}
 
namespace detail {
 
constexpr size_t kI2CBusCacheSize   = 4;
constexpr size_t kUARTPortCacheSize = 4;
constexpr size_t kSPIHostCacheSize  = 2;  // SPI2_HOST / SPI3_HOST
constexpr size_t kSPIDevCacheSize   = 4;
 
#if __has_include(<driver/i2c_master.h>)
struct I2CCacheEntry {
    uint32_t key;
    i2c_master_bus_handle_t handle;
};
#endif
 
struct UARTCacheEntry {
    uint32_t key;
    uart_port_t port;
};
 
struct SPIHostEntry {
    spi_host_device_t host;
    bool initialized;
};
 
struct SPIDevEntry {
    uint32_t key;
    spi_device_handle_t handle;
};
 
#if __has_include(<driver/i2c_master.h>)
inline i2c_master_bus_handle_t ensureI2CBus(const i2c_port_t port, const gpio_num_t sda, const gpio_num_t scl,
                                            const uint32_t /*clock - not used to key, single bus per pins*/)
{
    const uint32_t key = (static_cast<uint32_t>(static_cast<uint8_t>(port)) << 24) |
                         (static_cast<uint32_t>(static_cast<uint8_t>(sda)) << 16) |
                         (static_cast<uint32_t>(static_cast<uint8_t>(scl)) << 8);
    static I2CCacheEntry cache[kI2CBusCacheSize]{};
    static size_t count{};
    for (size_t i = 0; i < count; ++i) {
        if (cache[i].key == key) return cache[i].handle;
    }
    if (count >= kI2CBusCacheSize) {
        M5_LIB_LOGE("wiring: I2C bus cache full (max %zu)", kI2CBusCacheSize);
        return nullptr;
    }
    i2c_master_bus_config_t cfg{};
    cfg.i2c_port   = port;
    cfg.sda_io_num = sda;
    cfg.scl_io_num = scl;
#if SOC_LP_I2C_SUPPORTED
    if (port == LP_I2C_NUM_0) {
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 3, 0)
        // LP I2C uses RTC_FAST clock (union with clk_source, mutually exclusive).
        cfg.lp_source_clk = LP_I2C_SCLK_DEFAULT;
#else
        // i2c_master_bus_config_t has no lp_source_clk before ESP-IDF 5.3; LP I2C cannot be opened
        M5_LIB_LOGE("wiring: LP I2C needs ESP-IDF >= 5.3");
        return nullptr;
#endif
    } else
#endif
    {
        cfg.clk_source = I2C_CLK_SRC_DEFAULT;
    }
    cfg.glitch_ignore_cnt            = 7;
    cfg.flags.enable_internal_pullup = true;
    if (i2c_new_master_bus(&cfg, &cache[count].handle) != ESP_OK) {
        M5_LIB_LOGE("wiring: i2c_new_master_bus failed port=%d sda=%d scl=%d", (int)port, (int)sda, (int)scl);
        return nullptr;
    }
    cache[count].key = key;
    return cache[count++].handle;
}
#else  // legacy driver/i2c.h (IDF 5.0 / 5.1)
inline bool ensureI2CLegacyDriver(const i2c_port_t port, const gpio_num_t sda, const gpio_num_t scl,
                                  const uint32_t clock)
{
    const uint32_t key = (static_cast<uint32_t>(static_cast<uint8_t>(port)) << 24) |
                         (static_cast<uint32_t>(static_cast<uint8_t>(sda)) << 16) |
                         (static_cast<uint32_t>(static_cast<uint8_t>(scl)) << 8);
    static uint32_t cache[kI2CBusCacheSize]{};
    static size_t count{};
    for (size_t i = 0; i < count; ++i) {
        if (cache[i] == key) return true;
    }
    if (count >= kI2CBusCacheSize) {
        M5_LIB_LOGE("wiring: I2C bus cache full (max %zu)", kI2CBusCacheSize);
        return false;
    }
    // i2c_driver_install returns ESP_FAIL for several distinct reasons in IDF 5.0/5.1 (already
    // installed by another owner / OOM / slave-setup failure). Probe i2c_get_period to disambiguate:
    // it writes high/low only when the driver object exists (p_i2c_obj != NULL), so high>0 && low>0
    // means the port is genuinely installed and can be borrowed.
    const esp_err_t install_err = i2c_driver_install(port, I2C_MODE_MASTER, 0, 0, 0);
    if (install_err == ESP_OK) {
        // Freshly installed by us: configure pins and timing.
        i2c_config_t conf{};
        conf.mode = I2C_MODE_MASTER;
        conf.sda_io_num = sda;
        conf.scl_io_num = scl;
        conf.sda_pullup_en = true;
        conf.scl_pullup_en = true;
        conf.master.clk_speed = clock;
        if (i2c_param_config(port, &conf) != ESP_OK) {
            M5_LIB_LOGE("wiring: legacy i2c param_config failed port=%d sda=%d scl=%d", (int)port, (int)sda, (int)scl);
            i2c_driver_delete(port);
            return false;
        }
        M5_LIB_LOGI("wiring: legacy i2c INSTALLED(new) port=%d sda=%d scl=%d clock=%u", (int)port, (int)sda, (int)scl,
                    (unsigned)clock);
    } else if (install_err == ESP_FAIL) {
        // Already installed by another owner -> borrow it (keep the owner's pins/timing; do NOT
        // re-run i2c_param_config and override them). Confirm the driver really exists first.
        int high = 0, low = 0;
        i2c_get_period(port, &high, &low);
        if (!(high > 0 && low > 0)) {
            M5_LIB_LOGE("wiring: legacy i2c driver install failed port=%d sda=%d scl=%d", (int)port, (int)sda,
                        (int)scl);
            return false;
        }
        M5_LIB_LOGI("wiring: legacy i2c BORROW(already) port=%d sda=%d scl=%d high=%d low=%d", (int)port, (int)sda,
                    (int)scl, high, low);
    } else {
        M5_LIB_LOGE("wiring: legacy i2c driver install error=0x%x port=%d sda=%d scl=%d", (int)install_err, (int)port,
                    (int)sda, (int)scl);
        return false;
    }
    cache[count++] = key;
    return true;
}
#endif
 
inline uart_port_t ensureUARTPort(const uart_port_t port, const gpio_num_t rx, const gpio_num_t tx, const uint32_t baud,
                                  const UartConfig config)
{
    const uint32_t key = (static_cast<uint32_t>(static_cast<uint8_t>(port)) << 24) |
                         (static_cast<uint32_t>(static_cast<uint8_t>(rx)) << 16) |
                         (static_cast<uint32_t>(static_cast<uint8_t>(tx)) << 8);
    static UARTCacheEntry cache[kUARTPortCacheSize]{};
    static size_t count{};
    for (size_t i = 0; i < count; ++i) {
        if (cache[i].key == key) return cache[i].port;
    }
    if (count >= kUARTPortCacheSize) {
        M5_LIB_LOGE("wiring: UART port cache full (max %zu)", kUARTPortCacheSize);
        return UART_NUM_MAX;
    }
    if (uart_is_driver_installed(port)) {
        cache[count] = {key, port};
        return cache[count++].port;
    }
    const auto p = toIdfUartParams(config);
    uart_config_t uc{};
    uc.baud_rate  = static_cast<int>(baud);
    uc.data_bits  = p.word_length;
    uc.parity     = p.parity;
    uc.stop_bits  = p.stop_bits;
    uc.flow_ctrl  = UART_HW_FLOWCTRL_DISABLE;
    uc.source_clk = UART_SCLK_DEFAULT;
    if (uart_param_config(port, &uc) != ESP_OK ||
        uart_set_pin(port, tx, rx, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE) != ESP_OK ||
        uart_driver_install(port, 256, 0, 0, nullptr, 0) != ESP_OK) {
        M5_LIB_LOGE("wiring: uart setup failed port=%d", (int)port);
        return UART_NUM_MAX;
    }
    cache[count] = {key, port};
    return cache[count++].port;
}
 
inline spi_device_handle_t ensureSPIDevice(const spi_host_device_t host, const gpio_num_t mosi, const gpio_num_t miso,
                                           const gpio_num_t sck, const uint32_t clock_hz, const uint8_t mode,
                                           const uint8_t bit_order)
{
    static SPIHostEntry host_cache[kSPIHostCacheSize]{};
    static SPIDevEntry dev_cache[kSPIDevCacheSize]{};
    static size_t host_count{};
    static size_t dev_count{};
 
    bool host_init = false;
    for (size_t i = 0; i < host_count; ++i) {
        if (host_cache[i].host == host) {
            host_init = host_cache[i].initialized;
            break;
        }
    }
    if (!host_init) {
        spi_bus_config_t bc{};
        bc.mosi_io_num     = mosi;
        bc.miso_io_num     = miso;
        bc.sclk_io_num     = sck;
        bc.quadwp_io_num   = -1;
        bc.quadhd_io_num   = -1;
        bc.max_transfer_sz = 4096;
        if (spi_bus_initialize(host, &bc, SPI_DMA_CH_AUTO) != ESP_OK) {
            M5_LIB_LOGE("wiring: spi_bus_initialize failed host=%d", (int)host);
            return nullptr;
        }
        if (host_count < kSPIHostCacheSize) host_cache[host_count++] = {host, true};
    }
 
    const uint32_t key = (static_cast<uint32_t>(static_cast<uint8_t>(host)) << 24) |
                         (static_cast<uint32_t>(clock_hz / 1000U) << 8) | (static_cast<uint32_t>(mode) << 4) |
                         static_cast<uint32_t>(bit_order);
    for (size_t i = 0; i < dev_count; ++i) {
        if (dev_cache[i].key == key) return dev_cache[i].handle;
    }
    if (dev_count >= kSPIDevCacheSize) {
        M5_LIB_LOGE("wiring: SPI device cache full (max %zu)", kSPIDevCacheSize);
        return nullptr;
    }
    spi_device_interface_config_t dc{};
    dc.clock_speed_hz = static_cast<int>(clock_hz);
    dc.mode           = mode;
    dc.spics_io_num   = GPIO_NUM_NC;  // manual CS control by adapter
    dc.queue_size     = 1;
    if (bit_order == 1) dc.flags |= SPI_DEVICE_BIT_LSBFIRST;
    if (spi_bus_add_device(host, &dc, &dev_cache[dev_count].handle) != ESP_OK) {
        M5_LIB_LOGE("wiring: spi_bus_add_device failed host=%d", (int)host);
        return nullptr;
    }
    dev_cache[dev_count].key = key;
    return dev_cache[dev_count++].handle;
}
 
}  // namespace detail
 
#if __has_include(<driver/i2c_master.h>)
inline i2c_master_bus_handle_t i2cBusHandle(const i2c_port_t port, const gpio_num_t sda, const gpio_num_t scl,
                                            const uint32_t clock = 100000)
{
    return detail::ensureI2CBus(port, sda, scl, clock);
}
#endif
 
inline uart_port_t uartPortHandle(const uart_port_t port, const gpio_num_t rx, const gpio_num_t tx, const uint32_t baud,
                                  const UartConfig config = UartConfig::Default)
{
    return detail::ensureUARTPort(port, rx, tx, baud, config);
}
 
inline spi_device_handle_t spiDeviceHandle(const spi_host_device_t host, const gpio_num_t mosi, const gpio_num_t miso,
                                           const gpio_num_t sck, const uint32_t clock_hz, const uint8_t mode = 0,
                                           const uint8_t bit_order = 0)
{
    return detail::ensureSPIDevice(host, mosi, miso, sck, clock_hz, mode, bit_order);
}
 
//
// === ESP-IDF native generic helpers (Phase C) — same signatures as Arduino ===
//
 
#if defined(__M5UNIFIED_HPP__)
inline bool addI2C(UnitUnified& units, Component& unit, const uint32_t clock = 0,
                   const NessoPort nesso = NessoPort::PortB)
{
    // clock == 0: use the unit's own configured clock; clock > 0: override it. component_config().clock
    // is the single source of truth applied per transaction (Wire / I2C_Class / master device / legacy).
    if (clock != 0) {
        auto cfg  = unit.component_config();
        cfg.clock = clock;
        unit.component_config(cfg);
    }
    const uint32_t eff_clock = unit.component_config().clock;
    const auto pins          = i2cPins(nesso);
    const auto board         = M5.getBoard();
    M5_LIB_LOGI("wiring(ESP-IDF): addI2C board=0x%02x nesso=%d sda=%d scl=%d clock=%u backend=%d", (int)board,
                (int)nesso, (int)pins.sda, (int)pins.scl, (unsigned)eff_clock, (int)pins.backend);
    switch (pins.backend) {
        case I2CPins::Backend::SoftwareI2C:
#if defined(M5_HAL_HPP)
            return i2cSoftware(units, unit, pins.sda, pins.scl);
#else
            M5_LIB_LOGE("wiring: SoftwareI2C backend requires M5HAL");
            return false;
#endif
        case I2CPins::Backend::Wire:
            if (board == m5::board_t::board_ArduinoNessoN1) {
                // NessoN1 PortA (QWIIC) -> Wire == M5.In_I2C (NessoN1 maps Wire to In_I2C).
                // M5Unified already holds I2C_NUM_0 here, so borrow instead of installing.
                return i2cClass(units, unit, M5.In_I2C);
            } else {
                // Stick / S3 etc: M5Unified does not call Wire.begin(), so install ourselves
                // (Core is routed to ExI2C by i2cPins() and never reaches this branch)
#if __has_include(<driver/i2c_master.h>)
                auto bus = i2cBusHandle(I2C_NUM_0, (gpio_num_t)pins.sda, (gpio_num_t)pins.scl, eff_clock);
                if (!bus) return false;
                return units.add(unit, bus, I2C_NUM_0, (gpio_num_t)pins.sda, (gpio_num_t)pins.scl);
#else  // legacy driver (IDF 5.0 / 5.1): install legacy driver, then add by port
                if (!detail::ensureI2CLegacyDriver(I2C_NUM_0, (gpio_num_t)pins.sda, (gpio_num_t)pins.scl, eff_clock)) {
                    return false;
                }
                return units.add(unit, I2C_NUM_0, (gpio_num_t)pins.sda, (gpio_num_t)pins.scl);
#endif
            }
        case I2CPins::Backend::ExI2C:
            // Core / NanoC6 / NanoH2: M5Unified manages Ex_I2C (Core shares it with In_I2C) -> borrow
            return i2cClass(units, unit, M5.Ex_I2C);
    }
    return false;
}
 
inline bool addGPIO(UnitUnified& units, Component& unit, const GpioRole role = GpioRole::Both)
{
    auto p = gpioPins(role);
    if (role == GpioRole::OutOnly) p.rx = -1;
    if (role == GpioRole::InOnly) p.tx = -1;
    M5_LIB_LOGI("wiring(ESP-IDF): GPIO rx=%d tx=%d role=%d fallback_a=%d", (int)p.rx, (int)p.tx, (int)role,
                (int)p.fallback_a);
    return units.add(unit, p.rx, p.tx);
}
 
inline bool addUART(UnitUnified& units, Component& unit, const uint32_t baud = 115200,
                    const UartConfig config = UartConfig::Default)
{
    const auto pins = uartPins();
    M5_LIB_LOGI("wiring(ESP-IDF): UART rx=%d tx=%d baud=%u fallback_a=%d", (int)pins.rx, (int)pins.tx, (unsigned)baud,
                (int)pins.fallback_a);
    auto port = uartPortHandle(defaultUartPort(), (gpio_num_t)pins.rx, (gpio_num_t)pins.tx, baud, config);
    if (port == UART_NUM_MAX) return false;
    return units.add(unit, port);
}
 
inline bool addSPI(UnitUnified& units, Component& unit, const uint32_t clock_hz, const uint8_t mode = 0,
                   const uint8_t bit_order = 0)
{
    const auto pins = spiPins();
    M5_LIB_LOGI("wiring(ESP-IDF): addSPI sclk=%d miso=%d mosi=%d clock=%u mode=%u bit_order=%u", (int)pins.sclk,
                (int)pins.miso, (int)pins.mosi, (unsigned)clock_hz, (unsigned)mode, (unsigned)bit_order);
    auto dev = spiDeviceHandle(SPI2_HOST, (gpio_num_t)pins.mosi, (gpio_num_t)pins.miso, (gpio_num_t)pins.sclk, clock_hz,
                               mode, bit_order);
    if (!dev) return false;
    return units.add(unit, dev);  // cs omitted -> Component::assign uses address() as CS
}
 
inline bool addHatI2C(UnitUnified& units, Component& unit, const uint32_t clock = 0)
{
    const auto p = hatI2CPins();
    if (p.sda < 0 || p.scl < 0) {
        M5_LIB_LOGE("wiring: Hat I2C unsupported board=0x%02x", (int)M5.getBoard());
        return false;
    }
    // clock == 0: use the unit's own configured clock; clock > 0: override it.
    if (clock != 0) {
        auto cfg  = unit.component_config();
        cfg.clock = clock;
        unit.component_config(cfg);
    }
    const uint32_t eff_clock = unit.component_config().clock;
    i2c_port_t port;
    if (p.useWire1) {
#if M5_UNIT_UNIFIED_WIRING_HP_I2C_NUM >= 2
        port = I2C_NUM_1;  // HP I2C #1 (ESP32 / S2 / S3 / P4 / H2 etc.)
#elif SOC_LP_I2C_SUPPORTED
        port = LP_I2C_NUM_0;  // C6: 2nd I2C is LP (= Arduino Wire1)
#else
        M5_LIB_LOGE("wiring: addHatI2C needs a 2nd I2C port, none available board=0x%02x", (int)M5.getBoard());
        return false;
#endif
    } else {
        port = I2C_NUM_0;
    }
    M5_LIB_LOGI("wiring(ESP-IDF): addHatI2C port=%d sda=%d scl=%d clock=%u", (int)port, (int)p.sda, (int)p.scl,
                (unsigned)eff_clock);
#if __has_include(<driver/i2c_master.h>)
    auto bus = i2cBusHandle(port, (gpio_num_t)p.sda, (gpio_num_t)p.scl, eff_clock);
    if (!bus) return false;
    return units.add(unit, bus, port, (gpio_num_t)p.sda, (gpio_num_t)p.scl);
#else  // legacy driver (IDF 5.0 / 5.1)
    if (!detail::ensureI2CLegacyDriver(port, (gpio_num_t)p.sda, (gpio_num_t)p.scl, eff_clock)) return false;
    return units.add(unit, port, (gpio_num_t)p.sda, (gpio_num_t)p.scl);
#endif
}
 
inline bool addHatGPIO(UnitUnified& units, Component& unit, const GpioRole role = GpioRole::Both)
{
    auto p = hatGPIOPins();
    if (p.rx < 0 || p.tx < 0) {
        M5_LIB_LOGE("wiring: Hat GPIO unsupported board=0x%02x", (int)M5.getBoard());
        return false;
    }
    if (role == GpioRole::OutOnly) p.rx = -1;
    if (role == GpioRole::InOnly) p.tx = -1;
    M5_LIB_LOGI("wiring(ESP-IDF): addHatGPIO board=0x%02x rx=%d tx=%d role=%d", (int)M5.getBoard(), (int)p.rx,
                (int)p.tx, (int)role);
    return units.add(unit, p.rx, p.tx);
}
 
inline bool addHatUART(UnitUnified& units, Component& unit, const uint32_t baud = 115200,
                       const UartConfig config = UartConfig::Default)
{
    const auto p = hatUARTPins();
    if (p.rx < 0 || p.tx < 0) {
        M5_LIB_LOGE("wiring: Hat UART unsupported board=0x%02x", (int)M5.getBoard());
        return false;
    }
    M5_LIB_LOGI("wiring(ESP-IDF): addHatUART board=0x%02x rx=%d tx=%d baud=%u", (int)M5.getBoard(), (int)p.rx,
                (int)p.tx, (unsigned)baud);
    auto port = uartPortHandle(defaultUartPort(), (gpio_num_t)p.rx, (gpio_num_t)p.tx, baud, config);
    if (port == UART_NUM_MAX) return false;
    return units.add(unit, port);
}
#endif  // __M5UNIFIED_HPP__
 
#endif  // !ARDUINO && ESP_PLATFORM
 
#if defined(__M5UNIFIED_HPP__)
[[noreturn]] inline void failStop()
{
    M5.Display.fillScreen(0xF800 /* TFT_RED */);
    while (true) {
        m5::utility::delay(10000);
    }
}
#endif
 
}  // namespace wiring
}  // namespace unit
}  // namespace m5
#endif  // M5_UNIT_UNIFIED_WIRING_HPP