Heltec E-Ink Modules

Third-party Arduino Library for Heltec E-Ink Module displays, and Wireless Paper boards
Run-time drawing, using Adafruit-GFX.

Read the API

Get started with "Wireless Paper" boards

• Supported Platforms
• Supported Displays - Identify your model
  • 1.54 Inch
  • 2.13 Inch
  • 2.9 Inch
  • Wireless Paper
• Wiring
• Drawing
  • Compatibility or Convenience?
  • Shapes and Text
  • Fonts
  • Images
  • SD card
• Configuration
  • Model Name
  • Pins
  • Saving RAM
  • Saving Flash
  • Saving Power
  • Fast Mode (Partial Refresh)
• Troubleshooting
• Installation
• Acknowledgements

Supported Platforms

Platform	Tested
ATmega328P	Arduino Uno R3, Arduino Nano
ATmega2560	Arduino Mega 2560
ESP32	Devkit V1, Heltec Wireless Paper
ESP8266	NodeMcu v3, LOLIN D1 Mini
SAMD21G18A	Protoneer Nano ARM

Supported Displays - Identify your model

Pay attention to the model name: you will need it to use the library.

1.54 Inch

Model Name	Flex Connector Label	Front Image	Rear Image	Colors	Screen Protector	Resolution (px)	Fastmode (partial refresh)
DEPG0154BNS800	FPC-7525			Black, White	Red Tab	152 x 152	Yes
DEPG0150BNS810	FPC-8101			Black, White	Red Tab	200 x 200	Yes
GDEP015OC1 1	HINK-E0154A05-A2			Black, White	Blue Tab	200 x 200	Yes

¹ Closest match. No official information available.

2.13 Inch

Model Name	Flex Connector Label	Front Image	Rear Image	Colors	Screen Protector	Resolution (px)	Fastmode (partial refresh)
DEPG0213RWS800 2	FPC-7528B			Black, White, Red	Red Tab	250 x 122	No
QYEG0213RWS800 2	FPC-7528			Black, White, Red	Red Tab	250 x 122	No

² Currently, these two displays use the same driver. This is not guaranteed in the future.

2.9 Inch

Model Name	Flex Connector Label	Front Image	Rear Image	Colors	Screen Protector	Resolution (px)	Fastmode (partial refresh)
DEPG0290BNS800	FPC-7519 rev.b			Black, White	Red Tab	296 x 128	Yes
DEPG0290BNS75A	FPC-750			Black, White	Red Tab	296 x 128	Yes
GDE029A1	SYX-1553			Black, White	Blue Tab	296 x 128	Yes

Wireless Paper

Model Name	Flex Connector Label	Front Image	Rear Image 3	Colors	Screen Protector	Resolution (px)	Fastmode (partial refresh)
LCMEN2R13EFC1	Hidden, printed on back-side (HINK-E0213A162-FPC-A0)			Black, White	Green Tab	250 x 122	Yes
DEPG0213BNS800	FPC-7528B			Black, White	Red Tab	250 x 122	Yes

³ Version-marking sticker is present on some LCMEN2R13EFC1 boards.

Wiring

Warning: in some cases, connecting directly to the display will cause damage!
See your boards's wiring page for specific information:

• Wiring: Arduino Uno R3 / Arduino Nano
• Wiring: Arduino Mega 2560
• Wiring: ESP32
• Wiring: ESP8266
• Wiring: SAMD21G18A
• Wireless Paper

Drawing

Compatibility or Convenience?

1. Compatibility

The DRAW() operation allows for RAM saving tricks (paging). Required for older boards, configurable for new boards.
More info about paging here.

#include "heltec-eink-modules.h"

// Use the correct class for your display; set pins for D/C, CS, BUSY
DEPG0150BNS810 display(2, 4, 5);

void setup() {

    // Any config is set first
    display.setBackgroundColor(BLACK);

    // Drawing action goes inside DRAW()
    DRAW (display) {
        display.fillCircle(50, 100, 20, WHITE);
        display.fillCircle(50, 100, 10, BLACK);
    }

}

void loop() {}

2. Convenience

If you're using a fancy new device, you can choose to avoid the DRAW() pattern:

#include "heltec-eink-modules.h"

// Use the correct class for your display; set pins for D/C, CS, BUSY
DEPG0150BNS810 display(2, 4, 5);

void setup() {
    
    display.setBackgroundColor(BLACK);

    // Start working on a new drawing (with a BLACK background)
    display.clearMemory();

    // Draw the same circles from the other example
    display.fillCircle(50, 100, 20, WHITE);
    display.fillCircle(50, 100, 10, BLACK);
    
    // Whenever you're ready, display your masterpiece
    display.update();

}

void loop() {}

Shapes and Text

Drawing operations come from the Adafruit GFX library You'll find a full list of supported commands in the API. Check out the examples folder to see them in action. Alternatively, the official adafruit-gfx tutorial is a good place to start.

Fonts

The library comes with a selection of custom fonts. You can create more with truetype2gfx.
See the Fonts example.

Images

As decided by the Adafruit library, the ancient "XBitmap" is the format of choice for pre-rendered graphics. Luckily, GIMP maintains good support for it. If you need a hint on how to use it, I have thrown together a tutorial on preparing XBitmap images.

SD card

It is possible to load and save .bmp images, using a cheap SD card SPI adapter. Read more

Configuration

Model Name

The Model Name of your display is used to select the correct driver. Find your model name.

Pins

// Make sure to use the correct class for your display model
DEPG0150BNS810 display(dc, cs, busy);   

Pass the pin numbers to which the D/C, CS, and BUSY pins from the display are connected.

If you're using ESP32, you are free to set custom SDI, and CLK pins if you wish.
If you're using SAMD21G18A, you are able to make some changes to SDI and CLK assignment. See wiring.

DEPG0150BNS810 display(dc, cs, busy, sdi, clk);

If you're using a "Wireless Paper" board, you don't need to pass pins; they are already set.

Saving RAM

On older boards, this library makes use of paging.This technique allows drawing with less RAM, with the cost of decreased speed.
On newer boards, this technique is not required, and is disabled by default (regardless of your code style)

If you wish to tweak this speed vs. RAM trade-off, or enable the technique on a newer board, you can usually specificy a custom "page_height" in the display constructor. This specifies how many lines of the display should be calculated at once.

DEPG0150BNS810 display(dc, cs, busy, page_height);

Saving Flash

On older boards in particular, the library can occupy a large portion of the "flash memory". If you need to reduce this, you can manually edit the optimization.h file, to disable unused features.

Note: for ATmega328, some of the more-obscure features are disabled by default.

Saving Power

Many E-ink manufacturers provide a deep-sleep mode. With Heltec display modules, this mode is often not usable.

For "Display Modules":

Consider using a PNP transistor, or other switching device, to disconnect your display when needed. The library can handle this for you. Configure your custom switch hardware with useCustomPowerSwitch(), then call customPowerOff() and customPowerOn() as required.

See your board's wiring page for a suggested schematic.

For "Wireless Paper":

A low power state is available for the whole board (18μA while sleeping). See Wireless Paper

Fast Mode (Partial Refresh)

E-Ink displays generally take several seconds to refresh. Some displays have an alternative mode, where the image updates much faster. This is known officially as a "Partial Refresh". For the sake of simplicity, this library instead 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.

Call fastmodeOn() to enable.
Call fastmodeOff() to return to normal.

Troubleshooting

• Double-check your wiring
  On breadboard, or header pins, it is easy to be one row out.
  Make sure to use a level-shifter, if needed.

• Double-check your constructor
  

  // Make sure to use the correct class for your display model,
  // and the correct pins to match your wiring
  
  DEPG0150BNS810 display(dc, cs, busy);   

• Take a look at the examples, and the API
  Some commands might not work the way you would expect. If unsure, double check.

• Disconnect and Reconnect
  If the display has been used incorrectly, it can get "stuck".
  Remove all power from the display and Arduino for 5 seconds.

Installation

Arduino: Library can be installed to Arduino IDE with Sketch -> Include Library -> Add .Zip Library.., or through the built-in Library Manager.

Platform.io: Available through the built-in library registry, or alternatively, can be installed by extracting the Zip file to the lib folder of your project.

Acknowledgements

• Display information referenced from both official Heltec sources, and GxEPD2.
• Drawing functions provided by GFX Root, which itself is a stripped down version of Adafruit GFX.
• A bundled version of SdFat is used with some platforms.
• TJpg_Decoder is bundled with certain examples.