Skip to content

Latest commit

 

History

History
2645 lines (1746 loc) · 55 KB

API.md

File metadata and controls

2645 lines (1746 loc) · 55 KB
Raw

Heltec E-Ink Modules - API

Include Library

#include <heltec-eink-modules.h>

Display Constructors

DEPG0150BNS810()

Create a display controller object, for model DEPG0150BNS810.

Syntax

DEPG0150BNS810(DC_PIN, CS_PIN, BUSY_PIN)
DEPG0150BNS810(DC_PIN, CS_PIN, BUSY_PIN, page_height)
DEPG0150BNS810(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN)  // ESP32 or SAMD21G18A only
DEPG0150BNS810(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN, page_height) // ESP32 or SAMD21G18A only

Parameters

  • DC_PIN: pin which connects to "Display / Command" (D/C) pin on the display.
  • CS_PIN: pin which connects to "Chip Select" (CS) on the display.
  • BUSY_PIN: pin which connects to "BUSY" on the display.
  • SDI_PIN: pin which connects to "SDI" on the display. ESP32 or SAMD21G18A only
  • CLK_PIN: pin which connects to "CLK" on the display. ESP32 or SAMD21G18A only
  • page_height (optional): number of rows per page. For Arduino Uno default value is 20, meaning the display is calculated 20 rows at a time. Higher values consume more RAM. For more powerful boards, paging is disabled by default.

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

DEPG0154BNS800()

Create a display controller object, for model DEPG0154BNS800.

Syntax

DEPG0154BNS800(DC_PIN, CS_PIN, BUSY_PIN)
DEPG0154BNS800(DC_PIN, CS_PIN, BUSY_PIN, page_height)
DEPG0154BNS800(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN)  // ESP32 or SAMD21G18A only
DEPG0154BNS800(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN, page_height) // ESP32 or SAMD21G18A only

Parameters

  • DC_PIN: pin which connects to "Display / Command" (D/C) pin on the display.
  • CS_PIN: pin which connects to "Chip Select" (CS) on the display.
  • BUSY_PIN: pin which connects to "BUSY" on the display.
  • SDI_PIN: pin which connects to "SDI" on the display. ESP32 or SAMD21G18A only
  • CLK_PIN: pin which connects to "CLK" on the display. ESP32 or SAMD21G18A only
  • page_height (optional): number of rows per page. For Arduino Uno default value is 20, meaning the display is calculated 20 rows at a time. Higher values consume more RAM. For more powerful boards, paging is disabled by default.

Example

#include <heltec-eink-modules.h>

DEPG0154BNS800 display(2, 4, 5);

DEPG0213BWS800

Create a display controller object, for for model DEPG0213BWS800, which is used on "Wireless Paper" all-in-one boards.

Display instances of this class should be declared without parentheses, or they will be mistaken for a function prototype. See example.

Syntax

DEPG0213BWS800

Parameters

None.

Example

#include <heltec-eink-modules.h>

DEPG0213BWS800 display;

DEPG0213RWS800()

Create a display controller object, for model DEPG0213RWS800.

Syntax

DEPG0213RWS800(DC_PIN, CS_PIN, BUSY_PIN)
DEPG0213RWS800(DC_PIN, CS_PIN, BUSY_PIN, page_height)
DEPG0213RWS800(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN)  // ESP32 or SAMD21G18A only
DEPG0213RWS800(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN, page_height) // ESP32 or SAMD21G18A only

Parameters

  • DC_PIN: pin which connects to "Display / Command" (D/C) pin on the display.
  • CS_PIN: pin which connects to "Chip Select" (CS) on the display.
  • BUSY_PIN: pin which connects to "BUSY" on the display.
  • SDI_PIN: pin which connects to "SDI" on the display. ESP32 or SAMD21G18A only
  • CLK_PIN: pin which connects to "CLK" on the display. ESP32 or SAMD21G18A only
  • page_height (optional): number of rows per page. For Arduino Uno default value is 20, meaning the display is calculated 20 rows at a time. Higher values consume more RAM. For more powerful boards, paging is disabled by default.

Example

#include <heltec-eink-modules.h>

DEPG0213RWS800 display(2, 4, 5);

DEPG0290BNS75A()

Create a display controller object, for model DEPG0290BNS75A.

Syntax

DEPG0290BNS75A(DC_PIN, CS_PIN, BUSY_PIN)
DEPG0290BNS75A(DC_PIN, CS_PIN, BUSY_PIN, page_height)
DEPG0290BNS75A(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN)  // ESP32 or SAMD21G18A only
DEPG0290BNS75A(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN, page_height) // ESP32 or SAMD21G18A only

Parameters

  • DC_PIN: pin which connects to "Display / Command" (D/C) pin on the display.
  • CS_PIN: pin which connects to "Chip Select" (CS) on the display.
  • BUSY_PIN: pin which connects to "BUSY" on the display.
  • SDI_PIN: pin which connects to "SDI" on the display. ESP32 or SAMD21G18A only
  • CLK_PIN: pin which connects to "CLK" on the display. ESP32 or SAMD21G18A only
  • page_height (optional): number of rows per page. For Arduino Uno default value is 20, meaning the display is calculated 20 rows at a time. Higher values consume more RAM. For more powerful boards, paging is disabled by default.

Example

#include <heltec-eink-modules.h>

DEPG0290BNS75A display(2, 4, 5);

DEPG0290BNS800()

Create a display controller object, for model DEPG0290BNS800.

Syntax

DEPG0290BNS800(DC_PIN, CS_PIN, BUSY_PIN)
DEPG0290BNS800(DC_PIN, CS_PIN, BUSY_PIN, page_height)
DEPG0290BNS800(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN)  // ESP32 or SAMD21G18A only
DEPG0290BNS800(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN, page_height) // ESP32 or SAMD21G18A only

Parameters

  • DC_PIN: pin which connects to "Display / Command" (D/C) pin on the display.
  • CS_PIN: pin which connects to "Chip Select" (CS) on the display.
  • BUSY_PIN: pin which connects to "BUSY" on the display.
  • SDI_PIN: pin which connects to "SDI" on the display. ESP32 or SAMD21G18A only
  • CLK_PIN: pin which connects to "CLK" on the display. ESP32 or SAMD21G18A only
  • page_height (optional): number of rows per page. For Arduino Uno default value is 20, meaning the display is calculated 20 rows at a time. Higher values consume more RAM. For more powerful boards, paging is disabled by default.

Example

#include <heltec-eink-modules.h>

DEPG0290BNS800 display(2, 4, 5);

GDE029A1()

Create a display controller object, for model GDE029A1.

Syntax

GDE029A1(DC_PIN, CS_PIN, BUSY_PIN)
GDE029A1(DC_PIN, CS_PIN, BUSY_PIN, page_height)
GDE029A1(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN)  // ESP32 or SAMD21G18A only
GDE029A1(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN, page_height) // ESP32 or SAMD21G18A only

Parameters

  • DC_PIN: pin which connects to "Display / Command" (D/C) pin on the display.
  • CS_PIN: pin which connects to "Chip Select" (CS) on the display.
  • BUSY_PIN: pin which connects to "BUSY" on the display.
  • SDI_PIN: pin which connects to "SDI" on the display. ESP32 or SAMD21G18A only
  • CLK_PIN: pin which connects to "CLK" on the display. ESP32 or SAMD21G18A only
  • page_height (optional): number of rows per page. For Arduino Uno default value is 20, meaning the display is calculated 20 rows at a time. Higher values consume more RAM. For more powerful boards, paging is disabled by default.

Example

#include <heltec-eink-modules.h>

GDE029A1 display(2, 4, 5);

GDEP015OC1()

Create a display controller object, for model GDEP015OC1.

Syntax

GDEP015OC1(DC_PIN, CS_PIN, BUSY_PIN)
GDEP015OC1(DC_PIN, CS_PIN, BUSY_PIN, page_height)
GDEP015OC1(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN)  // ESP32 or SAMD21G18A only
GDEP015OC1(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN, page_height) // ESP32 or SAMD21G18A only

Parameters

  • DC_PIN: pin which connects to "Display / Command" (D/C) pin on the display.
  • CS_PIN: pin which connects to "Chip Select" (CS) on the display.
  • BUSY_PIN: pin which connects to "BUSY" on the display.
  • SDI_PIN: pin which connects to "SDI" on the display. ESP32 or SAMD21G18A only
  • CLK_PIN: pin which connects to "CLK" on the display. ESP32 or SAMD21G18A only
  • page_height (optional): number of rows per page. For Arduino Uno default value is 20, meaning the display is calculated 20 rows at a time. Higher values consume more RAM. For more powerful boards, paging is disabled by default.

Example

#include <heltec-eink-modules.h>

GDEP015OC1 display(2, 4, 5);

LCMEN2R13EFC1

Create a display controller object, for for model LCMEN2R13EFC1, which is used on "Wireless Paper" all-in-one boards.

Display instances of this class should be declared without parentheses, or they will be mistaken for a function prototype. See example.

Syntax

LCMEN2R13EFC1

Parameters

None.

Example

#include <heltec-eink-modules.h>

LCMEN2R13EFC1 display;

QYEG0213RWS800()

Create a display controller object, for model QYEG0213RWS800.

Syntax

QYEG0213RWS800(DC_PIN, CS_PIN, BUSY_PIN)
QYEG0213RWS800(DC_PIN, CS_PIN, BUSY_PIN, page_height)
QYEG0213RWS800(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN)  // ESP32 or SAMD21G18A only
QYEG0213RWS800(DC_PIN, CS_PIN, BUSY_PIN, SDI_PIN, CLK_PIN, page_height) // ESP32 or SAMD21G18A only

Parameters

  • DC_PIN: pin which connects to "Display / Command" (D/C) pin on the display.
  • CS_PIN: pin which connects to "Chip Select" (CS) on the display.
  • BUSY_PIN: pin which connects to "BUSY" on the display.
  • SDI_PIN: pin which connects to "SDI" on the display. ESP32 or SAMD21G18A only
  • CLK_PIN: pin which connects to "CLK" on the display. ESP32 or SAMD21G18A only
  • page_height (optional): number of rows per page. For Arduino Uno default value is 20, meaning the display is calculated 20 rows at a time. Higher values consume more RAM. For more powerful boards, paging is disabled by default.

Example

#include <heltec-eink-modules.h>

QYEG0213RWS800 display(2, 4, 5);

Methods

begin()

You shouldn't need to call this method.
Perform initial hardware setup at start of sketch. In theory, this is all handled automatically, but maybe your use case has a need for this?

Syntax

begin()

Parameters

None.

Example

#include <heltec-eink-modules.h>

// Class is "display model"
QYEG0213RWS800 display(2, 4, 5);

void setup() {

    display.begin();    // Get ready to draw - call once only
    
    display.setCursor(5, 10);
    display.print("Hello, World!");
    
    display.update();   // Display whatever we've drawn

    delay(4000);        // Let user read
    dispaly.clear();    // Wipe the screen immediately
}

bottom()

Get the bottom edge of the display. Value will change to match the current rotation.

Syntax

display.bottom()

Parameters

None.

Returns

Position bottom edge of the full display, in pixels.

centerX()

Get the horizontal midpoint of the display. If the center is between two pixels, the leftmost is returned. Value will change to match the current rotation.

Syntax

display.centerX()

Parameters

None.

Returns

Horizontal center of the full display, in pixels.

centerY()

Get the vertical midpoint of the display. If the center is between two pixels, the topmost is returned. Value will change to match the current rotation.

Syntax

display.centerY()

Parameters

None.

Returns

Vertical center of the full display, in pixels.

clear()

Clear the display, along with its internal memory. This is a standalone method, called outside of the DRAW loop. The display will be cleared to solid white, unless changed using setBackgroundColor().

Syntax

clear()

Parameters

None.

Example

#include <heltec-eink-modules.h>

QYEG0213RWS800 display(2, 4, 5);

void setup() {
    display.clear();    // Display now changes to show solid white
    
    display.setBackgroundColor(BLACK);
    display.clear();    // Display clears instead to solid black
    
    ...

    display.clear();    // Clears again to solid black
}

See also

clearMemory()

ATmega328P (Uno / Nano): not supported
ATmega2560: disabled for some displays

Reset the drawing memory to default color, if not using a DRAW() loop. Changes are not displayed until update() is called.

Syntax

clearMemory()

Parameters

None.

Example

#include <heltec-eink-modules.h>

QYEG0213RWS800 display(2, 4, 5);

void setup() {
    display.clear();    // Whole display immediately changes now to white

    display.setCursor(10, 10);
    display.print("First line.");

    display.update();   // Display now shows "first line"

    display.clearMemory();    // Last drawing cleared from memory; display unchanged
    
    display.setCursor(10, 40);
    display.print("Second line.");
    
    display.update();   // Display now shows "second line", and not "first line"
}

void loop() {}

See also

DRAW()

Performs drawing commands, then updates the display. If necessary, paging is used.

Syntax

DRAW (display)

Parameters

  • display: the display on which to execute the drawing commands.

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {

    DRAW (display) {
        //Graphics commands go here, for example:
        display.fillCircle(50, 100, 20, BLACK);
    }

}

See also

draw24bitBMP()

ATmega328P (Uno / Nano): not supported
ATmega2560: disabled for some displays

Draw a 24-bit .bmp image, from SD card, at the specified (x,y) position. Alpha-mask color can be set, either by Color enum, or RGB values.

Syntax

display.draw24bitBMP(left, top, filename)
display.draw24bitBMP(left, top, filename, mask)
display.draw24bitBMP(left, top, filename, mask_r, mask_g, mask_b)

Parameters

  • left: Top left corner x coordinate
  • top: Top left corner y coordinate
  • filename: filename of the .bmp image on SD card
  • mask (optional): Color to draw transparent
  • mask_r (optional): Color to draw transparent - Red channel
  • mask_g (optional): Color to draw transparent - Green channel
  • mask_b (optional): Color to draw transparent - Blue channel

See also

drawBitmap()

Draw a RAM-resident 1-bit image at the specified (x,y) position, using the specified foreground color (unset bits are transparent).

This is an AdafruitGFX method

Syntax

display.drawBitmap(x, y, bitmap, w, h, color, bg)

Parameters

  • x: Top left corner x coordinate
  • y: Top left corner y coordinate
  • bitmap: byte array with monochrome bitmap
  • w: Width of bitmap in pixels
  • h: Height of bitmap in pixels
  • color: Color to draw pixels with
  • bg: Color to draw background with

See also

drawCircle()

Draw a circle outline

This is an AdafruitGFX method

Syntax

display.drawCircle( x, y, r, color)

Parameters

  • x0: Center-point x coordinate
  • y0: Center-point y coordinate
  • r: Radius of circle
  • color: Color to draw with

See also

drawCircleHelper()

Quarter-circle drawer, outline only

This is an AdafruitGFX method

Syntax

display.drawCircleHelper(x, y, r, corner_mask, color)

Parameters

  • x: Center-point x coordinate
  • y: Center-point y coordinate
  • r: Radius of circle
  • corner_mask: Which corner(s) to draw. Select by setting the first four bits: Least Significant Bit for top left, traveling clockwise as bit # increases.
  • color: Color to draw with

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {
    byte corners = 0;
    
    bool TOP_LEFT = false;
    bool TOP_RIGHT = true;
    bool BOTTOM_RIGHT = false;
    bool BOTTOM_LEFT = true;

    corners = (TOP_LEFT << 0) | (TOP_RIGHT << 1) | (BOTTOM_RIGHT << 2) | (BOTTOM_LEFT << 3);

    // Or alternatively..
    // corners = B1010;

    DRAW (display) {
        display.drawCircleHelper(50, 50, 50, corners, BLACK);
    }

}

void loop() {}

See also

drawLine()

Draw a line

This is an AdafruitGFX method

Syntax

display.drawLine(x0, y0, x1, y1, color)

Parameters

  • x0: Start point x coordinate
  • y0: Start point y coordinate
  • x1: End point x coordinate
  • y1: End point y coordinate
  • color: Color to draw with

See also

drawMonoBMP()

Draw a 1-bit .bmp image, from SD card, at the specified (x,y) position, using the specified foreground color. Unset bits are transparent by default, unless argument bg is passed.

Syntax

display.drawMonoBMP(left, top, filename, color)
display.drawMonoBMP(left, top, filename, color, bg)

Parameters

  • left: Top left corner x coordinate
  • top: Top left corner y coordinate
  • filename: filename of the .bmp image on SD card
  • color: Color to draw pixels with
  • bg: Color to draw background with

See also

drawPixel()

Draw a single pixel

Syntax

display.drawPixel(x, y, color)

Parameters

  • x: X coordinate
  • y: Y coordinate
  • color: Color to draw with

See also

drawRect()

Draw a rectangle with no fill color

This is an AdafruitGFX method

Syntax

display.drawRect(x, y, w, h, color)

Parameters

  • x: Top left corner x coordinate
  • y: Top left corner y coordinate
  • w: Width in pixels
  • h: Height in pixels
  • r: Radius of corner rounding
  • color: Color to draw with

See also

drawRoundRect()

Draw a rounded rectangle with no fill color

This is an AdafruitGFX method

Syntax

display.drawRoundRect(x, y, w, h, r, color)

Parameters

  • x: Top left corner x coordinate
  • y: Top left corner y coordinate
  • w: Width in pixels
  • h: Height in pixels
  • r: Radius of corner rounding
  • color: Color to draw with

drawTriangle()

Draw a triangle with no fill color

This is an AdafruitGFX method

Syntax

display.drawTriangle(x0, y0, x1, y1, x2, y2, color)

Parameters

  • x0: Vertex #0 x coordinate
  • y0: Vertex #0 y coordinate
  • x1: Vertex #1 x coordinate
  • y1: Vertex #1 y coordinate
  • x2: Vertex #2 x coordinate
  • y2: Vertex #2 y coordinate
  • color: Color to draw with

See also

drawXBitmap()

Draw PROGMEM-resident XBitMap Files (*.xbm), exported from GIMP. See tutorial on preparing XBitmap images.

This is an AdafruitGFX method

Syntax

display.drawXBitmap( x, y, bitmap[], w, h, color)

Parameters

  • x: Top left corner x coordinate
  • y: Top left corner y coordinate
  • bitmap: byte array with monochrome bitmap (PROGMEM only)
  • w: Width of bitmap in pixels
  • h: Height of bitmap in pixels
  • color: Color to draw pixels with

Example

#include <heltec-eink-modules.h>
#include "chess_200x200.h"

DEPG0150BNS810 display(2, 4, 5);

void setup() {

    // Don't forget to set the rotation, so your image fits how you intended
    display.setRotation(PINS_LEFT);  

    DRAW (display) {
        display.drawXBitmap(0, 0, chess_bits, chess_width, chess_height, BLACK);
    }

}

void loop() {}

See also

customPowerOff()

Disconnect power from the display, using an external power switch, such as a transistor.

Must be configured with useCustomPowerSwitch().

Syntax

display.customPowerOff()

customPowerOn()

Connect power to the display, using an external power switch, such as a transistor.

Must be configured with useCustomPowerSwitch().

Syntax

display.customPowerOn()

fastmodeOff()

Disable fastmode, return to normal ("full refresh").

Syntax

display.fastmodeOff()

Parameters

None.

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {
    display.clear();

    // Begin fastmode
    display.fastmodeOn();

    DRAW (display) {
        display.setCursor(10, 10);
        display.print("ON");
    }
    delay(2000);

    DRAW (display) {
        display.setCursor(10, 10);
        display.print("still ON");
    }
    delay(2000);

    // Back to normal drawing
    display.fastmodeOff();

    display.setWindow(0, 40, 100, 100);

    DRAW (display) {
        display.setCursor(10, 40);
        display.print("OFF now..");
    }

}

fastmodeOn()

Enable fastmode.

Some displays have a second mode, where the image updates much faster. This is known officially as a "Partial Refresh". For the sake of user-friendliness, this library uses the term "Fast Mode".

The trade-off is that images drawn in fast mode are of a lower quality. The process may also be particularly difficult on the hardware. Use sparingly.

Not all displays support fast mode.

Syntax

display.fastmodeOn()
display.fastmodeOn(clear_if_reset)

Parameters

  • clear_if_reset (optional): Pass false to use the display memory "as-is". Useful after a processor deep sleep. If you intend to use fast-mode, make sure to at least run a normal refresh (or clear() / clearMemory()) on inital boot. Otherwise, you'll get a whole lot of static.

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {
    display.clear();

    // Begin fastmode
    display.fastmodeOn();

    DRAW (display) {
        display.setCursor(10, 10);
        display.print("ON");
    }
    delay(2000);

    DRAW (display) {
        display.setCursor(10, 10);
        display.print("still ON");
    }
    delay(2000);

    // Back to normal drawing
    display.fastmodeOff();

    display.setWindow(0, 40, 100, 100);

    DRAW (display) {
        display.setCursor(10, 40);
        display.print("OFF now..");
    }

}

void loop() {}

See also

fastmodeTurbo()

A variation of fastmodeOn(). Use with caution

Slightly faster refresh times, particularly with lower-spec microcontrollers. Slightly lower image quality.

Note: To prevent changes to your previous image, before calling setWindow(), setRotation(), or setFlip(), you must draw the same identical image, twice.

This is a quirk of the display controller IC.

Syntax

display.fastmodeTurbo()
display.fastmodeTurbo(clear_if_reset)

Parameters

  • clear_if_reset (optional): Pass false to use the display memory "as-is". Useful after a processor deep sleep. If you intend to use fast-mode, make sure to at least run a normal refresh (or clear() / clearMemory()) on inital boot. Otherwise, you'll get a whole lot of static.

Example

void setup() {
    display.clear();

    // Fastmode turbo
    display.fastmodeTurbo();

    // Print "Turbo Test"
    DRAW (display) {
        display.setCursor(10, 10);
        display.print("Turbo Test");
    }
    delay(2000);

    // Print twice: "Double writing..""
    for(int i=0; i < 2; i++) {
        DRAW (display) {
            display.setCursor(10, 10);
            display.print("Double writing..");
        }
    }
    delay(2000);

    // Move window
    display.setWindow(0, 40, 100, 100);
    display.setBackgroundColor(BLACK);
    display.setTextColor(WHITE);

    // Print "Old image OK", in window
    DRAW (display) {
        display.setCursor(5, 45);
        display.println("Old image OK");
    }

}

See also

fillCircle()

Draw a circle with filled color

This is an AdafruitGFX method

Syntax

display.fillCircle(x, y, r, color)

Parameters

  • x0: Center-point x coordinate
  • y0: Center-point y coordinate
  • r: Radius of circle
  • color: Color to fill with

fillRect()

Fill a rectangle completely with one color

This is an AdafruitGFX method

Syntax

display.fillRect(x, y, w, h, color)

Parameters

  • x: Start point x coordinate
  • y: Start point y coordinate
  • x: End point x coordinate
  • y: End point y coordinate
  • color: Color to fill with

See also

fillRoundRect()

Draw a rounded rectangle with fill color

This is an AdafruitGFX method

Syntax

display.fillRoundRect(x, y, w, h, r, color)

Parameters

  • x: Top left corner x coordinate
  • y: Top left corner y coordinate
  • w: Width in pixels
  • h: Height in pixels
  • r: Radius of corner rounding
  • color: 16-bit 5-6-5 Color to draw/fill with

See also

fillScreen()

Fill the screen completely with one color. Inefficient, consider instead setBackgroundColor()

This is an AdafruitGFX method

Syntax

display.fillScreen(color)

Parameters

  • color: Color to draw with

See also

fillTriangle()

Draw a triangle with color-fill

This is an AdafruitGFX method

Syntax

display.fillTriangle(x0, y0, x1, y1, x2, y2, color)

Parameters

  • x0: Vertex #0 x coordinate
  • y0: Vertex #0 y coordinate
  • x1: Vertex #1 x coordinate
  • y1: Vertex #1 y coordinate
  • x2: Vertex #2 x coordinate
  • y2: Vertex #2 y coordinate
  • color: Color to fill with

See also

fullscreen()

Draw to the entire screen, rather than just a particular part. Undoes the setWindow() method. Call before the DRAW loop.

Fullscreen is the default state at start of sketch.

Syntax

display.fullscreen()

Parameters

None.

See also

fullscreenBMPValid()

Check if file is a valid fullscreen .bmp image for this display.

Syntax

display.fullscreenBMPValid(filename)
display.fullscreenBMPValid(prefix, number)
display.fullscreenBMPValid(filename, purge)
display.fullscreenBMPValid(prefix, number, purge)

Parameters

  • filename: canvas file to check
  • prefix: identifies different sets of imagess
  • number: image's location in the set
  • purge (optional): when purge = true, canvas will be deleted from SD card, if detected as invalid.

Returns

true if canvas is valid for this display. false if invalid, wrong display, or doesn't exist.

See also

getBMPHeight()

Gets height of a .bmp image stored on SD card.

Syntax

display.getBMPHeight(filename)

Parameters

  • filename: the name of the image to read, on SD card

Returns

The height of the image.

See also

getBMPWidth()

Gets width of a .bmp image stored on SD card.

Syntax

display.getBMPWidth(filename)

Parameters

  • filename: the name of the image to read, on SD card

Returns

The width of the image.

See also

getCursorX()

Get current cursor position

This is an AdafruitGFX method

Syntax

display.getCursorX()

Parameters

None.

Returns

X Coordinate in pixels

getCursorY()

Get text cursor Y location

This is an AdafruitGFX method

Syntax

display.getCursorY()

Parameters

None.

Returns

Y coordinate in pixels

getRotation()

Get rotation setting for display

This is an AdafruitGFX method

Syntax

display.getRotation()

Parameters

None.

Returns

0 through 3, corresponding to 4 cardinal rotations

See also

getTextBounds()

Helper to determine size of a string with current font/size. Pass string and a cursor position, returns UL corner and W,H.

This is an AdafruitGFX method

Syntax

getTextBounds(str, x, y, x1 y1 )

Parameters

  • str: The ascii string to measure
  • x: The current cursor X
  • y: The current cursor Y
  • x1: The boundary X coordinate, set by function, pass by reference
  • y1: The boundary Y coordinate, set by function, pass by reference
  • w: The boundary width, set by function, pass by reference
  • h: The boundary height, set by function, pass by reference

Returns

None. Variables passed by reference will be set.

See also

getTextCenterX()

Gets the required cursor x position to horizontally center text.

Syntax

display.getTextCenterX(text)

Parameters

  • text: the string to use for dimensioning, as a char array or char pointer

Returns

X value for use with setCursor()

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {

    const char text[] = "Hello!";

    int x = display.getTextCenterX(text);   // Horizontal
    int y = display.getTextCenterY(text);   // Vertical

    DRAW (display) {
        display.setCursor(x, y);
        display.print(text);
    }
    
}

void loop() {}

See also

getTextCenterY()

Gets the required cursor y position to vertically center text.

Syntax

display.getTextCenterY(text)

Parameters

  • text: the string to use for dimensioning, as a char array or char pointer

Returns

Y value for use with setCursor()

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {

    const char text[] = "Hello!";

    int x = display.getTextCenterX(text);   // Horizontal
    int y = display.getTextCenterY(text);   // Vertical

    DRAW (display) {
        display.setCursor(x, y);
        display.print(text);
    }
    
}

void loop() {}

See also

getTextHeight()

Gets height of a string, given the current font settings. Wrapper for getTextBounds()

Syntax

display.getTextHeight(text)

Parameters

  • text: the string to measure, as a char array or char pointer

Returns

The height of the string.

See also

getTextWidth()

Gets width of a string, given the current font settings. Wrapper for getTextBounds()

Syntax

display.getTextWidth(text)

Parameters

  • text: the string to measure, as a char array or char pointer

Returns

The width of the string.

See also

height()

Get the height of the display. A display with height 200 will have a top edge of 0, and a bottom edge of 199. Value will change to match the current rotation.

Syntax

display.height()

Parameters

None.

Returns

Height of the full display, in pixels.

landscape()

Alias for setRotation(3). Enters a landscape orientation. 270 degrees rotation is used because it is the physical orientation of the display on Wireless Paper all-in-one boards.

See also

left()

Get the left edge of the display. This will always be zero, but is included for completeness.

Syntax

display.left()

Parameters

None.

Returns

Position of the left edge of the full display, in pixels.

loadFullscreenBMP()

Load a fullscreen .bmp, from SD card to display, in one pass. Can be loaded by filename, or using a prefix and numeric identifier, if convenient.

Accepts only a specific type of .bmp image.

  • 24bit .bmp file
  • Portrait, not landscape
  • Dimensions: full screen width x height

Syntax

display.loadFullscreenBMP(filename)
display.loadFullscreenBMP(prefix, number)

Parameters

  • filename: fullscreen .bmp file to load
  • prefix: identifies different sets of imagess
  • number: image's location in the set

See also

print()

Draw text to screen, at position of setCursor().

Syntax

print(text)

Parameters

  • text: printable to draw to screen

See also

printCenter()

Center text on-screen, with optional x and y offset.

Syntax

printCenter(str, offset_x, offset_y)
printCenter(int, offset_x, offset_y)
printCenter(float, decimal_places, offset_x, offset_y)
printCenter(double, decimal_places, offset_x, offset_y)

Parameters

  • str: text to draw to screen (C-String or Arduino String)
  • int: integer value to draw to screen
  • float: float value to draw to screen
  • double: double value to draw to screen
  • offset_x: (optional) offset left(negative) or right(positive) of center, in pixels. Default 0
  • offset_y: (optional) offset above (negative) or below(positive) of center, in pixels. Default 0
  • decimal_places: (optional) with double or float values, how many decimal places should be printed. Default 2

println()

Draw text to screen, followed by a newline, at position of setCursor().

Syntax

println(text)

Parameters

  • text: printable to draw to screen

See also

portrait()

Alias for setRotation(0). Enters a portrait orientation.

See also

right()

Get the right edge of the display. Value will change to match the current rotation.

Syntax

display.right()

Parameters

None.

Returns

Position of the right edge of the full display, in pixels.

SAVE_TO_SD()

Performs drawing commands, outputting to SD card, instead of display. If necessary, paging is used.

Output filename can be specified, or instead a prefix and numeric identifier can be given, which will be used to generate a unique filename. The prefix has a maximum length of 6 characters.

On Arduino Uno:

  • this feature is disabled by default, to minimize sketch size. See optimization.h
  • feature interferes with Serial. The MinimalSerial class provided by SdFat should be used instead

Syntax

SAVE_TO_SD (display, filename)
SAVE_TO_SD (display, prefix, number)

Parameters

  • display: display for which the saved image is suitable
  • filename: save canvas on SD card with this filename
  • prefix: identifies different sets of images
  • number: image's location in the set

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {
    // SD card CS pin 7
    display.useSD(7);

    // Save by filename
    SAVE_TO_SD (display, "canvas01.bmp") {
        //Graphics commands go here, for example:
        display.fillCircle(50, 100, 20, BLACK);
    }

    // Or: save by prefix + number
    SAVE_TO_SD (display, "canvas", 1) {
        //Graphics commands go here, for example:
        display.fillCircle(50, 100, 20, BLACK);
    }

}

See also

saveToSD()

ATmega328P (Uno / Nano): not supported
ATmega2560: disabled for some displays

Draw a canvas image to SD card, outside of a SAVE_TO_SD loop, on-top of any existing screen data.

Output filename can be specified, or instead a prefix and numeric identifier can be given, which will be used to generate a unique filename. The prefix has a maximum length of 6 characters.

Syntax

display.saveToSD(filename)
display.saveToSD(prefix, number)

Parameters

  • filename: save canvas on SD card with this filename
  • prefix: identifies different sets of imagess
  • number: image's location in the set

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {

    display.setCursor(10, 10);
    display.print("Example");

    // Save by filename
    display.saveToSD("canvas01.bmp");   // Result of first two commands saved to SD

    // Or: save by prefix + identifier
    display.saveToSD("canvas", 1);
}

See also

SDCardFound()

Check if SD card is connected and accessible.

Syntax

display.SDCardFound()

Parameters

None.

Returns

true if card is accessible. false if there is an error.

See also

SDFileExists()

Check if an image exists on SD card.

Syntax

display.SDFileExits(filename)
display.SDFileExits(prefix, number)

Parameters

  • filename: image file
  • prefix: identifies different sets of imagess
  • number: image's location in the set

Returns

true if exists. false if not found.

See also

setBackgroundColor()

Sets the background color to be used for future display updates. All graphics operations are drawn on top of this background color. Also determines the color which is set during the standalone clear() method.

Default value is WHITE

Syntax

display.setBackgroundColor(bgcolor)

Parameters

  • bgcolor: color to set as background

Example

#include <heltec-eink-modules.h>

QYEG0213RWS800 display(2, 4, 5);

void setup() {
    display.clear();    // Display now changes to show solid white
    
    display.setBackgroundColor(BLACK);
    display.clear();    // Display clears instead to solid black
    
    ...

    display.clear();    // Clears again to solid black
}

See also

setCursor()

Set text cursor location. Make sure to use inside the DRAW() loop.

This is an AdafruitGFX method

Syntax

display.setCursor(x, y)

Parameters

  • x: X coordinate in pixels
  • y: Y coordinate in pixels

See also

setCursorTopLeft()

Wraps getTextBounds() and setCursor(), for convenience. Set the text cursor according to the desired upper left corner

Syntax

display.setCursorTopLeft(text, x, y)

Parameters

  • text: The text, as char array or char pointer, to be measured for finding top left.
  • x: Target X coordinate
  • y: Target Y coordinate

See also

setFont()

Set the font to display when print()ing, either custom or default. Several fonts are included with this library, in the Fonts folder. Fonts can take up a bit of memory, so don't #include too many!

This is an AdafruitGFX method

Syntax

display.setFont(f)

Parameters

  • f: (address of) The GFXfont object, if NULL use built in 6x8 font.

Example

#include <heltec-eink-modules.h>
#include "Fonts/FreeSerifBold12pt7b.h"

DEPG0150BNS810 display(2, 4, 5);

void setup() {
    // Pass (the address of) the font to the library
    display.setFont( &FreeSerifBold12pt7b );   

    DRAW (display) {
        // Set the (word-processor-like) cursor to the arbitrary position of x=10, y=50
        display.setCursor(10, 50);                      
        display.print("example");
    }

}

void loop() {}

setFlip()

Reverse the image, either horizontally, or vertically.

Flip can be applied in the context of the window, or the whole screen. Flip is applied relative to the current rotation.

Because of a hardware limitation, window width (or height, if you are using a landscape rotation) is always a multiple of 8. Be aware that this may affect window dimensions when drawing flipped. If you are using a window, your window's width will be automatically rounded up to the nearest multiple. For your convenience, these new "rounded up" dimensions are available through the .window feature. In this way, you can draw your graphics to cover the slightly expanded window, and work around the limitation. Note that the window will never "round down"; your originally requested region will always fit within the window provided.

Syntax

setFlip(axis)

Parameters

  • axis: which way to flip the image.
    Supported values:
    • OFF
    • HORIZONTAL
    • VERTICAL
    • HORIZONTAL_WINDOW
    • VERTICAL_WINDOW

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {

    // Flip horizontally
    display.setFlip( HORIZONTAL );
    
    DRAW (display) {
        display.setCursor(10, 10);
        display.print("Mirrored Text");
    }
}

See also

setRotation()

Rotate future drawing operations by a multiple of 90 degrees.

Because of a hardware limitation, window width (or height, if you are using a landscape rotation) is always a multiple of 8. If you are using a window, your window's width will be automatically rounded up to the nearest multiple. For your convenience, these new "rounded up" dimensions are available through the .window feature. In this way, you can draw your graphics to cover the slightly expanded window, and work around the limitation. Note that the window will never "round down"; your originally requested region will always fit within the window provided.

Syntax

setRotation(rotation)

Parameters

  • rotation: clockwise rotation:
    • 0, 90, 180, 270 (degrees), negative allowed
    • in 90 degree increments (1 = 90°, 2=180° etc), negative allowed
    • relative to "display module" header pins:
      • PINS_ABOVE  (0°)
      • PINS_LEFT  (90°)
      • PINS_BELOW  (180°)
      • PINS_RIGHT  (279°)
    • relative to "Wireless Paper" boards' USB connector:
      • USB_ABOVE  (0°)
      • USB_LEFT  (90°)
      • USB_BELOW  (180°)
      • USB_RIGHT  (279°)

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {

    // Set the rotation before
    display.setRotation( PINS_BELOW );
    DRAW (display) {
        display.setCursor(10, 10);
        display.print("Upside Down");
    }

    delay(2000);    // Pause to view the image

    // Set the rotation during
    DRAW (display) {
        display.setCursor(10, 10);
        display.setRotation(0);     // No rotation
        display.print("top");

        display.setCursor(10, 10);
        display.setRotation(1);     // 1 * 90deg rotation
        display.print("left");

        display.setCursor(10, 10);
        display.setRotation( PINS_BELOW );  // 2 * 90deg rotation. (display's pins are now below the screen)
        display.print("bottom");
    }

}

void loop() {}

See also

setTextColor()

Set text font color, with or without a background

This is an AdafruitGFX method

Note from Adafruit:

// NOTE: THERE IS NO 'BACKGROUND' COLOR OPTION ON CUSTOM FONTS.
// THIS IS ON PURPOSE AND BY DESIGN.  The background color feature
// has typically been used with the 'classic' font to overwrite old
// screen contents with new data.  This ONLY works because the
// characters are a uniform size; it's not a sensible thing to do with
// proportionally-spaced fonts with glyphs of varying sizes (and that
// may overlap).

Syntax

display.setTextColor(c)
display.setTextColor(c, bg)

Parameters

  • c: color to draw text with
  • bg: (optional) color to draw background/fill with

See also

setTextWrap()

Set whether text that is too long for the screen width should automatically wrap around to the next line (else clip right).

This is an AdafruitGFX method

Syntax

display.setTextWrap(w)

Parameters

  • w: true for wrapping, false for clipping.

setWindow()

Draw to only a particular part of the screen ("a window"), leaving the remainder unchanged. Call before the DRAW() loop.

Window parameters are interpreted in the context of the current rotation and flip.

Because of a hardware limitation, window width (or height, if you are using a landscape rotation) is always a multiple of 8. Any value given will be automatically rounded up to the nearest multiple. For your convenience, these new "rounded up" dimensions are available through the .window feature. In this way, you can draw your graphics to cover the slightly expanded window, and work around the limitation. Note that the window will never "round down"; your originally requested region will always fit within the window provided.

Syntax

display.setWindow(left, top, width, height)

Parameters

  • left: left edge of the window
  • top: top edge of the window
  • width: width of the window
  • height: height of the window

Example

#include <heltec-eink-modules.h>

QYEG0213RWS800 display(2, 4, 5);

void setup() {
    display.clear();    // Fill screen with white

    display.setWindow(0, 1, 8, 3);                      // Set the window dimensions
    display.setBackgroundColor(BLACK);      // Use black as our background color

    DRAW (display) {
        // Not actually doing anything
        // Just drawing the black background
        // (For the example)
    }
}

/* The result:

    0   1   2   3   4   5   6   7   8   
0   
1   #   #   #   #   #   #   #   #
2   #   #   #   #   #   #   #   #
3   #   #   #   #   #   #   #   #
4

*/

See also

top()

Get the top edge of the display. This will always be zero, but is included for completeness.

Syntax

display.top()

Parameters

None.

Returns

Position of the top edge of the full display, in pixels.

update()

ATmega328P (Uno / Nano): not supported
ATmega2560: disabled for some displays

Execute drawing commands outside of a DRAW loop, drawing on-top of the existing screen data.

Syntax

display.update()

Parameters

None.

Example

#include <heltec-eink-modules.h>

DEPG0150BNS810 display(2, 4, 5);

void setup() {

    display.setCursor(10, 10);
    display.print("Example");

    display.update();   // Image on display changes with this command
}

See also

useCustomPowerSwitch()

Configure the display to use an external power switch, such as a transistor, for power-saving. When requested, the library will configure the display appropriately, and then set the specified switch pin.

Syntax

display.useCustomPowerSwitch(pin, type)

Parameters

  • pin: pin connected to base of a transistor, or other low current switching device.
  • type: type of signal to output on pin
    Supported values:
    • NPN
    • PNP
    • ACTIVE_HIGH
    • ACTIVE_LOW

useSD()

Configure the library to use an SD card - SPI adapter. Must be called before and SD code is used.

Syntax

display.useSD(cs_pin)
display.useSD(cs_pin, miso_pin) // ESP32 or SAMD21G18A only

Parameters

  • cs_pin: pin connected to the CS pin of the SD card adapter
  • miso_pin: custom pin for the MISO connection of the the SD card adapter

See also

width()

Get the width of the display. A display with width 200 will have a left edge of 0, and a right edge of 199. Value will change to match the current rotation.

Syntax

display.width()

Parameters

None.

Returns

Width of the full display, in pixels.

window.left()

Get the left edge of the current window, after it has been expanded to meet hardware requirements. Value will change to match the current rotation.

Syntax

display.window.left()

Parameters

None.

Returns

Position of the left edge of the current window, in pixels.

window.top()

Get the top edge of the current window, after it has been expanded to meet hardware requirements. Value will change to match the current rotation.

Syntax

display.window.top()

Parameters

None.

Returns

Position of the top edge of the current window, in pixels.

window.right()

Get the right edge of the current window, after it has been expanded to meet hardware requirements. Value will change to match the current rotation.

Syntax

display.window.right()

Parameters

None.

Returns

Position of the right edge of the current window, in pixels.

window.bottom()

Get the bottom edge of the current window, after it has been expanded to meet hardware requirements. Value will change to match the current rotation.

Syntax

display.window.bottom()

Parameters

None.

Returns

Position bottom edge of the current window, in pixels.

window.width()

Get the width of the current window. A window with a left edge of 0, and a right edge of 7, would have a width of 8. Value will change to match the current rotation.

Syntax

display.window.width()

Parameters

None.

Returns

Width of the current window, in pixels.

window.height()

Get the height of the current window. A window with a top edge of 0, and a bottom edge of 7, would have a height of 8. Value will change to match the current rotation.

Syntax

display.window.height()

Parameters

None.

Returns

Height of the current window, in pixels.

window.centerX()

Get the horizontal midpoint of the current window. If the center is between two pixels, the leftmost is returned. Value will change to match the current rotation.

Syntax

display.window.centerX()

Parameters

None.

Returns

Horizontal center of the current window, in pixels.

window.centerY()

Get the vertical midpoint of the current window. If the center is between two pixels, the topmost is returned. Value will change to match the current rotation.

Syntax

display.window.centerY()

Parameters

None.

Returns

Vertical center of the current window, in pixels.

Constants

This section describes the various constants (as enumerations), which are accepted as parameters by various methods throughout the library.

Color

Values

  • WHITE
  • BLACK
  • RED - Supported displays only

Example

display.setBackgroundColor( BLACK )

Flip

Specify along which axis the screen should be flipped (mirrored)

Values

  • NONE
  • HORIZONTAL
  • VERTICAL
  • HORIZONTAL_WINDOW
  • VERTICAL_WINDOW

Example

display.setFlip( HORIZONTAL )

Rotation

A convenient shortcut for getting the correct display rotation. Describes the desired rotation in relation to the header pins on the module.

Values

  • PINS_ABOVE
  • PINS_LEFT
  • PINS_BELOW
  • PINS_RIGHT

Example

display.setRotation( PINS_LEFT )

SwitchType

Values passed to useCustomPowerSwitch(), to specify the type of external switch in user's custom power control circuit.

Values

  • NPN
  • PNP
  • ACTIVE_HIGH
  • ACTIVE_LOW

See also