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.

PIC microcontroller with SSD1306 OLED circuit connection

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

18 thoughts on “SSD1306 OLED Library for CCS C compiler”

  1. AYUUUDAAAAAAA!!!!
    Tengo una pantalla oled ssd1306 128x64pxz
    si puedo escribir dibujar triangulos circulos etc
    pero no coge el llamado *bitmap
    en la pantalla SALE UNA ABERRACION
    ya intente mil formas. tienen alguna sugerencia?

    SSD1306_ROMBMP(0, 0,LOGO, 128, 64);
    SSD1306_Display();

    void SSD1306_ROMBMP(uint8_t x, uint8_t y,rom uint8_t*bitmap, uint8_t w, uint8_t h)
    {int8 j,i;
    //SSD1306_LCDHEIGHT==h;
    //SSD1306_LCDWIDTH==w;
    for( i= 0 ; i < h/8; i++ )
    {
    for(j = 0; j < w * 8; j++ )
    {
    if( bit_test(bitmap[j/8 + i * w],j % 8 )==1 )
    SSD1306_DrawPixel(x + j/8, y + i*8 + (j % 8));
    else
    SSD1306_DrawPixel( x + j/8, y + i*8 + (j % 8), 0);
    }
    }

  2. João Francisco Montanhani

    I’m developing with PIC16F690 and I want to use OLED Display 0.66″ 64×48. Is there any driver to use this display on CCS PIC? Thank you.

  3. Mauricio Rodriguez Quiroga

    The library works with SSD1306, but does not work with SH1106 displays. How can I modify the library to work with that controller?

  4. Thank you for publishing this code. I would like to use a 0.49″ 64×32 OLED display. If I add defines for a 64×32 display to your SSD1306.c code will it work with this display. Thanks

  5. I have these errors, the I2C functions are not included and the SSD1306_STREAM is undeclared. Anyone has a solution for this? I am using a PIC12F1822

    SSD1306OLED.c:315:5: warning: implicit declaration of function ‘I2C_Start’ is invalid in C99 [-Wimplicit-function-declaration]
    I2C_Start(SSD1306_STREAM);
    ^
    SSD1306OLED.c:315:15: error: use of undeclared identifier ‘SSD1306_STREAM’
    I2C_Start(SSD1306_STREAM);
    ^
    SSD1306OLED.c:316:5: warning: implicit declaration of function ‘I2C_Write’ is invalid in C99 [-Wimplicit-function-declaration]
    I2C_Write(SSD1306_STREAM, _i2caddr);
    ^
    SSD1306OLED.c:316:15: error: use of undeclared identifier ‘SSD1306_STREAM’
    I2C_Write(SSD1306_STREAM, _i2caddr);

    1. Hi for the SSD1306_STREAM undeclared the solution is in the order of the code, if you call the library before the #use and #defines it wont work, the proper way to do this is

      #use I2C(MASTER, I2C1, FAST = 400000, stream = SSD1306_STREAM) // Initialize I2C
      #define SSD1306_RST PIN_B0
      #define SSD1306_128_32
      #include

      and after that you can start wit the initialization an all the program code

    1. The reset pin shouldn’t be defined in the main C code because the display doesn’t have it (there is no RESET line between the display and the PIC microcontroller). SCL and SDA pins of the display are respectively connected to SCL and SDA pins of the PIC MCU.
      You should use a delay before initializing the display!

      1. Hola
        Tengo tambien ésa pantalla de solo 4 pines, comenté la linea: //#define SSD1306_RST PIN_D4
        pero no funciona, ya verifiqué la dirección del I2C pero sigue sin funcionar, qué podria ser?

  6. I’m having many problems compiling my code. The main error is:
    ***Error 87 “C:…\Drivers\SSD1306OLED.c” Line 226(63,64): Data item too big
    then other errors like:
    *** Error 43 “C:…\Drivers\SSD1306OLED.c” Line 226(67,68): Expecting a declaration

    My code (PIC16F876A)
    #include
    #device PASS_STRINGS = IN_RAM

    #define SSD1306_128_32
    #define SSD1306_RST PIN_C5

    #fuses HS,NOWDT,NOPROTECT,NOLVP
    #use delay(clock = 20MHz)
    #use I2C(MASTER, I2C1, FAST = 400000, stream = SSD1306_STREAM) // Initialize I2C

    // Include SSD1306 OLED driver source code
    #include

    int8 i = 0;

    void main() {

    delay_ms(500);

    // Initialize the SSD1306 OLED with an I2C addr = 0x7A (default address)
    SSD1306_Init(SSD1306_SWITCHCAPVCC, SSD1306_I2C_ADDRESS);

    // clear the display
    SSD1306_ClearDisplay();

    SSD1306_GotoXY(1, 1);
    SSD1306_PutC(“Interfacing PIC16F877A with SSD1306 OLED display”);
    delay_ms(5000);

    SSD1306_ClearDisplay();

    SSD1306_GotoXY(6, 2);
    SSD1306_PutC(“Hello world!”);
    delay_ms(2000);

    SSD1306_StartScrollRight(1, 1);
    delay_ms(3000);
    SSD1306_StopScroll();

    SSD1306_StartScrollLeft(1, 1);
    delay_ms(3000);
    SSD1306_StopScroll();

    SSD1306_StartScrollDiagRight(1, 1);
    delay_ms(3000);
    SSD1306_StopScroll();

    SSD1306_StartScrollDiagLeft(1, 1);
    delay_ms(3000);
    SSD1306_StopScroll();

    delay_ms(3000);
    SSD1306_ClearDisplay();

    SSD1306_GotoXY(6, 2);
    SSD1306_PutC(“Hello world!”);
    delay_ms(2000);

    while(TRUE) {
    SSD1306_GotoXY(10, 5);
    printf(SSD1306_PutC, “%03u”, i++);
    delay_ms(500);
    }

    }

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Scroll to Top