Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Node.js library for easily creating an ePaper display on a Raspberry Pi using HTML and Javascript.

Example weather station Example ereader gif

Working with the API

Create static/index.html. The contents of this webpage will be rendered onto the ePaper display.

<!DOCTYPE html>
<html lang="en">
        <h1>Hello from ePaper.js</h1>
            // connect to the WebSocket API
            const ws = new WebSocket('ws://localhost:8080');
            ws.addEventListener('open', () => {
                // draw contents of DOM onto ePaper display

From Node.js initialize ePaper.js. This does the following:

  • Creates a webserver that serves index.html from the static directory
  • Loads index.html in a headless instance of Chromium, using Puppeteer
  • Creates a WebSocket API that the frontend can use to trigger a display refresh, or perform custom actions
  • Renders the contents of the browser DOM onto the ePaper display
const { init } = require('epaperjs');


Additional Configuration

Additional Configuration Options

const { devices, init } = require('epaperjs');
init(devices.waveshare4in2, {
    webPort: 3000, // WebServer Port
    websocketPort: 8080, // WebSocket API Port
    staticDirectory: 'static', // Directory to serve frontend from
    url: `http://localhost:3000/index.html`, // Initial URL to load

Extend the server side WebSocket API

const { devices, init } = require('epaperjs');

const render = (page, ws) => {
    // Forward frontend console output to Node.js console

    // When recieving 'render' from frontend, update display
    ws.on('message', async (message) => {
        if (message === 'render') {
            await page.display();

    // forward keypresses to the frontend over WebSocket
    process.stdin.addListener('keypress', (key, data) => {
        if ( === 'left') {
        if ( === 'right') {

init(devices.waveshare4in2, {}, render);

See the examples directory

  • weather-station: This creates and example weather station display
  • ereader: An ereader that reads epub files and uses the left and right keypresses to change pages


Raspberry PI
Enable SPI

sudo raspi-config
# Choose Interfacing Options -> SPI -> Yes  to enable SPI interface
sudo reboot

Install Dependencies

# Install latest Node.js LTS
curl -sL | sudo bash

sudo apt-get update

# Install wiringpi
sudo apt-get install -y wiringpi

# For Pi 4, you need to update wiringpi (skip otherwise):
cd /tmp
sudo dpkg -i wiringpi-latest.deb
#You will get 2.52 information if you've installed it correctly
gpio -v

# Remaining dependencies
sudo apt-get install -y build-essential chromium-browser

Install ePaper.js

npm install -S epaperjs

Supported Hardware

Device Supprted Display Modes
Waveshare 4.2" Black / White, 4 Gray
Waveshare 7.5" v2 Black / White
Waveshare 3.7" hat Black / White, 4 Gray
Waveshare 2.13" hat v2 Black / White

Adding Support For Additional Displays

It's easy to extend ePaper.js to support additional Waveshare devices. Displays from other manufacturers should be possible to support as well, as long as there is a C / C++ driver available.

If you would like to request support for another display, please open an issue with the title 'Add support for <Device Make \ Model>'. If you're a developer and have extended support yourself, put up a pull request!

Feature Backlog

  • Add support for portrait or landscape display (rotate 90 deg)
  • Add support for remaining Waveshare SPI ePaper displays
  • Implement 4 Color Grayscale
  • Implement Red / White / Black Color Mode
  • Implement Yellow / White / Black Color Mode
  • Implement Partial Refresh


Node.js library for easily creating an ePaper display on a Raspberry PI using HTML and Javascript.




No packages published