GPIO refactored (#495)

* **Refactor**
  * GPIO subsystem moved to a descriptor-based model for per-pin ownership and runtime pin management; many platform drivers now acquire/release descriptors.
  * Device trees and drivers now use GPIO phandle-style pin specifications across all boards and all drivers.

* **Behavior**
  * Device list now encodes per-device status (ok/disabled); boot will skip disabled devices accordingly.

* **Deprecation**
  * Legacy GPIO HAL marked deprecated and replaced with descriptor-based interfaces.

* **Chores**
  * Bindings and platform configs updated to the new GPIO pin-spec format.

Platforms/PlatformEsp32/Bindings/espressif,esp32-i2c.yaml

@@ -16,14 +16,8 @@ properties:
     required: true
     description: Initial clock frequency in Hz
   pin-sda:
-    type: int
+    type: phandle-array
     required: true
   pin-scl:
-    type: int
+    type: phandle-array
     required: true
-  pin-sda-pull-up:
-    type: bool
-    description: enable internal pull-up resistor for SDA pin
-  pin-scl-pull-up:
-    type: bool
-    description: enable internal pull-up resistor for SCL pin

Platforms/PlatformEsp32/Bindings/espressif,esp32-i2s.yaml

@@ -12,23 +12,22 @@ properties:
       The port number, defined by i2s_port_t.
       Depending on the hardware, these values are available: I2S_NUM_0, I2S_NUM_1
   pin-bclk:
-    type: int
+    type: phandle-array
     required: true
-    description: BCK pin
+    description: Bit clock pin
   pin-ws:
-    type: int
+    type: phandle-array
     required: true
-    description: WS pin
+    description: Word (slot) select pin
   pin-data-out:
-    type: int
-    default: GPIO_PIN_NONE
-    description: DATA OUT pin
+    type: phandle-array
+    default: GPIO_PIN_SPEC_NONE
+    description: Data output pin
   pin-data-in:
-    type: int
-    default: GPIO_PIN_NONE
-    description: DATA IN pin
+    type: phandle-array
+    default: GPIO_PIN_SPEC_NONE
+    description: Data input pin
   pin-mclk:
-    type: int
-    required: false
-    default: GPIO_PIN_NONE
-    description: MCLK pin
+    type: phandle-array
+    default: GPIO_PIN_SPEC_NONE
+    description: Master clock pin

Platforms/PlatformEsp32/Bindings/espressif,esp32-spi.yaml

@@ -11,25 +11,24 @@ properties:
     description: |
       The SPI host (controller) to use.
       Defined by spi_host_device_t (e.g. SPI2_HOST, SPI3_HOST).
+  pin-sclk:
+    type: phandle-array
+    default: GPIO_PIN_SPEC_NONE
   pin-mosi:
-    type: int
-    default: GPIO_PIN_NONE
+    type: phandle-array
+    default: GPIO_PIN_SPEC_NONE
     description: MOSI (Data 0) pin
   pin-miso:
-    type: int
-    default: GPIO_PIN_NONE
+    type: phandle-array
+    default: GPIO_PIN_SPEC_NONE
     description: MISO (Data 1) pin
-  pin-sclk:
-    type: int
-    required: true
-    description: Clock pin
   pin-wp:
-    type: int
-    default: GPIO_PIN_NONE
+    type: phandle-array
+    default: GPIO_PIN_SPEC_NONE
     description: WP (Data 2) pin
   pin-hd:
-    type: int
-    default: GPIO_PIN_NONE
+    type: phandle-array
+    default: GPIO_PIN_SPEC_NONE
     description: HD (Data 3) pin
   max-transfer-size:
     type: int

Platforms/PlatformEsp32/Bindings/espressif,esp32-uart.yaml

@@ -12,18 +12,18 @@ properties:
       The port number, defined by uart_port_t.
       Depending on the hardware, these values are available: UART_NUM_0, UART_NUM_1, UART_NUM_2
   pin-tx:
-    type: int
+    type: phandle-array
     required: true
     description: TX pin
   pin-rx:
-    type: int
+    type: phandle-array
     required: true
     description: RX pin
   pin-cts:
-    type: int
-    default: GPIO_PIN_NONE
+    type: phandle-array
+    default: GPIO_PIN_SPEC_NONE
     description: CTS pin
   pin-rts:
-    type: int
-    default: GPIO_PIN_NONE
+    type: phandle-array
+    default: GPIO_PIN_SPEC_NONE
     description: RTS pin

Platforms/PlatformEsp32/CMakeLists.txt

@@ -5,5 +5,6 @@ file(GLOB_RECURSE SOURCES "Source/*.c**")
 idf_component_register(
     SRCS ${SOURCES}
     INCLUDE_DIRS "Include/"
+    PRIV_INCLUDE_DIRS "Private/"
     REQUIRES TactilityKernel driver
 )

Platforms/PlatformEsp32/Include/tactility/bindings/esp32_gpio.h

@@ -9,6 +9,16 @@
 extern "C" {
 #endif
 
+#define GPIO_ACTIVE_HIGH GPIO_FLAG_ACTIVE_HIGH
+#define GPIO_ACTIVE_LOW GPIO_FLAG_ACTIVE_LOW
+
+#define GPIO_DIRECTION_INPUT GPIO_FLAG_DIRECTION_INPUT
+#define GPIO_DIRECTION_OUTPUT GPIO_FLAG_DIRECTION_OUTPUT
+#define GPIO_DIRECTION_INPUT_OUTPUT GPIO_FLAG_DIRECTION_INPUT_OUTPUT
+
+#define GPIO_PULL_UP GPIO_FLAG_PULL_UP
+#define GPIO_PULL_DOWN GPIO_FLAG_PULL_DOWN
+
 DEFINE_DEVICETREE(esp32_gpio, struct Esp32GpioConfig)
 
 #ifdef __cplusplus

Platforms/PlatformEsp32/Include/tactility/bindings/esp32_i2s.h

@@ -3,6 +3,7 @@
 
 #include <tactility/bindings/bindings.h>
 #include <tactility/drivers/esp32_i2s.h>
+#include <tactility/drivers/esp32_gpio.h>
 #include <driver/i2s_common.h>
 
 #ifdef __cplusplus

Platforms/PlatformEsp32/Include/tactility/drivers/esp32_i2c.h

@@ -11,13 +11,10 @@ extern "C" {
 struct Esp32I2cConfig {
     i2c_port_t port;
     uint32_t clockFrequency;
-    gpio_pin_t pinSda;
-    gpio_pin_t pinScl;
-    bool pinSdaPullUp;
-    bool pinSclPullUp;
+    struct GpioPinSpec pinSda;
+    struct GpioPinSpec pinScl;
 };
 
-
 #ifdef __cplusplus
 }
 #endif

Platforms/PlatformEsp32/Include/tactility/drivers/esp32_i2s.h

@@ -2,6 +2,7 @@
 #pragma once
 
 #include <tactility/drivers/i2s_controller.h>
+#include <tactility/drivers/gpio.h>
 #include <driver/i2s_common.h>
 
 #ifdef __cplusplus
@@ -10,11 +11,11 @@ extern "C" {
 
 struct Esp32I2sConfig {
     i2s_port_t port;
-    int pin_bclk;
-    int pin_ws;
-    int pin_data_out;
-    int pin_data_in;
-    int pin_mclk;
+    struct GpioPinSpec pin_bclk;
+    struct GpioPinSpec pin_ws;
+    struct GpioPinSpec pin_data_out;
+    struct GpioPinSpec pin_data_in;
+    struct GpioPinSpec pin_mclk;
 };
 
 #ifdef __cplusplus

Platforms/PlatformEsp32/Include/tactility/drivers/esp32_spi.h

@@ -3,6 +3,7 @@
 
 #include <driver/spi_common.h>
 #include <tactility/drivers/spi_controller.h>
+#include <tactility/drivers/gpio.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -10,16 +11,16 @@ extern "C" {
 
 struct Esp32SpiConfig {
     spi_host_device_t host;
-    /** Data 0 pin */
-    int pin_mosi;
-    /** Data 1 pin */
-    int pin_miso;
     /** Clock pin */
-    int pin_sclk;
+    struct GpioPinSpec pin_sclk;
+    /** Data 0 pin */
+    struct GpioPinSpec pin_mosi;
+    /** Data 1 pin */
+    struct GpioPinSpec pin_miso;
     /** Data 2 pin */
-    int pin_wp;
+    struct GpioPinSpec pin_wp;
     /** Data 3 pin */
-    int pin_hd;
+    struct GpioPinSpec pin_hd;
     /** Data transfer size limit in bytes. 0 means the platform decides the limit. */
     int max_transfer_size;
 };

Platforms/PlatformEsp32/Include/tactility/drivers/esp32_uart.h

@@ -3,6 +3,7 @@
 
 #include <driver/uart.h>
 #include <tactility/drivers/uart_controller.h>
+#include <tactility/drivers/gpio.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -10,10 +11,10 @@ extern "C" {
 
 struct Esp32UartConfig {
     uart_port_t port;
-    int pinTx;
-    int pinRx;
-    int pinCts;
-    int pinRts;
+    struct GpioPinSpec pin_tx;
+    struct GpioPinSpec pin_rx;
+    struct GpioPinSpec pin_cts;
+    struct GpioPinSpec pin_rts;
 };
 
 #ifdef __cplusplus

Platforms/PlatformEsp32/Private/tactility/drivers/esp32_gpio_helpers.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#include <tactility/drivers/gpio_descriptor.h>
+
+#include <driver/gpio.h>
+
+/**
+ * Releases the given pin descriptor and sets the pointer value to NULL.
+ * If the descriptor pointer is null, do nothing.
+ */
+void release_pin(GpioDescriptor** gpio_descriptor);
+
+/**
+ * Acquires the pin descriptor for the given pin spec.
+ * If the pin spec is invalid, the pointer is set to null.
+ * @return true if the pin was acquired successfully
+ */
+bool acquire_pin_or_set_null(const GpioPinSpec& pin_spec, GpioDescriptor** gpio_descriptor);
+
+/**
+ * Safely acquire the native pin value.
+ * Set to GPIO_NUM_NC if the descriptor is null.
+ * @param[in] descriptor Pin descriptor to acquire
+ * @return Native pin number
+ */
+gpio_num_t get_native_pin(GpioDescriptor* descriptor);
+
+/**
+ * Returns true if the given pin is inverted.
+ * @param[in] descriptor Pin descriptor to check, nullable
+ */
+bool is_pin_inverted(GpioDescriptor* descriptor);

Platforms/PlatformEsp32/Source/drivers/esp32_gpio.cpp

@@ -8,6 +8,7 @@
 #include <tactility/log.h>
 #include <tactility/drivers/gpio.h>
 #include <tactility/drivers/gpio_controller.h>
+#include <tactility/drivers/gpio_descriptor.h>
 
 #define TAG "esp32_gpio"
 
@@ -15,40 +16,40 @@
 
 extern "C" {
 
-static error_t set_level(Device* device, gpio_pin_t pin, bool high) {
-    auto esp_error = gpio_set_level(static_cast<gpio_num_t>(pin), high);
+static error_t set_level(GpioDescriptor* descriptor, bool high) {
+    auto esp_error = gpio_set_level(static_cast<gpio_num_t>(descriptor->pin), high);
     return esp_err_to_error(esp_error);
 }
 
-static error_t get_level(Device* device, gpio_pin_t pin, bool* high) {
-    *high = gpio_get_level(static_cast<gpio_num_t>(pin)) != 0;
+static error_t get_level(GpioDescriptor* descriptor, bool* high) {
+    *high = gpio_get_level(static_cast<gpio_num_t>(descriptor->pin)) != 0;
     return ERROR_NONE;
 }
 
-static error_t set_options(Device* device, gpio_pin_t pin, gpio_flags_t options) {
-    const Esp32GpioConfig* config = GET_CONFIG(device);
+static error_t set_flags(GpioDescriptor* descriptor, gpio_flags_t flags) {
+    const Esp32GpioConfig* config = GET_CONFIG(descriptor->controller);
 
-    if (pin >= config->gpioCount) {
+    if (descriptor->pin >= config->gpioCount) {
         return ERROR_INVALID_ARGUMENT;
     }
 
     gpio_mode_t mode;
-    if ((options & GPIO_DIRECTION_INPUT_OUTPUT) == GPIO_DIRECTION_INPUT_OUTPUT) {
+    if ((flags & GPIO_FLAG_DIRECTION_INPUT_OUTPUT) == GPIO_FLAG_DIRECTION_INPUT_OUTPUT) {
         mode = GPIO_MODE_INPUT_OUTPUT;
-    } else if (options & GPIO_DIRECTION_INPUT) {
+    } else if (flags & GPIO_FLAG_DIRECTION_INPUT) {
         mode = GPIO_MODE_INPUT;
-    } else if (options & GPIO_DIRECTION_OUTPUT) {
+    } else if (flags & GPIO_FLAG_DIRECTION_OUTPUT) {
         mode = GPIO_MODE_OUTPUT;
     } else {
         return ERROR_INVALID_ARGUMENT;
     }
 
     const gpio_config_t esp_config = {
-        .pin_bit_mask = 1ULL << pin,
+        .pin_bit_mask = 1ULL << descriptor->pin,
         .mode = mode,
-        .pull_up_en = (options & GPIO_PULL_UP) ? GPIO_PULLUP_ENABLE : GPIO_PULLUP_DISABLE,
-        .pull_down_en = (options & GPIO_PULL_DOWN) ? GPIO_PULLDOWN_ENABLE : GPIO_PULLDOWN_DISABLE,
-        .intr_type = GPIO_INTERRUPT_FROM_OPTIONS(options),
+        .pull_up_en = (flags & GPIO_FLAG_PULL_UP) ? GPIO_PULLUP_ENABLE : GPIO_PULLUP_DISABLE,
+        .pull_down_en = (flags & GPIO_FLAG_PULL_DOWN) ? GPIO_PULLDOWN_ENABLE : GPIO_PULLDOWN_DISABLE,
+        .intr_type = GPIO_FLAG_INTERRUPT_FROM_OPTIONS(flags),
 #if SOC_GPIO_SUPPORT_PIN_HYS_FILTER
         .hys_ctrl_mode = GPIO_HYS_SOFT_DISABLE
 #endif
@@ -58,59 +59,61 @@ static error_t set_options(Device* device, gpio_pin_t pin, gpio_flags_t options)
     return esp_err_to_error(esp_error);
 }
 
-static int get_options(Device* device, gpio_pin_t pin, gpio_flags_t* options) {
+static error_t get_flags(GpioDescriptor* descriptor, gpio_flags_t* flags) {
     gpio_io_config_t esp_config;
-    if (gpio_get_io_config(static_cast<gpio_num_t>(pin), &esp_config) != ESP_OK) {
+    if (gpio_get_io_config(static_cast<gpio_num_t>(descriptor->pin), &esp_config) != ESP_OK) {
         return ERROR_RESOURCE;
     }
 
     gpio_flags_t output = 0;
 
     if (esp_config.pu) {
-        output |= GPIO_PULL_UP;
+        output |= GPIO_FLAG_PULL_UP;
     }
 
     if (esp_config.pd) {
-        output |= GPIO_PULL_DOWN;
+        output |= GPIO_FLAG_PULL_DOWN;
     }
 
     if (esp_config.ie) {
-        output |= GPIO_DIRECTION_INPUT;
+        output |= GPIO_FLAG_DIRECTION_INPUT;
     }
 
     if (esp_config.oe) {
-        output |= GPIO_DIRECTION_OUTPUT;
+        output |= GPIO_FLAG_DIRECTION_OUTPUT;
     }
 
     if (esp_config.oe_inv) {
-        output |= GPIO_ACTIVE_LOW;
+        output |= GPIO_FLAG_ACTIVE_LOW;
     }
 
-    *options = output;
+    *flags = output;
     return ERROR_NONE;
 }
 
-error_t get_pin_count(struct Device* device, uint32_t* count) {
-    *count = GET_CONFIG(device)->gpioCount;
+static error_t get_native_pin_number(GpioDescriptor* descriptor, void* pin_number) {
+    auto* esp_pin_number = reinterpret_cast<gpio_num_t*>(pin_number);
+    *esp_pin_number = static_cast<gpio_num_t>(descriptor->pin);
     return ERROR_NONE;
 }
 
 static error_t start(Device* device) {
     ESP_LOGI(TAG, "start %s", device->name);
-    return ERROR_NONE;
+    auto pin_count = GET_CONFIG(device)->gpioCount;
+    return gpio_controller_init_descriptors(device, pin_count, nullptr);
 }
 
 static error_t stop(Device* device) {
     ESP_LOGI(TAG, "stop %s", device->name);
-    return ERROR_NONE;
+    return gpio_controller_deinit_descriptors(device);
 }
 
 const static GpioControllerApi esp32_gpio_api  = {
     .set_level = set_level,
     .get_level = get_level,
-    .set_options = set_options,
-    .get_options = get_options,
-    .get_pin_count = get_pin_count
+    .set_flags = set_flags,
+    .get_flags = get_flags,
+    .get_native_pin_number = get_native_pin_number
 };
 
 extern struct Module platform_module;

Platforms/PlatformEsp32/Source/drivers/esp32_gpio_helpers.cpp

@@ -0,0 +1,40 @@
+#include <tactility/drivers/esp32_gpio_helpers.h>
+#include <tactility/drivers/gpio_controller.h>
+
+#define TAG "gpio"
+
+void release_pin(GpioDescriptor** gpio_descriptor) {
+    if (*gpio_descriptor == nullptr) return;
+    check(gpio_descriptor_release(*gpio_descriptor) == ERROR_NONE);
+    *gpio_descriptor = nullptr;
+}
+
+bool acquire_pin_or_set_null(const GpioPinSpec& pin_spec, GpioDescriptor** gpio_descriptor) {
+    if (pin_spec.gpio_controller == nullptr) {
+        *gpio_descriptor = nullptr;
+        return true;
+    }
+    *gpio_descriptor = gpio_descriptor_acquire(pin_spec.gpio_controller, pin_spec.pin, GPIO_OWNER_GPIO);
+    if (*gpio_descriptor == nullptr) {
+        LOG_E(TAG, "Failed to acquire pin %u from %s", pin_spec.pin, pin_spec.gpio_controller->name);
+    }
+
+    return *gpio_descriptor != nullptr;
+}
+
+gpio_num_t get_native_pin(GpioDescriptor* descriptor) {
+    if (descriptor != nullptr) {
+        gpio_num_t pin;
+        check(gpio_descriptor_get_native_pin_number(descriptor, &pin) == ERROR_NONE);
+        return pin;
+    } else {
+        return GPIO_NUM_NC;
+    }
+}
+
+bool is_pin_inverted(GpioDescriptor* descriptor) {
+    if (!descriptor) return false;
+    gpio_flags_t flags;
+    check(gpio_descriptor_get_flags(descriptor, &flags) == ERROR_NONE);
+    return (flags & GPIO_FLAG_ACTIVE_LOW) != 0;
+}

Platforms/PlatformEsp32/Source/drivers/esp32_i2c.cpp

@@ -1,31 +1,38 @@
 // SPDX-License-Identifier: Apache-2.0
 #include <driver/i2c.h>
 
-#include <tactility/driver.h>
-#include <tactility/drivers/i2c_controller.h>
-#include <tactility/log.h>
+#include <new>
 
-#include <tactility/time.h>
 #include <tactility/error_esp32.h>
+#include <tactility/driver.h>
+#include <tactility/drivers/gpio_controller.h>
+#include <tactility/drivers/i2c_controller.h>
 #include <tactility/drivers/esp32_i2c.h>
+#include <tactility/log.h>
+#include <tactility/time.h>
 
 #define TAG "esp32_i2c"
 #define ACK_CHECK_EN 1
 
-struct Esp32SpiInternal {
-    Mutex mutex { 0 };
+struct Esp32I2cInternal {
+    Mutex mutex {};
+    GpioDescriptor* sda_descriptor = nullptr;
+    GpioDescriptor* scl_descriptor = nullptr;
 
-    Esp32SpiInternal() {
+    Esp32I2cInternal(GpioDescriptor* sda_descriptor, GpioDescriptor* scl_descriptor) :
+        sda_descriptor(sda_descriptor),
+        scl_descriptor(scl_descriptor)
+    {
         mutex_construct(&mutex);
     }
 
-    ~Esp32SpiInternal() {
+    ~Esp32I2cInternal() {
         mutex_destruct(&mutex);
     }
 };
 
 #define GET_CONFIG(device) ((Esp32I2cConfig*)device->config)
-#define GET_DATA(device) ((Esp32SpiInternal*)device_get_driver_data(device))
+#define GET_DATA(device) ((Esp32I2cInternal*)device_get_driver_data(device))
 
 #define lock(data) mutex_lock(&data->mutex);
 #define unlock(data) mutex_unlock(&data->mutex);
@@ -149,12 +156,35 @@ static error_t start(Device* device) {
     ESP_LOGI(TAG, "start %s", device->name);
     auto dts_config = GET_CONFIG(device);
 
+    auto& sda_spec = dts_config->pinSda;
+    auto& scl_spec = dts_config->pinScl;
+    auto* sda_descriptor = gpio_descriptor_acquire(sda_spec.gpio_controller, sda_spec.pin, GPIO_OWNER_GPIO);
+    if (!sda_descriptor) {
+        LOG_E(TAG, "Failed to acquire pin %u", sda_spec.pin);
+        return ERROR_RESOURCE;
+    }
+
+    auto* scl_descriptor = gpio_descriptor_acquire(scl_spec.gpio_controller, scl_spec.pin, GPIO_OWNER_GPIO);
+    if (!scl_descriptor) {
+        LOG_E(TAG, "Failed to acquire pin %u", scl_spec.pin);
+        gpio_descriptor_release(sda_descriptor);
+        return ERROR_RESOURCE;
+    }
+
+    gpio_num_t sda_pin, scl_pin;
+    check(gpio_descriptor_get_native_pin_number(sda_descriptor, &sda_pin) == ERROR_NONE);
+    check(gpio_descriptor_get_native_pin_number(scl_descriptor, &scl_pin) == ERROR_NONE);
+
+    gpio_flags_t sda_flags, scl_flags;
+    check(gpio_descriptor_get_flags(sda_descriptor, &sda_flags) == ERROR_NONE);
+    check(gpio_descriptor_get_flags(scl_descriptor, &scl_flags) == ERROR_NONE);
+
     i2c_config_t esp_config = {
         .mode = I2C_MODE_MASTER,
-        .sda_io_num = dts_config->pinSda,
-        .scl_io_num = dts_config->pinScl,
-        .sda_pullup_en = dts_config->pinSdaPullUp,
-        .scl_pullup_en = dts_config->pinSclPullUp,
+        .sda_io_num = sda_pin,
+        .scl_io_num = scl_pin,
+        .sda_pullup_en = (sda_flags & GPIO_FLAG_PULL_UP) != 0,
+        .scl_pullup_en = (scl_flags & GPIO_FLAG_PULL_UP) != 0,
         .master {
             .clk_speed = dts_config->clockFrequency
         },
@@ -164,22 +194,33 @@ static error_t start(Device* device) {
     esp_err_t error = i2c_param_config(dts_config->port, &esp_config);
     if (error != ESP_OK) {
         LOG_E(TAG, "Failed to configure port %d: %s", static_cast<int>(dts_config->port), esp_err_to_name(error));
+        check(gpio_descriptor_release(sda_descriptor) == ERROR_NONE);
+        check(gpio_descriptor_release(scl_descriptor) == ERROR_NONE);
         return ERROR_RESOURCE;
     }
 
     error = i2c_driver_install(dts_config->port, esp_config.mode, 0, 0, 0);
     if (error != ESP_OK) {
         LOG_E(TAG, "Failed to install driver at port %d: %s", static_cast<int>(dts_config->port), esp_err_to_name(error));
+        check(gpio_descriptor_release(sda_descriptor) == ERROR_NONE);
+        check(gpio_descriptor_release(scl_descriptor) == ERROR_NONE);
         return ERROR_RESOURCE;
     }
-    auto* data = new Esp32SpiInternal();
+
+    auto* data = new(std::nothrow) Esp32I2cInternal(sda_descriptor, scl_descriptor);
+    if (data == nullptr) {
+        check(gpio_descriptor_release(sda_descriptor) == ERROR_NONE);
+        check(gpio_descriptor_release(scl_descriptor) == ERROR_NONE);
+        return ERROR_OUT_OF_MEMORY;
+    }
+
     device_set_driver_data(device, data);
     return ERROR_NONE;
 }
 
 static error_t stop(Device* device) {
     ESP_LOGI(TAG, "stop %s", device->name);
-    auto* driver_data = static_cast<Esp32SpiInternal*>(device_get_driver_data(device));
+    auto* driver_data = static_cast<Esp32I2cInternal*>(device_get_driver_data(device));
 
     i2c_port_t port = GET_CONFIG(device)->port;
     esp_err_t result = i2c_driver_delete(port);
@@ -188,6 +229,9 @@ static error_t stop(Device* device) {
         return ERROR_RESOURCE;
     }
 
+    check(gpio_descriptor_release(driver_data->sda_descriptor) == ERROR_NONE);
+    check(gpio_descriptor_release(driver_data->scl_descriptor) == ERROR_NONE);
+
     device_set_driver_data(device, nullptr);
     delete driver_data;
     return ERROR_NONE;

Platforms/PlatformEsp32/Source/drivers/esp32_i2s.cpp

@@ -3,11 +3,14 @@
 #include <driver/i2s_common.h>
 
 #include <tactility/driver.h>
+#include <tactility/drivers/gpio_controller.h>
+#include <tactility/drivers/gpio_descriptor.h>
 #include <tactility/drivers/i2s_controller.h>
 #include <tactility/log.h>
 
 #include <tactility/time.h>
 #include <tactility/error_esp32.h>
+#include <tactility/drivers/esp32_gpio_helpers.h>
 #include <tactility/drivers/esp32_i2s.h>
 
 #include <new>
@@ -16,21 +19,58 @@
 
 struct Esp32I2sInternal {
     Mutex mutex {};
-    i2s_chan_handle_t tx_handle = nullptr;
-    i2s_chan_handle_t rx_handle = nullptr;
     I2sConfig config {};
     bool config_set = false;
+    GpioDescriptor* bclk_descriptor = nullptr;
+    GpioDescriptor* ws_descriptor = nullptr;
+    GpioDescriptor* data_out_descriptor = nullptr;
+    GpioDescriptor* data_in_descriptor = nullptr;
+    GpioDescriptor* mclk_descriptor = nullptr;
+    i2s_chan_handle_t tx_handle = nullptr;
+    i2s_chan_handle_t rx_handle = nullptr;
 
     Esp32I2sInternal() {
         mutex_construct(&mutex);
     }
 
     ~Esp32I2sInternal() {
+        cleanup_pins();
         mutex_destruct(&mutex);
     }
+
+    void cleanup_pins() {
+        release_pin(&bclk_descriptor);
+        release_pin(&ws_descriptor);
+        release_pin(&data_out_descriptor);
+        release_pin(&data_in_descriptor);
+        release_pin(&mclk_descriptor);
+    }
+
+    bool init_pins(Esp32I2sConfig* dts_config) {
+        check (!ws_descriptor && !bclk_descriptor && !data_out_descriptor && !data_in_descriptor && !mclk_descriptor);
+        auto& ws_spec = dts_config->pin_ws;
+        auto& bclk_spec = dts_config->pin_bclk;
+        auto& data_in_spec = dts_config->pin_data_in;
+        auto& data_out_spec = dts_config->pin_data_out;
+        auto& mclk_spec = dts_config->pin_mclk;
+
+        bool success = acquire_pin_or_set_null(ws_spec, &ws_descriptor) &&
+            acquire_pin_or_set_null(bclk_spec, &bclk_descriptor) &&
+            acquire_pin_or_set_null(data_in_spec, &data_in_descriptor) &&
+            acquire_pin_or_set_null(data_out_spec, &data_out_descriptor) &&
+            acquire_pin_or_set_null(mclk_spec, &mclk_descriptor);
+
+        if (!success) {
+            cleanup_pins();
+            LOG_E(TAG, "Failed to acquire all pins");
+            return false;
+        }
+
+        return true;
+    }
 };
 
-#define GET_CONFIG(device) ((Esp32I2sConfig*)device->config)
+#define GET_CONFIG(device) ((Esp32I2sConfig*)(device)->config)
 #define GET_DATA(device) ((Esp32I2sInternal*)device_get_driver_data(device))
 
 #define lock(data) mutex_lock(&data->mutex);
@@ -63,10 +103,10 @@ static i2s_data_bit_width_t to_esp32_bits_per_sample(uint8_t bits) {
     }
 }
 
-static void get_esp32_std_config(const I2sConfig* config, const Esp32I2sConfig* dts_config, i2s_std_config_t* std_cfg) {
+static void get_esp32_std_config(Esp32I2sInternal* internal, const I2sConfig* config, i2s_std_config_t* std_cfg) {
     std_cfg->clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG(config->sample_rate);
     std_cfg->slot_cfg = I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(to_esp32_bits_per_sample(config->bits_per_sample), I2S_SLOT_MODE_STEREO);
-    
+
     if (config->communication_format & I2S_FORMAT_STAND_MSB) {
         std_cfg->slot_cfg = I2S_STD_MSB_SLOT_DEFAULT_CONFIG(to_esp32_bits_per_sample(config->bits_per_sample), I2S_SLOT_MODE_STEREO);
     } else if (config->communication_format & (I2S_FORMAT_STAND_PCM_SHORT | I2S_FORMAT_STAND_PCM_LONG)) {
@@ -81,16 +121,28 @@ static void get_esp32_std_config(const I2sConfig* config, const Esp32I2sConfig*
         std_cfg->slot_cfg.slot_mask = I2S_STD_SLOT_BOTH;
     }
 
+    gpio_num_t mclk_pin = get_native_pin(internal->mclk_descriptor);
+    gpio_num_t bclk_pin = get_native_pin(internal->bclk_descriptor);
+    gpio_num_t ws_pin = get_native_pin(internal->ws_descriptor);
+    gpio_num_t data_out_pin = get_native_pin(internal->data_out_descriptor);
+    gpio_num_t data_in_pin = get_native_pin(internal->data_in_descriptor);
+    LOG_I(TAG, "Configuring I2S pins: MCLK=%d, BCLK=%d, WS=%d, DATA_OUT=%d, DATA_IN=%d", mclk_pin, bclk_pin, ws_pin, data_out_pin, data_in_pin);
+
+    bool mclk_inverted = is_pin_inverted(internal->mclk_descriptor);
+    bool bclk_inverted = is_pin_inverted(internal->bclk_descriptor);
+    bool ws_inverted = is_pin_inverted(internal->ws_descriptor);
+    LOG_I(TAG, "Inverted pins: MCLK=%u, BCLK=%u, WS=%u", mclk_inverted, bclk_inverted, ws_inverted);
+
     std_cfg->gpio_cfg = {
-        .mclk = (gpio_num_t)dts_config->pin_mclk,
-        .bclk = (gpio_num_t)dts_config->pin_bclk,
-        .ws = (gpio_num_t)dts_config->pin_ws,
-        .dout = (gpio_num_t)dts_config->pin_data_out,
-        .din = (gpio_num_t)dts_config->pin_data_in,
+        .mclk = mclk_pin,
+        .bclk = bclk_pin,
+        .ws = ws_pin,
+        .dout = data_out_pin,
+        .din = data_in_pin,
         .invert_flags = {
-            .mclk_inv = false,
-            .bclk_inv = false,
-            .ws_inv = false
+            .mclk_inv = mclk_inverted,
+            .bclk_inv = bclk_inverted,
+            .ws_inv = ws_inverted
         }
     };
 }
@@ -129,46 +181,46 @@ static error_t set_config(Device* device, const struct I2sConfig* config) {
         return ERROR_INVALID_ARGUMENT;
     }
 
-    auto* driver_data = GET_DATA(device);
+    auto* internal = GET_DATA(device);
     auto* dts_config = GET_CONFIG(device);
-    lock(driver_data);
+    lock(internal);
 
-    cleanup_channel_handles(driver_data);
-    driver_data->config_set = false;
+    cleanup_channel_handles(internal);
+    internal->config_set = false;
 
     // Create new channel handles
     i2s_chan_config_t chan_cfg = I2S_CHANNEL_DEFAULT_CONFIG(dts_config->port, I2S_ROLE_MASTER);
-    esp_err_t esp_error = i2s_new_channel(&chan_cfg, &driver_data->tx_handle, &driver_data->rx_handle);
+    esp_err_t esp_error = i2s_new_channel(&chan_cfg, &internal->tx_handle, &internal->rx_handle);
     if (esp_error != ESP_OK) {
         LOG_E(TAG, "Failed to create I2S channels: %s", esp_err_to_name(esp_error));
-        unlock(driver_data);
+        unlock(internal);
         return ERROR_RESOURCE;
     }
 
-    i2s_std_config_t std_cfg;
-    get_esp32_std_config(config, dts_config, &std_cfg);
+    i2s_std_config_t std_cfg = {};
+    get_esp32_std_config(internal, config, &std_cfg);
 
-    if (driver_data->tx_handle) {
-        esp_error = i2s_channel_init_std_mode(driver_data->tx_handle, &std_cfg);
-        if (esp_error == ESP_OK) esp_error = i2s_channel_enable(driver_data->tx_handle);
+    if (internal->tx_handle) {
+        esp_error = i2s_channel_init_std_mode(internal->tx_handle, &std_cfg);
+        if (esp_error == ESP_OK) esp_error = i2s_channel_enable(internal->tx_handle);
     }
-    if (esp_error == ESP_OK && driver_data->rx_handle) {
-        esp_error = i2s_channel_init_std_mode(driver_data->rx_handle, &std_cfg);
-        if (esp_error == ESP_OK) esp_error = i2s_channel_enable(driver_data->rx_handle);
+    if (esp_error == ESP_OK && internal->rx_handle) {
+        esp_error = i2s_channel_init_std_mode(internal->rx_handle, &std_cfg);
+        if (esp_error == ESP_OK) esp_error = i2s_channel_enable(internal->rx_handle);
     }
 
     if (esp_error != ESP_OK) {
         LOG_E(TAG, "Failed to initialize/enable I2S channels: %s", esp_err_to_name(esp_error));
-        cleanup_channel_handles(driver_data);
-        unlock(driver_data);
+        cleanup_channel_handles(internal);
+        unlock(internal);
         return esp_err_to_error(esp_error);
     }
 
     // Update runtime config to reflect current state
-    memcpy(&driver_data->config, config, sizeof(I2sConfig));
-    driver_data->config_set = true;
+    memcpy(&internal->config, config, sizeof(I2sConfig));
+    internal->config_set = true;
 
-    unlock(driver_data);
+    unlock(internal);
     return ERROR_NONE;
 }
 
@@ -188,9 +240,18 @@ static error_t get_config(Device* device, struct I2sConfig* config) {
 
 static error_t start(Device* device) {
     ESP_LOGI(TAG, "start %s", device->name);
+
+    auto* dts_config = GET_CONFIG(device);
+
     auto* data = new(std::nothrow) Esp32I2sInternal();
     if (!data) return ERROR_OUT_OF_MEMORY;
 
+    if (!data->init_pins(dts_config)) {
+        LOG_E(TAG, "Failed to init one or more pins");
+        delete data;
+        return ERROR_RESOURCE;
+    }
+
     device_set_driver_data(device, data);
 
     return ERROR_NONE;

Platforms/PlatformEsp32/Source/drivers/esp32_spi.cpp

@@ -3,6 +3,8 @@
 #include <tactility/drivers/esp32_spi.h>
 #include <tactility/concurrent/recursive_mutex.h>
 
+#include "tactility/drivers/gpio_descriptor.h"
+#include <tactility/drivers/esp32_gpio_helpers.h>
 #include <cstring>
 #include <esp_log.h>
 #include <new>
@@ -19,13 +21,29 @@ struct Esp32SpiInternal {
     RecursiveMutex mutex = {};
     bool initialized = false;
 
-    Esp32SpiInternal() {
+    // Pin descriptors
+    GpioDescriptor* sclk_descriptor = nullptr;
+    GpioDescriptor* mosi_descriptor = nullptr;
+    GpioDescriptor* miso_descriptor = nullptr;
+    GpioDescriptor* wp_descriptor = nullptr;
+    GpioDescriptor* hd_descriptor = nullptr;
+
+    explicit Esp32SpiInternal() {
         recursive_mutex_construct(&mutex);
     }
 
     ~Esp32SpiInternal() {
+        cleanup_pins();
         recursive_mutex_destruct(&mutex);
     }
+
+    void cleanup_pins() {
+        release_pin(&sclk_descriptor);
+        release_pin(&mosi_descriptor);
+        release_pin(&miso_descriptor);
+        release_pin(&wp_descriptor);
+        release_pin(&hd_descriptor);
+    }
 };
 
 static error_t lock(Device* device) {
@@ -50,19 +68,35 @@ static error_t unlock(Device* device) {
 
 static error_t start(Device* device) {
     ESP_LOGI(TAG, "start %s", device->name);
-    auto* data = new(std::nothrow) Esp32SpiInternal();
+    auto* data = new (std::nothrow) Esp32SpiInternal();
     if (!data) return ERROR_OUT_OF_MEMORY;
 
     device_set_driver_data(device, data);
 
     auto* dts_config = GET_CONFIG(device);
 
+    // Acquire pins from the specified GPIO pin specs. Optional pins are allowed.
+    bool pins_ok =
+        acquire_pin_or_set_null(dts_config->pin_sclk, &data->sclk_descriptor) &&
+        acquire_pin_or_set_null(dts_config->pin_mosi, &data->mosi_descriptor) &&
+        acquire_pin_or_set_null(dts_config->pin_miso, &data->miso_descriptor) &&
+        acquire_pin_or_set_null(dts_config->pin_wp, &data->wp_descriptor) &&
+        acquire_pin_or_set_null(dts_config->pin_hd, &data->hd_descriptor);
+
+    if (!pins_ok) {
+        ESP_LOGE(TAG, "Failed to acquire required SPI pins");
+        data->cleanup_pins();
+        device_set_driver_data(device, nullptr);
+        delete data;
+        return ERROR_RESOURCE;
+    }
+
     spi_bus_config_t buscfg = {
-        .mosi_io_num = dts_config->pin_mosi,
-        .miso_io_num = dts_config->pin_miso,
-        .sclk_io_num = dts_config->pin_sclk,
-        .data2_io_num = dts_config->pin_wp,
-        .data3_io_num = dts_config->pin_hd,
+        .mosi_io_num = get_native_pin(data->mosi_descriptor),
+        .miso_io_num = get_native_pin(data->miso_descriptor),
+        .sclk_io_num = get_native_pin(data->sclk_descriptor),
+        .data2_io_num = get_native_pin(data->wp_descriptor),
+        .data3_io_num = get_native_pin(data->hd_descriptor),
         .data4_io_num = GPIO_NUM_NC,
         .data5_io_num = GPIO_NUM_NC,
         .data6_io_num = GPIO_NUM_NC,
@@ -76,8 +110,9 @@ static error_t start(Device* device) {
 
     esp_err_t ret = spi_bus_initialize(dts_config->host, &buscfg, SPI_DMA_CH_AUTO);
     if (ret != ESP_OK) {
-        delete data;
+        data->cleanup_pins();
         device_set_driver_data(device, nullptr);
+        delete data;
         ESP_LOGE(TAG, "Failed to initialize SPI bus: %s", esp_err_to_name(ret));
         return ERROR_RESOURCE;
     }
@@ -95,6 +130,7 @@ static error_t stop(Device* device) {
         spi_bus_free(dts_config->host);
     }
 
+    driver_data->cleanup_pins();
     device_set_driver_data(device, nullptr);
     delete driver_data;
     return ERROR_NONE;

Platforms/PlatformEsp32/Source/drivers/esp32_uart.cpp

@@ -9,6 +9,8 @@
 #include <tactility/error_esp32.h>
 #include <tactility/log.h>
 #include <tactility/time.h>
+#include <tactility/drivers/gpio_descriptor.h>
+#include <tactility/drivers/esp32_gpio_helpers.h>
 
 #include <new>
 
@@ -20,13 +22,27 @@ struct Esp32UartInternal {
     bool config_set = false;
     bool is_open = false;
 
+    // Pin descriptors
+    GpioDescriptor* tx_descriptor = nullptr;
+    GpioDescriptor* rx_descriptor = nullptr;
+    GpioDescriptor* cts_descriptor = nullptr;
+    GpioDescriptor* rts_descriptor = nullptr;
+
     Esp32UartInternal() {
         mutex_construct(&mutex);
     }
 
     ~Esp32UartInternal() {
+        cleanup_pins();
         mutex_destruct(&mutex);
     }
+
+    void cleanup_pins() {
+        release_pin(&tx_descriptor);
+        release_pin(&rx_descriptor);
+        release_pin(&cts_descriptor);
+        release_pin(&rts_descriptor);
+    }
 };
 
 #define GET_CONFIG(device) ((Esp32UartConfig*)device->config)
@@ -254,7 +270,7 @@ static error_t open(Device* device) {
         }
     };
 
-    if (dts_config->pinCts != UART_PIN_NO_CHANGE || dts_config->pinRts != UART_PIN_NO_CHANGE) {
+    if (dts_config->pin_cts.gpio_controller != nullptr || dts_config->pin_rts.gpio_controller != nullptr) {
         LOG_W(TAG, "%s: CTS/RTS pins are defined but hardware flow control is disabled (not supported in UartConfig)", device->name);
     }
 
@@ -266,9 +282,31 @@ static error_t open(Device* device) {
         return ERROR_RESOURCE;
     }
 
-    esp_error = uart_set_pin(dts_config->port, dts_config->pinTx, dts_config->pinRx, dts_config->pinCts, dts_config->pinRts);
+    // Acquire pins from the specified GPIO pin specs. Optional pins are allowed.
+    bool pins_ok =
+        acquire_pin_or_set_null(dts_config->pin_tx, &driver_data->tx_descriptor) &&
+        acquire_pin_or_set_null(dts_config->pin_rx, &driver_data->rx_descriptor) &&
+        acquire_pin_or_set_null(dts_config->pin_cts, &driver_data->cts_descriptor) &&
+        acquire_pin_or_set_null(dts_config->pin_rts, &driver_data->rts_descriptor);
+
+    if (!pins_ok) {
+        LOG_E(TAG, "%s failed to acquire UART pins", device->name);
+        driver_data->cleanup_pins();
+        uart_driver_delete(dts_config->port);
+        unlock(driver_data);
+        return ERROR_RESOURCE;
+    }
+
+    esp_error = uart_set_pin(dts_config->port,
+        get_native_pin(driver_data->tx_descriptor),
+        get_native_pin(driver_data->rx_descriptor),
+        get_native_pin(driver_data->rts_descriptor),
+        get_native_pin(driver_data->cts_descriptor)
+    );
+
     if (esp_error != ESP_OK) {
         LOG_E(TAG, "%s failed to set uart pins: %s", device->name, esp_err_to_name(esp_error));
+        driver_data->cleanup_pins();
         uart_driver_delete(dts_config->port);
         unlock(driver_data);
         return ERROR_RESOURCE;
@@ -293,6 +331,7 @@ static error_t close(Device* device) {
         return ERROR_INVALID_STATE;
     }
     uart_driver_delete(dts_config->port);
+    driver_data->cleanup_pins();
     driver_data->is_open = false;
     unlock(driver_data);