gpio.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/flags>
#include <idfxx/intr_alloc>
 
#include <esp_idf_version.h>
#include <functional>
#include <hal/gpio_types.h>
#include <soc/gpio_num.h>
#include <soc/soc_caps.h>
#include <string>
#include <utility>
 
namespace idfxx {
 
template<int N>
struct gpio_constant;
class gpio {
    template<int N>
    friend struct gpio_constant;
 
public:
    enum class level : int {
        low = 0,  
        high = 1, 
    };
 
    enum class mode : int {
        disable = GPIO_MODE_DISABLE,                 
        input = GPIO_MODE_INPUT,                     
        output = GPIO_MODE_OUTPUT,                   
        output_od = GPIO_MODE_OUTPUT_OD,             
        input_output_od = GPIO_MODE_INPUT_OUTPUT_OD, 
        input_output = GPIO_MODE_INPUT_OUTPUT,       
    };
 
    enum class pull_mode : int {
        pullup = GPIO_PULLUP_ONLY,              
        pulldown = GPIO_PULLDOWN_ONLY,          
        pullup_pulldown = GPIO_PULLUP_PULLDOWN, 
        floating = GPIO_FLOATING,               
    };
 
    enum class drive_cap : int {
        cap_0 = GPIO_DRIVE_CAP_0,             
        cap_1 = GPIO_DRIVE_CAP_1,             
        cap_2 = GPIO_DRIVE_CAP_2,             
        cap_default = GPIO_DRIVE_CAP_DEFAULT, 
        cap_3 = GPIO_DRIVE_CAP_3,             
    };
 
    enum class intr_type : int {
        disable = GPIO_INTR_DISABLE,       
        posedge = GPIO_INTR_POSEDGE,       
        negedge = GPIO_INTR_NEGEDGE,       
        anyedge = GPIO_INTR_ANYEDGE,       
        low_level = GPIO_INTR_LOW_LEVEL,   
        high_level = GPIO_INTR_HIGH_LEVEL, 
    };
 
#if SOC_GPIO_SUPPORT_PIN_HYS_FILTER
    enum class hys_ctrl_mode : int {
#if SOC_GPIO_SUPPORT_PIN_HYS_CTRL_BY_EFUSE
        efuse = GPIO_HYS_CTRL_EFUSE, 
#endif
        soft_disable = GPIO_HYS_CTRL_SOFT_DISABLE, 
        soft_enable = GPIO_HYS_CTRL_SOFT_ENABLE,   
    };
#endif
 
    class unique_isr_handle;
 
    class isr_handle {
        friend class gpio;
        friend class unique_isr_handle;
        constexpr isr_handle(gpio_num_t num, uint32_t id)
            : _num(num)
            , _id(id) {}
        gpio_num_t _num;
        uint32_t _id;
    };
 
    class unique_isr_handle {
    public:
        explicit unique_isr_handle() noexcept
            : _num(GPIO_NUM_NC)
            , _id(0) {}
 
        explicit unique_isr_handle(isr_handle handle) noexcept
            : _num(handle._num)
            , _id(handle._id) {}
 
        unique_isr_handle(unique_isr_handle&& other) noexcept
            : _num(std::exchange(other._num, GPIO_NUM_NC))
            , _id(other._id) {}
 
        unique_isr_handle& operator=(unique_isr_handle&& other) noexcept {
            if (this != &other) {
                if (_num != GPIO_NUM_NC) {
                    gpio{_num}.try_isr_handler_remove(isr_handle{_num, _id});
                }
                _num = std::exchange(other._num, GPIO_NUM_NC);
                _id = other._id;
            }
            return *this;
        }
 
        unique_isr_handle(const unique_isr_handle&) = delete;
        unique_isr_handle& operator=(const unique_isr_handle&) = delete;
 
        ~unique_isr_handle() {
            if (_num != GPIO_NUM_NC) {
                // Removing the ISR handler will not fail, so we can ignore the result
                gpio{_num}.try_isr_handler_remove(isr_handle{_num, _id});
            }
        }
 
        [[nodiscard]] isr_handle release() noexcept {
            auto handle = isr_handle{_num, _id};
            _num = GPIO_NUM_NC;
            return handle;
        }
 
    private:
        gpio_num_t _num;
        uint32_t _id;
    };
 
    struct config {
        enum mode mode = mode::disable;
        enum pull_mode pull_mode = pull_mode::floating;
        enum intr_type intr_type = intr_type::disable;
#if SOC_GPIO_SUPPORT_PIN_HYS_FILTER
        enum hys_ctrl_mode hys_ctrl_mode = hys_ctrl_mode::soft_disable;
#endif
    };
 
public:
    constexpr gpio()
        : _num(GPIO_NUM_NC) {}
 
    [[nodiscard]] static result<gpio> make(int num);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit gpio(int num);
#endif
 
    [[nodiscard]] static constexpr gpio nc() { return gpio{GPIO_NUM_NC}; }
 
    [[nodiscard]] static constexpr gpio max() { return gpio{static_cast<gpio_num_t>(GPIO_NUM_MAX - 1)}; }
 
    // Copyable and movable
    gpio(const gpio&) = default;
    gpio(gpio&&) = default;
    gpio& operator=(const gpio&) = default;
    gpio& operator=(gpio&&) = default;
 
    [[nodiscard]] constexpr bool operator==(const gpio&) const noexcept = default;
 
    [[nodiscard]] constexpr bool is_connected() const { return _num != GPIO_NUM_NC && _is_valid_gpio_num(_num); }
 
    [[nodiscard]] constexpr bool is_output_capable() const { return _is_valid_output_gpio_num(_num); }
 
    [[nodiscard]] constexpr bool is_digital_io_pin_capable() const { return _is_valid_digital_io_gpio_num(_num); }
 
    [[nodiscard]] constexpr int num() const { return static_cast<int>(_num); }
 
    [[nodiscard]] constexpr gpio_num_t idf_num() const { return _num; }
 
    void reset();
 
    // Direction and pull configuration
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_direction(enum mode mode) { unwrap(try_set_direction(mode)); }
    void set_pull_mode(enum pull_mode mode) { unwrap(try_set_pull_mode(mode)); }
    void pullup_enable() { unwrap(try_pullup_enable()); }
    void pullup_disable() { unwrap(try_pullup_disable()); }
    void pulldown_enable() { unwrap(try_pulldown_enable()); }
    void pulldown_disable() { unwrap(try_pulldown_disable()); }
#endif
    result<void> try_set_direction(enum mode mode);
    void input_enable();
 
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
    void output_enable();
 
    void output_disable();
 
    void od_enable();
 
    void od_disable();
#endif
 
    struct state {
        bool input_enabled;            
        bool output_enabled;           
        bool open_drain;               
        bool pullup_enabled;           
        bool pulldown_enabled;         
        enum drive_cap drive_strength; 
    };
 
    [[nodiscard]] state get_state() const;
 
    result<void> try_set_pull_mode(enum pull_mode mode);
    result<void> try_pullup_enable();
    result<void> try_pullup_disable();
    result<void> try_pulldown_enable();
    result<void> try_pulldown_disable();
 
    // Level (input/output)
    void set_level(enum level level);
    [[nodiscard]] enum level get_level() const;
    void toggle_level();
 
    // Drive capability
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_drive_capability(enum drive_cap strength) { unwrap(try_set_drive_capability(strength)); }
    [[nodiscard]] enum drive_cap get_drive_capability() const { return unwrap(try_get_drive_capability()); }
#endif
    result<void> try_set_drive_capability(enum drive_cap strength);
    result<drive_cap> try_get_drive_capability() const;
 
    // ISR service (must be installed before adding handlers)
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    static void install_isr_service(idfxx::intr_levels levels = intr_level_lowmed, idfxx::flags<intr_flag> flags = {}) {
        unwrap(try_install_isr_service(levels, flags));
    }
    static void install_isr_service(idfxx::flags<intr_flag> flags) { unwrap(try_install_isr_service(flags)); }
#endif
    [[nodiscard]] static result<void>
    try_install_isr_service(idfxx::intr_levels levels = intr_level_lowmed, idfxx::flags<intr_flag> flags = {});
    [[nodiscard]] static result<void> try_install_isr_service(idfxx::flags<intr_flag> flags) {
        return try_install_isr_service(intr_level_lowmed, flags);
    }
    static void uninstall_isr_service();
 
    // ISR handlers
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    isr_handle isr_handler_add(std::move_only_function<void() const> handler) {
        return unwrap(try_isr_handler_add(std::move(handler)));
    }
    isr_handle isr_handler_add(void (*fn)(void*), void* arg) { return unwrap(try_isr_handler_add(fn, arg)); }
    void isr_handler_remove(isr_handle handle) { unwrap(try_isr_handler_remove(handle)); }
#endif
    result<isr_handle> try_isr_handler_add(std::move_only_function<void() const> handler);
    result<isr_handle> try_isr_handler_add(void (*fn)(void*), void* arg);
    result<void> try_isr_handler_remove(isr_handle handle);
    void isr_handler_remove_all();
 
    // Interrupt configuration
    void set_intr_type(enum intr_type intr_type);
    void intr_enable();
    void intr_disable();
 
    // Wakeup configuration
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void wakeup_enable(enum intr_type intr_type) { unwrap(try_wakeup_enable(intr_type)); }
    void wakeup_disable() { unwrap(try_wakeup_disable()); }
#endif
    result<void> try_wakeup_enable(enum intr_type intr_type);
    result<void> try_wakeup_disable();
 
    // Hold configuration (maintains state during sleep/reset)
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void hold_enable() { unwrap(try_hold_enable()); }
    void hold_disable() { unwrap(try_hold_disable()); }
#endif
    result<void> try_hold_enable();
    result<void> try_hold_disable();
#if !SOC_GPIO_SUPPORT_HOLD_SINGLE_IO_IN_DSLP
    static void deep_sleep_hold_enable();
    static void deep_sleep_hold_disable();
#endif
 
    // Sleep mode configuration
    void sleep_sel_enable();
    void sleep_sel_disable();
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void sleep_set_direction(enum mode mode) { unwrap(try_sleep_set_direction(mode)); }
#endif
    result<void> try_sleep_set_direction(enum mode mode);
    void sleep_set_pull_mode(enum pull_mode pull);
 
private:
    constexpr gpio(gpio_num_t num)
        : _num(num) {}
 
    static constexpr bool _is_valid_gpio_num(int num) {
        return num >= 0 && num < GPIO_NUM_MAX && (SOC_GPIO_VALID_GPIO_MASK & (1ULL << num));
    }
    static constexpr bool _is_valid_output_gpio_num(int num) {
        return num >= 0 && num < GPIO_NUM_MAX && (SOC_GPIO_VALID_OUTPUT_GPIO_MASK & (1ULL << num));
    }
    static constexpr bool _is_valid_digital_io_gpio_num(int num) {
        return num >= 0 && num < GPIO_NUM_MAX && (SOC_GPIO_VALID_DIGITAL_IO_PAD_MASK & (1ULL << num));
    }
 
    gpio_num_t _num;
};
 
[[nodiscard]] result<void> try_configure_gpios(const gpio::config& cfg, std::vector<gpio> gpios);
template<typename... Gpios>
[[nodiscard]] result<void> try_configure_gpios(const gpio::config& cfg, Gpios&&... gpios) {
    return try_configure_gpios(cfg, std::vector<gpio>{std::forward<Gpios>(gpios)...});
}
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
inline void configure_gpios(const gpio::config& cfg, std::vector<gpio> gpios) {
    unwrap(try_configure_gpios(cfg, std::move(gpios)));
}
template<typename... Gpios>
void configure_gpios(const gpio::config& cfg, Gpios&&... gpios) {
    unwrap(try_configure_gpios(cfg, std::vector<gpio>{std::forward<Gpios>(gpios)...}));
}
#endif
 
#if SOC_GPIO_SUPPORT_FORCE_HOLD
void force_hold_all_gpios();
 
void force_unhold_all_gpios();
#endif // SOC_GPIO_SUPPORT_FORCE_HOLD
 
/* Validates at compile time that the GPIO number is valid.
 * Used internally to create the predefined GPIO constants.
 */
template<int N>
struct gpio_constant {
    static_assert(N == GPIO_NUM_NC || gpio::_is_valid_gpio_num(N), "Invalid GPIO number");
    static constexpr gpio value{static_cast<gpio_num_t>(N)};
};
inline constexpr gpio gpio_nc = gpio_constant<GPIO_NUM_NC>::value;
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 0))
inline constexpr gpio gpio_0 = gpio_constant<0>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 1))
inline constexpr gpio gpio_1 = gpio_constant<1>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 2))
inline constexpr gpio gpio_2 = gpio_constant<2>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 3))
inline constexpr gpio gpio_3 = gpio_constant<3>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 4))
inline constexpr gpio gpio_4 = gpio_constant<4>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 5))
inline constexpr gpio gpio_5 = gpio_constant<5>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 6))
inline constexpr gpio gpio_6 = gpio_constant<6>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 7))
inline constexpr gpio gpio_7 = gpio_constant<7>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 8))
inline constexpr gpio gpio_8 = gpio_constant<8>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 9))
inline constexpr gpio gpio_9 = gpio_constant<9>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 10))
inline constexpr gpio gpio_10 = gpio_constant<10>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 11))
inline constexpr gpio gpio_11 = gpio_constant<11>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 12))
inline constexpr gpio gpio_12 = gpio_constant<12>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 13))
inline constexpr gpio gpio_13 = gpio_constant<13>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 14))
inline constexpr gpio gpio_14 = gpio_constant<14>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 15))
inline constexpr gpio gpio_15 = gpio_constant<15>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 16))
inline constexpr gpio gpio_16 = gpio_constant<16>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 17))
inline constexpr gpio gpio_17 = gpio_constant<17>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 18))
inline constexpr gpio gpio_18 = gpio_constant<18>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 19))
inline constexpr gpio gpio_19 = gpio_constant<19>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 20))
inline constexpr gpio gpio_20 = gpio_constant<20>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 21))
inline constexpr gpio gpio_21 = gpio_constant<21>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 22))
inline constexpr gpio gpio_22 = gpio_constant<22>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 23))
inline constexpr gpio gpio_23 = gpio_constant<23>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 24))
inline constexpr gpio gpio_24 = gpio_constant<24>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 25))
inline constexpr gpio gpio_25 = gpio_constant<25>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 26))
inline constexpr gpio gpio_26 = gpio_constant<26>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 27))
inline constexpr gpio gpio_27 = gpio_constant<27>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 28))
inline constexpr gpio gpio_28 = gpio_constant<28>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 29))
inline constexpr gpio gpio_29 = gpio_constant<29>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 30))
inline constexpr gpio gpio_30 = gpio_constant<30>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 31))
inline constexpr gpio gpio_31 = gpio_constant<31>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 32))
inline constexpr gpio gpio_32 = gpio_constant<32>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 33))
inline constexpr gpio gpio_33 = gpio_constant<33>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 34))
inline constexpr gpio gpio_34 = gpio_constant<34>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 35))
inline constexpr gpio gpio_35 = gpio_constant<35>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 36))
inline constexpr gpio gpio_36 = gpio_constant<36>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 37))
inline constexpr gpio gpio_37 = gpio_constant<37>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 38))
inline constexpr gpio gpio_38 = gpio_constant<38>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 39))
inline constexpr gpio gpio_39 = gpio_constant<39>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 40))
inline constexpr gpio gpio_40 = gpio_constant<40>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 41))
inline constexpr gpio gpio_41 = gpio_constant<41>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 42))
inline constexpr gpio gpio_42 = gpio_constant<42>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 43))
inline constexpr gpio gpio_43 = gpio_constant<43>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 44))
inline constexpr gpio gpio_44 = gpio_constant<44>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 45))
inline constexpr gpio gpio_45 = gpio_constant<45>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 46))
inline constexpr gpio gpio_46 = gpio_constant<46>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 47))
inline constexpr gpio gpio_47 = gpio_constant<47>::value;
#endif
#if (SOC_GPIO_VALID_GPIO_MASK & (1ULL << 48))
inline constexpr gpio gpio_48 = gpio_constant<48>::value;
#endif
 
 
[[nodiscard]] inline std::string to_string(gpio g) {
    if (!g.is_connected()) {
        return "GPIO_NC";
    }
    return "GPIO_" + std::to_string(g.num());
}
 
[[nodiscard]] inline std::string to_string(gpio::level l) {
    return l == gpio::level::high ? "high" : "low";
}
 
[[nodiscard]] constexpr gpio::level operator~(gpio::level l) noexcept {
    return l == gpio::level::high ? gpio::level::low : gpio::level::high;
}
 
 
} // namespace idfxx
 
#include "sdkconfig.h"
#ifdef CONFIG_IDFXX_STD_FORMAT
#include <algorithm>
#include <format>
namespace std {
template<>
struct formatter<idfxx::gpio> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::gpio g, FormatContext& ctx) const {
        auto s = to_string(g);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
template<>
struct formatter<idfxx::gpio::level> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::gpio::level l, FormatContext& ctx) const {
        auto s = to_string(l);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
} // namespace std
#endif // CONFIG_IDFXX_STD_FORMAT