oled-display

OLED display renderer [I2C/SPI]

Description

Portable display rendering library for RPi and clones.

Works with the latest Node.js (no node-gyp), high framerate, fully working, feature rich, easy to use.

Install Dependencies:

# Python 3 & Python Pillow 
sudo apt install python3 python3-pip python3-dev git
sudo pip3 install --upgrade setuptools wheel
sudo apt install libjpeg8-dev zlib1g-dev libtiff-dev libfreetype6 libfreetype6-dev libwebp-dev libopenjp2-7-dev libopenjp2-7-dev -y
sudo pip3 install pillow --global-option="build_ext" --global-option="--enable-zlib" --global-option="--enable-jpeg" --global-option="--enable-freetype" --global-option="--enable-webp" --global-option="--enable-webpmux" --global-option="--enable-jpeg2000"
 
# Adafruit Python SSD1306 
git clone https://github.com/adafruit/Adafruit_Python_SSD1306.git
cd Adafruit_Python_SSD1306
sudo python3 setup.py install
 
# Luma.OLED Python 
sudo pip3 install --upgrade luma.oled
 
# Give write permission to the I2C device 
sudo chmod 777 /dev/i2c-*

Install Package:

npm install --save oled-display

Compatibility & Drivers

	Interface	Cost (USD)	Working	Errors	Driver	Backend
SSD1306	I2C/SPI	$2	✔	✔	SSD1306_128_32	Adafruit_Py
SSD1306	I2C/SPI	$2	✔	✔	SSD1306_128_64	Adafruit_Py
SSD1309	I2C/SPI	$9-17	?	✖	SSD1309_128_64	Luma.OLED
SSD1322	SPI	$20	?	✖	SSD1322_256_64	Luma.OLED
SSD1325	SPI	$35	?	✖	SSD1325_128_64	Luma.OLED
SSD1327	I2C/SPI	$9-14	✔	✖	SSD1327_128_128	Luma.OLED
SSD1331	SPI	$8.50	?	✖	SSD1331_96_64	Luma.OLED
SSD1351	SPI	$17-20	?	✖	SSD1351_128_96	Luma.OLED
SSH1106	I2C/SPI	$4	?	✖	SSD1106_128_64	Luma.OLED

Example

const Display = require('oled-display');
 
const config = {
  driver: 'SSD1306_128_64', // Drivers: SSD1306_128_64, SSD1306_128_32, ...
  interface: 'I2C', // Interfaces: I2C, SPI
  // I2C
  i2c_bus: 0, // Often 0/1. Armbian enable in 'armbian-config'
  i2c_address: 0x3C, // If this fails, try 0x3D
  // SPI
  spi_rst_pin: 24, // Change this (SSD1306 only)
  spi_dc_pin: 23, // Change this (SSD1306 only)
  spi_port: 0, // Might need to change this
  spi_device: 0, // Might need to change this
  spi_hz: 8000000, // (SSD1306 only)
};
 
let frame_rate = 0; // 0 is uncapped, frames per second
async function start() {
  let display = new Display(config, __dirname);
 
  while(true) {
    try {
      display.clear(); // Color: clear(0/1)
      
      // Draw here
      display.drawRectangleSize(0, 1, 0, 0, display.getWidth() - 1, display.getHeight() - 1); // Display border
      display.drawText(1, 'HELLO WORLD!', 3, 2, 1, 1); // Horizontally aligned right
      
      await display.render(10000); // Timeout after timeout of 10 seconds
      await display.sync(frame_rate); // Sync's to backend as well as framerate
    }
    catch(e) {
      if (e instanceof Display.Error) {
        console.error(e.name + ',', e.status + ',', e.message);
        process.exit(1);
      } else
        throw e;
    }
  };
};
 
start();

Functions

let display = new Display(config);
display.*

Function	Description
Sync with display backend & limit framerate.	sync(fps=0)
Re-initialize display if something goes wrong.	reinit()
Clear display to color.	clear(o_color=0)
Rotate display.	rotate(degrees)
Render to display.	render(timeout=0, o_invert=false)
Invert display.	setInvert(invert)
Invert boundary of display.	drawInvertRectangle(x1, y1, x2, y2)
Invert boundary of display.	drawInvertRectangleSize(x1, y1, width, height)
Dim display to the lowest contrast.	setDim(enable)
Dim display to a specified contrast.	setContrast(value)
Get width of display, ignoring rotation.	getOutputWidth()
Get height of display, ignoring rotation.	getOutputHeight()
Get width of display, considering rotation.	getWidth()
Get height of display, considering rotation.	getHeight()
Draw rectangle, filled and outline.	drawRectangle(fill, outline=1, x1, y1, x2, y2)
Draw rectangle, filled and outline.	drawRectangleSize(fill, outline=1, x1, y1, x2, y2)
Draw solid line.	drawLine(fill, x1, y1, x2, y2)
Draw dashed line horizontally.	drawLineDashHor(fill, x, y, o_length)
Draw dashed line vertically.	drawLineDashVer(fill, x, y, o_length)
Draw pixel.	drawPoint(fill, x, y)
Draw pixel.	drawPixel(fill, x, y)
Draw pixel.	drawPoints(fill, x, y, ...)
Draw polygon.	drawPolygon(fill, outline=1, xn, yn, ...)
Draw circle.	drawCircle(fill, outline=1, x, y, radius)
Create new render target.	newTarget()
Set current render target.	setTarget(targetId)
Reset to default render target.	resetTarget()
Draw render target to the default.	drawTarget(targetId, x=0, y=0, o_width, o_height)
Converts and loads image file.	let imageId = await loadImage(path)
Draws/overlays specified image.	drawImage(imageId)
Loads font file.	loadFont(path, name, size)
Set current font.	setFont(name)
Gets width of message in pixels, using set font.	getFontWidth(message)
Gets height of message in pixels, using set font.	getFontWidth(message)
Draw text using set font.	drawText(fill, message, x, y, halign=1, valign=1, wrap=false, o = {vspacing: 2})
Draw text using micro font.	drawTextMicro(fill, message, x, y, halign=1, valign=1, wrap=false, o = {padding: 1, vspacing: 3})

Examples

To come.

Warning

This has only been tested using an Orange Pi Zero running Armbian - Ubuntu Bionic.

There is currently not much in the way of error checking and correction. If something goes wrong, debug your script, value ranges and verify parameters.

Setup - Orange Pi Zero - Armbian

1. Attach your display to the pinout above.
2. Enable i2c0 overlay: sudo sed -i -e '/overlays=/s/$/ i2c0/' /boot/armbianEnv.txt
3. Reboot sudo reboot
4. Install dependencies into a directory, paste the example into a new file index.js and run node index