This class makes it easy to display text and graphics on a 128x64 SH1106 OLED. More...

#include <PololuSH1106Main.h>

Inheritance diagram for PololuSH1106Main< C >:

Public Member Functions
void	init ()
	Initializes the OLED if it has not already been initialized. More...

void	reinitialize ()
	Reinitializes the OLED and its settings. More...

void	invert ()
	Configures the OLED to invert all the pixels, resulting in black-on-white text. More...

void	noInvert ()
	Configures the OLED to not invert its pixels (the default). More...

void	rotate180 ()
	Configures the OLED to rotate its display 180 degrees from normal. More...

void	noRotate ()
	Configures the OLED to use the default orientation. More...

void	setContrast (uint8_t contrast)
	Sets the contrast (i.e. brightness) of the OLED. More...

void	setLayout8x2 ()
	Configures this library to use its default layout, which allows for 8 columns and 2 rows of text. More...

void	setLayout8x2WithGraphics (const uint8_t *graphics)
	Configures this library to use a layout with 8 columns and 2 rows of text, XORed with a graphics buffer. More...

void	setLayout11x4 ()
	Configures this library to use a layout with 11 columns and 4 rows of text. More...

void	setLayout11x4WithGraphics (const uint8_t *graphics)
	Configures this library to use a layout with 11 columns and 4 rows of text, XORed with a graphics buffer. More...

void	setLayout21x8 ()
	Configures this library to use a layout with 21 columns and 8 rows of text. More...

void	setLayout21x8WithGraphics (const uint8_t *graphics)
	Configures this library to use a layout with 21 columns and 8 rows of text, XORed with a graphics buffer. More...

void	display ()
	Writes all of the text/graphics to the OLED. More...

void	displayPartial (uint8_t x, uint8_t y, uint8_t width)
	Writes a certain region of text/graphics to the OLED. More...

void	noAutoDisplay ()
	Turns off auto display mode. More...

uint8_t *	getLinePointer (uint8_t line)
	Gets a pointer to a line of text in this library's text buffer. More...

void	gotoXY (uint8_t x, uint8_t y)
	Changes the location of the text cursor. More...

uint8_t	getX ()
	Gets the X coordinate of the text cursor. More...

uint8_t	getY ()
	Gets the Y coordinate of the text cursor. More...

void	scrollDisplayUp ()
	Moves all the text up one row. (Does not change the cursor position.) More...

void	clear ()
	Clears the text and resets the text cursor to the upper left. More...

size_t	write (const uint8_t *buffer, size_t size) override
	Writes a string of text. More...

size_t	write (uint8_t d) override
	Writes a single character of text. More...

void	loadCustomCharacterFromRam (const uint8_t *picture, uint8_t number)
	Defines a custom character from RAM. More...

void	loadCustomCharacter (const uint8_t *picture, uint8_t number)
	Defines a custom character. More...

void	loadCustomCharacter (const char *picture, uint8_t number)
	Defines a custom character. More...

Public Attributes
C	core
	This object handles all low-level communication with the SH1106. More...

Detailed Description

template<class C>
class PololuSH1106Main< C >

This class makes it easy to display text and graphics on a 128x64 SH1106 OLED.

Core class

Instead of passing pin numbers to this class to specify what pins your OLED is on, you pass a core class as a first template parameter. The core class must implement the following public functions which take care of communication with the SH1106 at a low level:

void initPins();
void reset();
void sh1106TransferStart();
void sh1106TransferEnd();
void sh1106CommandMode();
void sh1106DataMode();
void sh1106Write(uint8_t);

For an example implementation of a core class, see PololuSH1106Core.

Text buffer

This class holds a text buffer to keep track of what text to show on the screen. The clear(), write(), and print() functions all write to the text buffer.

This class inherits from the Arduino Print class (via PololuSH1106Main), so you can call print() with a variety of arguments. See the Arduino print() documentation for more information.

The default contents of the text buffer, and the contents after you call clear(), consists entirely of space characters.

You can also use the getLinePointer() function to get a pointer to a specific line in the text buffer, and then manipulate the characters using arbitrary code.

Font

This library maps each character code from 0 to 255 to a corresponding 8x5 image.

Characters from 0 to 7 are custom characters: they are blank by default, but you can use loadCustomCharacter() or loadCustomCharacterFromRam() to specify their appearance.

Characters 8 through 31 are hardcoded to be blank.

Characters 32 through 255 come from pololuOledFont.

It is possible to change the appearance (but not the size) of the font used for characters 32 through 255 without modifying this library. To do so, simply copy the file font.cpp into your sketch directory, remove __attribute__((weak)), and then make your changes.

Graphics buffer

This class can be configured to hold a pointer to an external 1024-byte graphics buffer that will get mixed (XORed) with the text. Each byte of the graphics buffer represents a 1x8 vertical column of pixels, with the least-significant bit holding the top-most pixel. The first byte represents the pixels in the upper left corner of the screen, and the bytes in the buffer are ordered left-to-right, then top-to-bottom. (So byte at offset 128 is displayed immediately below the byte at offset 0.)

You can define and manipulate this graphics buffer using your own code, or you can use a third-party library such as Adafruit_SSD1306 to do it.

HD44780 LCD class compatibility

This class implements clear(), gotoXY(), write(), print() (provided by the Arduino Print class), loadCustomCharacter(), and loadCustomCharacterFromRam(), so a class based on PololuSH1106Main can be used as a a drop-in replacement for a class based on PololuHD44780Base from the PololuHD44780 library in most applications.

However, one difference between the SH1106 OLED and the HD44780 LCD is that if you have an application that frequently clears the screen and then redraws it, you will probably notice a flickering effect due to the fast response time of the OLED. To solve this, you can call noAutoDisplay() before clear() to tell the library to refrain from writing to the display automatically. Then, when you are done using functions such as clear(), gotoXY(), write(), and print() to update the desired text on the screen, you can call display() to write the new contents to the entire screen without flicker.

The display() function turns auto-display mode back on, so you will need to call noAutoDisplay() again whenever you want to do a flickerless update.

Definition at line 109 of file PololuSH1106Main.h.

Member Function Documentation

◆ clear()

template<class C >

void PololuSH1106Main< C >::clear ( )

inline

Clears the text and resets the text cursor to the upper left.

After calling this function, the text buffer will consist entirely of space characters.

By default, this function also calls display() to write these changes to the OLED, but noAutoDisplay() disables that behavior.

Definition at line 901 of file PololuSH1106Main.h.

◆ display()

template<class C >

void PololuSH1106Main< C >::display ( )

inline

Writes all of the text/graphics to the OLED.

This also turns on auto display mode, undoing the effect of noAutoDisplay().

Note that this function does not always write to the entire display: for text-only modes, it will normally only write to the portion of the screen containing text.

Definition at line 794 of file PololuSH1106Main.h.

◆ displayPartial()

template<class C >

void PololuSH1106Main< C >::displayPartial	(	uint8_t	x,
		uint8_t	y,
		uint8_t	width
	)

inline

Writes a certain region of text/graphics to the OLED.

This function is like display(), but it only writes text/graphics to the OLED which are in a region corresponding to one or more consecutive characters in a line of text. This function cannot write arbitrary regions.

Most users will not need to call this because the clear(), write(), and print() functions automatically write to the display as needed. You can also use the display() function to write all of the text/graphics.

However, this function is useful to users who have disabled auto display mode, or are directly writing to the text buffer, and want an efficient way to update part of the screen.

Parameters

x	The row number of the text to update (0 means top row).
y	The column number of the first character to update (0 means left-most column).
width	The number of characters to update.

Definition at line 822 of file PololuSH1106Main.h.

◆ getLinePointer()

template<class C >

uint8_t* PololuSH1106Main< C >::getLinePointer ( uint8_t line )

inline

Gets a pointer to a line of text in this library's text buffer.

This is for advanced users who want to use their own code to directly manipulate the text buffer.

The returned pointer will point to a region of memory at least 21 bytes long that holds the specified line of text. You can perform arbitrary operations on these bytes.

Note that you should not assume anything about where the lines are in relation to each other, and you should not assume it is safe to write beyond the 21st byte of a line.

Note that functions like snprintf will add a null (0) character at the end of their output. This is probably undesirable if you have configured character 0 to be a custom character using loadCustomCharacter(). Also, it means that the maximum content they can safely write to the text buffer is limited to 19 characters.

Definition at line 862 of file PololuSH1106Main.h.

◆ getX()

template<class C >

uint8_t PololuSH1106Main< C >::getX ( )

inline

Gets the X coordinate of the text cursor.

Definition at line 881 of file PololuSH1106Main.h.

◆ getY()

template<class C >

uint8_t PololuSH1106Main< C >::getY ( )

inline

Gets the Y coordinate of the text cursor.

Definition at line 884 of file PololuSH1106Main.h.

◆ gotoXY()

template<class C >

void PololuSH1106Main< C >::gotoXY	(	uint8_t	x,
		uint8_t	y
	)

inline

Changes the location of the text cursor.

This function changes the text cursor, which is the location of the text that will be overwritten by the next call to write() or print().

Parameters

x	The column number (0 means left-most column).
y	The row number (0 means top row).

Definition at line 874 of file PololuSH1106Main.h.

◆ init()

template<class C >

void PololuSH1106Main< C >::init ( )

inline

Initializes the OLED if it has not already been initialized.

This resets the OLED, clears the contents of the OLED RAM, sets some default settings, and turns on the display.

Most users do not have to call this, because it is automatically called by any public function in this class that writes to the OLED.

Definition at line 176 of file PololuSH1106Main.h.

◆ invert()

template<class C >

void PololuSH1106Main< C >::invert ( )

inline

Configures the OLED to invert all the pixels, resulting in black-on-white text.

Definition at line 195 of file PololuSH1106Main.h.

◆ loadCustomCharacter() [1/2]

template<class C >

void PololuSH1106Main< C >::loadCustomCharacter	(	const char *	picture,
		uint8_t	number
	)

inline

Defines a custom character.

This overload is only provided for compatibility existing code that defines char arrays instead of uint8_t arrays.

Definition at line 1005 of file PololuSH1106Main.h.

◆ loadCustomCharacter() [2/2]

template<class C >

void PololuSH1106Main< C >::loadCustomCharacter	(	const uint8_t *	picture,
		uint8_t	number
	)

inline

Defines a custom character.

Parameters

picture	A pointer to the character dot pattern, in program space.
number	A character code between 0 and 7.

Definition at line 991 of file PololuSH1106Main.h.

◆ loadCustomCharacterFromRam()

template<class C >

void PololuSH1106Main< C >::loadCustomCharacterFromRam	(	const uint8_t *	picture,
		uint8_t	number
	)

inline

Defines a custom character from RAM.

Parameters

picture	A pointer to the character dot pattern, in RAM.
number	A character code between 0 and 7.

Definition at line 969 of file PololuSH1106Main.h.

◆ noAutoDisplay()

template<class C >

void PololuSH1106Main< C >::noAutoDisplay ( )

inline

Turns off auto display mode.

This causes the clear(), write(), and print() functions to not perform any I/O or write any data to the OLED.

Calling display() will write to the display and turn auto display mode on again.

Definition at line 839 of file PololuSH1106Main.h.

◆ noInvert()

template<class C >

void PololuSH1106Main< C >::noInvert ( )

inline

Configures the OLED to not invert its pixels (the default).

Definition at line 205 of file PololuSH1106Main.h.

◆ noRotate()

template<class C >

void PololuSH1106Main< C >::noRotate ( )

inline

Configures the OLED to use the default orientation.

This is the orientation that results in the text shown on the Graphical OLED Display: 128x64, 1.3", White, SPI from Pololu being the same orientation as the pin labels.

Definition at line 232 of file PololuSH1106Main.h.

◆ reinitialize()

template<class C >

void PololuSH1106Main< C >::reinitialize ( )

inline

Reinitializes the OLED and its settings.

This redoes the initialization that is automatically done by init() the first time any function is called that writes to the OLED.

This can be useful if you want to plug the OLED into the robot after the library has already been initialized.

The screen will be blank after calling this, so you might want to call display() to show the graphics/text that you were shown before.

Definition at line 188 of file PololuSH1106Main.h.

◆ rotate180()

template<class C >

void PololuSH1106Main< C >::rotate180 ( )

inline

Configures the OLED to rotate its display 180 degrees from normal.

Definition at line 215 of file PololuSH1106Main.h.

◆ scrollDisplayUp()

template<class C >

void PololuSH1106Main< C >::scrollDisplayUp ( )

inline

Moves all the text up one row. (Does not change the cursor position.)

Definition at line 887 of file PololuSH1106Main.h.

◆ setContrast()

template<class C >

void PololuSH1106Main< C >::setContrast ( uint8_t contrast )

inline

Sets the contrast (i.e. brightness) of the OLED.

Parameters

contrast A number between 0 (darkest, but still visible) and 255 (brightest, default).

Definition at line 246 of file PololuSH1106Main.h.

◆ setLayout11x4()

template<class C >

void PololuSH1106Main< C >::setLayout11x4 ( )

inline

Configures this library to use a layout with 11 columns and 4 rows of text.

Note that the last column of text will have one column of pixels cut off. You can choose not to use this column or only use it for narrow characters such as punctuation.

Definition at line 284 of file PololuSH1106Main.h.

◆ setLayout11x4WithGraphics()

template<class C >

void PololuSH1106Main< C >::setLayout11x4WithGraphics ( const uint8_t * graphics )

inline

Configures this library to use a layout with 11 columns and 4 rows of text, XORed with a graphics buffer.

Parameters

graphics A pointer to a 1024-byte graphics buffer.

Note that the last column of text will have one column of pixels cut off. You can choose not to use this column or only use it for narrow characters such as punctuation.

Definition at line 300 of file PololuSH1106Main.h.

◆ setLayout21x8()

template<class C >

void PololuSH1106Main< C >::setLayout21x8 ( )

inline

Configures this library to use a layout with 21 columns and 8 rows of text.

Definition at line 310 of file PololuSH1106Main.h.

◆ setLayout21x8WithGraphics()

template<class C >

void PololuSH1106Main< C >::setLayout21x8WithGraphics ( const uint8_t * graphics )

inline

Configures this library to use a layout with 21 columns and 8 rows of text, XORed with a graphics buffer.

Parameters

graphics A pointer to a 1024-byte graphics buffer.

Definition at line 322 of file PololuSH1106Main.h.

◆ setLayout8x2()

template<class C >

void PololuSH1106Main< C >::setLayout8x2 ( )

inline

Configures this library to use its default layout, which allows for 8 columns and 2 rows of text.

Definition at line 258 of file PololuSH1106Main.h.

◆ setLayout8x2WithGraphics()

template<class C >

void PololuSH1106Main< C >::setLayout8x2WithGraphics ( const uint8_t * graphics )

inline

Configures this library to use a layout with 8 columns and 2 rows of text, XORed with a graphics buffer.

Parameters

graphics A pointer to a 1024-byte graphics buffer.

Definition at line 270 of file PololuSH1106Main.h.

◆ write() [1/2]

template<class C >

size_t PololuSH1106Main< C >::write	(	const uint8_t *	buffer,
		size_t	size
	)

inlineoverride

Writes a string of text.

This function writes the specified string of text to the text buffer at the location specified by the text cursor (see gotoXY()), and moves the text cursor to the position immediately to the right of the string.

By default, this function also calls displayPartial() to write these changes to the OLED, but noAutoDisplay() disables that behavior.

There is no limit to how much text you can pass to this function, but the text will be discarded when you reach the end of the current line.

To advance to the next line, use gotoXY(). The newline and carriage return characters do not have any special effect on the text cursor position like they might have in a terminal emulator.

This function is called by (certain overloads of) the print() function provided by the Arduino print class.

Definition at line 926 of file PololuSH1106Main.h.

◆ write() [2/2]

template<class C >

size_t PololuSH1106Main< C >::write ( uint8_t d )

inlineoverride

Writes a single character of text.

This is equivalent to writing a single character using write(const uint8_t *, size_t).

Definition at line 950 of file PololuSH1106Main.h.

Member Data Documentation

◆ core

template<class C >

C PololuSH1106Main< C >::core

This object handles all low-level communication with the SH1106.

Definition at line 1012 of file PololuSH1106Main.h.

The documentation for this class was generated from the following file:

src/PololuSH1106Main.h

Public Member Functions

Public Attributes

Detailed Description

template<class C> class PololuSH1106Main< C >

Core class

Text buffer

Font

Graphics buffer

HD44780 LCD class compatibility

Member Function Documentation

◆ clear()

◆ display()

◆ displayPartial()

◆ getLinePointer()

◆ getX()

◆ getY()

◆ gotoXY()

◆ init()

◆ invert()

◆ loadCustomCharacter() [1/2]

◆ loadCustomCharacter() [2/2]

◆ loadCustomCharacterFromRam()

◆ noAutoDisplay()

◆ noInvert()

◆ noRotate()

◆ reinitialize()

◆ rotate180()

◆ scrollDisplayUp()

◆ setContrast()

◆ setLayout11x4()

◆ setLayout11x4WithGraphics()

◆ setLayout21x8()

◆ setLayout21x8WithGraphics()

◆ setLayout8x2()

◆ setLayout8x2WithGraphics()

◆ write() [1/2]

◆ write() [2/2]

Member Data Documentation

◆ core

template<class C>
class PololuSH1106Main< C >