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";
Legacy version 5
#include "PDLS_EXT3_Advanced_Fast_Small.h";
The pre-processor statement includes the screen libraries.
1 2 3 |
|
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 board connected to the EXT3-1 extension board;
The optional parameter is
- The third line links to the frame-buffer if declared statistically 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 family CS
and type 09
. The last digit 4
is ignored.
- | Size | Family | 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, boardRaspberryPiPico_RP2040);
The family defines the features of the screen.
Code | Family | Colour | Update | Commercial name |
---|---|---|---|---|
CS |
Monochrome | Black and white | Global update | |
JS |
Red | Black, white, red | Global update | Spectra |
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 specific cases for the constructor are listed below.
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 type 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 type 0E
.
- | Size | Family | 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, boardRaspberryPiPico_RP2040);
A better solution is to include the type 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 type 0B
.
- | Size | Family | Type | Colour |
---|---|---|---|---|
CE2 |
969 |
JS |
0B |
|
eScreen_EPD_EXT3_ |
969 |
_BWR |
The screen model for the constructor is eScreen_EPD_EXT3_969_BWR
. The type is omitted.
eScreen_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 type 0F
.
- | Size | Family | Type | Colour |
---|---|---|---|---|
CE2 |
154 |
QS |
0F |
|
eScreen_EPD_EXT3_ |
154 |
_BWRY |
The screen model for the constructor is eScreen_EPD_EXT3_154_BWRY
. The type is omitted.
eScreen_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 type, 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 type 09
.
- | Size | Family | Type | Fast |
---|---|---|---|---|
SE2 |
271 |
PS |
09 |
|
eScreen_EPD_EXT3_ |
271 |
_ |
09 |
_Fast |
The screen model for the constructor is eScreen_EPD_EXT3_271_09_Fast
.
eScreen_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 type, 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 type 09
.
- | Size | Family | Type | Wide |
---|---|---|---|---|
SE2 |
271 |
KS |
09 |
|
eScreen_EPD_EXT3_ |
271 |
_ |
09 |
_Wide |
The screen model for the constructor is eScreen_EPD_EXT3_271_09_Wide
.
eScreen_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 type, 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 type 0C
.
- | Size | Family | Type | Touch |
---|---|---|---|---|
QT2 |
370 |
PS |
0C |
|
eScreen_EPD_EXT3_ |
370 |
_ |
0C |
_Touch |
The screen model for the constructor is eScreen_EPD_EXT3_370_0C_Touch
.
eScreen_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 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 |
---|---|
boardFeatherNRF52840 |
Adafruit Feather |
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 |
boardFeatherNRF52832 |
Adafruit Feather |
boardFeatherNRF52840 |
Adafruit Feather |
boardFeatherRP2040 |
Adafruit Feather |
boardParticlePhoton |
Particle Photon and RedBear Duo |
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 |
boardRaspberryPiPico_RP2040 |
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
.panelPower = NOT_CONNECTED, ///< Optional power circuit
.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 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 statistically 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, boardRaspberryPiPico_RP2040, frameBuffer);
The constant for the size of the frame-buffer starts with frameSize_EPD_EXT3_
and contains the size taken from the product number.
Diagonal (inches) | Frame-buffer (bytes) | Frame-buffer (constant) |
---|---|---|
1.50 | 10,000 | frameSize_EPD_EXT3_150 |
1.52 | 10,000 | frameSize_EPD_EXT3_152 |
1.54 | 5,776 | frameSize_EPD_EXT3_154 |
2.06 | 7,936 | frameSize_EPD_EXT3_206 |
2.13 | 5,512 | frameSize_EPD_EXT3_213 |
2.66 | 11,248 | frameSize_EPD_EXT3_266 |
2.71 | 11,616 | frameSize_EPD_EXT3_271 |
2.87 | 9,472 | frameSize_EPD_EXT3_287 |
2.90 | 16,128 | frameSize_EPD_EXT3_290 |
3.70 | 24,960 | frameSize_EPD_EXT3_370 |
4.17 | 30,000 | frameSize_EPD_EXT3_417 |
4.20 | 30,000 | frameSize_EPD_EXT3_420 |
4.37 | 21,120 | frameSize_EPD_EXT3_437 |
5.81 | 46,080 | frameSize_EPD_EXT3_581 |
7.41 | 96,000 | frameSize_EPD_EXT3_741 |
9.69 | 161,280 | frameSize_EPD_EXT3_969 |
11.98 | 184,320 | frameSize_EPD_EXT3_B98 |
Specifying the frame-buffer statistically at build-time is required for the cases listed below.
For MCUs where the memory location is managed statistically 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 for selected monochrome screens and screens with touch.
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()
.
Warning
The partial update mode is deprecated. Use fast update instead.
Legacy version 5
myScreen.gText(4, 4, myScreen.whoAmI());
myScreen.flushPartial();
whoAmI()
returns the name of the screen.
gText()
prints text on the screen.
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.
Legacy version 5 requires beginPartial()
to start partial mode and reset the coordinates of the window.
myScreen.beginPartial();
myScreen.gText(4, 4, myScreen.whoAmI());
myScreen.flushPartial();
beginPartial()
starts the partial mode and resets the coordinates of the window.
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.
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 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_PDLS.h"
// Define variables and constants
Screen_EPD_EXT3_Fast myScreen(eScreen_EPD_EXT3_271_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);
}