Adafruit SSD1306

Main Page Classes Files Search

Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Adafruit_SSD1306 Class Reference

Class that stores state and functions for interacting with SSD1306 OLED displays. More...

#include <Adafruit_SSD1306.h>

Inheritance diagram for Adafruit_SSD1306:

Public Member Functions

Adafruit_SSD1306 (uint8_t w, uint8_t h, TwoWire *twi=&Wire, int8_t rst_pin=-1, uint32_t clkDuring=400000UL, uint32_t clkAfter=100000UL)
Constructor for I2C-interfaced SSD1306 displays. More...

Adafruit_SSD1306 (uint8_t w, uint8_t h, int8_t mosi_pin, int8_t sclk_pin, int8_t dc_pin, int8_t rst_pin, int8_t cs_pin)
Constructor for SPI SSD1306 displays, using software (bitbang) SPI. More...

Adafruit_SSD1306 (uint8_t w, uint8_t h, SPIClass *spi, int8_t dc_pin, int8_t rst_pin, int8_t cs_pin, uint32_t bitrate=8000000UL)
Constructor for SPI SSD1306 displays, using native hardware SPI. More...

Adafruit_SSD1306 (int8_t mosi_pin, int8_t sclk_pin, int8_t dc_pin, int8_t rst_pin, int8_t cs_pin)
DEPRECATED constructor for SPI SSD1306 displays, using software (bitbang) SPI. Provided for older code to maintain compatibility with the current library. Screen size is determined by enabling
one of the SSD1306_* size defines in Adafruit_SSD1306.h. New code should NOT use this. More...

Adafruit_SSD1306 (int8_t dc_pin, int8_t rst_pin, int8_t cs_pin)

DEPRECATED constructor for SPI SSD1306 displays, using native hardware SPI. Provided for older code to maintain compatibility with the current library. Screen size is determined by enabling one
of the SSD1306_* size defines in Adafruit_SSD1306.h. New code should NOT use this. Only the primary SPI bus is supported, and bitrate is fixed at 8 MHz. More...

Adafruit_SSD1306 (int8_t rst_pin=-1)

DEPRECATED constructor for I2C SSD1306 displays. Provided for older code to maintain compatibility with the current library. Screen size is determined by enabling one of the SSD1306_* size
defines in Adafruit_SSD1306.h. New code should NOT use this. Only the primary I2C bus is supported. More...

~Adafruit_SSD1306 (void)
Destructor for Adafruit_SSD1306 object.

bool begin (uint8_t switchvcc=SSD1306_SWITCHCAPVCC, uint8_t i2caddr=0, bool reset=true, bool periphBegin=true)
Allocate RAM for image buffer, initialize peripherals and pins. More...

void display (void)

Push data currently in RAM to SSD1306 display. More...

void clearDisplay (void)

Clear contents of display buffer (set all pixels to off). More...

void invertDisplay (bool i)

Enable or disable display invert mode (white-on-black vs black-on-white). More...

void dim (bool dim)

Dim the display. More...

void drawPixel (int16_t x, int16_t y, uint16_t color)

Set/clear/invert a single pixel. This is also invoked by the Adafruit_GFX library in generating many higher-level graphics primitives. More...

virtual void drawFastHLine (int16_t x, int16_t y, int16_t w, uint16_t color)

Draw a horizontal line. This is also invoked by the Adafruit_GFX library in generating many higher-level graphics primitives. More...

virtual void drawFastVLine (int16_t x, int16_t y, int16_t h, uint16_t color)

Draw a vertical line. This is also invoked by the Adafruit_GFX library in generating many higher-level graphics primitives. More...

void startscrollright (uint8_t start, uint8_t stop)

Activate a right-handed scroll for all or part of the display. More...

void startscrollleft (uint8_t start, uint8_t stop)

Activate a left-handed scroll for all or part of the display. More...

void startscrolldiagright (uint8_t start, uint8_t stop)

Activate a diagonal scroll for all or part of the display. More...

void startscrolldiagleft (uint8_t start, uint8_t stop)

Activate alternate diagonal scroll for all or part of the display. More...

void stopscroll (void)

Cease a previously-begun scrolling action. More...

void ssd1306_command (uint8_t c)

Issue a single low-level command directly to the SSD1306 display, bypassing the library. More...

bool getPixel (int16_t x, int16_t y)

Return color of a single pixel in display buffer. More...

uint8_t * getBuffer (void)

Get base address of display buffer for direct reading or writing. More...

Protected Member Functions

void SPIwrite (uint8_t d) __attribute__((always_inline))
Write a single byte to the SPI port. More...

void drawFastHLineInternal (int16_t x, int16_t y, int16_t w, uint16_t color)

Draw a horizontal line with a width and color. Used by public methods drawFastHLine,drawFastVLine. More...

void drawFastVLineInternal (int16_t x, int16_t y, int16_t h, uint16_t color)

Draw a vertical line with a width and color. Used by public method drawFastHLine,drawFastVLine. More...

void ssd1306_command1 (uint8_t c)

Issue single command to SSD1306, using I2C or hard/soft SPI as needed. Because command calls are often grouped, SPI transaction and selection must be started/ended in calling function for efficiency.
This is a protected function, not exposed (see ssd1306_command() instead). More...

void ssd1306_commandList (const uint8_t *c, uint8_t n)

Issue list of commands to SSD1306, same rules as above re: transactions. This is a protected function, not exposed. More...

Protected Attributes
SPIClass * spi
TwoWire * wire
uint8_t * buffer
int8_t i2caddr
I2C address initialized when begin method is called.

int8_t vccstate
VCC selection, set by begin method.

int8_t page_end
not used

int8_t mosiPin
int8_t clkPin
(Clock Pin) set when using SPI set during construction.

int8_t dcPin
(Data Pin) set when using SPI set during construction.

int8_t csPin
(Chip Select Pin) set when using SPI set during construction.

int8_t rstPin
Display reset pin assignment. Set during construction.

uint8_t contrast
normal contrast setting for this device

Detailed Description
Class that stores state and functions for interacting with SSD1306 OLED displays.

Constructor & Destructor Documentation

◆ Adafruit_SSD1306() [1/6]
Adafruit_SSD1306::Adafruit_SSD1306 ( uint8_t w,
uint8_t h,
TwoWire * twi = &Wire,
int8_t rst_pin = -1,
uint32_t clkDuring = 400000UL,
uint32_t clkAfter = 100000UL
)

Constructor for I2C-interfaced SSD1306 displays.

Parameters
w Display width in pixels
h Display height in pixels
twi Pointer to an existing TwoWire instance (e.g. &Wire, the microcontroller's primary I2C bus).
rst_pin Reset pin (using Arduino pin numbering), or -1 if not used (some displays might be wired to share the microcontroller's reset pin).
clkDuring Speed (in Hz) for Wire transmissions in SSD1306 library calls. Defaults to 400000 (400 KHz), a known 'safe' value for most microcontrollers, and meets the SSD1306 datasheet spec. Some
systems can operate I2C faster (800 KHz for ESP32, 1 MHz for many other 32-bit MCUs), and some (perhaps not all) SSD1306's can work with this – so it's optionally be specified here and is
not a default behavior. (Ignored if using pre-1.5.7 Arduino software, which operates I2C at a fixed 100 KHz.)
clkAfter Speed (in Hz) for Wire transmissions following SSD1306 library calls. Defaults to 100000 (100 KHz), the default Arduino Wire speed. This is done rather than leaving it at the 'during' speed
because other devices on the I2C bus might not be compatible with the faster rate. (Ignored if using pre-1.5.7 Arduino software, which operates I2C at a fixed 100 KHz.)

Returns
Adafruit_SSD1306 object.

Note
Call the object's begin() function before use – buffer allocation is performed there!

◆ Adafruit_SSD1306() [2/6]
Adafruit_SSD1306::Adafruit_SSD1306 ( uint8_t w,
uint8_t h,
int8_t mosi_pin,
int8_t sclk_pin,
int8_t dc_pin,
int8_t rst_pin,
int8_t cs_pin
)

Constructor for SPI SSD1306 displays, using software (bitbang) SPI.

Parameters
w Display width in pixels
h Display height in pixels
mosi_pin MOSI (master out, slave in) pin (using Arduino pin numbering). This transfers serial data from microcontroller to display.
sclk_pin SCLK (serial clock) pin (using Arduino pin numbering). This clocks each bit from MOSI.
dc_pin Data/command pin (using Arduino pin numbering), selects whether display is receiving commands (low) or data (high).
rst_pin Reset pin (using Arduino pin numbering), or -1 if not used (some displays might be wired to share the microcontroller's reset pin).
cs_pin Chip-select pin (using Arduino pin numbering) for sharing the bus with other devices. Active low.

Returns
Adafruit_SSD1306 object.

Note
Call the object's begin() function before use – buffer allocation is performed there!

◆ Adafruit_SSD1306() [3/6]
Adafruit_SSD1306::Adafruit_SSD1306 ( uint8_t w,
uint8_t h,
SPIClass * spi_ptr,
int8_t dc_pin,
int8_t rst_pin,
int8_t cs_pin,
uint32_t bitrate = 8000000UL
)

Constructor for SPI SSD1306 displays, using native hardware SPI.

Parameters
w Display width in pixels
h Display height in pixels
spi_ptr Pointer to an existing SPIClass instance (e.g. &SPI, the microcontroller's primary SPI bus).
dc_pin Data/command pin (using Arduino pin numbering), selects whether display is receiving commands (low) or data (high).
rst_pin Reset pin (using Arduino pin numbering), or -1 if not used (some displays might be wired to share the microcontroller's reset pin).
cs_pin Chip-select pin (using Arduino pin numbering) for sharing the bus with other devices. Active low.
bitrate SPI clock rate for transfers to this display. Default if unspecified is 8000000UL (8 MHz).

Returns
Adafruit_SSD1306 object.

Note
Call the object's begin() function before use – buffer allocation is performed there!

◆ Adafruit_SSD1306() [4/6]
Adafruit_SSD1306::Adafruit_SSD1306 ( int8_t mosi_pin,
int8_t sclk_pin,
int8_t dc_pin,
int8_t rst_pin,
int8_t cs_pin
)

DEPRECATED constructor for SPI SSD1306 displays, using software (bitbang) SPI. Provided for older code to maintain compatibility with the current library. Screen size is determined by enabling one of the
SSD1306_* size defines in Adafruit_SSD1306.h. New code should NOT use this.

Parameters
mosi_pin MOSI (master out, slave in) pin (using Arduino pin numbering). This transfers serial data from microcontroller to display.
sclk_pin SCLK (serial clock) pin (using Arduino pin numbering). This clocks each bit from MOSI.
dc_pin Data/command pin (using Arduino pin numbering), selects whether display is receiving commands (low) or data (high).
rst_pin Reset pin (using Arduino pin numbering), or -1 if not used (some displays might be wired to share the microcontroller's reset pin).
cs_pin Chip-select pin (using Arduino pin numbering) for sharing the bus with other devices. Active low.

Returns
Adafruit_SSD1306 object.

Note
Call the object's begin() function before use – buffer allocation is performed there!

◆ Adafruit_SSD1306() [5/6]
Adafruit_SSD1306::Adafruit_SSD1306 ( int8_t dc_pin,
int8_t rst_pin,
int8_t cs_pin
)

DEPRECATED constructor for SPI SSD1306 displays, using native hardware SPI. Provided for older code to maintain compatibility with the current library. Screen size is determined by enabling one of the
SSD1306_* size defines in Adafruit_SSD1306.h. New code should NOT use this. Only the primary SPI bus is supported, and bitrate is fixed at 8 MHz.

Parameters
dc_pin Data/command pin (using Arduino pin numbering), selects whether display is receiving commands (low) or data (high).
rst_pin Reset pin (using Arduino pin numbering), or -1 if not used (some displays might be wired to share the microcontroller's reset pin).
cs_pin Chip-select pin (using Arduino pin numbering) for sharing the bus with other devices. Active low.

Returns
Adafruit_SSD1306 object.

Note
Call the object's begin() function before use – buffer allocation is performed there!

◆ Adafruit_SSD1306() [6/6]
Adafruit_SSD1306::Adafruit_SSD1306 ( int8_t rst_pin = -1 )

DEPRECATED constructor for I2C SSD1306 displays. Provided for older code to maintain compatibility with the current library. Screen size is determined by enabling one of the SSD1306_* size defines in
Adafruit_SSD1306.h. New code should NOT use this. Only the primary I2C bus is supported.

Parameters
rst_pin Reset pin (using Arduino pin numbering), or -1 if not used (some displays might be wired to share the microcontroller's reset pin).

Returns
Adafruit_SSD1306 object.

Note
Call the object's begin() function before use – buffer allocation is performed there!

Member Function Documentation

◆ begin()
bool Adafruit_SSD1306::begin ( uint8_t vcs = SSD1306_SWITCHCAPVCC,
uint8_t addr = 0,
bool reset = true,
bool periphBegin = true
)

Allocate RAM for image buffer, initialize peripherals and pins.

Parameters
vcs VCC selection. Pass SSD1306_SWITCHCAPVCC to generate the display voltage (step up) from the 3.3V source, or SSD1306_EXTERNALVCC otherwise. Most situations with Adafruit
SSD1306 breakouts will want SSD1306_SWITCHCAPVCC.
addr I2C address of corresponding SSD1306 display (or pass 0 to use default of 0x3C for 128x32 display, 0x3D for all others). SPI displays (hardware or software) do not use addresses, but this
argument is still required (pass 0 or any value really, it will simply be ignored). Default if unspecified is 0.
reset If true, and if the reset pin passed to the constructor is valid, a hard reset will be performed before initializing the display. If using multiple SSD1306 displays on the same bus, and if they all
share the same reset pin, you should only pass true on the first display being initialized, false on all others, else the already-initialized displays would be reset. Default if unspecified is true.
periphBegin If true, and if a hardware peripheral is being used (I2C or SPI, but not software SPI), call that peripheral's begin() function, else (false) it has already been done in one's sketch code. Cases
where false might be used include multiple displays or other devices sharing a common bus, or situations on some platforms where a nonstandard begin() function is available (e.g. a
TwoWire interface on non-default pins, as can be done on the ESP8266 and perhaps others).

Returns
true on successful allocation/init, false otherwise. Well-behaved code should check the return value before proceeding.

Note
MUST call this function before any drawing or updates!

◆ display()
void Adafruit_SSD1306::display ( void )

Push data currently in RAM to SSD1306 display.

Returns
None (void).

Note
Drawing operations are not visible until this function is called. Call after each graphics command, or after a whole set of graphics commands, as best needed by one's own application.

◆ clearDisplay()
void Adafruit_SSD1306::clearDisplay ( void )

Clear contents of display buffer (set all pixels to off).

Returns
None (void).

Note
Changes buffer contents only, no immediate effect on display. Follow up with a call to display(), or with other graphics commands as needed by one's own application.

◆ invertDisplay()
void Adafruit_SSD1306::invertDisplay ( bool i )

Enable or disable display invert mode (white-on-black vs black-on-white).

Parameters
i If true, switch to invert mode (black-on-white), else normal mode (white-on-black).

Returns
None (void).

Note
This has an immediate effect on the display, no need to call the display() function – buffer contents are not changed, rather a different pixel mode of the display hardware is used. When enabled, drawing
SSD1306_BLACK (value 0) pixels will actually draw white, SSD1306_WHITE (value 1) will draw black.

◆ dim()
void Adafruit_SSD1306::dim ( bool dim )

Dim the display.

Parameters
dim true to enable lower brightness mode, false for full brightness.

Returns
None (void).

Note
This has an immediate effect on the display, no need to call the display() function – buffer contents are not changed.

◆ drawPixel()
void Adafruit_SSD1306::drawPixel ( int16_t x,
int16_t y,
uint16_t color
)

Set/clear/invert a single pixel. This is also invoked by the Adafruit_GFX library in generating many higher-level graphics primitives.

Parameters
x Column of display – 0 at left to (screen width - 1) at right.
y Row of display – 0 at top to (screen height -1) at bottom.
color Pixel color, one of: SSD1306_BLACK, SSD1306_WHITE or SSD1306_INVERSE.

Returns
None (void).

Note
Changes buffer contents only, no immediate effect on display. Follow up with a call to display(), or with other graphics commands as needed by one's own application.

◆ drawFastHLine()
void Adafruit_SSD1306::drawFastHLine ( int16_t x,
int16_t y,
int16_t w,
uint16_t color
) virtual

Draw a horizontal line. This is also invoked by the Adafruit_GFX library in generating many higher-level graphics primitives.

Parameters
x Leftmost column – 0 at left to (screen width - 1) at right.
y Row of display – 0 at top to (screen height -1) at bottom.
w Width of line, in pixels.
color Line color, one of: SSD1306_BLACK, SSD1306_WHITE or SSD1306_INVERSE.

Returns
None (void).

Note
Changes buffer contents only, no immediate effect on display. Follow up with a call to display(), or with other graphics commands as needed by one's own application.

◆ drawFastVLine()
void Adafruit_SSD1306::drawFastVLine ( int16_t x,
int16_t y,
int16_t h,
uint16_t color
) virtual

Draw a vertical line. This is also invoked by the Adafruit_GFX library in generating many higher-level graphics primitives.

Parameters
x Column of display – 0 at left to (screen width -1) at right.
y Topmost row – 0 at top to (screen height - 1) at bottom.
h Height of line, in pixels.
color Line color, one of: SSD1306_BLACK, SSD1306_WHITE or SSD1306_INVERSE.

Returns
None (void).

Note
Changes buffer contents only, no immediate effect on display. Follow up with a call to display(), or with other graphics commands as needed by one's own application.

◆ startscrollright()
void Adafruit_SSD1306::startscrollright ( uint8_t start,
uint8_t stop
)

Activate a right-handed scroll for all or part of the display.

Parameters
start First row.
stop Last row.

Returns
None (void).

◆ startscrollleft()
void Adafruit_SSD1306::startscrollleft ( uint8_t start,
uint8_t stop
)

Activate a left-handed scroll for all or part of the display.

Parameters
start First row.
stop Last row.

Returns
None (void).

◆ startscrolldiagright()
void Adafruit_SSD1306::startscrolldiagright ( uint8_t start,
uint8_t stop
)

Activate a diagonal scroll for all or part of the display.

Parameters
start First row.
stop Last row.

Returns
None (void).

◆ startscrolldiagleft()
void Adafruit_SSD1306::startscrolldiagleft ( uint8_t start,
uint8_t stop
)

Activate alternate diagonal scroll for all or part of the display.

Parameters
start First row.
stop Last row.

Returns
None (void).

◆ stopscroll()
void Adafruit_SSD1306::stopscroll ( void )

Cease a previously-begun scrolling action.

Returns
None (void).

◆ ssd1306_command()
void Adafruit_SSD1306::ssd1306_command ( uint8_t c )

Issue a single low-level command directly to the SSD1306 display, bypassing the library.

Parameters
c Command to issue (0x00 to 0xFF, see datasheet).

Returns
None (void).

◆ getPixel()
bool Adafruit_SSD1306::getPixel ( int16_t x,
int16_t y
)

Return color of a single pixel in display buffer.

Parameters
x Column of display – 0 at left to (screen width - 1) at right.
y Row of display – 0 at top to (screen height -1) at bottom.

Returns
true if pixel is set (usually SSD1306_WHITE, unless display invert mode is enabled), false if clear (SSD1306_BLACK).

Note
Reads from buffer contents; may not reflect current contents of screen if display() has not been called.

◆ getBuffer()
uint8_t * Adafruit_SSD1306::getBuffer ( void )

Get base address of display buffer for direct reading or writing.

Returns
Pointer to an unsigned 8-bit array, column-major, columns padded to full byte boundary if needed.

◆ SPIwrite()
void Adafruit_SSD1306::SPIwrite ( uint8_t d ) inline protected

Write a single byte to the SPI port.

Parameters
d Data byte to be written.

Returns
void

Note
See HAVE_PORTREG which defines if the method uses a port or bit-bang method

◆ drawFastHLineInternal()
void Adafruit_SSD1306::drawFastHLineInternal ( int16_t x,
int16_t y,
int16_t w,
uint16_t color
) protected

Draw a horizontal line with a width and color. Used by public methods drawFastHLine,drawFastVLine.

Parameters
x Leftmost column – 0 at left to (screen width - 1) at right.
y Row of display – 0 at top to (screen height -1) at bottom.
w Width of line, in pixels.
color Line color, one of: SSD1306_BLACK, SSD1306_WHITE or SSD1306_INVERSE.

Returns
None (void).

Note
Changes buffer contents only, no immediate effect on display. Follow up with a call to display(), or with other graphics commands as needed by one's own application.

◆ drawFastVLineInternal()
void Adafruit_SSD1306::drawFastVLineInternal ( int16_t x,
int16_t __y,
int16_t __h,
uint16_t color
) protected

Draw a vertical line with a width and color. Used by public method drawFastHLine,drawFastVLine.

Parameters
x Leftmost column – 0 at left to (screen width - 1) at right.
__y Row of display – 0 at top to (screen height -1) at bottom.
__h height of the line in pixels
color Line color, one of: SSD1306_BLACK, SSD1306_WHITE or SSD1306_INVERSE.

Returns
None (void).

Note
Changes buffer contents only, no immediate effect on display. Follow up with a call to display(), or with other graphics commands as needed by one's own application.

◆ ssd1306_command1()
void Adafruit_SSD1306::ssd1306_command1 ( uint8_t c ) protected

Issue single command to SSD1306, using I2C or hard/soft SPI as needed. Because command calls are often grouped, SPI transaction and selection must be started/ended in calling function for efficiency. This
is a protected function, not exposed (see ssd1306_command() instead).

Parameters
c the command character to send to the display. Refer to ssd1306 data sheet for commands

Returns
None (void).

Note

◆ ssd1306_commandList()
void Adafruit_SSD1306::ssd1306_commandList ( const uint8_t * c,
uint8_t n
) protected

Issue list of commands to SSD1306, same rules as above re: transactions. This is a protected function, not exposed.

Parameters
c pointer to list of commands
n number of commands in the list

Returns
None (void).

Note

Member Data Documentation

◆ spi
SPIClass* Adafruit_SSD1306::spi protected

Initialized during construction when using SPI. See SPI.cpp, SPI.h

◆ wire
TwoWire* Adafruit_SSD1306::wire protected

Initialized during construction when using I2C. See Wire.cpp, Wire.h

◆ buffer
uint8_t* Adafruit_SSD1306::buffer protected

Buffer data used for display buffer. Allocated when begin method is called.

◆ mosiPin
int8_t Adafruit_SSD1306::mosiPin protected

(Master Out Slave In) set when using SPI set during construction.

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

Adafruit_SSD1306.h
Adafruit_SSD1306.cpp

Generated by 1.8.13