sleep.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 <concepts>
#include <cstdint>
#include <initializer_list>
#include <optional>
#include <soc/soc_caps.h>
#include <string>
#include <type_traits>
 
namespace idfxx::sleep {
 
enum class wakeup_source : int {
    // clang-format off
    ext0       = 2,  
    ext1       = 3,  
    timer      = 4,  
    touchpad   = 5,  
    ulp        = 6,  
    gpio       = 7,  
    uart       = 8,  
    wifi       = 9,  
    cocpu      = 10, 
    cocpu_trap = 11, 
    bt         = 12, 
    other      = 13, 
    // clang-format on
};
 
[[nodiscard]] std::string to_string(wakeup_source source);
 
// =============================================================================
// Wake-up source specifications
// =============================================================================
 
struct timer_wake {
    std::chrono::microseconds after; 
};
 
struct gpio_wake {
    idfxx::gpio pin;          
    idfxx::gpio::level level; 
};
 
#if SOC_PM_SUPPORT_EXT0_WAKEUP
struct ext0_wake {
    idfxx::gpio pin;          
    idfxx::gpio::level level; 
};
#endif // SOC_PM_SUPPORT_EXT0_WAKEUP
 
namespace detail {
 
constexpr uint64_t pin_mask_of(std::initializer_list<idfxx::gpio> pins) noexcept {
    uint64_t mask = 0;
    for (const auto& pin : pins) {
        if (!pin.is_connected()) {
            return 0;
        }
        mask |= uint64_t{1} << static_cast<unsigned>(pin.num());
    }
    return mask;
}
 
} // namespace detail
 
#if SOC_PM_SUPPORT_EXT1_WAKEUP
enum class ext1_mode : int {
#if CONFIG_IDF_TARGET_ESP32
    all_low = 0, 
#else
    any_low = 0, 
#endif
    any_high = 1, 
};
 
class ext1_wake {
public:
    constexpr ext1_wake(std::initializer_list<idfxx::gpio> pins, enum ext1_mode mode) noexcept
        : _pin_mask(detail::pin_mask_of(pins))
        , _mode(mode) {}
 
    constexpr ext1_wake(uint64_t pin_mask, enum ext1_mode mode) noexcept
        : _pin_mask(pin_mask)
        , _mode(mode) {}
 
    [[nodiscard]] constexpr uint64_t pin_mask() const noexcept { return _pin_mask; }
 
    [[nodiscard]] constexpr enum ext1_mode mode() const noexcept { return _mode; }
 
private:
    uint64_t _pin_mask;
    enum ext1_mode _mode;
};
#endif // SOC_PM_SUPPORT_EXT1_WAKEUP
 
#if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
enum class deep_sleep_gpio_mode : int {
    wake_low = 0,  
    wake_high = 1, 
};
 
class deep_sleep_gpio_wake {
public:
    constexpr deep_sleep_gpio_wake(std::initializer_list<idfxx::gpio> pins, deep_sleep_gpio_mode mode) noexcept
        : _pin_mask(detail::pin_mask_of(pins))
        , _mode(mode) {}
 
    constexpr deep_sleep_gpio_wake(uint64_t pin_mask, deep_sleep_gpio_mode mode) noexcept
        : _pin_mask(pin_mask)
        , _mode(mode) {}
 
    [[nodiscard]] constexpr uint64_t pin_mask() const noexcept { return _pin_mask; }
 
    [[nodiscard]] constexpr deep_sleep_gpio_mode mode() const noexcept { return _mode; }
 
private:
    uint64_t _pin_mask;
    deep_sleep_gpio_mode _mode;
};
#endif // SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
 
namespace detail {
 
[[nodiscard]] result<void> arm(const timer_wake& source);
void disarm(const timer_wake& source) noexcept;
[[nodiscard]] result<void> arm(const gpio_wake& source);
void disarm(const gpio_wake& source) noexcept;
#if SOC_PM_SUPPORT_EXT0_WAKEUP
[[nodiscard]] result<void> arm(const ext0_wake& source);
void disarm(const ext0_wake& source) noexcept;
#endif
#if SOC_PM_SUPPORT_EXT1_WAKEUP
[[nodiscard]] result<void> arm(const ext1_wake& source);
void disarm(const ext1_wake& source) noexcept;
#endif
#if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
[[nodiscard]] result<void> arm(const deep_sleep_gpio_wake& source);
void disarm(const deep_sleep_gpio_wake& source) noexcept;
#endif
 
[[nodiscard]] result<wakeup_source> do_light_sleep();
[[noreturn]] void do_deep_sleep() noexcept;
 
template<typename... Sources>
[[nodiscard]] result<void> arm_all(const Sources&... sources) {
    result<void> r{};
    ((r = arm(sources)) && ...);
    return r;
}
 
template<typename... Sources>
void disarm_all(const Sources&... sources) noexcept {
    (disarm(sources), ...);
}
 
} // namespace detail
 
template<typename T>
concept wake_spec = requires(const std::remove_cvref_t<T>& source) {
    { detail::arm(source) } -> std::same_as<result<void>>;
    detail::disarm(source);
};
 
// =============================================================================
// Entering sleep
// =============================================================================
 
template<wake_spec... Sources>
[[nodiscard]] result<wakeup_source> try_light_sleep(const Sources&... sources);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
template<wake_spec... Sources>
[[nodiscard]] wakeup_source light_sleep(const Sources&... sources) {
    return unwrap(try_light_sleep(sources...));
}
#endif
 
template<wake_spec... Sources>
[[nodiscard]] result<wakeup_source> try_light_sleep(const Sources&... sources) {
    if (auto armed = detail::arm_all(sources...); !armed) {
        detail::disarm_all(sources...);
        return error(armed.error());
    }
    auto cause = detail::do_light_sleep();
    detail::disarm_all(sources...);
    return cause;
}
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
[[nodiscard]] wakeup_source light_sleep_for(std::chrono::microseconds duration);
#endif
 
[[nodiscard]] result<wakeup_source> try_light_sleep_for(std::chrono::microseconds duration);
 
template<wake_spec First, wake_spec... Rest>
[[nodiscard]] result<void> try_deep_sleep(const First& first, const Rest&... rest);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
template<wake_spec First, wake_spec... Rest>
[[noreturn]] void deep_sleep(const First& first, const Rest&... rest) {
    unwrap(try_deep_sleep(first, rest...));
    detail::do_deep_sleep(); // unreachable: try_deep_sleep only returns on failure
}
#endif
 
template<wake_spec First, wake_spec... Rest>
[[nodiscard]] result<void> try_deep_sleep(const First& first, const Rest&... rest) {
    if (auto armed = detail::arm_all(first, rest...); !armed) {
        detail::disarm_all(first, rest...);
        return error(armed.error());
    }
    detail::do_deep_sleep();
}
 
[[noreturn]] void deep_sleep() noexcept;
 
[[noreturn]] void deep_sleep(std::chrono::microseconds duration) noexcept;
 
// =============================================================================
// Status
// =============================================================================
 
[[nodiscard]] std::optional<wakeup_source> wakeup_cause() noexcept;
 
#if SOC_PM_SUPPORT_EXT1_WAKEUP
[[nodiscard]] uint64_t ext1_wakeup_status() noexcept;
#endif
 
// =============================================================================
// Persistent wake-up source configuration
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
template<wake_spec Source>
void enable_wakeup(const Source& source) {
    unwrap(detail::arm(source));
}
#endif
 
template<wake_spec Source>
[[nodiscard]] result<void> try_enable_wakeup(const Source& source) {
    return detail::arm(source);
}
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void disable_wakeup_source(wakeup_source source);
 
void disable_all_wakeup_sources();
#endif
 
result<void> try_disable_wakeup_source(wakeup_source source);
 
result<void> try_disable_all_wakeup_sources();
 
} // namespace idfxx::sleep
 
#include "sdkconfig.h"
#ifdef CONFIG_IDFXX_STD_FORMAT
#include <algorithm>
#include <format>
namespace std {
template<>
struct formatter<idfxx::sleep::wakeup_source> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::sleep::wakeup_source source, FormatContext& ctx) const {
        auto s = to_string(source);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
} // namespace std
#endif // CONFIG_IDFXX_STD_FORMAT