SSD1306 OLED Library for CCS C compiler

The SSD1306 OLED display contains a driver chip with the same name (SSD1306), it can communicate with the master device (microcontroller, microprocessor …) over I2C protocol, SPI protocol or 8-bit parallel protocol.
This topic shows how to use the SSD1306 OLED driver (& library) for CCS C compiler and how to connect it with Microchip PIC microcontroller. The driver is for I2C mode only, normally it supports three types: 128×64, 128×32 and 96×16.
The library is based on Adafruit SSD1306 OLED driver and Adafruit graphics library.

With this driver the SSD1306 OLED display communicates with the PIC microcontroller over I2C protocol which needs two data lines: SDA (serial data) and SCL (serial clock), an additional reset pin can be used between the microcontroller and the display (optional), some SSD1306 OLED displays does not have the reset pin.

Connecting the SSD1306 OLED with PIC microcontroller:
As mentioned above, the microcontroller uses I2C protocol to send and receive data to and from the SSD1306 OLED display. The I2C bus uses two lines SDA and SCL, an other line is connected between the MCU and the display which is used as a hardware reset line, this line is optional because some displays come with no reset pin.

It does not matter if the microcontroller has a hardware I2C module or not because the CCS C compiler can use software I2C instead of it.

As any I2C device, the SSD1306 OLED display has an I2C address, this address is used by the microcontroller (master) to start talking to the display (slave). The default address of the SSD1306 OLED is 0x7A or 0x78 depending on connection of pin D/C (data/command) which acts as a slave address bit (SA0) in I2C mode, if this pin is connected to +VCC the address is 0x7A and if it is connected to the ground the address becomes 0x78.

General circuit schematic diagram of the MCU and the display is shown by the image below, it shows an example for a display of 128×64 Pixel.

The PIC microcontroller as well as SSD1306 OLED display are supplied with 5V or 3.3V depending on the microcontroller operating voltage. There are 3 wires connected between the two devices: RESET, SDA and SCL.

The DC pin (same as D/C) of the SSD1306 OLED display is connected to +VCC which means the I2C slave address of the device is: 0x7A.

SSD1306 OLED Library for CCS C compiler:
This small SSD1306 OLED driver and graphics library allows us to print texts, draw lines, circles and many other function (listed below). This library is just a .C file named SSD306OLED.C which can be installed by adding it to project folder or CCS C compiler drivers folder (for example: C:\Program Files\CCS\Drivers)

The SSD1306 OLED display library can be downloaded from the link below:
SSD1306 OLED Library download

The I2C bus should be initialized in the main code as the example shown below where the hardware I2C module is used with a clock frequency of 100KHz (100000Hz):
#use I2C(MASTER, I2C1, FAST = 100000, stream = SSD1306_STREAM)

If the SSD1306 OLED display has a reset pin then it should be connected to the microcontroller where its pin connection is defined in the main code:
#define SSD1306_RST PIN_D0

The driver source file is included to the main code as any other file:
#include <SSD1306OLED.c>

The library supports 3 types of the SSD1306 OLED display depending on the screen resolution, these types are: 128×64 pixel, 128×32 pixel and 96×16 pixel. The default type is: 128×64 pixel.
If you want to use it with the 128×32 pixel type just define it in the main code as:
#define SSD1306_128_32

and if the 96×16 pixel type is used, the definition becomes:
#define SSD1306_96_16

Note that the library doesn’t support defining both previous types at once and compiling a code with the two definitions (#define SSD1306_128_32 and #define SSD1306_96_16) will give an error.

User functions:
SSD1306_Begin(vccstate, i2caddr); Initializes the display, i2caddr is the display address.

SSD1306_DrawPixel(x, y, color); Draws a pixel on the screen, x and y are coordinates in pixel.

SSD1306_StartScrollRight(start, stop); Scroll right
SSD1306_StartScrollLeft(start, stop); Scroll left
SSD1306_StartScrollDiagRight(start, stop); Scroll diagonal right
SSD1306_StartScrollDiagLeft(start, stop); Scroll diagonal left
SSD1306_StopScroll(); Stop scrolling

SSD1306_Dim(dim); Dim the display, dim can be 1 (true) or 0 (false).

SSD1306_Display(); Prints data buffer on the display, must be called after any draw action.
SSD1306_ClearDisplay(); Clears the buffer
SSD1306_FillScreen(color); Fills the whole screen, color can be 1 or 0.
SSD1306_InvertDisplay(i); Inverts the display, i can be 1 or 0.

SSD1306_DrawLine(x0, y0, x1, y1, color); Draws a line from (x0, y0) to (x1, y1). Color may be 1 or 0, 1 draw and 0 delete, default value is 1 (true).

SSD1306_DrawFastHLine(x, y, w, color); Draws a horizontal line from (x, y) with width of w. Color can be 1 or 0.
SSD1306_DrawFastVLine(x, y, h, color); Draws a vertical line from (x, y) with height of h. Color can be 1 or 0.

SSD1306_DrawRect(x, y, w, h); Draws a rectangle from (x,y) with width w and height h.
SSD1306_FillRect(x, y, w, h, color); Fills a rectangle from (x, y) with width w and height h. Color can be 1 or 0.
SSD1306_DrawRoundRect(x, y, w, h, r); Draws round rectangle from (x, y) with width w, height h and radius r.
SSD1306_FillRoundRect(x, y, w, h, r, color); Fills round rectangle from (x, y) with width w, height h and radius r.

SSD1306_DrawTriangle(x0, y0, x1, y1, x2, y2); Draws a triangle with points (x0, y0), (x1, y1) and (x2, y2).
SSD1306_FillTriangle(x0, y0, x1, y1, x2, y2, color); Fills a triangle with points (x0, y0), (x1, y1) and (x2, y2).

SSD1306_DrawCircle(x0, y0, r); Draws a circle from (x0, y0) with radius r.
SSD1306_FillCircle(x0, y0, r, color); Fills a circle from (x0, y0) with radius r.
SSD1306_DrawCircleHelper(x0, y0, r, cornername); Draws a circle helper from (x0, y0) with radius r and cornername.
SSD1306_FillCircleHelper(x0, y0, r, cornername, delta, color); Fills a circle helper from (x0, y0) with radius r and cornername.

SSD1306_DrawChar(x, y, c, size); Prints a character c starting from (x, y), size is text size (default is 1).
SSD1306_Drawtext(x, y, *_text, size); Prints a text _text starting from (x, y), size is text size (default is 1).
SSD1306_SetTextWrap(w); Sets text wrap, if w = 1 text wrap enabled (default), if w = 0 text wrap disabled.

Examples:
This is a list of some examples where the SSD1306 OLED display library is used.

Interfacing PIC18F4550 with SSD1306 OLED
PIC18F4550 with SSD1306 OLED and DHT11 sensor
Interfacing PIC18F4550 with DHT22 and SSD1306 display
PIC18F4550 Real time clock with DS1307 and SSD1306 display
Interfacing PIC18F4550 with DS3231 RTC and SSD1306 display