ssd1680.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/memory>
#include <idfxx/panel_io>
 
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <frequency/frequency>
#include <initializer_list>
#include <span>
#include <vector>
 
namespace idfxx::epaper {
 
class ssd1680 final : public panel {
public:
    struct config {
        size_t width = 122;
        size_t height = 250;
        gpio reset_gpio = gpio::nc();
        gpio busy_gpio = gpio::nc();
        std::chrono::milliseconds busy_timeout{15'000};
        bool mirror_x = false;
        bool mirror_y = false;
    };
 
    [[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 ssd1680(idfxx::panel_io& panel_io, config config);
#endif
 
    [[nodiscard]] static result<ssd1680> make(idfxx::panel_io& panel_io, config config);
 
    ~ssd1680() override;
 
    ssd1680(const ssd1680&) = delete;
    ssd1680& operator=(const ssd1680&) = delete;
    ssd1680(ssd1680&& other) noexcept;
    ssd1680& operator=(ssd1680&& other) noexcept;
 
private:
    // A rectangular pixel region of the panel, for RAM window programming.
    struct region {
        size_t x;
        size_t y;
        size_t width;
        size_t height;
    };
 
    explicit ssd1680(idfxx::panel_io& panel_io, config config, std::vector<uint8_t, dram_allocator<uint8_t>> shadow)
        : panel(
              config.width,
              config.height,
              config.busy_gpio,
              gpio::level::high,
              config.busy_timeout,
              config.reset_gpio
          )
        , _io(&panel_io)
        , _mirror_x(config.mirror_x)
        , _mirror_y(config.mirror_y)
        , _shadow(std::move(shadow)) {}
 
    // 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/ssd1680.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(uint8_t cmd, std::span<const uint8_t> data);
    [[nodiscard]] result<void> _drain();
    [[nodiscard]] result<void> _init();
    [[nodiscard]] result<void> _init_gray();
    [[nodiscard]] result<void> _init_scan();
    [[nodiscard]] result<void> _set_ram_window(region r);
    [[nodiscard]] result<void>
    _write_planes(region window, std::span<const uint8_t> new_plane, std::span<const uint8_t> old_plane);
    [[nodiscard]] result<void> _sync_old_plane();
    [[nodiscard]] size_t _stride() const noexcept { return (width() + 7) / 8; }
 
    idfxx::panel_io* _io = nullptr; // nullptr after move
    bool _mirror_x = false;
    bool _mirror_y = false;
    // Shadow of the last-written new-plane RAM bytes; re-sent to the
    // controller's old-image plane after each refresh so partial updates
    // diff against the frame actually on the glass.
    std::vector<uint8_t, dram_allocator<uint8_t>> _shadow;
};
 
} // namespace idfxx::epaper