Have ideas to improve npm?Join in the discussion! »


    1.0.25 • Public • Published

    OLED display renderer [I2C/SPI]

    alt text


    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


    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 (instanceof Display.Error) {
            console.error(e.name + ',', e.status + ',', e.message);
          } else
            throw e;


    let display = new Display(config);
    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})


    To come.


    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

    alt text

    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


    npm i oled-display

    DownloadsWeekly Downloads






    Unpacked Size

    593 kB

    Total Files


    Last publish


    • avatar