SSD1306 OLED display library for mikroC compiler | mikroC Projects

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 (& graphics library) for mikroC PRO for PIC compiler and how to connect it with Microchip PIC microcontroller. This library is for I2C mode only, 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.

This driver supports software I2C and hardware I2C (more faster). It will use the software I2C (using mikroC built-in soft I2C library) if the following line is defined in the main code:
#define SSD1306_SOFT_I2C

Otherwise the driver will automatically use hardware I2C1 module and it will use hardware I2C2 module if the line below is defined in the main code:
#define SSD1306_I2C2

As any I2C device, the SSD1306 OLED display has an I2C slave address, this address is used by the microcontroller (master) to start talking to the display (slave). The 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 (0V) 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 mikroC 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.

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

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 as show in the following example where the reset pin is connected to pin RD4 of the PIC microcontroller:
#define SSD1306_RST RD4_bit
#define SSD1306_RST_DIR TRISD4_bit

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.

SSD1306 OLED Library functions:
void SSD1306_Begin(vccstate, i2caddr): initializes the display, i2caddr is the display address.

void SSD1306_DrawPixel(x, y): draws a pixel on the screen, x and y are coordinates in pixel.

void SSD1306_StartScrollRight(start, stop): scroll right
void SSD1306_StartScrollLeft(start, stop): scroll left
void SSD1306_StartScrollDiagRight(start, stop): scroll diagonal right
void SSD1306_StartScrollDiagLeft(start, stop): scroll diagonal left
void SSD1306_StopScroll(): stop scrolling

void SSD1306_Dim(bool dim): dim the display, dim can be 1 (true) or 0 (false).

void SSD1306_Display(): prints data buffer on the display, must be called after any draw action.
void SSD1306_ClearDisplay(): clears the buffer
void SSD1306_FillScreen(): fills the whole screen.
void SSD1306_InvertDisplay(bool i): inverts the display, i can be 1 or 0.

void SSD1306_DrawLine(x0, y0, x1, y1): draws a line from (x0, y0) to (x1, y1).

void SSD1306_DrawFastHLine(x, y, w): draws a horizontal line from (x, y) with width of w.
void SSD1306_DrawFastVLine(x, y, h): draws a vertical line from (x, y) with height of h.

void SSD1306_DrawRect(x, y, w, h): draws a rectangle from (x,y) with width w and height h.
void SSD1306_FillRect(x, y, w, h): fills a rectangle from (x, y) with width w and height h.
void SSD1306_DrawRoundRect(x, y, w, h, r): draws round rectangle from (x, y) with width w, height h and radius r.
void SSD1306_FillRoundRect(x, y, w, h, r): fills round rectangle from (x, y) with width w, height h and radius r.

void SSD1306_DrawTriangle(x0, y0, x1, y1, x2, y2): draws a triangle with points (x0, y0), (x1, y1) and (x2, y2).
void SSD1306_FillTriangle(x0, y0, x1, y1, x2, y2): fills a triangle with points (x0, y0), (x1, y1) and (x2, y2).

void SSD1306_DrawCircle(x0, y0, r): draws a circle from (x0, y0) with radius r.
void SSD1306_FillCircle(x0, y0, r, color): fills a circle from (x0, y0) with radius r.
void SSD1306_DrawCircleHelper(x0, y0, r, cornername): draws a circle helper from (x0, y0) with radius r and cornername.
void SSD1306_FillCircleHelper(x0, y0, r, cornername, delta): fills a circle helper from (x0, y0) with radius r and cornername.

void SSD1306_SetTextWrap(bool w): sets text wrap, if w = 1 text wrap enabled (default), if w = 0 text wrap is disabled.

void SSD1306_PutC(uint8_t c): prints a single character c on the display. The character c can also be one of the following:
‘\a’: set cursor position to upper left (0, 0)
‘\b’: move back one position
‘\n’: go to start of current line
‘\r’: go to line below.

void SSD1306_Print(char *s): prints a text s on the display.

void SSD1306_PutCustomC(const uint8_t *c): prints a custom character c located in ROM. The dimension of the character should be 7×5 (the same dimension with the built-in font).

void SSD1306_GotoXY(uint8_t x, uint8_t y): moves the cursor to position (x, y) where x and y are in pixel.
void SSD1306_TextSize(uint8_t t_size): sets text size to t_size.

void SSD1306_DrawBMP(uint8_t x, uint8_t y, const uint8_t *bitmap, uint8_t w, uint8_t h): prints a BMP image (stored in ROM) with width of w and height of h.

As an addition to the user function, a variable named SSD1306_Color is used to set the color true (ON) or false (OFF), default is true.

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

Interfacing PIC18F46K22 with SSD1306 OLED display | mikroC Projects
Interfacing PIC18F46K22 with LM335 sensor and SSD1306 OLED display
PIC18F46K22 Interface with SSD1306 OLED display and LM35 sensor
PIC18F46K22 with SSD1306 OLED and DS1307 RTC | mikroC Projetcts
Interfacing PIC18F46K22 with DS18B20 sensor and SSD1306 OLED
PIC MCU with SSD1306 OLED and DHT11 sensor | mikroC Projects
PIC18F46K22 with SSD1306 OLED and DHT11 sensor | mikroC Projects
PIC18F46K22 with DHT22 sensor and SSD1306 OLED | mikroC Projects
PIC18F46K22 Interface with BMP280 sensor and SSD1306 OLED display
Weather Station with PIC18F46K22 and BME280 Sensor | mikroC Projects