From 013d21119fb03e2900a0966333fd02841fc7f575 Mon Sep 17 00:00:00 2001 From: clydebarrow <2366188+clydebarrow@users.noreply.github.com> Date: Thu, 7 May 2026 15:30:18 +1000 Subject: [PATCH 1/3] [gsl3670] Add touchscreen docs --- public/images/touchscreen.svg | 14 ++++ src/content/docs/components/index.mdx | 1 + .../docs/components/touchscreen/gsl3670.mdx | 70 +++++++++++++++++++ .../docs/components/touchscreen/index.mdx | 1 + 4 files changed, 86 insertions(+) create mode 100644 public/images/touchscreen.svg create mode 100644 src/content/docs/components/touchscreen/gsl3670.mdx diff --git a/public/images/touchscreen.svg b/public/images/touchscreen.svg new file mode 100644 index 0000000000..7b84b401d5 --- /dev/null +++ b/public/images/touchscreen.svg @@ -0,0 +1,14 @@ + + Touchscreen icon + Abstract monochrome icon: a rounded rectangle screen with a single touch point and concentric ripple rings + + + + + + + + + + + diff --git a/src/content/docs/components/index.mdx b/src/content/docs/components/index.mdx index e50bbf9856..9a7afa7410 100644 --- a/src/content/docs/components/index.mdx +++ b/src/content/docs/components/index.mdx @@ -1076,6 +1076,7 @@ Used for creating infrared (IR) remote control transmitters and/or receivers. ["CST816", "/components/touchscreen/cst816/", "cst816.jpg"], ["EKTF2232", "/components/touchscreen/ektf2232/", "ektf2232.svg", "Inkplate 6 Plus"], ["FT63X6", "/components/touchscreen/ft63x6/", "wt32-sc01.png"], + ["GSL3670", "/components/touchscreen/gsl3670/", "touchscreen.svg", "dark-invert"], ["GT911", "/components/touchscreen/gt911/", "esp32_s3_box_3.png"], ["Lilygo T5 4.7", "/components/touchscreen/lilygo_t5_47/", "lilygo_t5_47_touch.jpg"], ["TT21100", "/components/touchscreen/tt21100/", "esp32-s3-korvo-2-lcd.png"], diff --git a/src/content/docs/components/touchscreen/gsl3670.mdx b/src/content/docs/components/touchscreen/gsl3670.mdx new file mode 100644 index 0000000000..05b6e4e7f8 --- /dev/null +++ b/src/content/docs/components/touchscreen/gsl3670.mdx @@ -0,0 +1,70 @@ +--- +description: "Instructions for setting up GSL3670 touch screen controller with ESPHome" +title: "GSL3670 Touch Screen Controller" +--- + +import APIRef from '@components/APIRef.astro'; + +The `gsl3670` touchscreen platform allows using the touch screen controllers based on the GSL3670 chip with ESPHome. +An [I²C](/components/i2c) bus is required to be set up in your configuration for this touchscreen to work. + +This controller is used in the Seeed Studio reTerminal D1001. + +The component requires a binary firmware file to be loaded into the controller during initialization. A firmware file for the Seeed reTerminal D1001 is bundled with the component. + +## Base Touchscreen Configuration + +```yaml +# Example configuration entry using the built-in Seeed reTerminal D1001 model +touchscreen: + platform: gsl3670 + id: my_touchscreen + model: SEEED-RETERMINAL-D1001 +``` + +```yaml +# Example configuration entry using a custom firmware file +touchscreen: + platform: gsl3670 + id: my_touchscreen + interrupt_pin: GPIOXX + reset_pin: GPIOXX + firmware_file: my_gsl3670_firmware.bin +``` + +### Configuration variables + +- **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually set the ID of this touchscreen. +- **model** (*Optional*, string): A predefined model that sets default values for pin assignments, calibration, and firmware. Currently supported: + - `SEEED-RETERMINAL-D1001`: Seeed Studio reTerminal D1001. Sets appropriate defaults for interrupt pin, reset pin, calibration, axis mirroring/swapping, and firmware. + - `CUSTOM`: No defaults are applied; all options must be configured manually. This is the default. +- **interrupt_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The touch detection pin. +- **reset_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The chip reset pin. +- **firmware_file** (**Required**, string): Path to the GSL3670 binary firmware file. When using a built-in model, this is set automatically. The firmware file is validated at compile time for correct format and integrity. If the file is not found at the given path, the component will also look for it in its own directory. + +- All other options from [Touchscreen](/components/touchscreen#config-touchscreen). + +### Sample config for the Seeed reTerminal D1001 + +```yaml +i2c: + - id: lcd_i2c + sda: + ignore_strapping_warning: true + number: GPIO37 + scl: + ignore_strapping_warning: true + number: GPIO38 + scan: true + frequency: 400kHz + +touchscreen: + - platform: gsl3670 + i2c_id: lcd_i2c + model: SEEED-RETERMINAL-D1001 +``` + +## See Also + +- [Touchscreen Components](/components/touchscreen/) +- diff --git a/src/content/docs/components/touchscreen/index.mdx b/src/content/docs/components/touchscreen/index.mdx index ff9f28c2ce..d827ff71e5 100644 --- a/src/content/docs/components/touchscreen/index.mdx +++ b/src/content/docs/components/touchscreen/index.mdx @@ -293,6 +293,7 @@ binary_sensor: - [EKTF2232 Touchscreen Controller](/components/touchscreen/ektf2232/) - [XPT2046 Touch Screen Controller (Updated version)](/components/touchscreen/xpt2046/) - [TT21100 Touch Screen Controller](/components/touchscreen/tt21100/) +- [GSL3670 Touch Screen Controller](/components/touchscreen/gsl3670/) - [gt911 Touch Screen Controller](/components/touchscreen/gt911/) - - From e80c58384d356c38dd4be98d5eb5642e854812f0 Mon Sep 17 00:00:00 2001 From: clydebarrow <2366188+clydebarrow@users.noreply.github.com> Date: Fri, 8 May 2026 11:42:56 +1000 Subject: [PATCH 2/3] Change to trigger rebuild --- src/content/docs/components/touchscreen/gsl3670.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/components/touchscreen/gsl3670.mdx b/src/content/docs/components/touchscreen/gsl3670.mdx index 05b6e4e7f8..dfd220e7bc 100644 --- a/src/content/docs/components/touchscreen/gsl3670.mdx +++ b/src/content/docs/components/touchscreen/gsl3670.mdx @@ -23,7 +23,7 @@ touchscreen: ``` ```yaml -# Example configuration entry using a custom firmware file +# Example configuration entry for a custom touchscreen touchscreen: platform: gsl3670 id: my_touchscreen From 4cbd27b00f295014ea708094741b5c3d5adc8fcf Mon Sep 17 00:00:00 2001 From: clydebarrow <2366188+clydebarrow@users.noreply.github.com> Date: Mon, 1 Jun 2026 17:58:01 +1000 Subject: [PATCH 3/3] Update firmware docs --- .../docs/components/touchscreen/gsl3670.mdx | 28 +++++++++++++++---- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/src/content/docs/components/touchscreen/gsl3670.mdx b/src/content/docs/components/touchscreen/gsl3670.mdx index dfd220e7bc..4990ce15fa 100644 --- a/src/content/docs/components/touchscreen/gsl3670.mdx +++ b/src/content/docs/components/touchscreen/gsl3670.mdx @@ -10,7 +10,7 @@ An [I²C](/components/i2c) bus is required to be set up in your configuration fo This controller is used in the Seeed Studio reTerminal D1001. -The component requires a binary firmware file to be loaded into the controller during initialization. A firmware file for the Seeed reTerminal D1001 is bundled with the component. +The component requires a binary firmware file to be loaded into the controller during initialization. When using a built-in model, this firmware is downloaded automatically from the [esphome-libs/gsl3670-firmware](https://github.com/esphome-libs/gsl3670-firmware) release and cached locally, so it does not need to be supplied manually. The download is verified against a known SHA-256 checksum. Alternatively, a firmware file can be supplied from a custom URL or from a local file. ## Base Touchscreen Configuration @@ -23,24 +23,42 @@ touchscreen: ``` ```yaml -# Example configuration entry for a custom touchscreen +# Example configuration entry for a custom touchscreen, firmware from a URL touchscreen: platform: gsl3670 id: my_touchscreen interrupt_pin: GPIOXX reset_pin: GPIOXX - firmware_file: my_gsl3670_firmware.bin + firmware: + url: https://example.com/my_gsl3670_firmware.bin + sha256: 2e50501ad83656fb6fa3d92591f9f31add4d442c8e8a79f29f5c4d335bd127a4 +``` + +```yaml +# Example configuration entry using a local firmware file +touchscreen: + platform: gsl3670 + id: my_touchscreen + interrupt_pin: GPIOXX + reset_pin: GPIOXX + firmware: + file: my_gsl3670_firmware.bin ``` ### Configuration variables - **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually set the ID of this touchscreen. - **model** (*Optional*, string): A predefined model that sets default values for pin assignments, calibration, and firmware. Currently supported: - - `SEEED-RETERMINAL-D1001`: Seeed Studio reTerminal D1001. Sets appropriate defaults for interrupt pin, reset pin, calibration, axis mirroring/swapping, and firmware. + - `SEEED-RETERMINAL-D1001`: Seeed Studio reTerminal D1001. Sets appropriate defaults for interrupt pin, reset pin, calibration, axis mirroring/swapping, and the firmware download URL and checksum. - `CUSTOM`: No defaults are applied; all options must be configured manually. This is the default. - **interrupt_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The touch detection pin. - **reset_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The chip reset pin. -- **firmware_file** (**Required**, string): Path to the GSL3670 binary firmware file. When using a built-in model, this is set automatically. The firmware file is validated at compile time for correct format and integrity. If the file is not found at the given path, the component will also look for it in its own directory. +- **firmware** (**Required**, dict): The source of the GSL3670 binary firmware file. When using a built-in model, this is set automatically. Exactly one of `url` or `file` must be provided: + - **url** (*Optional*, string): URL of the firmware file. The file is downloaded and cached locally at build time. + - **sha256** (*Optional*, string): The expected SHA-256 checksum of the downloaded firmware file. When set, the download is rejected if the checksum does not match. + - **file** (*Optional*, string): Path to a local firmware file, used instead of downloading from `url`. If the file is not found at the given path, the component will also look for it in its own directory. + +The firmware is validated for correct format and integrity at config validation time. - All other options from [Touchscreen](/components/touchscreen#config-touchscreen).