OLED Display

Controls the optional 128×64 pixel monochrome OLED display. More...

Files
file	display.h

Functions
int8_t	sb_display_enable ()
	Activate (and setup) the OLED-display. More...
int8_t	sb_display_available ()
	Check if a functional OLED display is present. More...
int8_t	sb_display_disable ()
	Turn the OLED display off. More...
int8_t	sb_display_draw (uint8_t pageNum, uint8_t colNum, uint8_t content)
	Draw a single page segment onto the OLED display. More...
int8_t	sb_display_drawBitmap (uint8_t pageStart, uint8_t colStart, uint8_t pageCount, uint8_t colCount, const uint8_t *contents)
	Draw a (rectangular) bitmap onto the OLED display. More...
int8_t	sb_display_fillScreen (const uint8_t *contents)
	Draw the contents of a 8*128 item 8-bit array (8 pages with 128 columns, each filled with 8 bit) onto the OLED Display. More...
int8_t	sb_display_showString (uint8_t pageNum, uint8_t colStart, const char *str)
	Print a \0 terminated text string on the OLED display using a 8×8 pixel font. More...
int8_t	sb_display_showStringWide (uint8_t pageNum, uint8_t colStart, const char *str)
	Print a \0 terminated text string with a (slightly) wider 8×8 pixel font onto the OLED display. More...
int8_t	sb_display_showStringSmall (uint8_t pageNum, uint8_t colStart, const char *str)
	Print a \0 terminated text string on the OLED display using a small 6×4 pixel font. More...

Detailed Description

Controls the optional 128×64 pixel monochrome OLED display.

The SPiCboard v3 has a TWI (two wire interface, also known as I²C), which can be used to connect an OLED display. Especially the SSD1306 monochrome OLED display fits perfectly onto the board. It has a 0.96 inch diameter with 128 horizontal and 64 vertical pixels.

For the sake of simplicity the horizontal pixels are termed columns. The vertical pixels are divided into 8 so-called pages, therefore a byte can represent the contents of a page segment (with 8 pixels - from the LSB on top to the MSB on bottom of each page segement).

For additional details please have a look into the SSD1306 Datasheet.

In case your run into memory issues (which is quite easy with only 2 KB SRAM) you might want to have a look into the FromFlash function variants.

Warning

The display is quite sensitive to fluctuation of current. Try to avoid contact of any [semi-]conductive material (including your fingers) with the pins on the Xplained Mini Board – especially connecting PC3 with PC4 – or the connection to your display might stop (it stalls until you restart it, the LED on the Xplained Mini Board can indicate the error).

Function Documentation

sb_display_available()

int8_t sb_display_available

(

)

Check if a functional OLED display is present.

Tries to connect to the SSD1306 display (I²C device address 0x78) without enabling it.

Return values

0	display is available and seems to work
<0	display not available or not functional

sb_display_disable()

int8_t sb_display_disable

(

)

Turn the OLED display off.

Return values

0	success
<0	on I²C error (

See also

sb_display_enable() return codes)

sb_display_draw()

int8_t sb_display_draw	(	uint8_t	pageNum,
		uint8_t	colNum,
		uint8_t	content
	)

Draw a single page segment onto the OLED display.

Parameters

pageNum	page number (0-7) for vertical positioning the output
colNum	column number (0-127) for the horizontal position of the output
content	contents to be drawn on the page segment (LSB on top and MSB on bottom)

Return values

0	success
<0	on I²C error (

See also

sb_display_enable() return codes)

sb_display_drawBitmap()

int8_t sb_display_drawBitmap	(	uint8_t	pageStart,
		uint8_t	colStart,
		uint8_t	pageCount,
		uint8_t	colCount,
		const uint8_t *	contents
	)

Draw a (rectangular) bitmap onto the OLED display.

The result is similar to multiple calls of sb_display_draw() (although the execution of this function is way faster):

 for (uint8_t page = 0; page < pageCount; page++){
    for (uint8_t col = 0; col < colCount; col++){
        sb_display_draw(pageStart + page, colStart + col, contents[page * colCount + col]);
    }
}

Example:

We want to draw a square with a point in its center with some spacing to the to the left top corner of the screen.

The bitmap will be drawn across two pages, each with eight page segments.

Hence we first initialize an array with 2*8 elements (columns 5-12 for page 0 and 1) containing the contents of each page segement (1 for a white pixel and 0 for a black/clear one) and then transfer them to the screen.

#include <stdint.h>
#include <stddef.h>
#include "display.h"

void main(void){
    if (sb_display_enable() == 0){ // Enable display (if present)
        sb_display_fillScreen(NULL); // Clear display
        // Square Bitmap
        uint8_t bitmap[] = { 0xF0, 0x10, 0x10, 0x90, 0x90, 0x10, 0x10, 0xF0, 
                             0x0F, 0x08, 0x08, 0x09, 0x09, 0x08, 0x08, 0x0F };
        // From PAGE 0 and COLumn 5 draw 2 pages and 8 columns
        sb_display_drawBitmap(0, 5, 2, 8, bitmap);
    }
    while(1); // Stop loop
}

Parameters

pageStart	first page to set the top vertical position
colStart	first column to set the left horizontal position
pageCount	number of pages to set the bottom position (including the first page)
colCount	number of columns to define the right border (including the first column)
contents	array pointing to the bitmap (must have pageCount * colCount elements) - or NULL to clear the area

Return values

0	success
<0	on I²C error (see sb_display_enable() return codes)

sb_display_enable()

int8_t sb_display_enable

(

)

Activate (and setup) the OLED-display.

Return values

0	success
-1	initialization of I²C failed
-2	setting I²C device address failed
-3	writing to I²C device failed
-4	timeout during I²C communication
-5	out of bounds (addressing nonexistent page/column)

sb_display_fillScreen()

int8_t sb_display_fillScreen

(

const uint8_t *

contents

)

Draw the contents of a 8*128 item 8-bit array (8 pages with 128 columns, each filled with 8 bit) onto the OLED Display.

The function call is identical to

sb_display_drawBitmap(0, 0, 8, 128, contents);

In case the pointer is NULL, the entire screen will be cleared.

Warning

Make sure that the buffer points to an array with 1024 items - this is C, there is no range check!

Parameters

contents

pointer to a 8*128 item array - or NULL to clear the screen

Return values

0	success
<0	on I²C error (

See also

sb_display_enable() return codes)

sb_display_showString()

int8_t sb_display_showString	(	uint8_t	pageNum,
		uint8_t	colStart,
		const char *	str
	)

Print a \0 terminated text string on the OLED display using a 8×8 pixel font.

A single character will fit into one page (= eight rows) and eight columns. Therefore it is possible to print 16 characters at maximum.

If the length of the string exceeds the available columns (= columns right of the start column) in the current page, the output will not be continued on the next line!

The font was extract from the Linux kernel and is based on code page 437 (= extended ASCII, every possible character has a graphical string representation).

Consequently, the ASCII control characters (like line break) are displayed with special symbols but don't have any functional impact.

The Fonts Table contains a detailed list of the available characters

Warning

The font will be stored on the flash which will consume about 2300 bytes.

Parameters

pageNum	page number (0-7) for vertical positioning the output
colStart	first column to set the horizontal position of the output
str	0-terminated string

Return values

>=0	length of printed string (can be less than strlen(str) )
<0	on I²C error (

See also

sb_display_enable() return codes)

sb_display_showStringSmall()

int8_t sb_display_showStringSmall	(	uint8_t	pageNum,
		uint8_t	colStart,
		const char *	str
	)

Print a \0 terminated text string on the OLED display using a small 6×4 pixel font.

A single character will fit into one page (eight rows, even though it is just six pixels) and four columns, therefore it is possible to print 32 characters at maximum.

If the length of the string exceeds the available columns (= columns right of the start column) in the current page, the output will not be continued on the next line!

The Fonts Table contains a detailed list of the available characters

Warning

In contrast to the other showString functions the character set is quite limited - it only supports printable ASCII characters (neither control characters nor the extended ASCII set). Hence, the required flash memory consumption is (with about 700 bytes) less than a third of the space requirements of the other fonts.

Parameters

pageNum	page number (0-7) for vertical positioning the output
colStart	first column to set the horizontal position of the output
str	0-terminated string

Return values

>=0	length of printed string (can be less than strlen(str) )
<0	on I²C error (

See also

sb_display_enable() return codes)

sb_display_showStringWide()

int8_t sb_display_showStringWide	(	uint8_t	pageNum,
		uint8_t	colStart,
		const char *	str
	)

Print a \0 terminated text string with a (slightly) wider 8×8 pixel font onto the OLED display.

The character set is almost identical to the sb_display_showString() function and the space requirement is the same (up to 16 characters per line)

The Fonts Table contains a detailed list of the available characters.

Warning

This font will consume about 2300 bytes, too.

Parameters

pageNum	page number (0-7) for vertical positioning the output
colStart	first column to set the horizontal position of the output
str	0-terminated string

Return values

>=0	length of printed string (can be less than strlen(str) )
<0	on I²C error (see sb_display_enable() return codes)