Glossary¶

The glossary provides a short definition of the most common terms, and provides links to the related entries.

Board¶

There are two kinds of boards:

The main controller board or host is powered by a microcontroller or a microprocessor;
The extension board drives the e-paper display. PDLS supports the EXT3, EXT3.1 and EXT4 extension boards.

Check mode¶

The check mode sets how a GUI element reacts to touch and raises the corresponding event.

Three modes are available: normal, instant and direct.

The state of the GUI element needs to be enabled.

Colours¶

The monochrome e-paper screens provide two basic colours: black and white.

Combining those two basic colours gives one additional shade, totalling three colours.

white: basic colour;
black: basic colour;
grey: combined colour, one dot black, another dot white.

The black-white-red colour e-paper screens provide three basic colours. Combining those three basic colours gives two additional shades, totalling six colours.

white: basic colour;
black: basic colour;
red: basic colour.

and

grey: combined colour, one pixel black, another pixel white;
light red: combined colour, one pixel red, another pixel white;
dark red: combined colour, one pixel red, another pixel black.

The black-white-red-yellow colour e-paper screens provide four basic colours. Combining those four basic colours gives six additional shades, totalling ten colours.

white: basic colour;
black: basic colour;
red: basic colour;
yellow: basic colour;

and

grey: combined colour, one pixel black, another pixel white;
light red: combined colour, one pixel red, another pixel white;
dark red: combined colour, one pixel red, another pixel black;
light yellow: combined colour, one pixel yellow, another pixel white;
dark yellow: combined colour, one pixel yellow, another pixel black;
orange: combined colour, one pixel red, another pixel yellow.

Controller¶

The physical screen includes the controller on the circuit-on-glass.

The controllers store the parameters needed to drive the screen during refresh in the OTP or One-Time-Programmable memory.

The controller receives the commands and data from the host through the GPIOs and SPI bus to change the content of the screen.

See also

OTP memory, Physical screen, Update

Coordinates¶

Two systems are available:

Rectangular coordinates define the top-left and bottom-right points;
Vector coordinates define the top-left point and a distance.

Delegated update¶

Normally, the main code commands the refresh of the screen.

With the delegated update option, the GUI elements interact with the touch events, update themselves and trigger the refresh of the screen.

This option requires the fast update mode and allows a more fluid interface, especially for the GUI library.

Warning

The partial update mode is now deprecated. The fast update mode is used instead.

Direct check¶

Default mode is normal check mode.

In direct check mode, the GUI element raises the event when the finger is released from the element. A simplified cinematic sequence is performed.

The mode is recommended when the button triggers the display of a new page.

It requires the state of the GUI element to be enabled.

Disabled state¶

A GUI element with a disabled state does not react to touch.

See also

Enabled state, State

Element¶

An element is a basic interface component, either a self-contained high-level function or a object.

GUI library: Area, BarGraph, Button, CheckBox, Cursor, FlipFlop, Label, PlusMinus, RadioButtons, Text, TextBox, Table, Keyboard
Graphics library: Clock, Gauge, Histogram, Label, Multiple, Channels

The GUI elements react to touch, with parameters for state: enabled or disabled; and for check mode: normal, instant or direct.

With the delegated update option, the GUI elements interact with the touch events, update themselves and trigger the refresh of the screen.

Enabled state¶

A GUI element with an enabled state reacts to touch and raises the corresponding event.

See also

State, Disabled state

Extension board¶

The extension board drives the e-paper display and provides other components like external SPI memory and I²C sensors.

It is connected

to the e-paper display through a 24- or 34-way flat cable; and
to the main controller board through a 2x10 or 1x10-way cable.

PDLS supports the EXT3, EXT3.1, EXT3-Touch and EXT4 extension boards from Pervasive Displays.

The EXT3-Touch Expansion Board drives the I²C touch controller. It is placed below the EXT3.1.

Family¶

A family groups different screens according to the size of their diagonal.

The combination of the film and the family determines the driver to be used.

Family	Diagonal
Small	1.52” 1.54” 2.06” 2.13” 2.66” 2.71” 2.87” 2.90” 3.70” 4.17” 4.37”
Medium	3.40” 5.65” 5.81” 7.41”
Large	9.69” 11.98”

See also

Driver

Fast update¶

The fast update is faster than the global update mode. First, the previous and next contents of the full screen are uploaded to the screen, and then the screen refreshes without the blinking effect.

It supports monochrome screens only, and possible ghosting may appear.

The fast update offers a good balance between quality and speed.

File formats¶

There are multiple options to store and retrieve the content of the screen:

Image structure;
Portable bitmap or pixmap (with PBM or P4 extension);
Windows bitmap (with BMP extension);
Portable Network Graphic (with PNG extension) for the Viewer edition only.

Film¶

The film is a key element of the screen.

The film defines the features of the screen, monochrome or colour, black-white-red or black-white-red-yellow, normal update or embedded fast update, normal or wide temperature.

See also

Driver, Physical screen

Frame-buffer¶

Compared to other screens, the e-paper screens relies on a frame-buffer.

First, the commands for drawing text and graphics update the frame-buffer.
Then, the update command sends the content of the frame-buffer to the screen and refreshes the panel.

The frame-buffer resides on either the internal MCU RAM or on an external SPI SRAM.

See also

Logical screen, Update

Global update¶

The global update is the default for refreshing the screen. First, the next content of the full screen is uploaded to the screen, and then the screen refreshes with a blinking effect.

It supports both monochrome and colours screens. However, it is slower than the other modes.

The normal update is recommended for optimal quality without any ghosting.

Graphics¶

The Graphics library offers multiple interface components to display data.

They are either self-contained high-level functions or objects. They are grouped in pages.

The elements include:

clock, gauge,
histogram, multiple histogram, channels,
label.

See also

Element, Page

GUI¶

The GUI library offers multiple interface components, called elements, to design a human machine interface.

They are either self-contained high-level functions or objects. They are grouped in pages.

The elements include:

label, text, text-box,
area, button, check-box, flip-flop button, plus-minus button, radio-buttons,
bar-graph, cursor,
table, keyboard.

The GUI elements react to touch, with parameters for state: enabled or disabled; and for check mode: normal, instant or direct.

With the delegated update option, the GUI elements interact with the touch events, update themselves and trigger the refresh of the screen.

Host¶

The host is a synonym for the main controller board.

Image structure¶

The image structure is a specific file format to store the content of the screen.

It is used to write to a micro-SD card or to print to a serial console, for later reuse as a header file.

It comes in two formats: image for monochrome displays; and 16-bit image for monochrome and colour displays.

Instant check¶

Default mode is normal check mode.

In instant check mode, the GUI element raises the event when the finger touches the element. No cinematic sequence is performed.

It requires the state of the GUI element to be enabled.

Logical screen¶

The library manages the logical screen.

The logical screen contains the frame-buffer and uses x-y coordinates defined by the orientation.

See also

Frame-buffer, Physical screen, Screen

Main controller board¶

The main controller board or host is a physical device powered by a microcontroller or a microprocessor. It runs the application based on PDLS.

It is connected to the extension board through GPIOs and the SPI and I²C buses.

A dedicated header file provides the list of the pre-configured main controller boards.

The recommended boards are the Adafruit Feather nRF52840, the Arduino Nano Matter, the Espressif ESP32-DevKitC and the Raspberry Pi Pico RP2040.

A technical note explains how to define a non-listed main controller board.

See also

Board, Host

Normal check¶

Default mode is normal check mode.

In normal check mode, the GUI element requires the finger to be hold for a moment and raises the event when the finger is released from the element. Additionally, the element goes through a cinematic sequence.

It requires the state of the GUI element to be enabled.

OTP memory¶

The OTP memory contains the parameters needed to drive the screen during refresh. OTP stands for One-Time-Programmable.

Those parameters are calibrated to ensure the optimal image quality. The library reads them once and use them to refresh the screen.

See also

Controller

Page¶

A page is a set of elements that defines a screen of a human machine interface.

An application can have one single page or multiple pages.

See also

Element, Graphics, GUI

Partial update¶

Warning

The partial update mode is now deprecated and replaced by the fast update mode.

The partial update is the fastest among other update options. Instead of the full screen, only the previous and next contents of the modified window are uploaded to the screen, and then the screen refreshes without the blinking effect.

It supports monochrome screens only. Ghosting may appear, especially outside the modified window.

The partial update is highly recommended for human-machine interfaces.

Warning

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

Physical screen¶

The physical screen refers to the panel as described in the data-sheet, with horizontal-vertical coordinates.

The physical screen is defined by the film, the size of the diagonal, and the controller. It is connected to the extension board.

The coordinates for the physical screen are consistent with the horizontal and vertical axes from the data-sheet.

The library sends commands to the controller to manage the physical screen, and exposes the logical screen to the application.

Portable pixmap¶

The portable pixmap is a compact file format with a PBM or P4 extension to store the content of the screen.

It is used to write to and read from a micro-SD card. It only supports monochrome displays.

It is also available to print as a table to a serial console, for later reuse as a header file.

Rectangular coordinates¶

The rectangle coordinates include two points P1 and P2.

P1 is a pixel on the top left, with (x1, y1) coordinates.
P2 is a pixel on the bottom right, with (x2, y2) coordinates.

Example

rectangle (0, 0) - (319, 239)

See also

Coordinates, Vector coordinates

Screen¶

A screen can be both physical and logical.

The physical screen is the panel described in the data-sheet;
The logical screen is managed by the library.

See also

Logical screen, Physical screen

Special check¶

Default mode is normal check mode.

In special check mode, the GUI element raises the event when the finger is released from the element. A simplified cinematic sequence is performed.

The mode is a simplified and faster variant of the normal check mode.

It requires the state of the GUI element to be enabled.

State¶

The state of a GUI element defines whether the element reacts to touch.

Two states are available:

if state is disabled, the element does not react to touch;
if state is enabled, the element reacts to touch and raises the corresponding event.

Update¶

The update of the screen is the process for changing its content.

Commands and data are sent to the controller to

Initialise the panel;
Upload the content of the frame-buffer to the panel; and
Refresh the panel.

See also

Controller, Frame-buffer, Update modes

Update modes¶

Different update modes are available to change the content of the screen: normal update, fast update, partial update. Update type | Global update | Fast update | Partial update ---- | ---- | ---- | ---- Supported panels | Three-colours (BWR) and monochrome (B&W) panels | Monochrome (B&W) panels | Monochrome (B&W) panels Initialisation | Panel initialisation | Panel initialisation | Panel initialisation Content upload | Full screen with new content | Full screen with previous and new contents | Partial window with previous and new contents Panel refresh | Whole screen with flashing effect | Whole screen with fast mode | Partial window with fast mode Image quality | Optimal quality | Possible ghosting | Ghosting Upload speed | Slow | Slow | Fast Refresh panel speed | Slow | Fast | Fast Overall speed | Slow | Faster | Fastest

Warning

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

Vector coordinates¶

The vector coordinates include one point P0 and one distance.

P0 is a pixel and the origin, with (x0, y0) coordinates.
The distance (dx, dy) is specified on the x-y axes.

Example

vector (0, 0) - (320, 240)

Going from pixel 0 to pixel 319 represents 320 pixels in total.

See also

Coordinates, Rectangular coordinates

Viewer¶

The Viewer edition runs as a Linux and Windows native application to simulate an e-paper screen and manage touch. It shares the same fonts and application libraries with the Commercial edition.

It allows to develop the application software independently of the hardware. It is meant to be used with the Commercial edition.

Window¶

The window is the area to be updated on partial mode.

The library calculates the window automatically.

See also

Partial update

Windows bitmap¶

The Windows bitmap is a file format with a BMP extension to store the content of the screen.

It is used to write to and read from a micro-SD card. It supports monochrome and colour displays.