[cst9220] Add CST9220 and CST9217 touchscreen support (#16888)

CODEOWNERS

@@ -123,6 +123,7 @@ esphome/components/cs5460a/* @balrog-kun
 esphome/components/cse7761/* @berfenger
 esphome/components/cst226/* @clydebarrow
 esphome/components/cst816/* @clydebarrow
+esphome/components/cst9220/* @clydebarrow
 esphome/components/ct_clamp/* @jesserockz
 esphome/components/current_based/* @djwmarcx
 esphome/components/dac7678/* @NickB1

esphome/components/cst9220/__init__.py

@@ -0,0 +1,6 @@
+import esphome.codegen as cg
+
+CODEOWNERS = ["@clydebarrow"]
+DEPENDENCIES = ["i2c"]
+
+cst9220_ns = cg.esphome_ns.namespace("cst9220")

esphome/components/cst9220/touchscreen/__init__.py

@@ -0,0 +1,36 @@
+from esphome import pins
+import esphome.codegen as cg
+from esphome.components import i2c, touchscreen
+import esphome.config_validation as cv
+from esphome.const import CONF_ID, CONF_INTERRUPT_PIN, CONF_RESET_PIN
+
+from .. import cst9220_ns
+
+CST9220Touchscreen = cst9220_ns.class_(
+    "CST9220Touchscreen",
+    touchscreen.Touchscreen,
+    i2c.I2CDevice,
+)
+
+CONFIG_SCHEMA = (
+    touchscreen.touchscreen_schema("100ms")
+    .extend(
+        {
+            cv.GenerateID(): cv.declare_id(CST9220Touchscreen),
+            cv.Optional(CONF_INTERRUPT_PIN): pins.internal_gpio_input_pin_schema,
+            cv.Optional(CONF_RESET_PIN): pins.gpio_output_pin_schema,
+        }
+    )
+    .extend(i2c.i2c_device_schema(0x5A))
+)
+
+
+async def to_code(config):
+    var = cg.new_Pvariable(config[CONF_ID])
+    await touchscreen.register_touchscreen(var, config)
+    await i2c.register_i2c_device(var, config)
+
+    if interrupt_pin := config.get(CONF_INTERRUPT_PIN):
+        cg.add(var.set_interrupt_pin(await cg.gpio_pin_expression(interrupt_pin)))
+    if reset_pin := config.get(CONF_RESET_PIN):
+        cg.add(var.set_reset_pin(await cg.gpio_pin_expression(reset_pin)))

esphome/components/cst9220/touchscreen/cst9220_touchscreen.cpp

@@ -0,0 +1,141 @@
+#include "cst9220_touchscreen.h"
+#include "esphome/core/helpers.h"
+
+#include <cinttypes>
+
+namespace esphome::cst9220 {
+
+void CST9220Touchscreen::setup() {
+  if (this->reset_pin_ != nullptr) {
+    this->reset_pin_->setup();
+    this->reset_pin_->digital_write(true);
+    delay(5);
+    this->reset_pin_->digital_write(false);
+    delay(10);
+    this->reset_pin_->digital_write(true);
+  }
+  // Wait for the controller to leave its bootloader before talking to it.
+  this->set_timeout(30, [this] { this->continue_setup_(); });
+}
+
+void CST9220Touchscreen::continue_setup_() {
+  uint8_t buffer[4];
+
+  if (this->interrupt_pin_ != nullptr) {
+    this->interrupt_pin_->setup();
+    this->attach_interrupt_(this->interrupt_pin_, gpio::INTERRUPT_FALLING_EDGE);
+  }
+
+  // Enter command mode so the configuration registers can be read.
+  if (this->write_register16(REG_CMD_MODE, buffer, 0) != i2c::ERROR_OK) {
+    this->status_set_error(LOG_STR("Failed to enter command mode"));
+    this->mark_failed();
+    return;
+  }
+  delay(10);
+
+  // The firmware check code confirms that valid firmware is loaded.
+  if (this->read_register16(REG_CHECKCODE, buffer, 4) != i2c::ERROR_OK) {
+    this->status_set_error(LOG_STR("Failed to read check code"));
+    this->mark_failed();
+    return;
+  }
+  uint32_t checkcode = encode_uint32(buffer[3], buffer[2], buffer[1], buffer[0]);
+  if ((checkcode & 0xFFFF0000) != 0xCACA0000) {
+    ESP_LOGE(TAG, "Invalid firmware check code: 0x%08" PRIX32, checkcode);
+    this->status_set_error(LOG_STR("Invalid firmware check code"));
+    this->mark_failed();
+    return;
+  }
+
+  // Read the panel resolution unless the user supplied calibration values.
+  if (this->read_register16(REG_RESOLUTION, buffer, 4) == i2c::ERROR_OK) {
+    if (this->x_raw_max_ == this->x_raw_min_)
+      this->x_raw_max_ = encode_uint16(buffer[1], buffer[0]);
+    if (this->y_raw_max_ == this->y_raw_min_)
+      this->y_raw_max_ = encode_uint16(buffer[3], buffer[2]);
+  }
+
+  // Read the chip type and project id and validate the controller.
+  if (this->read_register16(REG_CHIP_INFO, buffer, 4) != i2c::ERROR_OK) {
+    this->status_set_error(LOG_STR("Failed to read chip ID"));
+    this->mark_failed();
+    return;
+  }
+  this->chip_id_ = encode_uint16(buffer[3], buffer[2]);
+  this->project_id_ = encode_uint16(buffer[1], buffer[0]);
+  if (this->chip_id_ != CST9220_CHIP_ID && this->chip_id_ != CST9217_CHIP_ID) {
+    ESP_LOGE(TAG, "Unknown chip ID: 0x%04X", this->chip_id_);
+    this->status_set_error(LOG_STR("Unknown chip ID"));
+    this->mark_failed();
+    return;
+  }
+
+  // Fall back to the display dimensions if the resolution read failed.
+  if (this->x_raw_max_ == this->x_raw_min_)
+    this->x_raw_max_ = this->display_->get_native_width();
+  if (this->y_raw_max_ == this->y_raw_min_)
+    this->y_raw_max_ = this->display_->get_native_height();
+
+  this->setup_complete_ = true;
+}
+
+void CST9220Touchscreen::update_touches() {
+  if (!this->setup_complete_)
+    return;
+  uint8_t data[CST9220_DATA_LENGTH];
+  // Only an actual I2C failure should skip the update; a successful read with no
+  // touches is a real "all fingers lifted" state that must flow through so the
+  // base class can generate the release event.
+  if (this->read_register16(REG_TOUCH_DATA, data, sizeof(data)) != i2c::ERROR_OK) {
+    this->status_set_warning();
+    this->skip_update_ = true;
+    return;
+  }
+  this->status_clear_warning();
+
+  // Acknowledge the report so the controller can prepare the next one.
+  uint8_t ack = TOUCH_ACK;
+  this->write_register16(REG_TOUCH_DATA, &ack, 1);
+
+  // A valid report carries the ACK marker at offset 6; offset 0 holds the first
+  // point and must be neither the ACK marker nor empty. Anything else means no
+  // valid touch data this cycle, which we report as zero touches (not a skip).
+  if (data[0] == TOUCH_ACK || data[0] == 0x00 || data[6] != TOUCH_ACK)
+    return;
+
+  uint8_t num_touches = data[5] & 0x7F;
+  if (num_touches > CST9220_MAX_TOUCHES)
+    num_touches = CST9220_MAX_TOUCHES;
+
+  for (uint8_t i = 0; i < num_touches; i++) {
+    // The first point starts at offset 0; subsequent points are offset by the
+    // two status bytes that follow it.
+    const uint8_t *p = data + i * 5 + (i == 0 ? 0 : 2);
+    uint8_t id = p[0] >> 4;
+    uint8_t event = p[0] & 0x0F;
+    if (event != TOUCH_EVENT_DOWN)
+      continue;
+    // p[3] is shared: high nibble holds the X LSBs, low nibble the Y LSBs.
+    uint16_t x = (p[1] << 4) | (p[3] >> 4);
+    uint16_t y = (p[2] << 4) | (p[3] & 0x0F);
+    ESP_LOGV(TAG, "Read touch %d: %d/%d", id, x, y);
+    this->add_raw_touch_position_(id, x, y);
+  }
+}
+
+void CST9220Touchscreen::dump_config() {
+  ESP_LOGCONFIG(TAG,
+                "CST9220 Touchscreen:\n"
+                "  Chip ID: 0x%04X\n"
+                "  Project ID: 0x%04X\n"
+                "  X Raw Min: %d, X Raw Max: %d\n"
+                "  Y Raw Min: %d, Y Raw Max: %d",
+                this->chip_id_, this->project_id_, this->x_raw_min_, this->x_raw_max_, this->y_raw_min_,
+                this->y_raw_max_);
+  LOG_I2C_DEVICE(this);
+  LOG_PIN("  Interrupt Pin: ", this->interrupt_pin_);
+  LOG_PIN("  Reset Pin: ", this->reset_pin_);
+}
+
+}  // namespace esphome::cst9220

esphome/components/cst9220/touchscreen/cst9220_touchscreen.h

@@ -0,0 +1,50 @@
+#pragma once
+
+#include "esphome/components/i2c/i2c.h"
+#include "esphome/components/touchscreen/touchscreen.h"
+#include "esphome/core/component.h"
+#include "esphome/core/hal.h"
+#include "esphome/core/log.h"
+
+namespace esphome::cst9220 {
+
+static const char *const TAG = "cst9220.touchscreen";
+
+// The CST92xx family uses 16-bit (big-endian) register addresses.
+static const uint16_t REG_TOUCH_DATA = 0xD000;  // touch report
+static const uint16_t REG_CMD_MODE = 0xD101;    // enter command mode
+static const uint16_t REG_CHECKCODE = 0xD1FC;   // firmware check code
+static const uint16_t REG_RESOLUTION = 0xD1F8;  // panel resolution
+static const uint16_t REG_CHIP_INFO = 0xD204;   // chip type + project id
+
+static const uint8_t TOUCH_ACK = 0xAB;
+static const uint8_t TOUCH_EVENT_DOWN = 0x06;
+
+static const uint16_t CST9220_CHIP_ID = 0x9220;
+static const uint16_t CST9217_CHIP_ID = 0x9217;
+
+// Maximum simultaneous touch points reported by the family.
+static const uint8_t CST9220_MAX_TOUCHES = 5;
+// Report layout: 5 bytes per touch point plus 5 bytes of status/ack overhead.
+static const size_t CST9220_DATA_LENGTH = CST9220_MAX_TOUCHES * 5 + 5;
+
+class CST9220Touchscreen : public touchscreen::Touchscreen, public i2c::I2CDevice {
+ public:
+  void setup() override;
+  void dump_config() override;
+
+  void set_interrupt_pin(InternalGPIOPin *pin) { this->interrupt_pin_ = pin; }
+  void set_reset_pin(GPIOPin *pin) { this->reset_pin_ = pin; }
+
+ protected:
+  void update_touches() override;
+  void continue_setup_();
+
+  InternalGPIOPin *interrupt_pin_{};
+  GPIOPin *reset_pin_{};
+  uint16_t chip_id_{};
+  uint16_t project_id_{};
+  bool setup_complete_{};
+};
+
+}  // namespace esphome::cst9220

tests/components/cst9220/common.yaml

@@ -0,0 +1,16 @@
+display:
+  - id: cst9220_display
+    platform: ili9xxx
+    model: ili9342
+    cs_pin: ${cs_pin}
+    dc_pin: ${dc_pin}
+    reset_pin: ${disp_reset_pin}
+    invert_colors: false
+
+touchscreen:
+  - id: ts_cst9220
+    i2c_id: i2c_bus
+    platform: cst9220
+    display: cst9220_display
+    interrupt_pin: ${interrupt_pin}
+    reset_pin: ${reset_pin}

tests/components/cst9220/test.esp32-idf.yaml

@@ -0,0 +1,12 @@
+substitutions:
+  cs_pin: GPIO4
+  dc_pin: GPIO5
+  disp_reset_pin: GPIO12
+  interrupt_pin: GPIO15
+  reset_pin: GPIO25
+
+packages:
+  i2c: !include ../../test_build_components/common/i2c/esp32-idf.yaml
+  spi: !include ../../test_build_components/common/spi/esp32-idf.yaml
+
+<<: !include common.yaml