Add driver for quad SPI AMOLED displays (#6354)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

CODEOWNERS

@@ -269,6 +269,7 @@ esphome/components/pvvx_mithermometer/* @pasiz
 esphome/components/pylontech/* @functionpointer
 esphome/components/qmp6988/* @andrewpc
 esphome/components/qr_code/* @wjtje
+esphome/components/qspi_amoled/* @clydebarrow
 esphome/components/qwiic_pir/* @kahrendt
 esphome/components/radon_eye_ble/* @jeffeb3
 esphome/components/radon_eye_rd200/* @jeffeb3

esphome/components/qspi_amoled/__init__.py

@@ -0,0 +1 @@
+CODEOWNERS = ["@clydebarrow"]

esphome/components/qspi_amoled/display.py

@@ -0,0 +1,131 @@
+import esphome.codegen as cg
+import esphome.config_validation as cv
+from esphome import pins
+from esphome.components import (
+    spi,
+    display,
+)
+from esphome.const import (
+    CONF_RESET_PIN,
+    CONF_ID,
+    CONF_DIMENSIONS,
+    CONF_WIDTH,
+    CONF_HEIGHT,
+    CONF_LAMBDA,
+    CONF_BRIGHTNESS,
+    CONF_ENABLE_PIN,
+    CONF_MODEL,
+    CONF_OFFSET_HEIGHT,
+    CONF_OFFSET_WIDTH,
+    CONF_INVERT_COLORS,
+    CONF_MIRROR_X,
+    CONF_MIRROR_Y,
+    CONF_SWAP_XY,
+    CONF_COLOR_ORDER,
+    CONF_TRANSFORM,
+)
+
+DEPENDENCIES = ["spi"]
+
+qspi_amoled_ns = cg.esphome_ns.namespace("qspi_amoled")
+QSPI_AMOLED = qspi_amoled_ns.class_(
+    "QspiAmoLed", display.Display, display.DisplayBuffer, cg.Component, spi.SPIDevice
+)
+ColorOrder = display.display_ns.enum("ColorMode")
+Model = qspi_amoled_ns.enum("Model")
+
+MODELS = {"RM690B0": Model.RM690B0, "RM67162": Model.RM67162}
+
+COLOR_ORDERS = {
+    "RGB": ColorOrder.COLOR_ORDER_RGB,
+    "BGR": ColorOrder.COLOR_ORDER_BGR,
+}
+DATA_PIN_SCHEMA = pins.internal_gpio_output_pin_schema
+
+CONFIG_SCHEMA = cv.All(
+    display.FULL_DISPLAY_SCHEMA.extend(
+        cv.Schema(
+            {
+                cv.GenerateID(): cv.declare_id(QSPI_AMOLED),
+                cv.Required(CONF_MODEL): cv.enum(MODELS, upper=True),
+                cv.Required(CONF_DIMENSIONS): cv.Any(
+                    cv.dimensions,
+                    cv.Schema(
+                        {
+                            cv.Required(CONF_WIDTH): cv.int_,
+                            cv.Required(CONF_HEIGHT): cv.int_,
+                            cv.Optional(CONF_OFFSET_HEIGHT, default=0): cv.int_,
+                            cv.Optional(CONF_OFFSET_WIDTH, default=0): cv.int_,
+                        }
+                    ),
+                ),
+                cv.Optional(CONF_TRANSFORM): cv.Schema(
+                    {
+                        cv.Optional(CONF_MIRROR_X, default=False): cv.boolean,
+                        cv.Optional(CONF_MIRROR_Y, default=False): cv.boolean,
+                        cv.Optional(CONF_SWAP_XY, default=False): cv.boolean,
+                    }
+                ),
+                cv.Optional(CONF_COLOR_ORDER, default="RGB"): cv.enum(
+                    COLOR_ORDERS, upper=True
+                ),
+                cv.Optional(CONF_INVERT_COLORS, default=False): cv.boolean,
+                cv.Optional(CONF_RESET_PIN): pins.gpio_output_pin_schema,
+                cv.Optional(CONF_ENABLE_PIN): pins.gpio_output_pin_schema,
+                cv.Optional(CONF_BRIGHTNESS, default=0xD0): cv.int_range(
+                    0, 0xFF, min_included=True, max_included=True
+                ),
+            }
+        ).extend(
+            spi.spi_device_schema(
+                cs_pin_required=False,
+                default_mode="MODE0",
+                default_data_rate=10e6,
+                quad=True,
+            )
+        )
+    ),
+    cv.only_with_esp_idf,
+)
+
+
+async def to_code(config):
+    var = cg.new_Pvariable(config[CONF_ID])
+    await display.register_display(var, config)
+    await spi.register_spi_device(var, config)
+
+    cg.add(var.set_color_mode(config[CONF_COLOR_ORDER]))
+    cg.add(var.set_invert_colors(config[CONF_INVERT_COLORS]))
+    cg.add(var.set_brightness(config[CONF_BRIGHTNESS]))
+    cg.add(var.set_model(config[CONF_MODEL]))
+    if enable_pin := config.get(CONF_ENABLE_PIN):
+        enable = await cg.gpio_pin_expression(enable_pin)
+        cg.add(var.set_enable_pin(enable))
+
+    if reset_pin := config.get(CONF_RESET_PIN):
+        reset = await cg.gpio_pin_expression(reset_pin)
+        cg.add(var.set_reset_pin(reset))
+
+    if transform := config.get(CONF_TRANSFORM):
+        cg.add(var.set_mirror_x(transform[CONF_MIRROR_X]))
+        cg.add(var.set_mirror_y(transform[CONF_MIRROR_Y]))
+        cg.add(var.set_swap_xy(transform[CONF_SWAP_XY]))
+
+    if CONF_DIMENSIONS in config:
+        dimensions = config[CONF_DIMENSIONS]
+        if isinstance(dimensions, dict):
+            cg.add(var.set_dimensions(dimensions[CONF_WIDTH], dimensions[CONF_HEIGHT]))
+            cg.add(
+                var.set_offsets(
+                    dimensions[CONF_OFFSET_WIDTH], dimensions[CONF_OFFSET_HEIGHT]
+                )
+            )
+        else:
+            (width, height) = dimensions
+            cg.add(var.set_dimensions(width, height))
+
+    if lamb := config.get(CONF_LAMBDA):
+        lambda_ = await cg.process_lambda(
+            lamb, [(display.DisplayRef, "it")], return_type=cg.void
+        )
+        cg.add(var.set_writer(lambda_))

esphome/components/qspi_amoled/qspi_amoled.cpp

@@ -0,0 +1,165 @@
+#ifdef USE_ESP_IDF
+#include "qspi_amoled.h"
+#include "esphome/core/log.h"
+
+namespace esphome {
+namespace qspi_amoled {
+
+void QspiAmoLed::setup() {
+  esph_log_config(TAG, "Setting up QSPI_AMOLED");
+  this->spi_setup();
+  if (this->enable_pin_ != nullptr) {
+    this->enable_pin_->setup();
+    this->enable_pin_->digital_write(true);
+  }
+  if (this->reset_pin_ != nullptr) {
+    this->reset_pin_->setup();
+    this->reset_pin_->digital_write(true);
+    delay(5);
+    this->reset_pin_->digital_write(false);
+    delay(5);
+    this->reset_pin_->digital_write(true);
+  }
+  this->set_timeout(120, [this] { this->write_command_(SLEEP_OUT); });
+  this->set_timeout(240, [this] { this->write_init_sequence_(); });
+}
+
+void QspiAmoLed::update() {
+  this->do_update_();
+  int w = this->x_high_ - this->x_low_ + 1;
+  int h = this->y_high_ - this->y_low_ + 1;
+  this->draw_pixels_at(this->x_low_, this->y_low_, w, h, this->buffer_, this->color_mode_, display::COLOR_BITNESS_565,
+                       true, this->x_low_, this->y_low_, this->get_width_internal() - w - this->x_low_);
+  // invalidate watermarks
+  this->x_low_ = this->width_;
+  this->y_low_ = this->height_;
+  this->x_high_ = 0;
+  this->y_high_ = 0;
+}
+
+void QspiAmoLed::draw_absolute_pixel_internal(int x, int y, Color color) {
+  if (x >= this->get_width_internal() || x < 0 || y >= this->get_height_internal() || y < 0) {
+    return;
+  }
+  if (this->buffer_ == nullptr)
+    this->init_internal_(this->width_ * this->height_ * 2);
+  if (this->is_failed())
+    return;
+  uint32_t pos = (y * this->width_) + x;
+  uint16_t new_color;
+  bool updated = false;
+  pos = pos * 2;
+  new_color = display::ColorUtil::color_to_565(color, display::ColorOrder::COLOR_ORDER_RGB);
+  if (this->buffer_[pos] != (uint8_t) (new_color >> 8)) {
+    this->buffer_[pos] = (uint8_t) (new_color >> 8);
+    updated = true;
+  }
+  pos = pos + 1;
+  new_color = new_color & 0xFF;
+
+  if (this->buffer_[pos] != new_color) {
+    this->buffer_[pos] = new_color;
+    updated = true;
+  }
+  if (updated) {
+    // low and high watermark may speed up drawing from buffer
+    if (x < this->x_low_)
+      this->x_low_ = x;
+    if (y < this->y_low_)
+      this->y_low_ = y;
+    if (x > this->x_high_)
+      this->x_high_ = x;
+    if (y > this->y_high_)
+      this->y_high_ = y;
+  }
+}
+
+void QspiAmoLed::reset_params_(bool ready) {
+  if (!ready && !this->is_ready())
+    return;
+  this->write_command_(this->invert_colors_ ? INVERT_ON : INVERT_OFF);
+  // custom x/y transform and color order
+  uint8_t mad = this->color_mode_ == display::COLOR_ORDER_BGR ? MADCTL_BGR : MADCTL_RGB;
+  if (this->swap_xy_)
+    mad |= MADCTL_MV;
+  if (this->mirror_x_)
+    mad |= MADCTL_MX;
+  if (this->mirror_y_)
+    mad |= MADCTL_MY;
+  this->write_command_(MADCTL_CMD, &mad, 1);
+  this->write_command_(BRIGHTNESS, &this->brightness_, 1);
+}
+
+void QspiAmoLed::write_init_sequence_() {
+  if (this->model_ == RM690B0) {
+    this->write_command_(PAGESEL, 0x20);
+    this->write_command_(MIPI, 0x0A);
+    this->write_command_(WRAM, 0x80);
+    this->write_command_(SWIRE1, 0x51);
+    this->write_command_(SWIRE2, 0x2E);
+    this->write_command_(PAGESEL, 0x00);
+    this->write_command_(0xC2, 0x00);
+    delay(10);
+    this->write_command_(TEON, 0x00);
+  }
+  this->write_command_(PIXFMT, 0x55);
+  this->write_command_(BRIGHTNESS, 0);
+  this->write_command_(DISPLAY_ON);
+  this->reset_params_(true);
+  this->setup_complete_ = true;
+  esph_log_config(TAG, "QSPI_AMOLED setup complete");
+}
+
+void QspiAmoLed::set_addr_window_(uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2) {
+  uint8_t buf[4];
+  x1 += this->offset_x_;
+  x2 += this->offset_x_;
+  y1 += this->offset_y_;
+  y2 += this->offset_y_;
+  put16_be(buf, x1);
+  put16_be(buf + 2, x2);
+  this->write_command_(CASET, buf, sizeof buf);
+  put16_be(buf, y1);
+  put16_be(buf + 2, y2);
+  this->write_command_(RASET, buf, sizeof buf);
+}
+
+void QspiAmoLed::draw_pixels_at(int x_start, int y_start, int w, int h, const uint8_t *ptr, display::ColorOrder order,
+                                display::ColorBitness bitness, bool big_endian, int x_offset, int y_offset, int x_pad) {
+  if (!this->setup_complete_ || this->is_failed())
+    return;
+  if (w <= 0 || h <= 0)
+    return;
+  if (bitness != display::COLOR_BITNESS_565 || order != this->color_mode_ ||
+      big_endian != (this->bit_order_ == spi::BIT_ORDER_MSB_FIRST)) {
+    return display::Display::draw_pixels_at(x_start, y_start, w, h, ptr, order, bitness, big_endian, x_offset, y_offset,
+                                            x_pad);
+  }
+  this->set_addr_window_(x_start, y_start, x_start + w - 1, y_start + h - 1);
+  this->enable();
+  // x_ and y_offset are offsets into the source buffer, unrelated to our own offsets into the display.
+  if (x_offset == 0 && x_pad == 0 && y_offset == 0) {
+    // we could deal here with a non-zero y_offset, but if x_offset is zero, y_offset probably will be so don't bother
+    this->write_cmd_addr_data(8, 0x32, 24, 0x2C00, ptr, w * h * 2, 4);
+  } else {
+    this->write_cmd_addr_data(8, 0x32, 24, 0x2C00, nullptr, 0, 4);
+    auto stride = x_offset + w + x_pad;
+    for (int y = 0; y != h; y++) {
+      this->write_cmd_addr_data(0, 0, 0, 0, ptr + ((y + y_offset) * stride + x_offset) * 2, w * 2, 4);
+    }
+  }
+  this->disable();
+}
+
+void QspiAmoLed::dump_config() {
+  ESP_LOGCONFIG("", "QSPI AMOLED");
+  ESP_LOGCONFIG(TAG, "  Height: %u", this->height_);
+  ESP_LOGCONFIG(TAG, "  Width: %u", this->width_);
+  LOG_PIN("  CS Pin: ", this->cs_);
+  LOG_PIN("  Reset Pin: ", this->reset_pin_);
+  ESP_LOGCONFIG(TAG, "  SPI Data rate: %dMHz", (unsigned) (this->data_rate_ / 1000000));
+}
+
+}  // namespace qspi_amoled
+}  // namespace esphome
+#endif

esphome/components/qspi_amoled/qspi_amoled.h

@@ -0,0 +1,165 @@
+//
+// Created by Clyde Stubbs on 29/10/2023.
+//
+#pragma once
+
+#ifdef USE_ESP_IDF
+#include "esphome/core/component.h"
+#include "esphome/components/spi/spi.h"
+#include "esphome/components/display/display.h"
+#include "esphome/components/display/display_buffer.h"
+#include "esphome/components/display/display_color_utils.h"
+#include "esp_lcd_panel_ops.h"
+
+#include "esp_lcd_panel_rgb.h"
+
+namespace esphome {
+namespace qspi_amoled {
+
+constexpr static const char *const TAG = "display.qspi_amoled";
+static const uint8_t SW_RESET_CMD = 0x01;
+static const uint8_t SLEEP_OUT = 0x11;
+static const uint8_t INVERT_OFF = 0x20;
+static const uint8_t INVERT_ON = 0x21;
+static const uint8_t ALL_ON = 0x23;
+static const uint8_t WRAM = 0x24;
+static const uint8_t MIPI = 0x26;
+static const uint8_t DISPLAY_ON = 0x29;
+static const uint8_t RASET = 0x2B;
+static const uint8_t CASET = 0x2A;
+static const uint8_t WDATA = 0x2C;
+static const uint8_t TEON = 0x35;
+static const uint8_t MADCTL_CMD = 0x36;
+static const uint8_t PIXFMT = 0x3A;
+static const uint8_t BRIGHTNESS = 0x51;
+static const uint8_t SWIRE1 = 0x5A;
+static const uint8_t SWIRE2 = 0x5B;
+static const uint8_t PAGESEL = 0xFE;
+
+static const uint8_t MADCTL_MY = 0x80;   ///< Bit 7 Bottom to top
+static const uint8_t MADCTL_MX = 0x40;   ///< Bit 6 Right to left
+static const uint8_t MADCTL_MV = 0x20;   ///< Bit 5 Reverse Mode
+static const uint8_t MADCTL_RGB = 0x00;  ///< Bit 3 Red-Green-Blue pixel order
+static const uint8_t MADCTL_BGR = 0x08;  ///< Bit 3 Blue-Green-Red pixel order
+
+// store a 16 bit value in a buffer, big endian.
+static inline void put16_be(uint8_t *buf, uint16_t value) {
+  buf[0] = value >> 8;
+  buf[1] = value;
+}
+
+enum Model {
+  RM690B0,
+  RM67162,
+};
+
+class QspiAmoLed : public display::DisplayBuffer,
+                   public spi::SPIDevice<spi::BIT_ORDER_MSB_FIRST, spi::CLOCK_POLARITY_LOW, spi::CLOCK_PHASE_LEADING,
+                                         spi::DATA_RATE_1MHZ> {
+ public:
+  void set_model(Model model) { this->model_ = model; }
+  void update() override;
+  void setup() override;
+  display::ColorOrder get_color_mode() { return this->color_mode_; }
+  void set_color_mode(display::ColorOrder color_mode) { this->color_mode_ = color_mode; }
+
+  void set_reset_pin(GPIOPin *reset_pin) { this->reset_pin_ = reset_pin; }
+  void set_enable_pin(GPIOPin *enable_pin) { this->enable_pin_ = enable_pin; }
+  void set_width(uint16_t width) { this->width_ = width; }
+  void set_dimensions(uint16_t width, uint16_t height) {
+    this->width_ = width;
+    this->height_ = height;
+  }
+  int get_width() override { return this->width_; }
+  int get_height() override { return this->height_; }
+  void set_invert_colors(bool invert_colors) {
+    this->invert_colors_ = invert_colors;
+    this->reset_params_();
+  }
+  void set_mirror_x(bool mirror_x) {
+    this->mirror_x_ = mirror_x;
+    this->reset_params_();
+  }
+  void set_mirror_y(bool mirror_y) {
+    this->mirror_y_ = mirror_y;
+    this->reset_params_();
+  }
+  void set_swap_xy(bool swap_xy) {
+    this->swap_xy_ = swap_xy;
+    this->reset_params_();
+  }
+  void set_brightness(uint8_t brightness) {
+    this->brightness_ = brightness;
+    this->reset_params_();
+  }
+  void set_offsets(int16_t offset_x, int16_t offset_y) {
+    this->offset_x_ = offset_x;
+    this->offset_y_ = offset_y;
+  }
+  display::DisplayType get_display_type() override { return display::DisplayType::DISPLAY_TYPE_COLOR; }
+  void dump_config() override;
+
+  int get_width_internal() override { return this->width_; }
+  int get_height_internal() override { return this->height_; }
+  bool can_proceed() override { return this->setup_complete_; }
+
+ protected:
+  void draw_absolute_pixel_internal(int x, int y, Color color) override;
+  void draw_pixels_at(int x_start, int y_start, int w, int h, const uint8_t *ptr, display::ColorOrder order,
+                      display::ColorBitness bitness, bool big_endian, int x_offset, int y_offset, int x_pad) override;
+  /**
+   * the RM67162 in quad SPI mode seems to work like this (not in the datasheet, this is deduced from the
+   * sample code.)
+   *
+   * Immediately after enabling /CS send 4 bytes in single-dataline SPI mode:
+   *    0: either 0x2 or 0x32. The first indicates that any subsequent data bytes after the initial 4 will be
+   *        sent in 1-dataline SPI. The second indicates quad mode.
+   *    1: 0x00
+   *    2: The command (register address) byte.
+   *    3: 0x00
+   *
+   *    This is followed by zero or more data bytes in either 1-wire or 4-wire mode, depending on the first byte.
+   *    At the conclusion of the write, de-assert /CS.
+   *
+   * @param cmd
+   * @param bytes
+   * @param len
+   */
+  void write_command_(uint8_t cmd, const uint8_t *bytes, size_t len) {
+    this->enable();
+    this->write_cmd_addr_data(8, 0x02, 24, cmd << 8, bytes, len);
+    this->disable();
+  }
+
+  void write_command_(uint8_t cmd, uint8_t data) { this->write_command_(cmd, &data, 1); }
+  void write_command_(uint8_t cmd) { this->write_command_(cmd, &cmd, 0); }
+  void reset_params_(bool ready = false);
+  void write_init_sequence_();
+  void set_addr_window_(uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2);
+
+  GPIOPin *reset_pin_{nullptr};
+  GPIOPin *enable_pin_{nullptr};
+  uint16_t x_low_{0};
+  uint16_t y_low_{0};
+  uint16_t x_high_{0};
+  uint16_t y_high_{0};
+  bool setup_complete_{};
+
+  bool invert_colors_{};
+  display::ColorOrder color_mode_{display::COLOR_ORDER_BGR};
+  size_t width_{};
+  size_t height_{};
+  int16_t offset_x_{0};
+  int16_t offset_y_{0};
+  bool swap_xy_{};
+  bool mirror_x_{};
+  bool mirror_y_{};
+  uint8_t brightness_{0xD0};
+  Model model_{RM690B0};
+
+  esp_lcd_panel_handle_t handle_{};
+};
+
+}  // namespace qspi_amoled
+}  // namespace esphome
+#endif

tests/components/qspi_amoled/test.esp32-s3-idf.yaml

@@ -0,0 +1,36 @@
+spi:
+  id: quad_spi
+  clk_pin: 15
+  type: quad
+  data_pins: [14, 10, 16, 12]
+
+display:
+  - platform: qspi_amoled
+    model: RM690B0
+    data_rate: 80MHz
+    spi_mode: mode0
+    dimensions:
+      width: 450
+      height: 600
+      offset_width: 16
+    color_order: rgb
+    invert_colors: false
+    brightness: 255
+    cs_pin: 11
+    reset_pin: 13
+    enable_pin: 9
+
+  - platform: qspi_amoled
+    model: RM67162
+    id: main_lcd
+    dimensions:
+      height: 240
+      width: 536
+    transform:
+      mirror_x: true
+      swap_xy: true
+    color_order: rgb
+    brightness: 255
+    cs_pin: 6
+    reset_pin: 17
+    enable_pin: 38