pwm.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 <idfxx/intr_alloc>
 
#include <algorithm>
#include <chrono>
#include <frequency/frequency>
#include <functional>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <utility>
 
namespace idfxx::pwm {
 
// ======================================================================
// Enums
// ======================================================================
 
enum class speed_mode : int {
    low_speed = 0, 
#if SOC_LEDC_SUPPORT_HS_MODE
    high_speed, 
#endif
};
 
enum class channel : int {
    ch_0 = 0, 
    ch_1,     
    ch_2,     
    ch_3,     
    ch_4,     
    ch_5,     
#if SOC_LEDC_CHANNEL_NUM > 6
    ch_6, 
#endif
#if SOC_LEDC_CHANNEL_NUM > 7
    ch_7, 
#endif
};
 
enum class clk_source : int {
    auto_select = 0, 
#if SOC_LEDC_SUPPORT_APB_CLOCK
    apb, 
#endif
#if SOC_LEDC_SUPPORT_REF_TICK
    ref_tick, 
#endif
#if SOC_LEDC_SUPPORT_PLL_DIV_CLOCK
    pll_div, 
#endif
#if SOC_LEDC_SUPPORT_XTAL_CLOCK
    xtal, 
#endif
};
 
enum class fade_mode : int {
    no_wait = 0, 
    wait_done,   
};
 
enum class sleep_mode : int {
    no_alive_no_pd = 0, 
    no_alive_allow_pd,  
    keep_alive,         
};
 
struct fade_param {
    bool increasing;    
    uint32_t cycle_num; 
    uint32_t scale;     
    uint32_t step_num;  
};
 
// ======================================================================
// Forward declarations
// ======================================================================
 
class output;
struct output_config;
template<int N, speed_mode M>
struct timer_constant;
// ======================================================================
// timer (value type)
// ======================================================================
 
class timer {
    template<int N, speed_mode M>
    friend struct timer_constant;
    friend std::optional<timer> get_timer(enum channel, enum speed_mode);
 
public:
    struct config {
        freq::hertz frequency{0};     
        uint8_t resolution_bits = 13; 
        enum clk_source clk_source = clk_source::auto_select; 
    };
 
    timer(const timer&) = default;
    timer& operator=(const timer&) = default;
    timer(timer&&) = default;
    timer& operator=(timer&&) = default;
 
    constexpr bool operator==(const timer& other) const = default;
 
    [[nodiscard]] constexpr unsigned int num() const noexcept { return _num; }
 
    [[nodiscard]] constexpr enum speed_mode speed_mode() const noexcept { return _speed_mode; }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void configure(const struct config& cfg) { unwrap(try_configure(cfg)); }
 
    void configure(freq::hertz frequency, uint8_t resolution_bits = 13) {
        unwrap(try_configure(frequency, resolution_bits));
    }
#endif
 
    [[nodiscard]] result<void> try_configure(const struct config& cfg);
 
    [[nodiscard]] result<void> try_configure(freq::hertz frequency, uint8_t resolution_bits = 13) {
        return try_configure({.frequency = frequency, .resolution_bits = resolution_bits});
    }
 
    [[nodiscard]] bool is_configured() const noexcept;
 
    [[nodiscard]] uint8_t resolution_bits() const noexcept;
 
    [[nodiscard]] uint32_t ticks_max() const noexcept;
 
    [[nodiscard]] freq::hertz frequency() const;
 
    [[nodiscard]] std::chrono::nanoseconds period() const;
 
    [[nodiscard]] std::chrono::nanoseconds tick_period() const;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_frequency(freq::hertz frequency) { unwrap(try_set_frequency(frequency)); }
#endif
 
    [[nodiscard]] result<void> try_set_frequency(freq::hertz frequency);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename Rep, typename Period>
    void set_period(const std::chrono::duration<Rep, Period>& period) {
        unwrap(try_set_period(period));
    }
#endif
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_set_period(const std::chrono::duration<Rep, Period>& period) {
        auto ns = std::chrono::ceil<std::chrono::nanoseconds>(period).count();
        if (ns <= 0) {
            return error(errc::invalid_arg);
        }
        return try_set_frequency(freq::hertz{1'000'000'000 / ns});
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void pause() { unwrap(try_pause()); }
#endif
 
    [[nodiscard]] result<void> try_pause();
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void resume() { unwrap(try_resume()); }
#endif
 
    [[nodiscard]] result<void> try_resume();
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void reset() { unwrap(try_reset()); }
#endif
 
    [[nodiscard]] result<void> try_reset();
 
private:
    friend result<output> try_start(idfxx::gpio, const config&, const output_config&);
 
    constexpr timer(unsigned int num, enum speed_mode mode) noexcept
        : _num(num)
        , _speed_mode(mode) {}
 
    unsigned int _num;
    enum speed_mode _speed_mode;
};
 
template<int N, speed_mode M>
struct timer_constant {
    static_assert(N >= 0 && N < SOC_LEDC_TIMER_NUM, "Invalid PWM timer number");
    static constexpr timer value{N, M};
};
inline constexpr timer timer_0 = timer_constant<0, speed_mode::low_speed>::value;
inline constexpr timer timer_1 = timer_constant<1, speed_mode::low_speed>::value;
inline constexpr timer timer_2 = timer_constant<2, speed_mode::low_speed>::value;
inline constexpr timer timer_3 = timer_constant<3, speed_mode::low_speed>::value;
 
#if SOC_LEDC_SUPPORT_HS_MODE
inline constexpr timer hs_timer_0 = timer_constant<0, speed_mode::high_speed>::value;
inline constexpr timer hs_timer_1 = timer_constant<1, speed_mode::high_speed>::value;
inline constexpr timer hs_timer_2 = timer_constant<2, speed_mode::high_speed>::value;
inline constexpr timer hs_timer_3 = timer_constant<3, speed_mode::high_speed>::value;
#endif
 
// ======================================================================
// start / try_start — free functions for starting PWM output
// ======================================================================
 
struct output_config {
    float duty = 0.0f;                                       
    int hpoint = 0;                                          
    bool output_invert = false;                              
    enum sleep_mode sleep_mode = sleep_mode::no_alive_no_pd; 
};
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
[[nodiscard]] output start(idfxx::gpio gpio, const timer& tmr, enum channel ch);
 
[[nodiscard]] output start(idfxx::gpio gpio, const timer& tmr, enum channel ch, const output_config& cfg);
 
[[nodiscard]] output start(idfxx::gpio gpio, const timer::config& cfg);
 
[[nodiscard]] output start(idfxx::gpio gpio, const timer::config& cfg, const output_config& out_cfg);
 
void stop(
    enum channel ch,
    enum speed_mode mode = speed_mode::low_speed,
    idfxx::gpio::level idle_level = idfxx::gpio::level::low
);
#endif
 
[[nodiscard]] result<output> try_start(idfxx::gpio gpio, const timer& tmr, enum channel ch);
 
[[nodiscard]] result<output> try_start(idfxx::gpio gpio, const timer& tmr, enum channel ch, const output_config& cfg);
 
[[nodiscard]] result<output> try_start(idfxx::gpio gpio, const timer::config& cfg);
 
[[nodiscard]] result<output> try_start(idfxx::gpio gpio, const timer::config& cfg, const output_config& out_cfg);
 
[[nodiscard]] bool is_active(enum channel ch, enum speed_mode mode = speed_mode::low_speed);
 
[[nodiscard]] std::optional<timer> get_timer(enum channel ch, enum speed_mode mode = speed_mode::low_speed);
 
result<void> try_stop(
    enum channel ch,
    enum speed_mode mode = speed_mode::low_speed,
    idfxx::gpio::level idle_level = idfxx::gpio::level::low
);
 
// ======================================================================
// output (RAII, move-only)
// ======================================================================
 
class output {
public:
    ~output();
 
    output(const output&) = delete;
    output& operator=(const output&) = delete;
    output(output&& other) noexcept;
    output& operator=(output&& other) noexcept;
 
    [[nodiscard]] class timer timer() const noexcept { return _timer; }
 
    [[nodiscard]] enum channel channel() const noexcept { return _channel; }
 
    [[nodiscard]] bool is_active() const noexcept;
 
    [[nodiscard]] uint32_t ticks_max() const noexcept;
 
    [[nodiscard]] float duty() const;
 
    [[nodiscard]] uint32_t duty_ticks() const;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_duty(float duty) { unwrap(try_set_duty(duty)); }
#endif
 
    [[nodiscard]] result<void> try_set_duty(float duty);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_duty_ticks(uint32_t duty) { unwrap(try_set_duty_ticks(duty)); }
 
    void set_duty_ticks(uint32_t duty, uint32_t hpoint) { unwrap(try_set_duty_ticks(duty, hpoint)); }
#endif
 
    [[nodiscard]] result<void> try_set_duty_ticks(uint32_t duty);
 
    [[nodiscard]] result<void> try_set_duty_ticks(uint32_t duty, uint32_t hpoint);
 
    [[nodiscard]] std::chrono::nanoseconds pulse_width() const;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename Rep, typename Period>
    void set_pulse_width(const std::chrono::duration<Rep, Period>& width) {
        unwrap(try_set_pulse_width(width));
    }
#endif
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_set_pulse_width(const std::chrono::duration<Rep, Period>& width) {
        return _try_set_pulse_width(std::chrono::ceil<std::chrono::nanoseconds>(width));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename Rep, typename Period>
    void fade_to(
        float target,
        const std::chrono::duration<Rep, Period>& duration,
        enum fade_mode mode = fade_mode::no_wait
    ) {
        unwrap(try_fade_to(target, duration, mode));
    }
#endif
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_fade_to(
        float target,
        const std::chrono::duration<Rep, Period>& duration,
        enum fade_mode mode = fade_mode::no_wait
    ) {
        return _try_fade_to_duty(
            static_cast<uint32_t>(std::clamp(target, 0.0f, 1.0f) * static_cast<float>(ticks_max())),
            std::chrono::ceil<std::chrono::milliseconds>(duration),
            mode
        );
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename Rep, typename Period>
    void fade_to_duty_ticks(
        uint32_t target_duty,
        const std::chrono::duration<Rep, Period>& duration,
        enum fade_mode mode = fade_mode::no_wait
    ) {
        unwrap(try_fade_to_duty_ticks(target_duty, duration, mode));
    }
#endif
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_fade_to_duty_ticks(
        uint32_t target_duty,
        const std::chrono::duration<Rep, Period>& duration,
        enum fade_mode mode = fade_mode::no_wait
    ) {
        return _try_fade_to_duty(target_duty, std::chrono::ceil<std::chrono::milliseconds>(duration), mode);
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename Rep1, typename Period1, typename Rep2, typename Period2>
    void fade_to_pulse_width(
        const std::chrono::duration<Rep1, Period1>& target_width,
        const std::chrono::duration<Rep2, Period2>& duration,
        enum fade_mode mode = fade_mode::no_wait
    ) {
        unwrap(try_fade_to_pulse_width(target_width, duration, mode));
    }
#endif
 
    template<typename Rep1, typename Period1, typename Rep2, typename Period2>
    [[nodiscard]] result<void> try_fade_to_pulse_width(
        const std::chrono::duration<Rep1, Period1>& target_width,
        const std::chrono::duration<Rep2, Period2>& duration,
        enum fade_mode mode = fade_mode::no_wait
    ) {
        return _try_fade_to_pulse_width(
            std::chrono::ceil<std::chrono::nanoseconds>(target_width),
            std::chrono::ceil<std::chrono::milliseconds>(duration),
            mode
        );
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void
    fade_with_step(uint32_t target_duty, uint32_t scale, uint32_t cycle_num, enum fade_mode mode = fade_mode::no_wait) {
        unwrap(try_fade_with_step(target_duty, scale, cycle_num, mode));
    }
#endif
 
    [[nodiscard]] result<void> try_fade_with_step(
        uint32_t target_duty,
        uint32_t scale,
        uint32_t cycle_num,
        enum fade_mode mode = fade_mode::no_wait
    );
 
#if SOC_LEDC_GAMMA_CURVE_FADE_SUPPORTED
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void multi_fade(uint32_t start_duty, std::span<const fade_param> steps, enum fade_mode mode = fade_mode::no_wait) {
        unwrap(try_multi_fade(start_duty, steps, mode));
    }
#endif
 
    [[nodiscard]] result<void>
    try_multi_fade(uint32_t start_duty, std::span<const fade_param> steps, enum fade_mode mode = fade_mode::no_wait);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] fade_param read_fade_param(uint32_t range) const { return unwrap(try_read_fade_param(range)); }
#endif
 
    [[nodiscard]] result<fade_param> try_read_fade_param(uint32_t range) const;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename Rep, typename Period>
    [[nodiscard]] std::vector<fade_param> fill_multi_fade_params(
        uint32_t start_duty,
        uint32_t end_duty,
        uint32_t linear_phases,
        const std::chrono::duration<Rep, Period>& max_fade_time,
        uint32_t (*gamma_correction)(uint32_t)
    ) {
        return unwrap(try_fill_multi_fade_params(start_duty, end_duty, linear_phases, max_fade_time, gamma_correction));
    }
#endif
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<std::vector<fade_param>> try_fill_multi_fade_params(
        uint32_t start_duty,
        uint32_t end_duty,
        uint32_t linear_phases,
        const std::chrono::duration<Rep, Period>& max_fade_time,
        uint32_t (*gamma_correction)(uint32_t)
    ) {
        return _try_fill_multi_fade_params(
            start_duty,
            end_duty,
            linear_phases,
            std::chrono::ceil<std::chrono::milliseconds>(max_fade_time),
            gamma_correction
        );
    }
#endif // SOC_LEDC_GAMMA_CURVE_FADE_SUPPORTED
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void register_fade_end_callback(std::move_only_function<bool() const> callback) {
        unwrap(try_register_fade_end_callback(std::move(callback)));
    }
#endif
 
    [[nodiscard]] result<void> try_register_fade_end_callback(std::move_only_function<bool() const> callback);
 
#if SOC_LEDC_SUPPORT_FADE_STOP
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void fade_stop() { unwrap(try_fade_stop()); }
#endif
 
    result<void> try_fade_stop();
#endif
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    static void
    install_fade_service(idfxx::intr_levels levels = intr_level_lowmed, idfxx::flags<intr_flag> flags = {}) {
        unwrap(try_install_fade_service(levels, flags));
    }
#endif
 
    [[nodiscard]] static result<void>
    try_install_fade_service(idfxx::intr_levels levels = intr_level_lowmed, idfxx::flags<intr_flag> flags = {});
 
    static void uninstall_fade_service();
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void stop(idfxx::gpio::level idle_level = idfxx::gpio::level::low) { unwrap(try_stop(idle_level)); }
#endif
 
    result<void> try_stop(idfxx::gpio::level idle_level = idfxx::gpio::level::low);
 
    enum channel release() noexcept;
 
private:
    friend result<output>
    try_start(idfxx::gpio gpio, const class timer& tmr, enum channel ch, const output_config& cfg);
    friend result<output> try_start(idfxx::gpio, const timer::config&, const output_config&);
 
    [[nodiscard]] static result<output>
    _make(idfxx::gpio gpio, const class timer& tmr, enum channel ch, const output_config& cfg);
 
    explicit output(class timer tmr, enum channel ch, uint32_t gen, uint32_t duty_ticks) noexcept;
 
    [[nodiscard]] result<void> _try_set_pulse_width(std::chrono::nanoseconds width);
 
    [[nodiscard]] result<void> _try_fade_to_pulse_width(
        std::chrono::nanoseconds target_width,
        std::chrono::milliseconds duration,
        enum fade_mode mode
    );
 
    [[nodiscard]] result<void>
    _try_fade_to_duty(uint32_t target_duty, std::chrono::milliseconds duration, enum fade_mode mode);
 
#if SOC_LEDC_GAMMA_CURVE_FADE_SUPPORTED
    [[nodiscard]] result<std::vector<fade_param>> _try_fill_multi_fade_params(
        uint32_t start_duty,
        uint32_t end_duty,
        uint32_t linear_phases,
        std::chrono::milliseconds max_fade_time,
        uint32_t (*gamma_correction)(uint32_t)
    );
#endif
 
    void _delete() noexcept;
 
    class timer _timer;
    enum channel _channel;
    std::optional<uint32_t> _gen;
    uint32_t _duty_ticks = 0;
    std::unique_ptr<std::move_only_function<bool() const>> _fade_cb;
};
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
inline output start(idfxx::gpio gpio, const timer& tmr, enum channel ch) {
    return unwrap(try_start(gpio, tmr, ch));
}
inline output start(idfxx::gpio gpio, const timer& tmr, enum channel ch, const output_config& cfg) {
    return unwrap(try_start(gpio, tmr, ch, cfg));
}
inline output start(idfxx::gpio gpio, const timer::config& cfg) {
    return unwrap(try_start(gpio, cfg));
}
inline output start(idfxx::gpio gpio, const timer::config& cfg, const output_config& out_cfg) {
    return unwrap(try_start(gpio, cfg, out_cfg));
}
inline void stop(enum channel ch, enum speed_mode mode, idfxx::gpio::level idle_level) {
    unwrap(try_stop(ch, mode, idle_level));
}
#endif
 
 
} // namespace idfxx::pwm
 
namespace idfxx {
 
[[nodiscard]] inline std::string to_string(const pwm::timer& t) {
    std::string s;
#if SOC_LEDC_SUPPORT_HS_MODE
    if (t.speed_mode() == pwm::speed_mode::high_speed) {
        s = "PWM_HS_TIMER_";
    } else {
        s = "PWM_TIMER_";
    }
#else
    s = "PWM_TIMER_";
#endif
    s += std::to_string(t.num());
    return s;
}
 
[[nodiscard]] inline std::string to_string(pwm::channel ch) {
    return "PWM_CH_" + std::to_string(std::to_underlying(ch));
}
 
[[nodiscard]] inline std::string to_string(pwm::speed_mode m) {
    switch (m) {
    case pwm::speed_mode::low_speed:
        return "low_speed";
#if SOC_LEDC_SUPPORT_HS_MODE
    case pwm::speed_mode::high_speed:
        return "high_speed";
#endif
    default:
        return "unknown(" + std::to_string(std::to_underlying(m)) + ")";
    }
}
 
} // namespace idfxx
 
#include "sdkconfig.h"
#ifdef CONFIG_IDFXX_STD_FORMAT
#include <format>
namespace std {
template<>
struct formatter<idfxx::pwm::timer> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(const idfxx::pwm::timer& t, FormatContext& ctx) const {
        auto s = idfxx::to_string(t);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
template<>
struct formatter<idfxx::pwm::channel> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::pwm::channel ch, FormatContext& ctx) const {
        auto s = idfxx::to_string(ch);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
template<>
struct formatter<idfxx::pwm::speed_mode> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::pwm::speed_mode m, FormatContext& ctx) const {
        auto s = idfxx::to_string(m);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
} // namespace std
#endif // CONFIG_IDFXX_STD_FORMAT