uc8179.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/epaper/panel>
#include <idfxx/error>
#include <idfxx/gpio>
#include <idfxx/panel_io>
 
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <frequency/frequency>
#include <initializer_list>
#include <span>
 
namespace idfxx::epaper {
 
class uc8179 final : public panel {
public:
    struct config {
        size_t width = 800;
        size_t height = 480;
        gpio reset_gpio = gpio::nc();
        gpio busy_gpio = gpio::nc();
        std::chrono::milliseconds busy_timeout{30'000};
    };
 
    [[nodiscard]] static panel_io::spi_config
    spi_io_config(gpio cs, gpio dc, freq::hertz pclk = freq::hertz{10'000'000}) noexcept;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit uc8179(idfxx::panel_io& panel_io, config config);
#endif
 
    [[nodiscard]] static result<uc8179> make(idfxx::panel_io& panel_io, config config);
 
    ~uc8179() override;
 
    uc8179(const uc8179&) = delete;
    uc8179& operator=(const uc8179&) = delete;
    uc8179(uc8179&& other) noexcept;
    uc8179& operator=(uc8179&& other) noexcept;
 
private:
    // Waveform configuration currently loaded into the controller. The
    // UC8179 selects its update waveform at initialization (OTP banks or
    // register-written LUTs), not per refresh command, so the driver
    // re-initializes when a refresh needs a different waveform.
    enum class waveform : uint8_t { full, fast, partial, gray };
 
    // A rectangular pixel region of the panel, for partial-window
    // programming.
    struct region {
        size_t x;
        size_t y;
        size_t width;
        size_t height;
    };
 
    // Tag distinguishing the non-initializing constructor make() uses from
    // the public throwing constructor with the same argument list.
    struct raw_tag {};
 
    explicit uc8179(raw_tag, idfxx::panel_io& panel_io, config config)
        : panel(config.width, config.height, config.busy_gpio, gpio::level::low, config.busy_timeout, config.reset_gpio)
        , _io(&panel_io) {}
 
    // epaper::panel customization hooks.
    [[nodiscard]] result<void>
    do_write(const mono_framebuffer& fb, size_t row_start, size_t row_end, size_t x, size_t y) override;
    [[nodiscard]] result<void>
    do_write(const gray4_framebuffer& fb, size_t row_start, size_t row_end, size_t x, size_t y) override;
    [[nodiscard]] result<void> do_clear() override;
    [[nodiscard]] result<void> do_refresh(refresh_mode mode) override;
    [[nodiscard]] result<void> do_set_color_mode(enum color_mode mode) override;
    [[nodiscard]] result<void> do_sleep() override;
    [[nodiscard]] result<void> do_wake() override;
 
    // Command sequencing helpers (see src/uc8179.cpp).
    [[nodiscard]] result<void> _cmd(uint8_t cmd);
    [[nodiscard]] result<void> _cmd(uint8_t cmd, std::initializer_list<uint8_t> params);
    [[nodiscard]] result<void> _cmd(uint8_t cmd, std::span<const uint8_t> params);
    [[nodiscard]] result<void> _stream(int cmd, std::span<const uint8_t> data);
    [[nodiscard]] result<void> _power_on();
    [[nodiscard]] result<void> _set_resolution();
    [[nodiscard]] result<void> _load_luts(
        std::span<const uint8_t> vcom,
        std::span<const uint8_t> ww,
        std::span<const uint8_t> kw,
        std::span<const uint8_t> wk,
        std::span<const uint8_t> kk
    );
    [[nodiscard]] result<void> _init_full();
    [[nodiscard]] result<void> _init_fast();
    [[nodiscard]] result<void> _init_partial();
    [[nodiscard]] result<void> _init_gray();
    [[nodiscard]] result<void> _ensure_waveform(waveform target);
    [[nodiscard]] result<void> _window_begin(region r);
    [[nodiscard]] result<void> _window_end();
    [[nodiscard]] result<void> _clear_ram(bool include_old_plane);
    [[nodiscard]] result<void> _update();
    [[nodiscard]] result<void> _enter_deep_sleep();
 
    idfxx::panel_io* _io = nullptr; // nullptr after move
    waveform _waveform = waveform::full;
};
 
} // namespace idfxx::epaper