T5S3 e-paper: grayscale driver with per pixel doses as default

Devices/lilygo-t5-epd47-s3/device.properties

@@ -10,7 +10,7 @@ hardware.spiRamSpeed=80M
 hardware.esptoolFlashFreq=80M
 hardware.bluetooth=true
 
-storage.userDataLocation=Internal
+storage.userDataLocation=SD
 
 display.size=4.7"
 display.dpi=235

Devices/lilygo-t5-epd47-s3/lilygo,t5-epd47-s3.dts

@@ -12,6 +12,7 @@
 #include <bindings/gt911.h>
 #include <tactility/bindings/esp32_sdspi.h>
 #include <bindings/t5s3_display.h>
+// #include <bindings/t5s3_display_bw.h>
 
 / {
 	compatible = "root";
@@ -33,6 +34,8 @@
 	// Listed before the I2C bus on purpose, the touch controller was only tested with the display started first
 	display {
 		compatible = "lilygo,t5s3-display";
+		// Black and white only with faster updates, enable it together with its include above
+		// compatible = "lilygo,t5s3-display-bw";
 	};
 
 	i2c_internal {

Drivers/lilygo-t5s3-epd-module/CMakeLists.txt

@@ -12,7 +12,8 @@ tactility_add_module(lilygo-t5s3-epd-module
 
 # The pixel loops of the display are too slow with the debug optimization level of the project
 set_source_files_properties(
-    source/t5s3_epd.cpp
+    source/t5s3_epd_board.cpp
+    source/t5s3_display_bw.cpp
     source/t5s3_display.cpp
     PROPERTIES COMPILE_OPTIONS -O2
 )

Drivers/lilygo-t5s3-epd-module/README.md

@@ -1,28 +1,30 @@
 # lilygo-t5s3-epd-module
 
-A kernel driver for the 4.7" 960x540 `ED047TC1` e-paper panel of the LILYGO T5 4.7 Inch E-Paper S3 (V2.3/V2.4).
+Kernel drivers for the 4.7" 960x540 `ED047TC1` e-paper panel of the LILYGO T5 4.7 Inch E-Paper S3 (V2.3/V2.4).
 
-The driver only works on this board. The pins of the panel, the 74HCT4094 shift register that carries the panel supplies and the sequence of the panel are fixed in the code, so the devicetree node only has the pixel clock as property.
+The drivers only work on this board. The pins of the panel, the 74HCT4094 shift register that carries the panel supplies and the sequence of the panel are fixed in the code, so the devicetree node only has the pixel clock as property.
 
-- `t5s3_display.cpp`: the Tactility display driver. It decides between fast and quality updates.
-- `t5s3_epd.cpp`: the engine. It controls the shift register, the CKV gate clock (RMT peripheral), the row transfer (LCD peripheral in i80 mode), the update loop and the clear sequence.
-- `t5s3_epd_rows.h`: the conversion of framebuffer rows into bus data. It has no hardware access.
-- `t5s3_epd_waveform.h`: the 30 phase drive table of the quality updates.
+There are two drivers. A devicetree uses one of them, the device `lilygo-t5-epd47-s3` uses the grayscale one and has the black and white one commented out in its devicetree:
 
-There are three update modes. Fast draws black and white only. Quality draws 16 levels and leaves white pixels that stay white alone, which is used for partial updates. Full also flashes those white pixels, which is used for the clear and the refresh.
+- `lilygo,t5s3-display` (`t5s3_display.cpp`): 16 shades from black to white, dithered between neighbouring shades. Each pixel whose target shade changes gets a dose of frames, in the manner of [InkBoy](https://github.com/kuslota/InkBoy): black is driven dark for 18 frames, white and the grays are driven light for 15 frames, which erases what the pixel showed before, and the grays then rest for 0 to 3 frames and are driven dark for 1 to 8 frames. Each frame of rest makes a gray a little darker, which gives 14 grays close to each other, so the dither is hardly visible. Every gray is reached the same way, so moving content leaves almost no trails. Frames of 40 ms cover the whole screen, so all changes show at once: black and white within a few frames, a gray after about 0.9 s. `refresh()` flashes the panel and draws the content again, and the driver does that by itself when the content changed without touches for 10 minutes. A frame that stalls, for example while the flash is written, makes the grays it interrupted start again. `draw_bitmap()` does not wait for the panel and pixels that do not change are never driven. It needs the pixel clock of 20 MHz of its binding.
+- `lilygo,t5s3-display-bw` (`t5s3_display_bw.cpp`): black and white with a pixel state machine, like the M5Stack PaperS3 driver. Gray levels are dithered. It is the fastest.
+
+Shared and internal files:
+
+- `t5s3_epd_board.cpp`: the signalling of the board. It controls the shift register, the CKV gate clock (RMT peripheral) and the row transfer (LCD peripheral in i80 mode), and sends one frame at a time.
+
+A pixel keeps its drive until its row is addressed again, so frames are padded to a fixed period. The doses, the frame counts and the shade brightness in the code were measured with a camera on the panel.
 
 ## License
 
-The engine and its tables are derived from [epdiy](https://github.com/vroland/epdiy) and are licensed under the
+The board signalling is derived from [epdiy](https://github.com/vroland/epdiy) and is licensed under the
 [LGPL v3.0 or later](LICENSE-LGPL-3.0.md) (the LGPL supplements the [GPL v3.0](../../Documentation/LICENSE-GPL-3.0.md)):
 
-- `source/t5s3_epd.cpp`
-- `source/t5s3_epd.h`
-- `source/t5s3_epd_rows.h`
-- `source/t5s3_epd_waveform.h`
+- `source/t5s3_epd_board.cpp`
+- `source/t5s3_epd_board.h`
 
-These files follow the sequences and timings of epdiy and contain its ED047TC1 waveform data. Each of them has an `SPDX-License-Identifier: LGPL-3.0-or-later` header.
+These files follow the sequences and timings of epdiy. Each of them has an `SPDX-License-Identifier: LGPL-3.0-or-later` header.
 
-The rest of the module (`source/t5s3_display.cpp`, `source/module.cpp`, the bindings and the headers in `include/`) is licensed under [Apache License v2.0](LICENSE-Apache-2.0.md).
+The rest of the module (`source/t5s3_display.cpp`, `source/t5s3_display_bw.cpp`, `source/module.cpp`, the bindings and the headers in `include/`) is licensed under [Apache License v2.0](LICENSE-Apache-2.0.md). The pixel state machine in `t5s3_display_bw.cpp` follows the M5Stack PaperS3 display driver of Tactility. The dose method of `t5s3_display.cpp` follows the description of InkBoy (MIT), no code of InkBoy is used.
 
-A project that contains this module has to follow the LGPL for the four files above.
+A project that contains this module has to follow the LGPL for the files above.

Drivers/lilygo-t5s3-epd-module/bindings/lilygo,t5s3-display-bw.yaml

@@ -0,0 +1,12 @@
+description: >
+  LILYGO T5 4.7 Inch E-Paper S3 (V2.3/V2.4) display with an ED047TC1 panel, driven in black and white with a pixel
+  state machine instead of waveform tables. Updates are fast and do not block. Gray levels are dithered.
+  The pins of the panel are fixed in the driver, so this node only has the pixel clock as property.
+
+compatible: "lilygo,t5s3-display-bw"
+
+properties:
+  pixel-clock-hz:
+    type: int
+    default: 10000000
+    description: Clock of the bus that sends the pixel data of a row. Faster speeds up updates if the panel accepts it.

Drivers/lilygo-t5s3-epd-module/bindings/lilygo,t5s3-display.yaml

@@ -1,11 +1,14 @@
 description: >
-  LILYGO T5 4.7 Inch E-Paper S3 (V2.3/V2.4) display with an ED047TC1 panel. The pins of the panel
-  are fixed in the driver, so this node only has the pixel clock as property.
+  LILYGO T5 4.7 Inch E-Paper S3 (V2.3/V2.4) display with an ED047TC1 panel, driven in 16 shades with a dose of
+  frames per pixel instead of waveform tables. Updates do not block and leave no trails on gray backgrounds.
+  The pins of the panel are fixed in the driver, so this node only has the pixel clock as property.
 
 compatible: "lilygo,t5s3-display"
 
 properties:
   pixel-clock-hz:
     type: int
-    default: 10000000
-    description: Clock of the bus that sends the pixel data of a row. Faster speeds up updates if the panel accepts it.
+    default: 20000000
+    description: >
+      Clock of the bus that sends the pixel data of a row. The doses of the shades were measured with 20 MHz,
+      which lets a frame of all rows fit in its period.

Drivers/lilygo-t5s3-epd-module/include/bindings/t5s3_display_bw.h

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <tactility/bindings/bindings.h>
+#include <drivers/t5s3_display_bw.h>
+
+DEFINE_DEVICETREE(t5s3_display_bw, struct T5s3DisplayBwConfig)
+
+#ifdef __cplusplus
+}
+#endif

Drivers/lilygo-t5s3-epd-module/include/drivers/t5s3_display_bw.h

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct T5s3DisplayBwConfig {
+    uint32_t pixel_clock_hz;
+};
+
+#ifdef __cplusplus
+}
+#endif

Drivers/lilygo-t5s3-epd-module/source/module.cpp

@@ -5,9 +5,11 @@
 extern "C" {
 
 extern Driver t5s3_display_driver;
+extern Driver t5s3_display_bw_driver;
 
 static Driver* const lilygo_t5s3_epd_drivers[] = {
     &t5s3_display_driver,
+    &t5s3_display_bw_driver,
     nullptr
 };