nanoFramework.Iot.Device.Ssd13xx 1.3.111

SSD13xx & SSH1106 OLED display family

The SSD1306/SSH1106 are a single-chip CMOS OLED/PLED driver with controllers for organic/polymer light emitting diode dot-matrix graphic display system. It consists of 128 segments and 64 commons. This IC is designed for Common Cathode type OLED panel.

Documentation

• IoT NanoFramework SSD1306/SSH1106 Driver
• SSD1306 datasheet
• SSD1327 datasheet

Related Devices

• Adafruit PiOLED - 128x32 Monochrome OLED Add-on for Raspberry Pi
• HiLetgo 1.3" SPI 128x64 SSH1106 OLED LCD Display LCD
• SunFounder 0.96" Inch Blue I2C IIC Serial 128x64 OLED LCD LED SSD1306 Modul
• Diymall 0.96" Inch Blue and Yellow I2c IIC Serial Oled LCD LED Module 12864 128X64 for Arduino Display Raspberry PI 51 Msp420 Stim32 SCR

Board

Address on the I2C bus: Ssd1306.DefaultI2cAddress 0x3C

Version with 7-pin I2C/SPI

Address on the I2C bus: Ssd1306.SecondaryI2cAddress 0x3D

Connecting resistors:

• I2C — R1, R4, R8;
• SPI — R3, R4.

For only I2C

Connection table

Binding Notes

This binding currently only supports commands and raw data. Eventually, the plan is to create a graphics library that can send text and images to the device. So this library is just a start and you'll find in the sample more advance commands.

The following connection types are supported by this binding.

• I2C
• SPI

Usage notes

There are two groups of drawing methods.

1. Various specialized drawing methods allowing to draw on screen pixel-by-pixel, like:

   • DrawPixel(...): draws one pixel
   • DrawHorizontalLine(...): draws a horizontal line
   • DrawVerticalLine(...): draws a vertical line
   • DrawFilledRectangle(...): draws a filled rectangle
   • DrawBitmap(...): draws a bitmap
   • DrawString(...): draws a string with preset font

   Using these methods you do not need to care about any technique the driver uses to display your drawing instructions.

2. Methods allowing to modify screen content by blocks of internal representation (screen buffer), like:

   • DrawDirectAligned(...): overwrites screen buffer with given content
   • ClearDirectAligned(...): clears out (with 0x00) given part of screen buffer

   These methods allow faster (~100 times) display access but with some constraints.

   • bitmaps handed over here must be in appropriate format (see SSD13xx docs for "GDDRAM" and "Horizontal addressing mode").
   • no bit operations occure with existing buffer data (with pixels drawn via other means), the new data will overwrite the pixels "below" newly drawed content.
   • the "y" coordinate and the bitmap height must be byte aligned with screen buffer (again, see above docs)

The use of two groups can be freely mixed (e.g. display text via DrawString(...) and displaying an image below via DrawDirectAligned(...))

Examples for 1. can be found in samples folder.

Example for 2. follows here.

// There are superb online helpers like the one below which are able to
// create an appropriate byte array from an image in code use ready format.
// https://www.mischianti.org/images-to-byte-array-online-converter-cpp-arduino/
// On the site above use these settings to get bytes needed here:
// - "plain bytes"
// - "vertical - 1 bit per pixel"
var buffer = new byte[] { ... }; 
var width = 16;
var height = 16;

// instantiation example
var ssd1306 = new Ssd1306(
    I2cDevice.Create(
        new I2cConnectionSettings(
            1, 
            Ssd1306.DefaultI2cAddress, 
            I2cBusSpeed.FastMode)), 
    Ssd13xx.DisplayResolution.OLED128x64);

// this line sends the image data to the screen
ssd1306.DrawDirectAligned(x, y, width, height, buffer);

// this one wipes its place to blank
ssd1306.ClearDirectAligned(x, y, width, height);

To display double byte fonts (for example fonts of Asian languages) you have to set the font to DoubleByteFont(), like this:

device.Font = new DoubleByteFont();
device.DrawString(2, 2, "功夫＄", 2, false);
device.DrawString(2, 34, "８９ＡＢ功夫＄", 1, true);
device.Display();

Follows the output on the display:

Fonts

Fonts can be used following the IFont implementation.

Sample fonts are provided both in the sample directory and in the additional font one. A tool called Bitmap2Font is also provided helping to automatically generate the Font class. In short, it can take any black and white image of fixed size font and generate the Font class. More information here.