SSD1306Device Class Reference

Driver for SSD1306-family OLED displays over bit-banged I2C. More...

#include <ssd1306xled.h>

Public Member Functions
	SSD1306Device (void)
void	ssd1306_init (void)
	Initialize the display and clear the screen.
void	ssd1306_tiny_init (void)
	Initialize the display without clearing the screen.
void	ssd1306_tiny_init_vertical (void)
	Initialize the display in vertical addressing mode.
void	ssd1306_send_data_start (void)
	Begin an I2C data transmission.
void	ssd1306_send_data_stop (void)
	End an I2C data transmission.
void	ssd1306_send_byte (uint8_t byte)
	Send one raw byte over I2C.
void	ssd1306_send_command_start (void)
	Begin an I2C command transmission.
void	ssd1306_send_command_stop (void)
	End an I2C command transmission.
void	ssd1306_send_command (uint8_t command)
	Send a single command byte (start + byte + stop).
void	ssd1306_setpos (uint8_t x, uint8_t y)
	Move the write cursor to a given position.
void	ssd1306_fillscreen (uint8_t fill)
	Fill the entire screen with a byte pattern.
void	ssd1306_set_contrast (uint8_t value)
	Set the display contrast (brightness).
void	ssd1306_display_off (void)
	Turn the display off (sleep mode).
void	ssd1306_display_on (void)
	Turn the display on (wake from sleep).
void	ssd1306_draw_bmp_px (uint8_t x, uint8_t y_px, uint8_t w, uint8_t h_pages, const uint8_t bitmap[])
	Draw a bitmap at a pixel-level Y position.
void	ssd1306_clear_area_px (uint8_t x, uint8_t y_px, uint8_t w, uint8_t h_pages)
	Clear the area a pixel-positioned sprite occupies.
void	ssd1306_draw_bmp_px_clipped (int16_t x, uint8_t y_px, uint8_t w, uint8_t h_pages, const uint8_t bitmap[])
	Draw a bitmap with signed X coordinate and automatic clipping.
void	ssd1306_clear_area_px_clipped (int16_t x, uint8_t y_px, uint8_t w, uint8_t h_pages)
	Clear a sprite area with signed X clipping.
void	ssd1306_compose_bmp_px (uint8_t *buf, uint8_t buf_x, uint8_t buf_w, int16_t sprite_x, uint8_t sprite_y_px, uint8_t sprite_w, uint8_t sprite_h_pages, const uint8_t bitmap[], uint8_t target_page)
	Composite one sprite into a page buffer using OR.
void	ssd1306_send_buf (uint8_t x, uint8_t page, const uint8_t *buf, uint8_t w)
	Send a pre-composited buffer to the display.

Detailed Description

Driver for SSD1306-family OLED displays over bit-banged I2C.

Talks to the display through the ATtiny85 USI peripheral. All drawing goes straight to the display – there is no framebuffer in RAM (the ATtiny85 only has 512 bytes). The display's 128x64 pixels are organized as 8 pages of 128 bytes each. Each byte controls 8 vertical pixels (LSB = top).

A global instance SSD1306 is created automatically. Use that instead of making your own.

Constructor & Destructor Documentation

SSD1306Device()

SSD1306Device::SSD1306Device

(

void

)

Member Function Documentation

ssd1306_clear_area_px()

void SSD1306Device::ssd1306_clear_area_px	(	uint8_t	x,
		uint8_t	y_px,
		uint8_t	w,
		uint8_t	h_pages
	)

Clear the area a pixel-positioned sprite occupies.

Writes zeros to every page the sprite would touch at the given y_px. Call this before redrawing a sprite at a new position to avoid ghost pixels from the old position.

Parameters

x	Column (0-127). Values >= 128 are a no-op.
y_px	Y position in pixels (0-63).
w	Width in columns.
h_pages	Height in pages.

See also

ssd1306_draw_bmp_px()

ssd1306_clear_area_px_clipped()

void SSD1306Device::ssd1306_clear_area_px_clipped	(	int16_t	x,
		uint8_t	y_px,
		uint8_t	w,
		uint8_t	h_pages
	)

Clear a sprite area with signed X clipping.

Same as ssd1306_clear_area_px() but with signed X and automatic clipping. Pair with ssd1306_draw_bmp_px_clipped().

Parameters

x	Column (can be negative).
y_px	Y position in pixels (0-63).
w	Width in columns.
h_pages	Height in pages.

ssd1306_compose_bmp_px()

void SSD1306Device::ssd1306_compose_bmp_px	(	uint8_t *	buf,
		uint8_t	buf_x,
		uint8_t	buf_w,
		int16_t	sprite_x,
		uint8_t	sprite_y_px,
		uint8_t	sprite_w,
		uint8_t	sprite_h_pages,
		const uint8_t	bitmap[],
		uint8_t	target_page
	)

Composite one sprite into a page buffer using OR.

When two sprites share a display page, drawing one normally erases the other (the SSD1306 has no read-back over I2C). Instead, composite both sprites into a buffer, then send the buffer once with ssd1306_send_buf().

Typical workflow:

uint8_t buf[16];
memset(buf, 0, 16);  // zero before each frame
SSD1306.ssd1306_compose_bmp_px(buf, 20, 16, 20, 20, 8, 1, sprA, 3);
SSD1306.ssd1306_compose_bmp_px(buf, 20, 16, 20, 28, 8, 1, sprB, 3);
SSD1306.ssd1306_send_buf(20, 3, buf, 16);

Parameters

buf	Caller-allocated buffer. Must be zeroed before compositing each frame.
buf_x	Buffer's starting column on screen.
buf_w	Buffer width in columns.
sprite_x	Sprite X position (signed, for off-screen sprites).
sprite_y_px	Sprite Y position in pixels.
sprite_w	Sprite width in columns.
sprite_h_pages	Sprite height in pages.
bitmap	Sprite pixel data in PROGMEM.
target_page	Which display page (0-7) to composite into.

See also

ssd1306_send_buf()

ssd1306_display_off()

void SSD1306Device::ssd1306_display_off

(

void

)

Turn the display off (sleep mode).

Puts the SSD1306 into sleep. Current draw drops to ~1 uA. Display RAM contents are preserved. Call ssd1306_display_on() to wake up.

ssd1306_display_on()

void SSD1306Device::ssd1306_display_on

(

void

)

Turn the display on (wake from sleep).

Resumes display output from RAM. Pair with ssd1306_display_off().

ssd1306_draw_bmp_px()

void SSD1306Device::ssd1306_draw_bmp_px	(	uint8_t	x,
		uint8_t	y_px,
		uint8_t	w,
		uint8_t	h_pages,
		const uint8_t	bitmap[]
	)

Draw a bitmap at a pixel-level Y position.

Unlike ssd1306_draw_bmp(), the Y coordinate is in pixels (0-63) rather than pages. The bitmap data is bit-shifted across page boundaries during transmission, so no RAM buffer is needed.

X values >= 128 are ignored. If the bitmap extends past column 127, the extra columns are clipped.

Warning

Overwrites all 8 vertical pixels in each affected page strip. Other content sharing those pages will be erased. The SSD1306 I2C interface does not support read-modify-write.

Parameters

x	Column (0-127). Values >= 128 are a no-op.
y_px	Y position in pixels (0-63).
w	Bitmap width in columns.
h_pages	Bitmap height in pages (1 page = 8 pixels).
bitmap	Byte array stored in PROGMEM.

See also

ssd1306_clear_area_px(), ssd1306_draw_bmp_px_clipped()

ssd1306_draw_bmp_px_clipped()

void SSD1306Device::ssd1306_draw_bmp_px_clipped	(	int16_t	x,
		uint8_t	y_px,
		uint8_t	w,
		uint8_t	h_pages,
		const uint8_t	bitmap[]
	)

Draw a bitmap with signed X coordinate and automatic clipping.

Same as ssd1306_draw_bmp_px() but X is a signed int16_t. Columns that fall outside 0-127 (left or right) are clipped. Use this when a sprite needs to slide smoothly on or off the screen edges.

Parameters

x	Column (can be negative).
y_px	Y position in pixels (0-63).
w	Full bitmap width in columns.
h_pages	Bitmap height in pages.
bitmap	Byte array stored in PROGMEM.

See also

ssd1306_clear_area_px_clipped()

ssd1306_fillscreen()

void SSD1306Device::ssd1306_fillscreen

(

uint8_t

fill

)

Fill the entire screen with a byte pattern.

Writes 1024 bytes (128 columns x 8 pages). Pass 0x00 to clear the screen, 0xFF to turn every pixel on, or any other pattern.

Parameters

fill	The byte pattern to repeat across the display.

ssd1306_init()

void SSD1306Device::ssd1306_init

(

void

)

Initialize the display and clear the screen.

Sends the full init sequence (clock, multiplex, charge pump, addressing mode, etc.) then fills every pixel with zero. Takes about 20 I2C command bytes (26 total) plus 1024 data bytes.

ssd1306_send_buf()

void SSD1306Device::ssd1306_send_buf	(	uint8_t	x,
		uint8_t	page,
		const uint8_t *	buf,
		uint8_t	w
	)

Send a pre-composited buffer to the display.

Writes the buffer contents to the display at the given column and page. Pair with ssd1306_compose_bmp_px().

Parameters

x	Starting column (0-127). Values >= 128 are a no-op.
page	Display page (0-7).
buf	Pointer to the composited byte buffer.
w	Buffer width in columns.

ssd1306_send_byte()

void SSD1306Device::ssd1306_send_byte

(

uint8_t

byte

)

Send one raw byte over I2C.

Must be called between a start/stop pair (either data or command). No framing is added – just the byte itself.

Parameters

byte	The byte to send.

ssd1306_send_command()

void SSD1306Device::ssd1306_send_command

(

uint8_t

command

)

Send a single command byte (start + byte + stop).

Convenience wrapper when you only need to send one command.

Parameters

command

The SSD1306 command byte.

ssd1306_send_command_start()

void SSD1306Device::ssd1306_send_command_start

(

void

)

Begin an I2C command transmission.

Sends the I2C start condition and the 0x00 control byte. After this, each byte sent with ssd1306_send_byte() is interpreted as a command by the display controller.

See also

ssd1306_send_command_stop(), ssd1306_send_command()

ssd1306_send_command_stop()

void SSD1306Device::ssd1306_send_command_stop

(

void

)

End an I2C command transmission.

See also

ssd1306_send_command_start()

ssd1306_send_data_start()

void SSD1306Device::ssd1306_send_data_start

(

void

)

Begin an I2C data transmission.

Sends the I2C start condition and the 0x40 control byte. After this, each byte sent with ssd1306_send_byte() goes into display RAM at the current cursor position.

See also

ssd1306_send_data_stop(), ssd1306_send_byte()

ssd1306_send_data_stop()

void SSD1306Device::ssd1306_send_data_stop

(

void

)

End an I2C data transmission.

See also

ssd1306_send_data_start()

ssd1306_set_contrast()

void SSD1306Device::ssd1306_set_contrast

(

uint8_t

value

)

Set the display contrast (brightness).

Controls the segment output current. Higher values draw more current and produce a brighter image. The init sequence sets this to 0x3F.

Measured current draw on a typical 128x64 module with all pixels on:

• 0x00: ~8-10 mA
• 0xFF: ~20-25 mA

Parameters

value

Contrast level (0x00 = dimmest, 0xFF = brightest).

ssd1306_setpos()

void SSD1306Device::ssd1306_setpos	(	uint8_t	x,
		uint8_t	y
	)

Move the write cursor to a given position.

Parameters

x	Column (0-127).
y	Page (0-7). Each page is 8 pixels tall.

ssd1306_tiny_init()

void SSD1306Device::ssd1306_tiny_init

(

void

)

Initialize the display without clearing the screen.

Same as ssd1306_init() but skips the fillscreen(0) call. Use this when you plan to draw immediately and do not care about leftover content from a previous power cycle. Saves ~52 bytes of flash and some startup time.

ssd1306_tiny_init_vertical()

void SSD1306Device::ssd1306_tiny_init_vertical

(

void

)

Initialize the display in vertical addressing mode.

After this, bytes auto-increment down pages within a column rather than across columns within a page. Only the low-level data/command functions work in this mode – the font and bitmap functions assume horizontal addressing.

---

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

• ssd1306xled.h
• ssd1306xled.cpp