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.h";

The pre-processor statement includes the screen libraries.

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_271_PS_09,
    boardRaspberryPiPico_RP2040,
    frameBuffer);

The constructor Screen_EPD_EXT3_Fast creates the screen object.

The required parameters are

The first line sets the model of the screen;
The second line selects the configuration of the main conrtoller board connected to the EXT3-1 extension board;

The optional parameter is

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

Screen model¶

The screen model starts with eScreen_EPD, contains the size, the film and the driver taken from the product number and separated with a _.

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 film CS and driver 09. The last digit 4 is ignored.

-	Size	Film	Driver	-
`CE2`	`271`	`CS`	`09`	`4`
`eScreen_EPD`	`_271`	`_CS`	`_09`

The screen model for the constructor is eScreen_EPD_271_CS_09.

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_271_CS_09, boardRaspberryPiPico_RP2040);

The film defines the features of the screen.

Film	Feature	Colour	Update	Commercial name
`CS`	Monochrome	Black and white	Global update
`HS`	Monochrome	Black and white	Global update	Freezer
`JS`	Red	Black, white, red	Global update	Spectra Red
`QS`	Red and yellow	Black, white, red, yellow	Global update	Spectra 4
`PS`	Embedded fast update	Black and white	Fast update	Aurora
`KS`	Wide temperature	Black and white	Fast update	Wide temperature
	Touch	Black and white	Fast update

The only specific case for the constructor corresponds to the screens featuring touch and embedded fast update.

The screens featuring touch and embedded fast update require the additional mention of _Touch.

The screen model starts with eScreen_EPD_EXT3 and contains the size, the film and the driver taken from the product number and separated by a _, then _Touch.

Example

The product number of the screens with touch includes a T at the second position.

The screen with product number QT2370PS0C1 corresponds to a 3.70” touch-panel with driver 0C.

-	Size	Film	Driver	Touch
`QT2`	`370`	`PS`	`0C`
`eScreen_EPD_EXT3`	`_370`	`_PS`	`_0C`	`_Touch`

The screen model for the constructor is eScreen_EPD_370_PS_0C_Touch.

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_370_PS_0C_Touch, boardRaspberryPiPico_RP2040);

Legacy version 7

The screen model starts with eScreen_EPD_EXT3_, contains the size and the driver, 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 film CS and driver 09. The last digit 4 is ignored.

-	Size	Film	Driver	-
`CE2`	`271`	`CS`	`09`	`4`
`eScreen_EPD_EXT3_`	`271`	`_`	`09`

The screen model for the constructor is eScreen_EPD_EXT3_271_09.

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_09, boardRaspberryPiPico_RP2040);

The specific cases for the constructor are listed below.

MonochromeRedRed and yellowEmbedded fast updateWide temperatureTouch

The product number of the screens with global update only includes a C after the size.

The screen model starts with eScreen_EPD_EXT3_ and mentions the size of the screen. Although the driver of the screen can be omitted, it is recommended to include it.

Example

The product number of the screens with global update only includes a C after the size 271.

The screen with product number CE2271CS0E corresponds to a 2.71” panel with driver 0E.

-	Size	Film	Driver
`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, boardRaspberryPiPico_RP2040);

A better solution is to include the driver with eScreen_EPD_EXT3_271_0E.

eScreen_EPD_EXT3 myScreen(eScreen_EPD_EXT3_271_0E, boardRaspberryPiPico_RP2040);

The product number of the screens with red colour includes a J after the size. The commercial name is Spectra.

The screens featuring red colour require the additional mention of BWR.

The screen model starts with eScreen_EPD_EXT3_ and contains the size taken from the product number, then _ and Red.

Example

The screen with product number CE2969JS08 corresponds to a 9.69” black-white-red panel with driver 0B.

-	Size	Film	Driver	Colour
`CE2`	`969`	`JS`	`0B`
`eScreen_EPD_EXT3_`	`969`			`_BWR`

The screen model for the constructor is eScreen_EPD_EXT3_969_BWR. The driver is omitted.

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_969_BWR, boardRaspberryPiPico_RP2040);

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

The product number of the screens with red and yellow colours includes a Q after the size. The commercial name is Spectra 4.

The screens featuring red colour require the additional mention of BWRY.

The screen model starts with eScreen_EPD_EXT3_ and contains the size taken from the product number, then _ and BWRY.

Example

The screen with product number CE2154QS0F corresponds to a 1.54” black-white-red-yellow panel with driver 0F.

-	Size	Film	Driver	Colour
`CE2`	`154`	`QS`	`0F`
`eScreen_EPD_EXT3_`	`154`			`_BWRY`

The screen model for the constructor is eScreen_EPD_EXT3_154_BWRY. The driver is omitted.

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_154_BWRY, boardRaspberryPiPico_RP2040);

The product number of the screens with embedded fast update includes a P after the size. The commercial name is Aurora.

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

The screen model starts with eScreen_EPD_EXT3_ and contains the size and the driver, both taken from the product number, then _ and Fast.

Example

The product number of the screens with embedded fast update includes a P after the size 271.

The screen with product number SE2271PS09 corresponds to a 2.71” panel with embedded fast update with driver 09.

-	Size	Film	Driver	Fast
`SE2`	`271`	`PS`	`09`
`eScreen_EPD_EXT3_`	`271`	`_`	`09`	`_Fast`

The screen model for the constructor is eScreen_EPD_EXT3_271_09_Fast.

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_09_Fast, boardRaspberryPiPico_RP2040);

The product number of the screens with wide temperature and embedded fast update includes a K after the size. The commercial name is Wide Temperature.

Screens with wide temperature and embedded fast update require the additional mention of Wide.

The screen model starts with eScreen_EPD_EXT3_ and contains the size and the driver, both taken from the product number, then _ and Wide.

The application note Manage temperatures discusses how to use the screens with wide temperature.

Example

The product number of the screens with touch includes a K after the size 271.

The screen with product number SE2271KS09 corresponds to a 2.71” panel with embedded fast update with driver 09.

-	Size	Film	Driver	Wide
`SE2`	`271`	`KS`	`09`
`eScreen_EPD_EXT3_`	`271`	`_`	`09`	`_Wide`

The screen model for the constructor is eScreen_EPD_EXT3_271_09_Wide.

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_09_Wide, boardRaspberryPiPico_RP2040);

The screens featuring touch and embedded fast update require the additional mention of Touch.

The screen model starts with eScreen_EPD_EXT3_ and contains the size and the driver, both taken from the product number, then _ and Touch.

Example

The product number of the screens with touch includes a T at the second position.

The screen with product number QT2370PS0C1 corresponds to a 3.70” touch-panel with driver 0C.

-	Size	Film	Driver	Touch
`QT2`	`370`	`PS`	`0C`
`eScreen_EPD_EXT3_`	`370`	`_`	`0C`	`_Touch`

The screen model for the constructor is eScreen_EPD_EXT3_370_0C_Touch.

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_370_0C_Touch, boardRaspberryPiPico_RP2040);

For more information about the screen model, please refer to the Model name explanation and The different types E Ink imaging film pages on the Pervasive Displays website.

Board configuration¶

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

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

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

Recommended boardsOther boardsDeprecated boardsNon-listed boards

The recommended boards are:

Constant	Board
`boardFeatherNRF52840`	Adafruit Feather
`boardArduinoNanoMatter`	Arduino Nano Matter
`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 EPD Pico Kit (EPDK) .

Other boards are also available:

Constant	Board
`boardArduinoZero`	Arduino Zero or M0 Pro
`boardFeatherNRF52832`	Adafruit Feather
`boardFeatherNRF52840`	Adafruit Feather
`boardFeatherRP2040`	Adafruit Feather
`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

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

Those boards are no longer supported. The configurations are provided for reference.

Constant	Board
`boardParticlePhoton`	Particle Photon and RedBear Duo
`boardLaunchPad`	Texas Instruments LaunchPad MSP430 and MSP432
`boardCC1352`	Texas Instruments LaunchPad and LPSTK CC1352R

Those boards are no longer sold or the related software is no longer mantained.

if the main controller board is not listed among the hV_List_Boards header file, it needs to be defined.

Please refer to the application note Define a non-listed board

Frame-buffer¶

By default, the frame-buffer is created dynamically 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.50	200	200	10,000
1.52	200	200	10,000
1.54	152	152	5,776
2.06	128	248	7,936
2.13	104	212	5,512
2.66	152	296	11,248
2.71	176	264	11,616
2.87	128	296	9,472
2.90	168	384	16,128
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 statically at build-time and passed on to the constructor as parameter.

uint8_t frameBuffer[frameSize_EPD_271];
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_271_PS_09, boardRaspberryPiPico_RP2040, frameBuffer);

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

Diagonal (inches)	Frame-buffer (bytes)	Frame-buffer (constant)
1.50	10,000	`frameSize_EPD_150`
1.52	10,000	`frameSize_EPD_152`
1.54	5,776	`frameSize_EPD_154`
2.06	7,936	`frameSize_EPD_206`
2.13	5,512	`frameSize_EPD_213`
2.66	11,248	`frameSize_EPD_266`
2.71	11,616	`frameSize_EPD_271`
2.87	9,472	`frameSize_EPD_287`
2.90	16,128	`frameSize_EPD_290`
3.70	24,960	`frameSize_EPD_370`
4.17	30,000	`frameSize_EPD_417`
4.20	30,000	`frameSize_EPD_420`
4.37	21,120	`frameSize_EPD_437`
5.81	46,080	`frameSize_EPD_581`
7.41	96,000	`frameSize_EPD_741`
9.69	161,280	`frameSize_EPD_969`
11.98	184,320	`frameSize_EPD_B98`

Legacy version 7

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

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

Internal FRAMExternal PSRAM

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

uint8_t frameBuffer[frameSize_EPD_271] PLACE_IN_FRAM;
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_271_PS_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_271);
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_271_PS_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.

Two different update modes are available for the panels: global update for all the monochrome and colour screens, fast update for selected monochrome screens and screens with touch.

Global updateFast updatePartial updateParametric update

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. It can also manage low-power.

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. It can also manage low-power.

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

Warning

The partial update mode is deprecated. Use fast update instead.

The parametric update is recommended for screens with wide temperature range.

myScreen.gText(4, 4, myScreen.whoAmI());
myScreen.setTemperatureC(25);
uint8_t mode = myScreen.flushMode(UPDATE_FAST);

whoAmI() returns the name of the screen.

gText() prints text on the screen.

setTemperatureC() sets the temperature in degrees Celsius, with default value 25 °C. For temperature in degrees Fahrenheit, use setTemperatureF() with default value 77 °F.

flushMode() checks the compatibility of the update mode with the temperature, performs the refresh when possible and returns the mode used. It can also manage low-power.

If the temperature is out of range, no refresh is carried out and the function returns UPDATE_NONE.

The application note provides the procedure to Manage temperature.

The functions are grouped in seven 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_PDLS.h"

// Define variables and constants
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_271_PS_09, boardRaspberryPiPico_RP2040);

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_Serial_crlf();
    hV_HAL_log(LEVEL_INFO, __FILE__);
    hV_HAL_log(LEVEL_INFO, __DATE__ " " __TIME__);
    hV_HAL_Serial_crlf();

    // Initialise screen
    myScreen.begin();
    hV_HAL_Serial_crlf();

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

    // Example
#if (DISPLAY_WHOAMI == 1)

    hV_HAL_log(LEVEL_INFO, "DISPLAY_WHOAMI... ");
    myScreen.clear();
    displayWhoAmI();
    hV_HAL_log(LEVEL_INFO, "done");
    hV_HAL_Serial_crlf();

    wait(4);

#endif // DISPLAY_WHOAMI

    hV_HAL_exit(0);
}

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