Skip to content

Screen

The screen is used by all other functions and libraries.

Configure

Select the library corresponding to the size of the screen and the edition of the library.

#include "PDLS_EXT3_Advanced_Fast_Small.h";

The pre-processor statement includes the screen libraries.

1
2
3
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_09,
    boardLaunchPad,
    frameBuffer);

The constructor Screen_EPD_EXT3_Fast creates the screen object.

The required parameters are

The optional parameter is

  • The third line links to the frame-buffer if declared at build-time.

Screen model

The screen model starts with eScreen_EPD_EXT3_, contains the size and the type, both taken from the product number.

The product number of the panel is printed on the back of the screen, on the top line close to the QR-code.

Example

The screen with product number CE2271CS094 corresponds to a 2.71" panel with type 09. The last digit 4 is ignored.

- Size - Type -
CE2 271 CS 09 4
eScreen_EPD_EXT3_ 271 _ 09

The screen model for the constructor is eScreen_EPD_EXT3_271_09.

    eScreen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_09, boardLaunchPad);

Other specific cases for the constructor are listed below.

Screens with embedded fast update require the additional mention of Fast.

The screen model starts with eScreen_EPD_EXT3_ and mentions the size of the screen, then _ and Fast.

Example

The screen with product number SE2271PS09 corresponds to a 2.71" panel with embedded fast update.

- Size - Type
SE2 271 PS 09
eScreen_EPD_EXT3_ 271 _ Fast

The screen model for the constructor is eScreen_EPD_EXT3_271_Fast.

eScreen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_Fast, boardLaunchPad);

The screen model starts with eScreen_EPD_EXT3_ and mentions the size of the screen.

Example

The screen with product number CE2271CS0E corresponds to a 2.71" panel with type 0E.

- Size - Type
CE2 271 CS 0E
eScreen_EPD_EXT3_ 271

The screen model for the constructor is eScreen_EPD_EXT3_271.

eScreen_EPD_EXT3 myScreen(eScreen_EPD_EXT3_271, boardLaunchPad);

Large screens may require the additional mention of the type, especially if it is 08.

The screen model starts with eScreen_EPD_EXT3_ and mentions the size of the screen, then _ and the type.

Example

The screen with product number CE2969JS08 corresponds to a 9.69" panel with type 08.

- Size - Type
CE2 969 CS 08
eScreen_EPD_EXT3_ 969 _ 08

The screen model for the constructor is eScreen_EPD_EXT3_969_08.

eScreen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_969_08, boardLaunchPad);

The size of the 12.0" panel is coded as B98 and corresponds to 11.98".

The screens featuring touch require the additional mention of Touch.

The screen model starts with eScreen_EPD_EXT3_ and mentions the size of the screen, then _ and Touch.

Example

The screen with product number QE2370PS0C1 corresponds to a 3.70" touch-panel with type 0C.

- Size - Type
QE2 370 PS 0C
eScreen_EPD_EXT3_ 370 _ Touch

The screen model for the constructor is eScreen_EPD_EXT3_370_Touch.

eScreen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_370_Touch, boardLaunchPad);

Board configuration

A board configuration defines all the GPIOs connected to the EXT3 extension board.

The SPI and I²C ports set their respective pins.

There are three families of boards. The configuration file lists the recommended boards and includes other boards. Additional non-listed boards can easily be defined.

The recommended boards are:

Constant Board
boardFeatherM0M4 Adafruit Feather M0 and M4
boardESP32DevKitC ‚ÄčEspressif ESP32-DevKitC
boardRaspberryPiPico_RP2040 Raspberry Pi Pico with Arduino-Pico

Those recommended boards have been extensively tested. The Raspberry Pi Pico with Arduino-Pico is part of the the EPD Pico Kit (EPDK) .

Other boards are also available:

Constant Board
boardArduinoZero Arduino Zero or M0 Pro
boardParticlePhoton Particle Photon and RedBear Duo
boardRaspberryPiZeroB_RasPiArduino Raspberry Pi Zero and B
boardRaspberryPiZeroB_BCM2835 Raspberry Pi Zero and B
boardRaspberryPiZeroB_MRAA Raspberry Pi Zero and B
boardRaspberryPiPico_Arduino Raspberry Pi Pico with Arduino Core mbed
boardNucleo64 STM32 Nucleo
boardLaunchPad Texas Instruments LaunchPad MSP430 and MSP432
boardCC1352 Texas Instruments LaunchPad and LPSTK CC1352R

Those boards are for reference only, as they may require specific SDK configurations.

To use another non-listed board,

  • Create a variable with the pins_t structure;
  • Set the pins of the connected GPIOs, or specify NOT_CONNECTED otherwise;
  • Mention this variable to the constructor.
Example
const pins_t myBoard =
{
    .panelBusy = 11, ///< EXT3 and EXT3-1 pin 3 Red
    .panelDC = 12, ///< EXT3 and EXT3-1 pin 4 Orange
    .panelReset = 13, ///< EXT3 and EXT3-1 pin 5 Yellow
    .flashCS = 18, ///< EXT3 and EXT3-1 pin 8 Violet
    .panelCS = 19, ///< EXT3 and EXT3-1 pin 9 Grey
    .panelCSS = 39, ///< EXT3 and EXT3-1 pin 12 Grey2
    .flashCSS = 38, ///< EXT3 and EXT3-1 pin 20 Black2
    .touchInt = NOT_CONNECTED, ///< EXT3-Touch pin 3 Red
    .touchReset = NOT_CONNECTED, ///< EXT3-Touch pin 4 Orange
    .cardCS = NOT_CONNECTED, ///< Separate SD-card board
    .cardDetect = NOT_CONNECTED, ///< Separate SD-card board
};

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271, myBoard);

Frame-buffer

By default, the frame-buffer is created at run-time with the MCU internal SRAM.

The size of the frame-buffer corresponds to the number of pixels divided by 8 (8 pixels per byte) and multiplied by two (1 bit per colour, two colours or previous and next images).

Diagonal (inches) Width (pixels) Height (pixels) Frame-buffer (bytes)
1.54 152 152 5,776
2.13 104 212 5,512
2.66 152 296 11,248
2.71 176 264 11,616
2.87 128 296 9,472
3.70 240 416 24,960
4.17 400 300 30,000
4.37 176 480 21,120
5.81 256 720 46,080
7.41 480 800 96,000
9.69 672 960 161,280
11.98 768 960 184,320

However, the frame-buffer can be specified at build-time and passed on to the constructor as parameter.

uint8_t frameBuffer[frameSize_EPD_EXT3_271];
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_09, boardLaunchPad, frameBuffer);

The constant for the size of the frame-buffer starts with frameBuffer_EPD_EXT3_ and contains the size taken from the product number.

Diagonal (inches) Frame-buffer (bytes) Frame-buffer (constant)
1.54 5,776 frameBuffer_EPD_EXT3_154
2.13 5,512 frameBuffer_EPD_EXT3_213
2.66 11,248 frameBuffer_EPD_EXT3_266
2.71 11,616 frameBuffer_EPD_EXT3_271
2.87 9,472 frameBuffer_EPD_EXT3_287
3.70 24,960 frameBuffer_EPD_EXT3_370
4.17 30,000 frameBuffer_EPD_EXT3_417
4.37 21,120 frameBuffer_EPD_EXT3_437
5.81 46,080 frameBuffer_EPD_EXT3_581
7.41 96,000 frameBuffer_EPD_EXT3_741
9.69 161,280 frameBuffer_EPD_EXT3_969
11.98 184,320 frameBuffer_EPD_EXT3_B98

Specifying the frame-buffer at build-time is required for the cases listed below.

For MCUs where the memory location is managed at build-time such as FRAM-based MSP430FR5994, use instead

uint8_t frameBuffer[frameSize_EPD_EXT3_271] PLACE_IN_FRAM;
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_09, boardLaunchPad, frameBuffer);

The PLACE_IN_FRAM macro tells the compiler to locate the frame-buffer in upper-FRAM.

For MCUs which manage external memory such as ESP32 with PSRAM or pseudo-static RAM, use instead

uint8_t * frameBuffer = (uint8_t *) ps_malloc(frameSize_EPD_EXT3_271);
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_09, boardESP32DevKitC, frameBuffer);

The ps_malloc() allocator tells the compiler to locate the frame-buffer on the PSRAM.

Use

myScreen.begin();

begin() initialises the screen, including the required GPIOs, and the SPI and I²C ports.

Up to three different update modes are available for the panels: global update for all the monochrome and colour screens, fast update and partial update for selected monochrome screens.

myScreen.gText(4, 4, myScreen.whoAmI());
myScreen.flush();

whoAmI() returns the name of the screen.

gText() prints text on the screen.

flush() uploads the frame-buffer to the screen and performs a global update of the panel.

myScreen.gText(4, 4, myScreen.whoAmI());
myScreen.flushFast();

whoAmI() returns the name of the screen.

gText() prints text on the screen.

flushFast() uploads the frame-buffer to the screen and performs a fast update of the panel.

When global update is not available, flush() redirects to flushFast().

myScreen.beginPartial();
myScreen.gText(4, 4, myScreen.whoAmI());
myScreen.flushPartial();

whoAmI() returns the name of the screen.

gText() prints text on the screen.

beginPartial() starts the partial mode and resets the coordinates of the window.

The coordinates of the modified window are updated automatically when drawing text and graphics.

flushPartial() uploads the modified window from the frame-buffer to the screen, and performs a partial update of the panel.

Note

For small screens, partial update may not be faster than fast update.

The application note provides the procedure to Optimise update modes.

The functions are grouped in six categories.

Example

This is the core of the code from the example WhoAmI.ino.

// Screen
#include "PDLS_EXT3_Advanced_Fast_Small.h";

// SDK
#include "hV_HAL_Peripherals.h"

// Configuration
#include "hV_Configuration.h"

// Set parameters
#define DISPLAY_WHOAMI 1

// Include application, user and local libraries
#include "hV_Utilities.h"

// Define variables and constants
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_09, boardLaunchPad);

uint8_t fontSans;

#if (DISPLAY_WHOAMI == 1)

void displayWhoAmI()
{
    myScreen.selectFont(fontSans);
    myScreen.setOrientation(myOrientation);

    myScreen.gText(4, 4, myScreen.WhoAmI());

    // Global update
    myScreen.flush();
}

#endif // DISPLAY_WHOAMI

// Add setup code
void setup()
{
    hV_HAL_begin();

    hV_HAL_Debug_begin(115200);
    hV_HAL_delayMilliseconds(500);
    hV_HAL_Debug_println("");
    hV_HAL_Debug_println("=== " __FILE__);
    hV_HAL_Debug_println("=== " __DATE__ " " __TIME__);
    hV_HAL_Debug_println("");

    // initialise screen
    hV_HAL_Debug_print("begin... ");
    myScreen.begin();
    hV_HAL_Debug_println("done");

    // Add fonts from header files
    fontSans = myScreen.addFont(Font_DejaVuSans16);
    fontSans -= (fontSans > 0) ? 1 : 0;

    // Example
#if (DISPLAY_WHOAMI == 1)

    hV_HAL_Debug_print("DISPLAY_WHOAMI... ");
    myScreen.clear();
    displayWhoAmI();
    hV_HAL_Debug_println("done");

    wait(4);

#endif // DISPLAY_WHOAMI

    hV_HAL_Debug_println("=== ");
    hV_HAL_exit(0);
}

// Add loop code
void loop()
{
    hV_HAL_delayMilliseconds(1000);
}