Screen¶

The screen object is used by all the 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 controller 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 constant 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 dedicated section Screen constants explains how the screen constants used by the constructor are built from the screen product numbers.

Board configuration¶

The board configuration defines all the GPIOs connected to the EXT3, EXT3.1 and EXT4 extension boards.

Example

boardRaspberryPiPico_RP204 sets the Raspberry Pi Pico as main controller board.

Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_271_CS_09, boardRaspberryPiPico_RP2040);

The dedicated section Boards definition details the content of the configuration and lists the pre-configured main controller boards.

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).

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)	Width (pixels)	Height (pixels)	Frame-buffer (bytes)	Frame-buffer (constant)
1.50	200	200	10,000	`frameSize_EPD_150`
1.52	200	200	10,000	`frameSize_EPD_152`
1.54	152	152	5,776	`frameSize_EPD_154`
2.06	128	248	7,936	`frameSize_EPD_206`
2.13	104	212	5,512	`frameSize_EPD_213`
2.66	152	296	11,248	`frameSize_EPD_266`
2.71	176	264	11,616	`frameSize_EPD_271`
2.87	128	296	9,472	`frameSize_EPD_287`
2.90	168	384	16,128	`frameSize_EPD_290`
3.70	240	416	24,960	`frameSize_EPD_370`
4.17	400	300	30,000	`frameSize_EPD_417`
4.37	176	480	21,120	`frameSize_EPD_437`
5.81	256	720	46,080	`frameSize_EPD_581`
7.41	480	800	96,000	`frameSize_EPD_741`
9.69	672	960	161,280	`frameSize_EPD_969`
11.98	768	960	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 with 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 technical 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

    // Against possible ghosting
    myScreen.regenerate();

    hV_HAL_exit(0);
}

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