⚠️ Disclaimer: This project is currently under active development and testing. Features may be incomplete or unstable. Use at your own risk. The authors are not responsible for any damage to your devices or hardware.

IT8951 USB Display Driver (TypeScript)

English Version | 中文版本

Node.js + TypeScript driver for IT8951 e-paper display controllers via USB.

Features

• 📘 TypeScript Support - Full type definitions for better IDE support
• 🔌 USB Interface - Cross-platform USB communication (no Raspberry Pi required)
• 🎨 Partial Updates - Automatic detection and update of changed regions
• 🔄 Multiple Display Modes - Support for INIT, DU, GC16, A2, and more
• 🗂️ Index Mode - Support for up to 16 separate image buffers
• 🚀 Fast Write - Optimized memory write command (up to 30MB/s)
• 🔍 Device Identification - SCSI Inquiry support to verify IT8951 controllers
• ✅ Comprehensive Testing - Jest test suite with 60+ tests and coverage reporting
• 📝 Well Documented - Comprehensive examples and API documentation
• 🚀 Modern ES Modules - Uses ES module syntax

Installation

npm install

System Dependencies

macOS

brew install libusb

Linux (Ubuntu/Debian)

sudo apt-get install libusb-1.0-0-dev

Quick Start

import { EPD, DisplayModes } from './src/index.js';

async function main() {
  const epd = new EPD({ vcom: -2.06 });
  await epd.init();

  console.log(`Display: ${epd.width} x ${epd.height}`);

  // Clear display
  await epd.clear();

  // Create image buffer
  const buffer = new Uint8Array(epd.width * epd.height);
  buffer.fill(255);

  // Display
  await epd.loadImageArea(buffer);
  await epd.displayArea(0, 0, epd.width, epd.height, DisplayModes.GC16);
  
  epd.close();
}

main();

Usage

Basic Display Control

import { EPD, DisplayModes } from './src/index.js';

const epd = new EPD({ vcom: -2.06 });
await epd.init();

// Clear
await epd.clear();

// Display modes: INIT, DU, GC16, GL16, A2, DU4
await epd.displayArea(0, 0, epd.width, epd.height, DisplayModes.GC16);

epd.close();

Device Identification

import { USBInterface } from './src/usb-interface.js';

const usb = new USBInterface();
await usb.open();

// Check if device is IT8951
const isIT8951 = await usb.identify();
console.log(`Device is IT8951: ${isIT8951}`);

// Get raw inquiry data
const inquiry = await usb.scsiInquiry();
console.log('Vendor:', inquiry.subarray(8, 16).toString('ascii').trim());
console.log('Product:', inquiry.subarray(16, 32).toString('ascii').trim());

usb.close();

Index Mode (Multiple Buffers)

import { EPD, DisplayModes } from './src/index.js';

const epd = new EPD();
await epd.init();

// Load images to different buffer indices
const buffer1 = new Uint8Array(epd.width * epd.height).fill(200);
const buffer2 = new Uint8Array(epd.width * epd.height).fill(100);

await epd.loadImageAreaIndexed(0, buffer1); // Load to buffer 0
await epd.loadImageAreaIndexed(1, buffer2); // Load to buffer 1

// Display from different buffers
await epd.displayAreaIndexed(0, 0, 0, epd.width, epd.height, DisplayModes.GC16);
await new Promise(resolve => setTimeout(resolve, 2000));
await epd.displayAreaIndexed(1, 0, 0, epd.width, epd.height, DisplayModes.GC16);

epd.close();

Fast Write Memory

import { USBInterface } from './src/usb-interface.js';

const usb = new USBInterface();
await usb.open();

const info = await usb.getDeviceInfo();
const address = info.imageBufferAddress;

// Fast write for large data transfers (up to 30MB/s)
const largeBuffer = Buffer.alloc(1024 * 1024); // 1MB
await usb.fastWriteMemory(address, largeBuffer);

usb.close();

Auto Display (Partial Updates)

import { EPD, AutoEPDDisplay, DisplayModes } from './src/index.js';

const epd = new EPD();
await epd.init();

const autoDisplay = new AutoEPDDisplay(epd);

// Automatic partial updates
await autoDisplay.drawPartial(DisplayModes.DU);

// Full update
await autoDisplay.drawFull(DisplayModes.GC16);

epd.close();

Display Modes

| Mode | Name | Speed | Quality | Use Case | |------|------|-------|---------|----------| | INIT | Initialization | Slow | High | Full refresh | | DU | Direct Update | Fast | Medium | Text | | GC16 | Grayscale 16 | Medium | High | Images | | A2 | Animation | Very Fast | Low | Video |

Testing

This project includes a comprehensive test suite using Jest with TypeScript support.

Running Tests

# Run all tests with coverage
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with verbose output
npm run test:verbose

Test Coverage

The test suite includes:

• Unit Tests: Tests for individual modules (constants, usb-interface, epd, auto-display)
• Integration Tests: Tests for module interactions and error handling
• Coverage Reports: HTML and text coverage reports generated in coverage/ directory

Current coverage:

• Statements: 53%+
• Branches: 49%+
• Functions: 55%+
• Lines: 53%+

Test Files

• src/__tests__/constants.test.ts - Constants and enum validation
• src/__tests__/usb-interface.test.ts - USB communication layer tests
• src/__tests__/epd.test.ts - EPD controller tests
• src/__tests__/auto-display.test.ts - Auto display and partial update tests
• src/__tests__/integration.test.ts - Integration and error handling tests

Coverage Reports

After running tests, view the HTML coverage report:

open coverage/index.html

Development

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Run example
node examples/basic.js

API Reference

EPD Class

• init() - Initialize display
• close() - Close connection
• clear() - Clear display
• loadImageArea(buffer, options) - Load image
• loadImageAreaIndexed(index, buffer, options) - Load image to indexed buffer
• displayArea(x, y, w, h, mode) - Display region
• displayAreaIndexed(index, x, y, w, h, mode) - Display from indexed buffer
• waitDisplayReady() - Wait for ready
• setVCOM(voltage) / getVCOM() - VCOM control

USBInterface Class

• open() - Open USB connection
• close() - Close connection
• scsiInquiry() - Send SCSI Inquiry command
• identify() - Check if device is IT8951
• getDeviceInfo() - Get device information
• loadImageArea(x, y, w, h, data) - Load image data
• loadImageAreaIndexed(index, x, y, w, h, data) - Load to indexed buffer
• displayArea(x, y, w, h, mode, wait) - Display area
• displayAreaIndexed(index, x, y, w, h, mode, wait) - Display from indexed buffer
• fastWriteMemory(addr, data) - Fast memory write (up to 30MB/s)
• setPowerVcom(vcom, powerOn) - Set VCOM and power state

Properties

• width, height - Display dimensions
• firmwareVersion, lutVersion - Version info

License

MIT

Acknowledgments

Based on the pyit8951 Python driver.