SSD1306 OLED display driver 1.7.8 This library is developed to control SSD1306/SSD1331/SSD1351/IL9163/PCD8554 RGB i2c/spi LED displays

Classes | Macros | Functions
DIRECT DRAW: 1-bit graphic functions for ssd1306 compatible mode.

LCD direct draw functions for all display types: color and monochrome. More...

## Classes
struct | SAppMenu

## Macros
#define | ssd1306_drawCanvas(x, y, w, h, buf) ssd1306_drawBuffer(x, y, w, h, buf)

## Functions
void | ssd1306_setPos (uint8_t x, uint8_t y)
void | ssd1306_fillScreen (uint8_t fill_Data)
void | ssd1306_clearScreen (void)
void | ssd1306_negativeMode (void)
void | ssd1306_positiveMode (void)
uint8_t | ssd1306_printFixed (uint8_t xpos, uint8_t y, const char *ch, EFontStyle style)
uint8_t | ssd1306_printFixed2x (uint8_t xpos, uint8_t y, const char ch[], EFontStyle style) __attribute__((deprecated))
uint8_t | ssd1306_printFixedN (uint8_t xpos, uint8_t y, const char ch[], EFontStyle style, uint8_t factor)
size_t | ssd1306_write (uint8_t ch)
| Prints single character to display at current cursor position. More...
size_t | ssd1306_print (const char ch[])
| Prints null-terminated string to display at current cursor position. More...
uint8_t | ssd1306_charF6x8 (uint8_t x, uint8_t y, const char ch[], EFontStyle style=STYLE_NORMAL) __attribute__((deprecated))
uint8_t | ssd1306_charF12x16 (uint8_t xpos, uint8_t y, const char ch[], EFontStyle style) __attribute__((deprecated))
uint8_t | ssd1306_charF6x8_eol (uint8_t left, uint8_t y, const char ch[], EFontStyle style, uint8_t right) __attribute__((deprecated))
void | ssd1306_putPixel (uint8_t x, uint8_t y)
void | ssd1306_putPixels (uint8_t x, uint8_t y, uint8_t pixels)
void | ssd1306_drawRect (uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2)
void | ssd1306_drawLine (uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2)
void | ssd1306_drawHLine (uint8_t x1, uint8_t y1, uint8_t x2)
void | ssd1306_drawVLine (uint8_t x1, uint8_t y1, uint8_t y2)
void | ssd1306_drawBuffer (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *buf)
void | ssd1306_drawBufferFast (lcdint_t x, lcdint_t y, lcduint_t w, lcduint_t h, const uint8_t *buf)
void | ssd1306_drawBitmap (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *buf)
void | gfx_drawMonoBitmap (lcdint_t x, lcdint_t y, lcduint_t w, lcduint_t h, const uint8_t *buf)
void | ssd1306_clearBlock (uint8_t x, uint8_t y, uint8_t w, uint8_t h)
void | ssd1306_drawSpriteEx (uint8_t x, uint8_t y, uint8_t w, const uint8_t *sprite)
void | ssd1306_drawSprite (SPRITE *sprite)
void | ssd1306_eraseSprite (SPRITE *sprite)
void | ssd1306_eraseTrace (SPRITE *sprite)
SPRITE | ssd1306_createSprite (uint8_t x, uint8_t y, uint8_t w, const uint8_t *data)
void | ssd1306_replaceSprite (SPRITE *sprite, const uint8_t *data)
void | ssd1306_createMenu (SAppMenu *menu, const char **items, uint8_t count)
void | ssd1306_showMenu (SAppMenu *menu)
void | ssd1306_showMenu8 (SAppMenu *menu)
void | ssd1306_updateMenu (SAppMenu *menu)
void | ssd1306_updateMenu8 (SAppMenu *menu)
uint8_t | ssd1306_menuSelection (SAppMenu *menu)
void | ssd1306_menuDown (SAppMenu *menu)
void | ssd1306_menuUp (SAppMenu *menu)

## Detailed Description

LCD direct draw functions for all display types: color and monochrome.

LCD direct draw functions are applicable for all display types. These functions will work both for monochrome and 8-bit/16-bit color OLED displays. You need remember, that for RGB oled displays these functions work only in special ssd1306 compatible mode. If you're going to combine NanoEngine capabilities with these functions, don't forget to switch addressing mode via ssd1306_setMode(). Direct draw functions draw directly in GDRAM and do not use any double-buffering.

## Macro Definition Documentation

## ◆ ssd1306_drawCanvas

#define ssd1306_drawCanvas | ( |  | x,
|  |  | y,
|  |  | w,
|  |  | h,
|  |  | buf
| ) |  | ssd1306_drawBuffer(x, y, w, h, buf)

Draws bitmap, located in SRAM, on the display Each byte represents 8 vertical pixels.

// Draw small rectangle 3x8 at position 10,8
uint8_t buffer[3] = { 0xFF, 0x81, 0xFF };
ssd1306_drawBuffer(10, 1, 3, 8, buffer);

Parameters

  x | - horizontal position in pixels
  y | - vertical position in blocks (pixels/8)
  w | - width of bitmap in pixels
  h | - height of bitmap in pixels (must be divided by 8)
  buf | - pointer to data, located in SRAM: each byte represents 8 vertical pixels.

Definition at line 317 of file ssd1306_1bit.h.

## Function Documentation

## ◆ gfx_drawMonoBitmap()

void gfx_drawMonoBitmap | ( | lcdint_t | x,
|  | lcdint_t | y,
|  | lcduint_t | w,
|  | lcduint_t | h,
|  | const uint8_t * | buf
| ) |  |

Draws bitmap, located in Flash, on the display

Parameters

  x | - horizontal position in pixels
  y | - vertical position in pixels
  w | - width of bitmap in pixels
  h | - height of bitmap in pixels (must be divided by 8)
  buf | - pointer to data, located in Flash: each byte represents 8 vertical pixels.

Definition at line 690 of file ssd1306_1bit.c.

## ◆ ssd1306_charF12x16()

uint8_t ssd1306_charF12x16 | ( | uint8_t | xpos,
|  | uint8_t | y,
|  | const char | ch[],
|  | EFontStyle | style
| ) |  |

Prints text to screen using double size font 12x16.

Parameters

  xpos | - horizontal position in pixels
  y | - vertical position in blocks (pixels/8)
  ch | - NULL-terminated string to print
  style | - font style (EFontStyle).

Returns
  number of chars in string

Deprecated:
  Use ssd1306_drawFixedN() instead.

Definition at line 434 of file ssd1306_1bit.c.

## ◆ ssd1306_charF6x8()

uint8_t ssd1306_charF6x8 | ( | uint8_t | x,
|  | uint8_t | y,
|  | const char | ch[],
|  | EFontStyle | style = `STYLE_NORMAL`
| ) |  |

Prints text to screen using font 6x8.

Parameters

  x | - horizontal position in pixels
  y | - vertical position in blocks (pixels/8)
  ch | - NULL-terminated string to print
  style | - font style (EFontStyle), normal by default.

Returns
  number of chars in string

Deprecated:
  Use ssd1306_printFixed() instead.

Definition at line 388 of file ssd1306_1bit.c.

## ◆ ssd1306_charF6x8_eol()

uint8_t ssd1306_charF6x8_eol | ( | uint8_t | left,
|  | uint8_t | y,
|  | const char | ch[],
|  | EFontStyle | style,
|  | uint8_t | right
| ) |  |

Prints text to screen using set font. If real text ends before right boundary, the remaining part on the display will be erased till right boundary.

Parameters

  left | - horizontal position in pixels
  y | - vertical position in blocks (pixels/8)
  ch | - NULL-terminated string to print
  style | - font style (EFontStyle), normal by default.
  right | - right boundary of the text to output

Returns
  number of chars in string

Deprecated:
  This function is removed as superflouse.

Definition at line 509 of file ssd1306_1bit.c.

## ◆ ssd1306_clearBlock()

void ssd1306_clearBlock | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h
| ) |  |

Fills block with black pixels

Parameters

  x | - horizontal position in pixels
  y | - vertical position in blocks (pixels/8)
  w | - width of block in pixels
  h | - height of block in pixels (must be divided by 8)

Note
  usually this method is used to erase bitmap on the screen.

Definition at line 747 of file ssd1306_1bit.c.

## ◆ ssd1306_clearScreen()

void ssd1306_clearScreen | ( | void |  | ) |

Fills screen with zero-byte

Definition at line 64 of file ssd1306_1bit.c.

## ◆ ssd1306_createMenu()

void ssd1306_createMenu | ( | SAppMenu * | menu,
|  | const char ** | items,
|  | uint8_t | count
| ) |  |

Creates menu object with the provided list of menu items. List of menu items (strings) must exist all until menu object is no longer needed. Selection is set to the first item by default.

Parameters

  menu | - Pointer to SAppMenu structure
  items | - array of null-termintated strings (located in SRAM)
  count | - count of menu items in the array

Definition at line 41 of file ssd1306_menu.c.

## ◆ ssd1306_createSprite()

SPRITE ssd1306_createSprite | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | const uint8_t * | data
| ) |  |

Creates sprite object. Sprite height is fixed to 8 pixels

Parameters

  x | - horizontal position in pixels
  y | - vertical position in pixels
  w | - width of sprite in pixels
  data | - pointer to data, located in Flash: each byte represents 8 vertical pixels.

Returns
  SPRITE structure

Definition at line 860 of file ssd1306_1bit.c.

## ◆ ssd1306_drawBitmap()

void ssd1306_drawBitmap | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h,
|  | const uint8_t * | buf
| ) |  |

Draws bitmap, located in Flash, on the display

Parameters

  x | - horizontal position in pixels
  y | - vertical position in blocks (pixels/8)
  w | - width of bitmap in pixels
  h | - height of bitmap in pixels (must be divided by 8)
  buf | - pointer to data, located in Flash: each byte represents 8 vertical pixels.

Definition at line 672 of file ssd1306_1bit.c.

## ◆ ssd1306_drawBuffer()

void ssd1306_drawBuffer | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h,
|  | const uint8_t * | buf
| ) |  |

Draws bitmap, located in SRAM, on the display Each byte represents 8 vertical pixels.

// Draw small rectangle 3x8 at position 10,8
uint8_t buffer[3] = { 0xFF, 0x81, 0xFF };
ssd1306_drawBuffer(10, 1, 3, 8, buffer);

Parameters

  x | - horizontal position in pixels
  y | - vertical position in blocks (pixels/8)
  w | - width of bitmap in pixels
  h | - height of bitmap in pixels (must be divided by 8)
  buf | - pointer to data, located in SRAM: each byte represents 8 vertical pixels.

Definition at line 657 of file ssd1306_1bit.c.

## ◆ ssd1306_drawBufferFast()

void ssd1306_drawBufferFast | ( | lcdint_t | x,
|  | lcdint_t | y,
|  | lcduint_t | w,
|  | lcduint_t | h,
|  | const uint8_t * | buf
| ) |  |

Draws bitmap, located in SRAM, on the display Each byte represents 8 vertical pixels.

// Draw small rectangle 3x8 at position 10,8
uint8_t buffer[3] = { 0xFF, 0x81, 0xFF };
ssd1306_drawBuffer(10, 1, 3, 8, buffer);

Parameters

  x | - horizontal position in pixels
  y | - vertical position in pixels (must be devided by 8)
  w | - width of bitmap in pixels
  h | - height of bitmap in pixels (must be divided by 8)
  buf | - pointer to data, located in SRAM: each byte represents 8 vertical pixels.

Note
  ssd1306_drawBufferFast() doesn't support negative draw mode. Use ssd1306_drawBuffer() instead.

Definition at line 644 of file ssd1306_1bit.c.

## ◆ ssd1306_drawHLine()

void ssd1306_drawHLine | ( | uint8_t | x1,
|  | uint8_t | y1,
|  | uint8_t | x2
| ) |  |

Draws horizontal line

Parameters

  x1 | - left boundary in pixels
  y1 | - position Y in pixels
  x2 | - right boundary in pixels

Definition at line 602 of file ssd1306_1bit.c.

## ◆ ssd1306_drawLine()

void ssd1306_drawLine | ( | uint8_t | x1,
|  | uint8_t | y1,
|  | uint8_t | x2,
|  | uint8_t | y2
| ) |  |

Draws line

Parameters

  x1 | - x position in pixels of start point
  y1 | - y position in pixels of start point
  x2 | - x position in pixels of end point
  y2 | - y position in pixels of end point

Warning
  Remember that this function draws line directly in GDRAM of oled controller. Since there is no way to detect pixels already being displayed, some pixels can be overwritten by black color. If you use RGB oled, based on ssd1331 controller, use ssd1331_drawLine() function.

Definition at line 558 of file ssd1306_1bit.c.

## ◆ ssd1306_drawRect()

void ssd1306_drawRect | ( | uint8_t | x1,
|  | uint8_t | y1,
|  | uint8_t | x2,
|  | uint8_t | y2
| ) |  |

Draws rectangle

Parameters

  x1 | - left boundary in pixel units
  y1 | - top boundary in pixel units
  x2 | - right boundary in pixel units
  y2 | - bottom boundary int pixel units

Definition at line 636 of file ssd1306_1bit.c.

## ◆ ssd1306_drawSprite()

void ssd1306_drawSprite | ( | SPRITE * | sprite | ) |

Draws sprite on the display. Position can be changed by updating x and y fields of SPRITE structure.

Parameters

  sprite | - pointer to SPRITE structure

Definition at line 775 of file ssd1306_1bit.c.

## ◆ ssd1306_drawSpriteEx()

void ssd1306_drawSpriteEx | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | const uint8_t * | sprite
| ) |  |

Draws bitmap, located in Flash, on the display. This sprite must have wx8 size

Parameters

  x | - horizontal position in pixels
  y | - vertical position in blocks (pixels/8)
  w | - width in pixels
  sprite | - pointer to data, located in Flash: each byte represents 8 vertical pixels.

Definition at line 763 of file ssd1306_1bit.c.

## ◆ ssd1306_drawVLine()

void ssd1306_drawVLine | ( | uint8_t | x1,
|  | uint8_t | y1,
|  | uint8_t | y2
| ) |  |

Draws vertical line

Parameters

  x1 | - position X in pixels
  y1 | - top boundary in pixels
  y2 | - bottom boundary in pixels

Definition at line 612 of file ssd1306_1bit.c.

## ◆ ssd1306_eraseSprite()

void ssd1306_eraseSprite | ( | SPRITE * | sprite | ) |

Clears sprite from the display leaving black rectangle.

Parameters

  sprite | - pointer to SPRITE structure

Definition at line 801 of file ssd1306_1bit.c.

## ◆ ssd1306_eraseTrace()

void ssd1306_eraseTrace | ( | SPRITE * | sprite | ) |

Clears some sprite parts in old position on the display.

Parameters

  sprite | - pointer to SPRITE structure

Definition at line 823 of file ssd1306_1bit.c.

## ◆ ssd1306_fillScreen()

void ssd1306_fillScreen | ( | uint8_t | fill_Data | ) |

Fills screen with pattern byte

Definition at line 49 of file ssd1306_1bit.c.

## ◆ ssd1306_menuDown()

void ssd1306_menuDown | ( | SAppMenu * | menu | ) |

Moves selection pointer down by 1 item. If there are no items below, it will set selection pointer to the first item. Use ssd1306_updateMenu() to refresh menu state on the display.

Parameters

  menu | - Pointer to SAppMenu structure

Definition at line 156 of file ssd1306_menu.c.

## ◆ ssd1306_menuSelection()

uint8_t ssd1306_menuSelection | ( | SAppMenu * | menu | ) |

Returns currently selected menu item. First item has zero-index.

Parameters

  menu | - Pointer to SAppMenu structure

Warning
  works only in 8-bit RGB normal mode.

Definition at line 151 of file ssd1306_menu.c.

## ◆ ssd1306_menuUp()

void ssd1306_menuUp | ( | SAppMenu * | menu | ) |

Moves selection pointer up by 1 item. If selected item is the first one, then selection pointer will set to the last item in menu list. Use ssd1306_updateMenu() to refresh menu state on the display.

Parameters

  menu | - Pointer to SAppMenu structure

Definition at line 168 of file ssd1306_menu.c.

## ◆ ssd1306_negativeMode()

void ssd1306_negativeMode | ( | void |  | ) |

All drawing functions start to work in negative mode. Old picture on the display remains unchanged.

Definition at line 870 of file ssd1306_1bit.c.

## ◆ ssd1306_positiveMode()

void ssd1306_positiveMode | ( | void |  | ) |

All drawing functions start to work in positive (default) mode. Old picture on the display remains unchanged.

Definition at line 875 of file ssd1306_1bit.c.

## ◆ ssd1306_print()

size_t ssd1306_print | ( | const char | ch[] | ) |

Prints null-terminated string to display at current cursor position.

Prints null-terminated string to display at current cursor position

Parameters

  ch | - string to print to the display. 'LF' and 'CR' are skipped

Returns
  returns number of printed characters.

Definition at line 377 of file ssd1306_1bit.c.

## ◆ ssd1306_printFixed()

uint8_t ssd1306_printFixed | ( | uint8_t | xpos,
|  | uint8_t | y,
|  | const char * | ch,
|  | EFontStyle | style
| ) |  |

Prints text to screen using fixed font.

Parameters

  xpos | - horizontal position in pixels
  y | - vertical position in pixels
  ch | - NULL-terminated string to print
  style | - font style (EFontStyle), normal by default.

Returns
  number of chars in string

See also
  ssd1306_setFixedFont

Warning
  ssd1306_printFixed() can output chars at fixed y positions: 0, 8, 16, 24, 32, etc. If you specify [10,18], ssd1306_printFixed() will output text starting at [10,16] position.
  Be careful with you flash space! Do not mix too many different functions in single sketch. ssd1306_printFixedN() uses much flash: ~396 bytes, ssd1306_printFixed() needs 388 bytes. Placing both of these functions to your sketch will consume almost 1KiB.

Definition at line 78 of file ssd1306_1bit.c.

## ◆ ssd1306_printFixed2x()

uint8_t ssd1306_printFixed2x | ( | uint8_t | xpos,
|  | uint8_t | y,
|  | const char | ch[],
|  | EFontStyle | style
| ) |  |

Prints text to screen using double size fixed font.

Parameters

  xpos | - horizontal position in pixels
  y | - vertical position in pixels
  ch | - NULL-terminated string to print
  style | - font style (EFontStyle), normal by default.

Returns
  number of chars in string

See also
  ssd1306_setFixedFont

Warning
  ssd1306_printFixed2x() can output chars at fixed y positions: 0, 8, 16, 24, 32, etc. If you specify [10,18], ssd1306_printFixed2x() will output text starting at [10,16] position.
  Be careful with you flash space! Do not mix too many different functions in single sketch. ssd1306_printFixedN() uses much flash: ~474 bytes, ssd1306_printFixed() needs 388 bytes. Placing both of these functions to your sketch will consume almost 1KiB.

Deprecated:
  Use ssd1306_printFixedN() instead.

Definition at line 161 of file ssd1306_1bit.c.

## ◆ ssd1306_printFixedN()

uint8_t ssd1306_printFixedN | ( | uint8_t | xpos,
|  | uint8_t | y,
|  | const char | ch[],
|  | EFontStyle | style,
|  | uint8_t | factor
| ) |  |

Prints text to screen using size fixed font, scaled by factor value.
Factor value 0 gives regular font size (6x8 for example)
Factor value 1 gives double font size (12x16 if 6x8 font is used)
Factor value 2 gives fourth font size (24x32 if 6x8 font is used)
Factor value 3 gives eighth font size (48x64 if 6x8 font is used)

Parameters

  xpos | - horizontal position in pixels
  y | - vertical position in pixels
  ch | - NULL-terminated string to print
  style | - font style (EFontStyle), normal by default.
  factor | - 0, 1, 2, 3.

Returns
  number of chars in string

See also
  ssd1306_setFixedFont

Warning
  ssd1306_printFixed2x() can output chars at fixed y positions: 0, 8, 16, 24, 32, etc. If you specify [10,18], ssd1306_printFixed2x() will output text starting at [10,16] position.
  Be careful with you flash space! Do not mix too many different functions in single sketch. ssd1306_printFixedN() uses much flash: ~474 bytes, ssd1306_printFixed() needs 388 bytes. Placing both of these functions to your sketch will consume almost 1KiB.

Definition at line 242 of file ssd1306_1bit.c.

## ◆ ssd1306_putPixel()

void ssd1306_putPixel | ( | uint8_t | x,
|  | uint8_t | y
| ) |  |

Put single pixel on the LCD.

Warning
  Please, take into account that there is no way to read data from ssd1306, thus since each byte contains 8 pixels, all other pixels in the same byte will be cleared on the display. Use ssd1306_putPixels() instead. If you need to have buffered output, please, refer to NanoCanvas.

Parameters

  x | - horizontal position in pixels
  y | - vertical position in pixels

Definition at line 524 of file ssd1306_1bit.c.

## ◆ ssd1306_putPixels()

void ssd1306_putPixels | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | pixels
| ) |  |

Puts eight vertical pixels on the LCD at once.

// Draw 8 vertical pixels, starting at [10,16] position
ssd1306_putPixels(10,2,0xFF);
// Draw 4 vertical pixels, starting at [32,28] position
ssd1306_putPixels(32,3,0x0F);

Parameters

  x | - horizontal position in pixels
  y | - vertical position pixels. Should be multiply of 8.
  pixels | - bit-pixels to draw on display

Definition at line 531 of file ssd1306_1bit.c.

## ◆ ssd1306_replaceSprite()

void ssd1306_replaceSprite | ( | SPRITE * | sprite,
|  | const uint8_t * | data
| ) |  |

Replaces image of the sprite with different data. The width must be the same as the width of original sprite image

Parameters

  sprite | - pointer to SPRITE structure
  data | - pointer to data, located in Flash: each byte represents 8 vertical pixels.

Definition at line 865 of file ssd1306_1bit.c.

## ◆ ssd1306_setPos()

void ssd1306_setPos | ( | uint8_t | x,
|  | uint8_t | y
| ) |  |

Set position in terms of display.

Parameters

  x | - horizontal position in pixels
  y | - vertical position in blocks (pixels/8)

## ◆ ssd1306_showMenu()

void ssd1306_showMenu | ( | SAppMenu * | menu | ) |

Shows menu items on the display. If menu items cannot fit the display, the function provides scrolling.

Parameters

  menu | - Pointer to SAppMenu structure

Warning
  works only in SSD1306 compatible mode.

Definition at line 91 of file ssd1306_menu.c.

## ◆ ssd1306_showMenu8()

void ssd1306_showMenu8 | ( | SAppMenu * | menu | ) |

Shows menu items on the display. If menu items cannot fit the display, the function provides scrolling.

Parameters

  menu | - Pointer to SAppMenu structure

Warning
  works only in 8-bit RGB normal mode.

Definition at line 102 of file ssd1306_menu.c.

## ◆ ssd1306_updateMenu()

void ssd1306_updateMenu | ( | SAppMenu * | menu | ) |

Updates menu items on the display. That is if selection is changed, the function will update only those areas, affected by the change.

Parameters

  menu | - Pointer to SAppMenu structure

Definition at line 113 of file ssd1306_menu.c.

## ◆ ssd1306_updateMenu8()

void ssd1306_updateMenu8 | ( | SAppMenu * | menu | ) |

Updates menu items on the display. That is if selection is changed, the function will update only those areas, affected by the change.

Parameters

  menu | - Pointer to SAppMenu structure

Warning
  works only in SSD1306 compatible mode.

Definition at line 132 of file ssd1306_menu.c.

## ◆ ssd1306_write()

size_t ssd1306_write | ( | uint8_t | ch | ) |

Prints single character to display at current cursor position.

Prints single character to display at current cursor position

Parameters

  ch | - character to print to the display. 'LF' and 'CR' are skipped

Returns
  returns number of printed characters.

Definition at line 343 of file ssd1306_1bit.c.