panel.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 <cstddef>
#include <cstdint>
#include <optional>
 
namespace idfxx::epaper {
 
class mono_framebuffer;
class gray4_framebuffer;
 
enum class refresh_mode : uint8_t {
    full,
    fast,
    partial,
};
 
enum class color_mode : uint8_t {
    mono,  
    gray4, 
};
 
class panel {
public:
    virtual ~panel() = default;
 
    panel(const panel&) = delete;
    panel& operator=(const panel&) = delete;
 
    // =========================================================================
    // Accessors
    // =========================================================================
 
    [[nodiscard]] size_t width() const noexcept { return _width; }
 
    [[nodiscard]] size_t height() const noexcept { return _height; }
 
    [[nodiscard]] enum color_mode color_mode() const noexcept { return _color_mode; }
 
    [[nodiscard]] bool asleep() const noexcept { return _asleep; }
 
    // =========================================================================
    // RAM upload
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void write(const mono_framebuffer& fb, size_t x = 0, size_t y = 0) { unwrap(try_write(fb, x, y)); }
 
    void write(const gray4_framebuffer& fb, size_t x = 0, size_t y = 0) { unwrap(try_write(fb, x, y)); }
 
    void write_rows(const mono_framebuffer& fb, size_t row_start, size_t row_end, size_t x = 0, size_t y = 0) {
        unwrap(try_write_rows(fb, row_start, row_end, x, y));
    }
 
    void write_rows(const gray4_framebuffer& fb, size_t row_start, size_t row_end, size_t x = 0, size_t y = 0) {
        unwrap(try_write_rows(fb, row_start, row_end, x, y));
    }
 
    void clear() { unwrap(try_clear()); }
#endif
 
    [[nodiscard]] result<void> try_write(const mono_framebuffer& fb, size_t x = 0, size_t y = 0);
 
    [[nodiscard]] result<void> try_write(const gray4_framebuffer& fb, size_t x = 0, size_t y = 0);
 
    [[nodiscard]] result<void>
    try_write_rows(const mono_framebuffer& fb, size_t row_start, size_t row_end, size_t x = 0, size_t y = 0);
 
    [[nodiscard]] result<void>
    try_write_rows(const gray4_framebuffer& fb, size_t row_start, size_t row_end, size_t x = 0, size_t y = 0);
 
    [[nodiscard]] result<void> try_clear() {
        if (_asleep) {
            return error(errc::invalid_state);
        }
        if (auto r = do_clear(); !r) {
            return r;
        }
        _has_baseline = false;
        return {};
    }
 
    // =========================================================================
    // Refresh
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void refresh(refresh_mode mode = refresh_mode::full) { unwrap(try_refresh(mode)); }
 
    void wait() { unwrap(try_wait()); }
 
    template<typename Rep, typename Period>
    void wait_for(const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_wait_for(timeout));
    }
#endif
 
    [[nodiscard]] result<void> try_refresh(refresh_mode mode = refresh_mode::full) {
        if (_asleep) {
            return error(errc::invalid_state);
        }
        if (mode == refresh_mode::partial && !_has_baseline) {
            mode = refresh_mode::full;
        }
        if (auto r = do_refresh(mode); !r) {
            return r;
        }
        _has_baseline = true;
        return {};
    }
 
    [[nodiscard]] result<void> try_wait() { return do_wait(std::nullopt); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_wait_for(const std::chrono::duration<Rep, Period>& timeout) {
        return do_wait(std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
    // =========================================================================
    // Color mode
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_color_mode(enum color_mode mode) { unwrap(try_set_color_mode(mode)); }
#endif
 
    [[nodiscard]] result<void> try_set_color_mode(enum color_mode mode) {
        if (_asleep) {
            return error(errc::invalid_state);
        }
        if (mode == _color_mode) {
            return {};
        }
        if (auto r = do_set_color_mode(mode); !r) {
            return r;
        }
        _color_mode = mode;
        _has_baseline = false;
        return {};
    }
 
    // =========================================================================
    // Power management
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void sleep() { unwrap(try_sleep()); }
 
    void wake() { unwrap(try_wake()); }
#endif
 
    result<void> try_sleep() {
        if (_asleep) {
            return {};
        }
        if (auto r = do_sleep(); !r) {
            return r;
        }
        _asleep = true;
        return {};
    }
 
    [[nodiscard]] result<void> try_wake() {
        if (auto r = do_wake(); !r) {
            return r;
        }
        _asleep = false;
        _has_baseline = false;
        return {};
    }
 
protected:
    panel(size_t width, size_t height) noexcept
        : _width(width)
        , _height(height) {}
 
    panel(
        size_t width,
        size_t height,
        gpio busy_gpio,
        enum gpio::level busy_level,
        std::chrono::milliseconds busy_timeout,
        gpio reset_gpio
    ) noexcept
        : _width(width)
        , _height(height)
        , _busy_gpio(busy_gpio)
        , _busy_level(busy_level)
        , _busy_timeout(busy_timeout)
        , _reset_gpio(reset_gpio) {}
 
    panel(panel&&) noexcept = default;
    panel& operator=(panel&&) noexcept = default;
 
    [[nodiscard]] gpio busy_gpio() const noexcept { return _busy_gpio; }
 
    [[nodiscard]] gpio reset_gpio() const noexcept { return _reset_gpio; }
 
    [[nodiscard]] std::chrono::milliseconds busy_timeout() const noexcept { return _busy_timeout; }
 
    // =========================================================================
    // Customization hooks
    //
    // Concrete drivers override these (typically privately). Each hook
    // implements the correspondingly named public method; validation common
    // to all controllers (alignment, bounds, sleep state, color-mode match,
    // partial-refresh baseline promotion) has already been performed by the
    // public wrappers.
    // =========================================================================
 
    [[nodiscard]] virtual result<void>
    do_write(const mono_framebuffer& fb, size_t row_start, size_t row_end, size_t x, size_t y) = 0;
    [[nodiscard]] virtual result<void>
    do_write(const gray4_framebuffer& fb, size_t row_start, size_t row_end, size_t x, size_t y) {
        (void)fb;
        (void)row_start;
        (void)row_end;
        (void)x;
        (void)y;
        return error(errc::not_supported);
    }
 
    [[nodiscard]] virtual result<void> do_clear() = 0;
 
    [[nodiscard]] virtual result<void> do_refresh(refresh_mode mode) = 0;
 
    [[nodiscard]] virtual result<void> do_set_color_mode(enum color_mode mode) {
        (void)mode;
        return error(errc::not_supported);
    }
 
    [[nodiscard]] virtual result<void> do_sleep() = 0;
    [[nodiscard]] virtual result<void> do_wake() = 0;
 
    [[nodiscard]] virtual result<void> do_wait(std::optional<std::chrono::milliseconds> timeout) {
        return wait_busy(timeout);
    }
 
    [[nodiscard]] static result<void> configure_control_lines(gpio busy_gpio, gpio reset_gpio);
 
    [[nodiscard]] result<void> wait_busy(std::optional<std::chrono::milliseconds> timeout = std::nullopt);
 
    [[nodiscard]] result<void> hardware_reset();
 
private:
    template<typename FB>
    [[nodiscard]] result<void>
    _try_write_rows(const FB& fb, enum color_mode expected, size_t row_start, size_t row_end, size_t x, size_t y);
 
    size_t _width;
    size_t _height;
    gpio _busy_gpio = gpio::nc();
    enum gpio::level _busy_level = gpio::level::high;
    std::chrono::milliseconds _busy_timeout{15'000};
    gpio _reset_gpio = gpio::nc();
    enum color_mode _color_mode = color_mode::mono;
    bool _asleep = false;
    // Whether the controller holds a refreshed image a partial update can
    // diff against; cleared by wake and color-mode changes.
    bool _has_baseline = false;
};
 
} // namespace idfxx::epaper