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

ePaper.js can be used as:

• A command line application for single step rendering of a URL onto an ePaper display
• A library that can interface ePaper displays with custom Node.js applications

Features include:

• Supports multiple ePaper Displays
• High performance, native c++ hardware access
• Multiple color modes: black / white, grayscale, black / white / red
• Dithering for black / white images

Usage

ejs <command> [options] <deviceType>

For example, the following command will update the Waveshare 7.5" v2 screen with the contents of http://localhost:8080 every 10 minutes.

ejs refresh rpi-7in5-v2 "http://localhost:8080"

For available devices types, see supported hardware. The different commands and suggested workflows are described below.

Commands

Display: display a single rendition of a URL

ejs display [options] <deviceType> <url>

Option	Description	Allowed Values
-o / --orientation	Use (h)orizontal or (v)ertical orientation	[h, v]
-c / --colorMode	Desired color mode	[black, 4gray, red]
--screenshotDelay	Wait an additional amount of time after loading the URL before displaying. Useful for client side apps	Time in milliseconds
--dither	Use a dithering algorithm to approximate grayscale / mid-tones on black and white displays
--username	Username for basic authentication	username as string
--password	Password for basic authentication	password as string
--debug	Print additional log info and stacktraces
--version	Show version number
--help	Show help

Refresh: continuously update and display the URL

ejs refresh [options] <deviceType> <url>

Option	Description	Allowed Values
-i / --interval	Amount of time between refreshes	Time in seconds (default 10 min)
-o / --orientation	Use (h)orizontal or (v)ertical orientation	[h, v]
-c / --colorMode	Desired color mode	[black, 4gray, red]
--screenshotDelay	Wait an additional amount of time after loading the URL before displaying. Useful for client side apps	Time in milliseconds
--dither	Use a dithering algorithm to approximate grayscale / mid-tones on black and white displays
--username	Username for basic authentication	username as string
--password	Password for basic authentication	password as string
--debug	Print additional log info and stacktraces
--version	Show version number
--help	Show help

Clear: clear the display

ejs clear [options] <deviceType>

Option	Description	Allowed Values
--debug	Print additional log info and stacktraces
--version	Show version number
--help	Show help

Workflows

Self-Hosting

• Create a web app and store it on your Raspberry Pi
• Host the web app with http-server
• Run ePaper.js with ejs refresh <deviceType> "http://localhost:8080" (or whatever port you configure http-server to run on)

Cloud Hosting

• Create a web app and host it on a service like GitHub Pages or Netlify
• Run ePaper.js with ejs refresh <deviceType> "<URL of your app>"

Running As a Daemon
There are several methods of automatically launching ePaper.js on startup and restarting in case of failures

• Run with pm2
• Create a systemd service

Example Applications

See the examples directory

• weather-station: This creates an example weather station display
• color-test: Used to test the various color modes
• 4gray: A demonstration of the 4gray capabilities
• dithering: A demonstration of the dithering feature

Installation

Raspberry PI

Enable SPI

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

Install Node The official recommendation by Node.js is to install Node with a package manager. This helps ensure you'll have the latest LTS version and the proper permissions to install global packages. ePaper.js recommends using nvm

Raspberry Pi 2, 3, 4 Zero 2:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
source ~/.bashrc
nvm install 16

Raspberry Pi 1, Zero:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
source ~/.bashrc
NVM_NODEJS_ORG_MIRROR=https://unofficial-builds.nodejs.org/download/release
nvm install 16

Install Dependencies

sudo apt-get update
sudo apt-get install -y build-essential chromium-browser

Install ePaper.js
Globally install the @epaperjs/cli command line app and the appropriate package for your screen (See supported hardware). For example, to install ePaper.js for the Waveshare 7.5" V2 Screen:

npm install --global @epaperjs/cli @epaperjs/rpi-7in5-v2

Supported Hardware

Device	Device Type	npm Package	Color Modes
Waveshare 4.2"	rpi-4in2	@epaperjs/rpi-4in2	black 4gray
Waveshare 7.5" v2	rpi-7in5-v2	@epaperjs/rpi-7in5-v2	black
Waveshare 3.7" hat	rpi-3in7	@epaperjs/rpi-3in7	black, 4gray
Waveshare 2.13" hat v2	rpi-2in13-v2	@epaperjs/rpi-2in13-v2	black, red
Waveshare 2.13" bc	rpi-2in13-bc	@epaperjs/rpi-2in13-bc	black
Waveshare 2.7"	rpi-2in7	@epaperjs/rpi-2in7	black

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!