README.md

MMM-IT8951

This is a module for the MagicMirror².

This module communicates with a IT8951 card to display MagicMirror² on a e-ink screen. It opens MagicMirror² page on a Chrome browser (with Puppeteer) and observes each DOM update. The e-ink is partially refreshed on DOM update and fully refreshed periodically.

Partial refresh is done in a flashy way by default (that is needed to support the 16 gray levels) but if image is only B/W or has only colors in the 4 gray-levels (gray4levels-x), the refresh mode is changed to have a direct update without flash. Another way to have a fast refresh without flash is by adding the CSS class eink-4levels to a module. Thus, the refresh is forced to 4-level gray only.

The IT8951 is typically used by some Waveshare e-paper screens.

Using the module

To use this module, add the following configuration block to the modules array in the config/config.js file:

var config = {
	modules: [
		{
			module: "MMM-IT8951",
			config: {
				updateInterval: 60 * 1000, // 1 minute // Full refresh screen
				bufferDelay: 1000, // 1 second // Delay before taking updated items
				defaultTo4levels: false,
				driverParam: { MAX_BUFFER_SIZE: 4096, VCOM: 1480 }, // see https://github.com/gaweee/node-it8951#functions-calls
				mock: false,
			},
		},
		{
			module: "foo", // One of your module you want to be refreshed in B/W only
			classes: "eink-4levels", // This class forces non flashy (but only on 4-levels gray) update of this module by MMM-IT8951 (only useful if defaultTo4levels == false)
		},
		{
			module: "bar", // One of your module you want to be refreshed in 16-levels of gray
			classes: "no-eink-4levels", // This class forces on 16-levels gray (but flashy) update of this module by MMM-IT8951 (only useful if defaultTo4levels == true)
		},
	]
}

To use a specific color within the 4 levels of gray, these colors are defined in CSS and can be used:

:root {
	/* Gray levels for IT8951 */
	--gray4levels-1: #fff;
	--gray4levels-2: #aaa;
	--gray4levels-3: #666;
	--gray4levels-4: #000;
}

When a refresh is done on an area that contains only these 4 colors, the refresh will not be flashy.

Installation

cd ~/MagicMirror/modules # Change path to modules directory of your actual MagiMirror² installation
git clone https://github.com/seb-ma/MMM-IT8951
cd MMM-IT8951

If nodejs version is compliant:

npm install --no-audit --no-fund --no-update-notifier --only=prod --omit=dev

Else, a full install + rebuild dependency may be needed:

npm install --no-audit --no-fund --no-update-notifier; npm rebuild rpio --update-binary

OS configuration related

To be able to communicate with IT8951 card, SPI must be activated and permissions to communicate with.

On Raspberry OS:

⚠️ Currently, this module only works with the root user; thus it needs MagicMirror to be launched by root user.

This is due to a problem accessing /dev/mem. It currently can't be accessed thru npm call at this stage, neither as sudo npm nor with sticky bit or cap_sys_rawio capability set.

It works only with user root (sudo su).

For future reference, here, what should work:

sudo raspi-config

Then, enable SPI:

• Interfacing options
• P4 SPI Enable / Disable automatic loading of SPI core module

And add your user in spi group:

sudo adduser $USER spi
sudo adduser $USER kmem

Configuration options

Option	Description
updateInterval	Optional Full refresh screen interval Type: int (milliseconds) Default: 60000 (1 minute)
bufferDelay	Optional Delay before taking updated items in DOM to refresh parts of screen (only applyied to no 4-levels parts. 4-levels parts are always instantly refreshed) Type: int (milliseconds) Default: 1000 (1 second) Set undefined to ignore partial refresh, 0 to refresh immediately
defaultTo4levels	Optional If true, it consider all modules are on 4-levels gray unless modules having class "no-eink-4levels" If false, it consider all modules are on 16-levels gray unless modules having class "eink-4levels" Type: boolean Default: false
driverParam	Optional Parameter to initialize IT8951 driver. See https://github.com/gaweee/node-it8951#functions-calls Default: {MAX_BUFFER_SIZE: 4096, ALIGN4BYTES: true, VCOM: 1480}
mock	Optional true to retrieve not initialize IT8951 driver and store png files of changed areas in /tmp instead Type: boolean Default: false

Notifications

To force a full refresh of the e-ink screen, the notification IT8951_ASK_FULL_REFRESH must be sent. Payload can be set to force a refresh with 4-levels (false) or 16-levels (undefined or true).

Examples to send it from another module:

// Refresh with 16-levels
this.sendNotification("IT8951_ASK_FULL_REFRESH");
// […]

// Refresh with 16-levels
this.sendNotification("IT8951_ASK_FULL_REFRESH", true);
// […]

// Refresh with 4-levels
this.sendNotification("IT8951_ASK_FULL_REFRESH", false);
// […]