SSD1306 OLED Controller Low-level driver

This is a low level driver for the SSD1306 OLED controller through 4-wire SPI.

It provides basic functions for initializing and writing to the OLED controller. In addition to hardware control and use of the OLED controller internal functions.

Before writing data to the display call ssd1306_init() which will set up the physical interface and the OLED. A file named conf_ssd1306.h is needed to define which interface to use. For more information see the Interface selection section. In addition one also need to define the pins SSD1306_DC_PIN, SSD1306_CS_PIN and SSD1306_RES_PIN and the display SSD1306_CLOCK_SPEED.

Warning

This driver is not reentrant and can not be used in interrupt\ service routines without extra care.

An example conf_ssd1306.h file could look like

// interface selection
#define SSD1306_SPI           SERCOM2

#define SSD1306_CLOCK_SPEED          1000000

#define SSD1306_DC_PIN               PIN_PB24
#define SSD1306_CS_PIN               PIN_PB27
#define SSD1306_RES_PIN              PIN_PA17

Dependencies

This driver depends on the following modules:

• SAM Port (PORT) Driver for IO port control.
• SAM System (SYSTEM) Driver for getting system clock speeds for init functions.
• SAM Serial Peripheral Interface (SERCOM SPI) Driver for communication with the OLED controller
• SAM Serial Peripheral Interface (SERCOM SPI) Driver for communication with the OLED controller

Modules
	Related Project(s)
	In this section you can find all the projects related to the SSD1306 OLED Controller Low-level driver.

Variables
struct spi_module	ssd1306_master
struct spi_slave_inst	ssd1306_slave

Fundamental Command defines
#define	SSD1306_CMD_COL_ADD_SET_LSB(column)   (0x00 | (column))
#define	SSD1306_CMD_COL_ADD_SET_MSB(column)   (0x10 | (column))
#define	SSD1306_CMD_SET_MEMORY_ADDRESSING_MODE   0x20
#define	SSD1306_CMD_SET_COLUMN_ADDRESS   0x21
#define	SSD1306_CMD_SET_PAGE_ADDRESS   0x22
#define	SSD1306_CMD_SET_DISPLAY_START_LINE(line)   (0x40 | (line))
#define	SSD1306_CMD_SET_CONTRAST_CONTROL_FOR_BANK0   0x81
#define	SSD1306_CMD_SET_CHARGE_PUMP_SETTING   0x8D
#define	SSD1306_CMD_SET_SEGMENT_RE_MAP_COL0_SEG0   0xA0
#define	SSD1306_CMD_SET_SEGMENT_RE_MAP_COL127_SEG0   0xA1
#define	SSD1306_CMD_ENTIRE_DISPLAY_AND_GDDRAM_ON   0xA4
#define	SSD1306_CMD_ENTIRE_DISPLAY_ON   0xA5
#define	SSD1306_CMD_SET_NORMAL_DISPLAY   0xA6
#define	SSD1306_CMD_SET_INVERSE_DISPLAY   0xA7
#define	SSD1306_CMD_SET_MULTIPLEX_RATIO   0xA8
#define	SSD1306_CMD_SET_DISPLAY_ON   0xAF
#define	SSD1306_CMD_SET_DISPLAY_OFF   0xAE
#define	SSD1306_CMD_SET_PAGE_START_ADDRESS(page)   (0xB0 | (page))
#define	SSD1306_CMD_SET_COM_OUTPUT_SCAN_UP   0xC0
#define	SSD1306_CMD_SET_COM_OUTPUT_SCAN_DOWN   0xC8
#define	SSD1306_CMD_SET_DISPLAY_OFFSET   0xD3
#define	SSD1306_CMD_SET_DISPLAY_CLOCK_DIVIDE_RATIO   0xD5
#define	SSD1306_CMD_SET_PRE_CHARGE_PERIOD   0xD9
#define	SSD1306_CMD_SET_COM_PINS   0xDA
#define	SSD1306_CMD_SET_VCOMH_DESELECT_LEVEL   0xDB
#define	SSD1306_CMD_NOP   0xE3

Graphic Acceleration Command defines
#define	SSD1306_CMD_SCROLL_H_RIGHT   0x26
#define	SSD1306_CMD_SCROLL_H_LEFT   0x27
#define	SSD1306_CMD_CONTINUOUS_SCROLL_V_AND_H_RIGHT   0x29
#define	SSD1306_CMD_CONTINUOUS_SCROLL_V_AND_H_LEFT   0x2A
#define	SSD1306_CMD_DEACTIVATE_SCROLL   0x2E
#define	SSD1306_CMD_ACTIVATE_SCROLL   0x2F
#define	SSD1306_CMD_SET_VERTICAL_SCROLL_AREA   0xA3

OLED controller write and read functions
void	ssd1306_write_command (uint8_t command)
	Writes a command to the display controller. More...
void	ssd1306_write_data (uint8_t data)
	Write data to the display controller. More...
static uint8_t	ssd1306_read_data (void)
	Read data from the controller. More...
static uint8_t	ssd1306_get_status (void)
	Read status from the controller. More...

OLED Controller reset
static void	ssd1306_hard_reset (void)
	Perform a hard reset of the OLED controller. More...

Sleep control
static void	ssd1306_sleep_enable (void)
	Enable the OLED sleep mode. More...
static void	ssd1306_sleep_disable (void)
	Disable the OLED sleep mode. More...

Address setup for the OLED
static void	ssd1306_set_page_address (uint8_t address)
	Set current page in display RAM. More...
static void	ssd1306_set_column_address (uint8_t address)
	Set current column in display RAM. More...
static void	ssd1306_set_display_start_line_address (uint8_t address)
	Set the display start draw line address. More...

Display hardware control
static void	ssd1306_display_on (void)
	Turn the OLED display on. More...
static void	ssd1306_display_off (void)
	Turn the OLED display off. More...
static uint8_t	ssd1306_set_contrast (uint8_t contrast)
	Set the OLED contrast level. More...
static void	ssd1306_display_invert_enable (void)
	Invert all pixels on the device. More...
static void	ssd1306_display_invert_disable (void)
	Disable invert of all pixels on the device. More...

Initialization
void	ssd1306_init (void)
	Initialize the OLED controller. More...

#define SSD1306_CMD_ACTIVATE_SCROLL   0x2F

#define SSD1306_CMD_COL_ADD_SET_LSB

(

column

)

(0x00 | (column))

Referenced by ssd1306_set_column_address().

#define SSD1306_CMD_COL_ADD_SET_MSB

(

column

)

(0x10 | (column))

Referenced by ssd1306_set_column_address().

#define SSD1306_CMD_CONTINUOUS_SCROLL_V_AND_H_LEFT   0x2A

#define SSD1306_CMD_CONTINUOUS_SCROLL_V_AND_H_RIGHT   0x29

#define SSD1306_CMD_DEACTIVATE_SCROLL   0x2E

#define SSD1306_CMD_ENTIRE_DISPLAY_AND_GDDRAM_ON   0xA4

Referenced by ssd1306_init().

#define SSD1306_CMD_ENTIRE_DISPLAY_ON   0xA5

#define SSD1306_CMD_NOP   0xE3

#define SSD1306_CMD_SCROLL_H_LEFT   0x27

#define SSD1306_CMD_SCROLL_H_RIGHT   0x26

#define SSD1306_CMD_SET_CHARGE_PUMP_SETTING   0x8D

Referenced by ssd1306_init().

#define SSD1306_CMD_SET_COLUMN_ADDRESS   0x21

#define SSD1306_CMD_SET_COM_OUTPUT_SCAN_DOWN   0xC8

Referenced by ssd1306_init().

#define SSD1306_CMD_SET_COM_OUTPUT_SCAN_UP   0xC0

#define SSD1306_CMD_SET_COM_PINS   0xDA

Referenced by ssd1306_init().

#define SSD1306_CMD_SET_CONTRAST_CONTROL_FOR_BANK0   0x81

Referenced by ssd1306_set_contrast().

#define SSD1306_CMD_SET_DISPLAY_CLOCK_DIVIDE_RATIO   0xD5

Referenced by ssd1306_init().

#define SSD1306_CMD_SET_DISPLAY_OFF   0xAE

Referenced by ssd1306_display_off(), and ssd1306_sleep_enable().

#define SSD1306_CMD_SET_DISPLAY_OFFSET   0xD3

Referenced by ssd1306_init().

#define SSD1306_CMD_SET_DISPLAY_ON   0xAF

Referenced by ssd1306_display_on(), and ssd1306_sleep_disable().

#define SSD1306_CMD_SET_DISPLAY_START_LINE

(

line

)

(0x40 | (line))

Referenced by ssd1306_init(), and ssd1306_set_display_start_line_address().

#define SSD1306_CMD_SET_INVERSE_DISPLAY   0xA7

Referenced by ssd1306_display_invert_enable().

#define SSD1306_CMD_SET_MEMORY_ADDRESSING_MODE   0x20

#define SSD1306_CMD_SET_MULTIPLEX_RATIO   0xA8

Referenced by ssd1306_init().

#define SSD1306_CMD_SET_NORMAL_DISPLAY   0xA6

Referenced by ssd1306_display_invert_disable().

#define SSD1306_CMD_SET_PAGE_ADDRESS   0x22

#define SSD1306_CMD_SET_PAGE_START_ADDRESS

(

page

)

(0xB0 | (page))

Referenced by ssd1306_set_page_address().

#define SSD1306_CMD_SET_PRE_CHARGE_PERIOD   0xD9

Referenced by ssd1306_init().

#define SSD1306_CMD_SET_SEGMENT_RE_MAP_COL0_SEG0   0xA0

#define SSD1306_CMD_SET_SEGMENT_RE_MAP_COL127_SEG0   0xA1

Referenced by ssd1306_init().

#define SSD1306_CMD_SET_VCOMH_DESELECT_LEVEL   0xDB

Referenced by ssd1306_init().

#define SSD1306_CMD_SET_VERTICAL_SCROLL_AREA   0xA3

static void ssd1306_display_invert_disable ( void  )

inlinestatic

Disable invert of all pixels on the device.

This function will disable invert on all pixels on the OLED

References SSD1306_CMD_SET_NORMAL_DISPLAY, and ssd1306_write_command().

Referenced by ssd1306_init().

static void ssd1306_display_invert_enable ( void  )

inlinestatic

Invert all pixels on the device.

This function will invert all pixels on the OLED

References SSD1306_CMD_SET_INVERSE_DISPLAY, and ssd1306_write_command().

static void ssd1306_display_off ( void  )

inlinestatic

Turn the OLED display off.

This function will turn off the OLED.

References SSD1306_CMD_SET_DISPLAY_OFF, and ssd1306_write_command().

static void ssd1306_display_on ( void  )

inlinestatic

Turn the OLED display on.

This function will turn on the OLED.

References SSD1306_CMD_SET_DISPLAY_ON, and ssd1306_write_command().

Referenced by ssd1306_init().

static uint8_t ssd1306_get_status ( void  )

inlinestatic

Read status from the controller.

Note

The controller does not support read in serial mode.

Return values

8	bit status read from the controller

static void ssd1306_hard_reset ( void  )

inlinestatic

Perform a hard reset of the OLED controller.

This functions will reset the OLED controller by setting the reset pin low.

References delay_cycles, port_pin_set_output_level(), and system_gclk_gen_get_hz().

Referenced by ssd1306_init().

void ssd1306_init

(

void

)

Initialize the OLED controller.

Call this function to initialize the hardware interface and the OLED controller. When initialization is done the display is turned on and ready to receive data.

References delay_init(), port_pin_set_output_level(), SSD1306_CMD_ENTIRE_DISPLAY_AND_GDDRAM_ON, SSD1306_CMD_SET_CHARGE_PUMP_SETTING, SSD1306_CMD_SET_COM_OUTPUT_SCAN_DOWN, SSD1306_CMD_SET_COM_PINS, SSD1306_CMD_SET_DISPLAY_CLOCK_DIVIDE_RATIO, SSD1306_CMD_SET_DISPLAY_OFFSET, SSD1306_CMD_SET_DISPLAY_START_LINE, SSD1306_CMD_SET_MULTIPLEX_RATIO, SSD1306_CMD_SET_PRE_CHARGE_PERIOD, SSD1306_CMD_SET_SEGMENT_RE_MAP_COL127_SEG0, SSD1306_CMD_SET_VCOMH_DESELECT_LEVEL, ssd1306_display_invert_disable(), ssd1306_display_on(), ssd1306_hard_reset(), ssd1306_interface_init(), ssd1306_set_contrast(), and ssd1306_write_command().

Referenced by gfx_mono_ssd1306_init(), and main().

static uint8_t ssd1306_read_data ( void  )

inlinestatic

Read data from the controller.

Note

The controller does not support read in serial mode.

Return values

8	bit data read from the controller

Referenced by gfx_mono_ssd1306_get_byte(), and gfx_mono_ssd1306_get_page().

static void ssd1306_set_column_address ( uint8_t  address )

inlinestatic

Set current column in display RAM.

Parameters

address

the column address

References SSD1306_CMD_COL_ADD_SET_LSB, SSD1306_CMD_COL_ADD_SET_MSB, and ssd1306_write_command().

Referenced by gfx_mono_ssd1306_get_byte(), gfx_mono_ssd1306_get_page(), gfx_mono_ssd1306_put_byte(), gfx_mono_ssd1306_put_page(), and main().

static uint8_t ssd1306_set_contrast ( uint8_t  contrast )

inlinestatic

Set the OLED contrast level.

Parameters

contrast

a number between 0 and 0xFF

Return values

contrast

the contrast value written to the OLED controller

References SSD1306_CMD_SET_CONTRAST_CONTROL_FOR_BANK0, and ssd1306_write_command().

Referenced by ssd1306_init().

static void ssd1306_set_display_start_line_address ( uint8_t  address )

inlinestatic

Set the display start draw line address.

This function will set which line should be the start draw line for the OLED.

References SSD1306_CMD_SET_DISPLAY_START_LINE, and ssd1306_write_command().

Referenced by gfx_mono_ssd1306_init(), main(), and main_task().

static void ssd1306_set_page_address ( uint8_t  address )

inlinestatic

Set current page in display RAM.

This command is usually followed by the configuration of the column address because this scheme will provide access to all locations in the display RAM.

Parameters

address

the page address

References SSD1306_CMD_SET_PAGE_START_ADDRESS, and ssd1306_write_command().

Referenced by gfx_mono_ssd1306_get_byte(), gfx_mono_ssd1306_get_page(), gfx_mono_ssd1306_put_byte(), gfx_mono_ssd1306_put_page(), and main().

static void ssd1306_sleep_disable ( void  )

inlinestatic

Disable the OLED sleep mode.

References SSD1306_CMD_SET_DISPLAY_ON, and ssd1306_write_command().

static void ssd1306_sleep_enable ( void  )

inlinestatic

Enable the OLED sleep mode.

References SSD1306_CMD_SET_DISPLAY_OFF, and ssd1306_write_command().

void ssd1306_write_command

(

uint8_t

command

)

Writes a command to the display controller.

This functions pull pin D/C# low before writing to the controller. Different data write function is called based on the selected interface.

Parameters

command

the command to write

References port_pin_set_output_level(), spi_select_slave(), spi_write_buffer_wait(), ssd1306_master, and ssd1306_slave.

Referenced by ssd1306_display_invert_disable(), ssd1306_display_invert_enable(), ssd1306_display_off(), ssd1306_display_on(), ssd1306_init(), ssd1306_set_column_address(), ssd1306_set_contrast(), ssd1306_set_display_start_line_address(), ssd1306_set_page_address(), ssd1306_sleep_disable(), and ssd1306_sleep_enable().

void ssd1306_write_data

(

uint8_t

data

)

Write data to the display controller.

This functions sets the pin D/C# before writing to the controller. Different data write function is called based on the selected interface.

Parameters

data	the data to write

References port_pin_set_output_level(), spi_select_slave(), spi_write_buffer_wait(), ssd1306_master, and ssd1306_slave.

Referenced by gfx_mono_ssd1306_put_byte(), gfx_mono_ssd1306_put_page(), and main().

struct spi_module ssd1306_master

Referenced by ssd1306_interface_init(), ssd1306_write_command(), and ssd1306_write_data().

struct spi_slave_inst ssd1306_slave

Referenced by ssd1306_interface_init(), ssd1306_write_command(), and ssd1306_write_data().