Screen object¶

The screen object generates the images and calls the driver to display them. It is used by all the other functions and libraries.

The screen object deals with the logical screen, with x-y coordinates, which takes into account the orientation. It is an abstraction of the physical screen with horizontal and vertical coordinates defined by the data-sheet.

Configure¶

Driver¶

Select the driver corresponding to the film and the size of the screen.

#include "Pervasive_Wide_Small.h"

The pre-processor statement includes the driver library.

Configure the driver according to the screen model and the board configuration.

Pervasive_Wide_Small myDriver(eScreen_EPD_271_KS_09,
    boardRaspberryPiPico_RP2040);

The constructor Pervasive_Wide_Small creates the driver object.

Screen¶

Select the library corresponding to the edition of the PDLS library.

#include "PDLS_Advanced.h"

The pre-processor statement includes the screen library.

Screen_EPD myScreen(&myDriver,
    frameBuffer);

The constructor Screen_EPD creates the screen object.

The required parameter is

The first line links to the driver declared just before.

The optional parameter is

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

Legacy release 8

#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, EXT3.1 or EXT4 extension board.

The optional parameter is

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

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 myScreen(&myDriver, frameBuffer);

Warning

This option requires the Evaluation, Commercila of Viewer edition.

Legacy release 8

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.40	456	392	22,344	`frameSize_EPD_340`
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.65	448	600	33,600	`frameSize_EPD_565`
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

Pervasive_Wide_Small myDriver(eScreen_EPD_271_KS_09,
    boardRaspberryPiPico_RP2040);

uint8_t frameBuffer[frameSize_EPD_271] PLACE_IN_FRAM;
Screen_EPD myScreen(&myDriver, frameBuffer);

Legacy version 8

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

Pervasive_Wide_Small myDriver(eScreen_EPD_271_KS_09,
    boardRaspberryPiPico_RP2040);

uint8_t * frameBuffer = (uint8_t *) ps_malloc(frameSize_EPD_271);
Screen_EPD myScreen(&myDriver, frameBuffer);

Legacy version 8

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: normal update for all the monochrome and colour screens, fast update for selected monochrome screens and screens with touch.

Normal 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 normal 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 normal 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.

// SDK and configuration
#include "PDLS_Common.h"

// Set parameters
#define DISPLAY_WHOAMI 1

// Define variables and constants
// Driver
#include "Pervasive_Wide_Small.h"
Pervasive_Wide_Small myDriver(eScreen_EPD_271_KS_09, boardRaspberryPiPico_RP2040);

// Screen
#include "PDLS_Advanced.h"
Screen_EPD myScreen(&myDriver);

uint8_t fontSans;

#if (DISPLAY_WHOAMI == 1)

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

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

    // Normal 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();
    wait(8);

#endif // DISPLAY_WHOAMI

    // Against possible ghosting
    myScreen.regenerate();

    hV_HAL_exit(0);
}

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