Add partialWindowUpdate function to the 13spectra driver

JosipKuci · JosipKuci · commit 86448e023fbd · 2026-03-30T09:05:47.000+02:00
diff --git a/examples/Inkplate13SPECTRA/Basic/Inkplate13SPECTRA_Partial_Update/Inkplate13SPECTRA_Partial_Update.ino b/examples/Inkplate13SPECTRA/Basic/Inkplate13SPECTRA_Partial_Update/Inkplate13SPECTRA_Partial_Update.ino
@@ -0,0 +1,100 @@
+/*
+   Inkplate13SPECTRA_Partial_Update example for Soldered Inkplate 13SPECTRA
+   Select "Soldered Inkplate 13SPECTRA" from Tools -> Board menu.
+
+   This example demonstrates partial screen updates on the Inkplate 13SPECTRA.
+   It draws a grid of 100x100 pixel coloured squares covering the entire screen,
+   then continuously picks a random square and updates only that square with a
+   new colour using displayPartial(), leaving the rest of the screen untouched.
+
+   displayPartial(x, y, w, h) accepts coordinates in the same user space as all
+   drawing functions (rotation=1: 1600 px wide, 1200 px tall).
+
+   Want to learn more about Inkplate? Visit www.inkplate.io
+   Looking to get support? Write on our forums: https://forum.soldered.com/
+   24 March 2026 by Soldered
+*/
+
+#ifndef ARDUINO_INKPLATE13SPECTRA
+#error "Wrong board selection for this example, please select Soldered Inkplate 13SPECTRA in the boards menu."
+#endif
+
+#include "Inkplate.h"
+
+Inkplate display;
+
+// Display dimensions at rotation=1
+#define DISPLAY_W 1600
+#define DISPLAY_H 1200
+
+// Square size and grid dimensions
+#define SQUARE_SIZE 200
+#define GRID_COLS   (DISPLAY_W / SQUARE_SIZE) // 8
+#define GRID_ROWS   (DISPLAY_H / SQUARE_SIZE) // 6
+
+// Available colours (indices 0-5 map to: black, white, yellow, red, blue, green)
+static const uint8_t COLORS[] = {0, 1, 2, 3, 4, 5};
+#define COLOR_COUNT 6
+
+// Tracks the current colour of every square so we can pick a different one
+uint8_t squareColor[GRID_COLS][GRID_ROWS];
+
+void setup()
+{
+    Serial.begin(115200);
+
+    display.begin();
+    display.clearDisplay();
+
+    // Fill each square with an initial colour, cycling through the palette
+    for (int col = 0; col < GRID_COLS; col++)
+    {
+        for (int row = 0; row < GRID_ROWS; row++)
+        {
+            uint8_t color = COLORS[(col + row) % COLOR_COUNT];
+            squareColor[col][row] = color;
+            display.fillRect(col * SQUARE_SIZE, row * SQUARE_SIZE,
+                             SQUARE_SIZE, SQUARE_SIZE, color);
+        }
+    }
+
+    display.display();
+
+    Serial.println("Initial grid drawn. Waiting 5 seconds before partial updates begin.");
+    delay(5000);
+}
+
+void loop()
+{
+    // Pick a random square
+    int col   = random(GRID_COLS);
+    int row   = random(GRID_ROWS);
+
+    // Pick a different colour than the current one
+    uint8_t current = squareColor[col][row];
+    uint8_t newColor;
+    do
+    {
+        newColor = COLORS[random(COLOR_COUNT)];
+    } while (newColor == current);
+
+    squareColor[col][row] = newColor;
+
+    // Update the framebuffer for just this square
+    display.fillRect(col * SQUARE_SIZE, row * SQUARE_SIZE,
+                     SQUARE_SIZE, SQUARE_SIZE, newColor);
+
+    // Refresh only the changed square; pass true to keep panel on for next call.
+    display.displayPartial(col * SQUARE_SIZE, row * SQUARE_SIZE,
+                           SQUARE_SIZE, SQUARE_SIZE, true);
+
+    Serial.print("Updated square (");
+    Serial.print(col);
+    Serial.print(", ");
+    Serial.print(row);
+    Serial.print(") to colour ");
+    Serial.println(newColor);
+
+    // 3 second delay between refreshes
+    delay(3000);
+}
diff --git a/src/boards/Inkplate13/Inkplate13Driver.cpp b/src/boards/Inkplate13/Inkplate13Driver.cpp
@@ -182,6 +182,220 @@ void EPDDriver::display(bool _leaveOn)
         setPanelState(false);
 }
 
+/**
+ * @brief       displayPartial refreshes only the specified rectangular region of the screen
+ *              using the PTLW (Partial Load Window) register of the GDEP133C02 controller.
+ *              Only the pixels inside the window are transferred to the panel; the rest of the
+ *              display is unaffected.
+ *
+ * @param       int16_t x        Left edge of the update window (user space)
+ * @param       int16_t y        Top edge of the update window (user space)
+ * @param       int16_t w        Width of the update window in pixels
+ * @param       int16_t h        Height of the update window in pixels
+ * @param       bool _leaveOn    If true, panel power is left on after the update
+ */
+void EPDDriver::displayPartial(int16_t x, int16_t y, int16_t w, int16_t h, bool _leaveOn)
+{
+    // Clip to the screen bounds for the current rotation.
+    if (x < 0) { w += x; x = 0; }
+    if (y < 0) { h += y; y = 0; }
+    if (x + w > _inkplate->width())  w = _inkplate->width()  - x;
+    if (y + h > _inkplate->height()) h = _inkplate->height() - y;
+    if (w <= 0 || h <= 0) return;
+
+    // Map user rectangle to panel-native rectangle.
+    // Panel native: col = 0..E_INK_WIDTH-1 (1199), row = 0..E_INK_HEIGHT-1 (1599).
+    // Each case mirrors the per-pixel transform in writePixelInternal.
+    int16_t colStart, colEnd, rowStart, rowEnd;
+    switch (_inkplate->getRotation())
+    {
+    case 0:
+        // User space: E_INK_WIDTH × E_INK_HEIGHT.
+        // panel_col = (E_INK_WIDTH-1) - x,  panel_row = (E_INK_HEIGHT-1) - y.
+        colStart = (int16_t)E_INK_WIDTH  - x - w;
+        colEnd   = (int16_t)E_INK_WIDTH  - 1 - x;
+        rowStart = (int16_t)E_INK_HEIGHT - y - h;
+        rowEnd   = (int16_t)E_INK_HEIGHT - 1 - y;
+        break;
+    case 2:
+        // User space: E_INK_WIDTH × E_INK_HEIGHT.
+        // panel_col = x,  panel_row = y  (identity — no transform applied in writePixelInternal).
+        colStart = x;
+        colEnd   = x + w - 1;
+        rowStart = y;
+        rowEnd   = y + h - 1;
+        break;
+    case 3:
+        // User space: E_INK_HEIGHT × E_INK_WIDTH.
+        // panel_col = (E_INK_WIDTH-1) - y,  panel_row = x.
+        colStart = (int16_t)E_INK_WIDTH - y - h;
+        colEnd   = (int16_t)E_INK_WIDTH - 1 - y;
+        rowStart = x;
+        rowEnd   = x + w - 1;
+        break;
+    default:
+    case 1:
+        // User space: E_INK_HEIGHT × E_INK_WIDTH.
+        // panel_col = y,  panel_row = (E_INK_HEIGHT-1) - x.
+        colStart = y;
+        colEnd   = y + h - 1;
+        rowStart = (int16_t)E_INK_HEIGHT - x - w;
+        rowEnd   = (int16_t)E_INK_HEIGHT - 1 - x;
+        break;
+    }
+
+    // PTLW alignment requirements (GDEP133C02):
+    //   H: colStart and (colEnd+1) must both be multiples of 4.
+    //   V: rowStart must be even; (rowEnd+1) must be even.
+    colStart = (colStart / 4) * 4;
+    colEnd   = (((colEnd + 4) / 4) * 4) - 1;
+    if (colEnd  >= (int16_t)E_INK_WIDTH)  colEnd  = (int16_t)E_INK_WIDTH  - 1;
+    if (rowStart % 2 != 0) rowStart--;
+    if (rowStart < 0) rowStart = 0;
+    if ((rowEnd + 1) % 2 != 0) rowEnd++;
+    if (rowEnd  >= (int16_t)E_INK_HEIGHT) rowEnd  = (int16_t)E_INK_HEIGHT - 1;
+
+    setPanelState(true);
+
+    const int16_t HALF_WIDTH = (int16_t)(E_INK_WIDTH / 2); // 600 pixels per chip
+    const int16_t HALF_BYTES = HALF_WIDTH / 2;              // 300 bytes per row per chip
+
+    bool masterNeeded = (colStart < HALF_WIDTH);
+    bool slaveNeeded  = (colEnd   >= HALF_WIDTH);
+
+    // Both chips must receive a full PTLW+DTM cycle before DRF, otherwise the
+    // uninvolved chip falls back to a full-panel refresh when DRF fires.
+    // For the uninvolved chip, a minimal 4×4 null window is used: it reads the
+    // existing framebuffer data (same as what is already on screen) so the
+    // refresh produces no visible change on that side.
+    static const uint8_t ptlwNull[9] = {
+        0x00, 0x00,  // HRST = 0
+        0x00, 0x07,  // HRED = 7
+        0x00, 0x00,  // VRST = 0
+        0x00, 0x01,  // VRED = 1
+        0x01         // PT   = 1 (enable)
+    };
+
+    // Master chip
+    {
+        uint8_t  ptlwData[9];
+        int16_t  bytesPerRow, memColOff, rStart, rEnd;
+
+        if (masterNeeded)
+        {
+            int16_t lcs     = colStart;
+            int16_t lce     = (colEnd < HALF_WIDTH) ? colEnd : (HALF_WIDTH - 1);
+            uint16_t HRST   = (uint16_t)lcs * 2;
+            uint16_t HRED   = (uint16_t)(lce + 1) * 2 - 1;
+            uint16_t VRST   = (uint16_t)rowStart / 2;
+            uint16_t VRED   = (uint16_t)(rowEnd + 1) / 2 - 1;
+            ptlwData[0] = HRST >> 8; ptlwData[1] = HRST & 0xFF;
+            ptlwData[2] = HRED >> 8; ptlwData[3] = HRED & 0xFF;
+            ptlwData[4] = VRST >> 8; ptlwData[5] = VRST & 0xFF;
+            ptlwData[6] = VRED >> 8; ptlwData[7] = VRED & 0xFF;
+            ptlwData[8] = 0x01;
+            bytesPerRow = (lce - lcs + 1) / 2;
+            memColOff   = lcs / 2;
+            rStart      = rowStart;
+            rEnd        = rowEnd;
+        }
+        else
+        {
+            memcpy(ptlwData, ptlwNull, 9);
+            bytesPerRow = 2;          // 4 px / 2 px-per-byte
+            memColOff   = 0;          // top-left corner of master's region
+            rStart      = 0;
+            rEnd        = 3;
+        }
+
+        SPI.beginTransaction(epdSpiSettings);
+        digitalWrite(SPECTRA133_CS_M_PIN, LOW);
+        SPI.write(SPECTRA133_REGISTER_CMD66);
+        SPI.writeBytes(SPECTRA133_REGISTER_CMD66_V, sizeof(SPECTRA133_REGISTER_CMD66_V));
+        digitalWrite(SPECTRA133_CS_M_PIN, HIGH);
+        SPI.endTransaction();
+
+        SPI.beginTransaction(epdSpiSettings);
+        digitalWrite(SPECTRA133_CS_M_PIN, LOW);
+        SPI.write(SPECTRA133_REGISTER_PTLW);
+        SPI.writeBytes(ptlwData, 9);
+        digitalWrite(SPECTRA133_CS_M_PIN, HIGH);
+        SPI.endTransaction();
+
+        SPI.beginTransaction(epdSpiSettings);
+        digitalWrite(SPECTRA133_CS_M_PIN, LOW);
+        SPI.write(SPECTRA133_REGISTER_DTM);
+        for (int16_t row = rStart; row <= rEnd; row++)
+            SPI.writeBytes(DMemory4Bit + row * (E_INK_WIDTH / 2) + memColOff, bytesPerRow);
+        digitalWrite(SPECTRA133_CS_M_PIN, HIGH);
+        SPI.endTransaction();
+    }
+
+    // Slave chip
+    waitForBusy();
+    {
+        uint8_t  ptlwData[9];
+        int16_t  bytesPerRow, memColOff, rStart, rEnd;
+
+        if (slaveNeeded)
+        {
+            int16_t lcs     = (colStart >= HALF_WIDTH) ? (colStart - HALF_WIDTH) : 0;
+            int16_t lce     = colEnd - HALF_WIDTH;
+            uint16_t HRST   = (uint16_t)lcs * 2;
+            uint16_t HRED   = (uint16_t)(lce + 1) * 2 - 1;
+            uint16_t VRST   = (uint16_t)rowStart / 2;
+            uint16_t VRED   = (uint16_t)(rowEnd + 1) / 2 - 1;
+            ptlwData[0] = HRST >> 8; ptlwData[1] = HRST & 0xFF;
+            ptlwData[2] = HRED >> 8; ptlwData[3] = HRED & 0xFF;
+            ptlwData[4] = VRST >> 8; ptlwData[5] = VRST & 0xFF;
+            ptlwData[6] = VRED >> 8; ptlwData[7] = VRED & 0xFF;
+            ptlwData[8] = 0x01;
+            bytesPerRow = (lce - lcs + 1) / 2;
+            memColOff   = HALF_BYTES + lcs / 2;
+            rStart      = rowStart;
+            rEnd        = rowEnd;
+        }
+        else
+        {
+            memcpy(ptlwData, ptlwNull, 9);
+            bytesPerRow = 2;          // 4 px / 2 px-per-byte
+            memColOff   = HALF_BYTES; // top-left corner of slave's region
+            rStart      = 0;
+            rEnd        = 3;
+        }
+
+        SPI.beginTransaction(epdSpiSettings);
+        digitalWrite(SPECTRA133_CS_S_PIN, LOW);
+        SPI.write(SPECTRA133_REGISTER_CMD66);
+        SPI.writeBytes(SPECTRA133_REGISTER_CMD66_V, sizeof(SPECTRA133_REGISTER_CMD66_V));
+        digitalWrite(SPECTRA133_CS_S_PIN, HIGH);
+        SPI.endTransaction();
+
+        SPI.beginTransaction(epdSpiSettings);
+        digitalWrite(SPECTRA133_CS_S_PIN, LOW);
+        SPI.write(SPECTRA133_REGISTER_PTLW);
+        SPI.writeBytes(ptlwData, 9);
+        digitalWrite(SPECTRA133_CS_S_PIN, HIGH);
+        SPI.endTransaction();
+
+        SPI.beginTransaction(epdSpiSettings);
+        digitalWrite(SPECTRA133_CS_S_PIN, LOW);
+        SPI.write(SPECTRA133_REGISTER_DTM);
+        for (int16_t row = rStart; row <= rEnd; row++)
+            SPI.writeBytes(DMemory4Bit + row * (E_INK_WIDTH / 2) + memColOff, bytesPerRow);
+        digitalWrite(SPECTRA133_CS_S_PIN, HIGH);
+        SPI.endTransaction();
+    }
+
+    // Both chips have received PTLW+DTM; trigger a coordinated refresh.
+    waitForBusy();
+    sendCommand(SPECTRA133_REGISTER_DRF, SPECTRA133_REGISTER_DRF_V, sizeof(SPECTRA133_REGISTER_DRF_V), eChipIdBoth);
+    waitForBusy();
+
+    if (!_leaveOn)
+        setPanelState(false);
+}
+
 /**
  * @brief       returns the current panel state, 0 for off, 1 for on
  *
@@ -334,6 +548,9 @@ void EPDDriver::sendCommand(uint8_t _cmd, const uint8_t *_parameters, uint32_t _
 }
 
 
+/**
+ * @brief       screenInit sends init commands to the panel.
+ */
 void EPDDriver::screenInit()
 {
     // Send magic values to the registers. These values are provided from the manufacturer.
@@ -484,7 +701,9 @@ double EPDDriver::readBattery()
     return (double(adc) * 2.0 / 1000);
 }
 
-// Method waits until the screen is ready to accept new commands.
+/**
+ * @brief       Method waits until the screen is ready to accept new commands.
+ */
 void EPDDriver::waitForBusy()
 {
     // Wait until the screen is ready to accept new commads.
@@ -496,7 +715,9 @@ void EPDDriver::waitForBusy()
     }
 }
 
-// Function helps empty capacitors, without this sometimes the panel refuses to refresh...
+/**
+ * @brief       Function helps empty capacitors, without this sometimes the panel refuses to refresh...
+ */
 void EPDDriver::setPanelPinsToLow()
 {
     pinMode(SPECTRA133_DC_PIN, OUTPUT);
diff --git a/src/boards/Inkplate13/Inkplate13Driver.h b/src/boards/Inkplate13/Inkplate13Driver.h
@@ -37,6 +37,7 @@ class EPDDriver
     int initDriver(Inkplate *_inkplatePtr);
 
     void display(bool _leaveOn = 0);
+    void displayPartial(int16_t x, int16_t y, int16_t w, int16_t h, bool _leaveOn = 0);
     void selectDisplayMode(uint8_t displayMode);
     void clearDisplay();
 
