Skip to content

Functions Manual

Jump to bottom
Microesque edited this page Dec 20, 2024 · 3 revisions

The Example: sections on this page are intended as a continuation of the Setup Guide page; as such, setup code is not included here.

Character drawing functions also assume that a font has already been set up for the display. For more information on how to set up a guide, refer to Font Guide.

Overview

Initialization Functions

ssd1306_init()

Prototype:

void ssd1306_init(struct ssd1306_display *display,
                  uint8_t i2c_address,
                  enum ssd1306_display_type display_type,
                  uint8_t *array,
                  void (*i2c_write)(uint8_t *data, uint16_t length));

Description:

  • Initializes the ssd1306_display structure as well as the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • i2c_address: 7-bit I2C address of the display.
  • display_type: Display type (128x32 or 128x64). Use the ssd1306_display_type enum provided in the header file.
  • array: Pointer to the array that will serve as the buffer for the display. Use the macros provided in the header file to declare an array of the appropriate size based on the display type.
  • i2c_write: Pointer to the callback function that writes a stream of data to the I2C bus. For proper setup, refer to Setup Guide.

Notes:

  • If this function has already been called at least once and you need to re-initialize the display, use ssd1306_reinit() instead.
  • The display will reset to default configurations. These configurations are defined as macros in the ssd1306.h file under the Library Setup section.

Example:

ssd1306_reinit()

Prototype:

void ssd1306_reinit(struct ssd1306_display *display);

Description:

  • Re-initializes the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.

Notes:

  • Equivalent to calling ssd1306_init(), but does not re-initialize the structure. Do NOT use this function unless ssd1306_init() has already been called at least once with the given ssd1306_display structure.
  • The display will reset to default configurations. These configurations are defined as macros in the ssd1306.h file under the Library Setup section.

Example:

Display Functions

ssd1306_display_update()

Prototype:

void ssd1306_display_update(struct ssd1306_display *display);

Description:

  • Updates the display with the current internal buffer contents.

Parameters:

  • display: Pointer to the ssd1306_display structure.

Notes:

Example:

/* Update the display with the internal buffer contents */
ssd1306_display_update(&display);

ssd1306_display_brightness()

Prototype:

void ssd1306_display_brightness(struct ssd1306_display *display,
                                uint8_t brightness);

Description:

  • Sets the brightness level of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • brightness: Brightness level [0-255].

Example:

/* Set brightness to maximum */
ssd1306_display_brightness(&display, 255);

ssd1306_display_enable()

Prototype:

void ssd1306_display_enable(struct ssd1306_display *display,
                            bool is_enabled);

Description:

  • Enables or disables the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • is_enabled: true to enable; false to disable.

Notes:

  • When enabled, the display works as normal. When disabled, the screen remains black, regardless of the display contents (the contents are not lost).

Example:

/* Display off */
ssd1306_display_enable(&display, false);

ssd1306_display_fully_on()

Prototype:

void ssd1306_display_fully_on(struct ssd1306_display *display,
                              bool is_enabled);

Description:

  • Enables or disables the fully-on feature of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • is_enabled: true to enable; false to disable.

Notes:

  • When enabled, all pixels of the display are turned on, regardless of the display contents (the contents are not lost).

Example:

/* All pixels on */
ssd1306_display_fully_on(&display, true);

ssd1306_display_inverse()

Prototype:

void ssd1306_display_inverse(struct ssd1306_display *display,
                             bool is_enabled);

Description:

  • Enables or disables the inverse feature of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • is_enabled: true to enable; false to disable.

Notes:

  • When enabled, the display contents are inverted, meaning pixels that are on will appear off, and vice versa.

Example:

/* Invert display contents */
ssd1306_display_inverse(&display, true);

ssd1306_display_mirror_h()

Prototype:

void ssd1306_display_mirror_h(struct ssd1306_display *display,
                              bool is_enabled);

Description:

  • Enables or disables the horizontal mirror feature of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • is_enabled: true to enable; false to disable.

Notes:

  • When enabled, the display contents are shown horizontally mirrored.

Example:

/* Horizontally mirror the display */
ssd1306_display_mirror_h(&display, true);

ssd1306_display_mirror_v()

Prototype:

void ssd1306_display_mirror_v(struct ssd1306_display *display,
                              bool is_enabled);

Description:

  • Enables or disables the vertical mirror feature of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • is_enabled: true to enable; false to disable.

Notes:

  • When enabled, the display contents are shown vertically mirrored.

Example:

/* Vertically mirror the display */
ssd1306_display_mirror_v(&display, true);

ssd1306_display_scroll_enable()

Prototype:

void ssd1306_display_scroll_enable(struct ssd1306_display *display,
                                   bool is_left,
                                   bool is_diagonal,
                                   uint8_t interval);

Description:

  • Starts a continuous horizontal or diagonal scroll.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • is_left: true to scroll left; false to scroll right.
  • is_diagonal: true to scroll diagonally; false to scroll horizontally.
  • interval: Interval between each scroll. Values higher than 7 will loop down the list:
    • 0 -> 5 frames
    • 1 -> 64 frames
    • 2 -> 128 frames
    • 3 -> 256 frames
    • 4 -> 3 frames
    • 5 -> 4 frames
    • 6 -> 25 frames
    • 7 -> 2 frames

Notes:

  • Limitations of the driver chip:
    • The display will be updated, and any subsequent updates will cause the contents of the display to be corrupted. To prevent corruption, call ssd1306_display_scroll_disable() before updating.
    • Vertical scrolling is not supported.
    • Diagonal scrolling will not work on 128x64 displays.
    • The vertical aspect of the diagonal scroll will always be upwards.

Example:

/* Start a right scroll (scroll every 25 frames) */
ssd1306_display_scroll_enable(&display, false, false, 6);

ssd1306_display_scroll_disable()

Prototype:

void ssd1306_display_scroll_disable(struct ssd1306_display *display);

Description:

  • Stops an ongoing scroll.

Parameters:

  • display: Pointer to the ssd1306_display structure.

Notes:

  • The display will be updated (limitation of the driver chip).
  • To start a scroll, call ssd1306_display_scroll_enable().

Example:

/* Stop the ongoing scroll */
ssd1306_display_scroll_disable(&display);

Draw Functions

ssd1306_draw_clear()

Prototype:

void ssd1306_draw_clear(struct ssd1306_display *display);

Description:

  • Clears the entire buffer (all pixels off).

Parameters:

  • display: Pointer to the ssd1306_display structure.

Notes:

  • Ignores buffer mode (draw/clear).
  • Ignores draw border.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Clear the the display */
ssd1306_draw_clear(&display);
ssd1306_display_update(&display);

ssd1306_draw_fill()

Prototype:

void ssd1306_draw_fill(struct ssd1306_display *display);

Description:

  • Fills the entire buffer (all pixels on).

Parameters:

  • display: Pointer to the ssd1306_display structure.

Notes:

  • Ignores buffer mode (draw/clear).
  • Ignores draw border.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Fill the display */
ssd1306_draw_fill(&display);
ssd1306_display_update(&display);

ssd1306_draw_invert()

Prototype:

void ssd1306_draw_invert(struct ssd1306_display *display);

Description:

  • Inverts the entire buffer (all pixels flipped).

Parameters:

  • display: Pointer to the ssd1306_display structure.

Notes:

  • Ignores buffer mode (draw/clear).
  • Ignores draw border.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Invert the display contents */
ssd1306_draw_invert(&display);
ssd1306_display_update(&display);

ssd1306_draw_mirror_h()

Prototype:

void ssd1306_draw_mirror_h(struct ssd1306_display *display);

Description:

  • Horizontally mirrors the entire buffer.

Parameters:

  • display: Pointer to the ssd1306_display structure.

Notes:

  • Ignores buffer mode (draw/clear).
  • Ignores draw border.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Horizontally mirror the display contents */
ssd1306_draw_mirror_h(&display);
ssd1306_display_update(&display);

ssd1306_draw_mirror_v()

Prototype:

void ssd1306_draw_mirror_v(struct ssd1306_display *display);

Description:

  • Vertically mirrors the entire buffer.

Parameters:

  • display: Pointer to the ssd1306_display structure.

Notes:

  • Ignores buffer mode (draw/clear).
  • Ignores draw border.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Vertically mirror the display contents */
ssd1306_draw_mirror_v(&display);
ssd1306_display_update(&display);

ssd1306_draw_shift_right()

Prototype:

void ssd1306_draw_shift_right(struct ssd1306_display *display,
                              bool is_rotated);

Description:

  • Shifts the buffer contents to the right by one pixel.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • is_rotated: true to enable rotation; false to just shift. When rotation is enabled, pixels that shift off-screen reappear on the opposite side. When rotation is disabled, pixels that shift off-screen are clipped, and the value for new pixels entering the screen is determined by the buffer mode.

Notes:

  • Ignores draw border.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Rotate the display contents to the right by 20 pixels */
for (uint8_t i = 0; i < 20; i++) {
    ssd1306_draw_shift_right(&display, true);
}
ssd1306_display_update(&display);

ssd1306_draw_shift_left()

Prototype:

void ssd1306_draw_shift_left(struct ssd1306_display *display,
                             bool is_rotated);

Description:

  • Shifts the buffer contents to the left by one pixel.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • is_rotated: true to enable rotation; false to just shift. When rotation is enabled, pixels that shift off-screen reappear on the opposite side. When rotation is disabled, pixels that shift off-screen are clipped, and the value for new pixels entering the screen is determined by the buffer mode.

Notes:

  • Ignores draw border.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Rotate the display contents to the left by 20 pixels */
for (uint8_t i = 0; i < 20; i++) {
    ssd1306_draw_shift_left(&display, true);
}
ssd1306_display_update(&display);

ssd1306_draw_shift_up()

Prototype:

void ssd1306_draw_shift_up(struct ssd1306_display *display,
                           bool is_rotated);

Description:

  • Shifts the buffer contents upward by one pixel.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • is_rotated: true to enable rotation; false to just shift. When rotation is enabled, pixels that shift off-screen reappear on the opposite side. When rotation is disabled, pixels that shift off-screen are clipped, and the value for new pixels entering the screen is determined by the buffer mode.

Notes:

  • Ignores draw border.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Rotate the display contents upward by 20 pixels */
for (uint8_t i = 0; i < 20; i++) {
    ssd1306_draw_shift_up(&display, true);
}
ssd1306_display_update(&display);

ssd1306_draw_shift_down()

Prototype:

void ssd1306_draw_shift_down(struct ssd1306_display *display,
                             bool is_rotated);

Description:

  • Shifts the buffer contents downward by one pixel.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • is_rotated: true to enable rotation; false to just shift. When rotation is enabled, pixels that shift off-screen reappear on the opposite side. When rotation is disabled, pixels that shift off-screen are clipped, and the value for new pixels entering the screen is determined by the buffer mode.

Notes:

  • Ignores draw border.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Rotate the display contents downward by 20 pixels */
for (uint8_t i = 0; i < 20; i++) {
    ssd1306_draw_shift_down(&display, true);
}
ssd1306_display_update(&display);

ssd1306_draw_pixel()

Prototype:

void ssd1306_draw_pixel(struct ssd1306_display *display,
                        int16_t x,
                        int16_t y);

Description:

  • Draws a pixel at the specified point.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x: x-coordinate of the point.
  • y: y-coordinate of the point.

Notes:

  • Clears the pixel instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw a pixel at (10, 10) */
ssd1306_draw_pixel(&display, 10, 10);
ssd1306_display_update(&display);

ssd1306_draw_line_h()

Prototype:

void ssd1306_draw_line_h(struct ssd1306_display *display,
                         int16_t x0,
                         int16_t y0,
                         int16_t width);

Description:

  • Draws a horizontal line starting from the specified coordinates and extending to the specified length.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the starting point.
  • y0: y-coordinate of the starting point.
  • width: Width of the line. A positive value extends the line to the right, while a negative value extends it to the left.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* 
 * Draw a horizontal line starting at (10, 10) and extending to the right with a
 * width of 20
 */
ssd1306_draw_line_h(&display, 10, 10, 20);
ssd1306_display_update(&display);

ssd1306_draw_line_v()

Prototype:

void ssd1306_draw_line_v(struct ssd1306_display *display,
                         int16_t x0,
                         int16_t y0,
                         int16_t height)

Description:

  • Draws a vertical line starting from the specified coordinates and extending to the specified length.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the starting point.
  • y0: y-coordinate of the starting point.
  • height: Height of the line. A positive value extends the line downward, while a negative value extends it upward.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* 
 * Draw a vertical line starting at (10, 10) and extending downward with a
 * height of 20
 */
ssd1306_draw_line_v(&display, 10, 10, 20);
ssd1306_display_update(&display);

ssd1306_draw_line()

Prototype:

void ssd1306_draw_line(struct ssd1306_display *display,
                       int16_t x0,
                       int16_t y0,
                       int16_t x1,
                       int16_t y1);

Description:

  • Draws a line connecting the two specified points.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the first point.
  • y0: y-coordinate of the first point.
  • x1: x-coordinate of the second point.
  • y1: y-coordinate of the second point.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw a line from (10, 10) to (100, 50) */
ssd1306_draw_line(&display, 10, 10, 100, 50);
ssd1306_display_update(&display);

ssd1306_draw_triangle()

Prototype:

void ssd1306_draw_triangle(struct ssd1306_display *display,
                           int16_t x0,
                           int16_t y0,
                           int16_t x1,
                           int16_t y1,
                           int16_t x2,
                           int16_t y2);

Description:

  • Draws a triangle connecting the three specified points.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the first point.
  • y0: y-coordinate of the first point.
  • x1: x-coordinate of the second point.
  • y1: y-coordinate of the second point.
  • x2: x-coordinate of the third point.
  • y2: y-coordinate of the third point.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw a triangle between (10, 10), (50, 50), and (100, 20) */
ssd1306_draw_triangle(&display, 10, 10, 50, 50, 100, 20);
ssd1306_display_update(&display);

ssd1306_draw_triangle_fill()

Prototype:

void ssd1306_draw_triangle_fill(struct ssd1306_display *display,
                                int16_t x0,
                                int16_t y0,
                                int16_t x1,
                                int16_t y1,
                                int16_t x2,
                                int16_t y2);

Description:

  • Draws a filled triangle connecting the three specified points.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the first point.
  • y0: y-coordinate of the first point.
  • x1: x-coordinate of the second point.
  • y1: y-coordinate of the second point.
  • x2: x-coordinate of the third point.
  • y2: y-coordinate of the third point.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw a filled triangle between (10, 10), (50, 50), and (100, 20) */
ssd1306_draw_triangle_fill(&display, 10, 10, 50, 50, 100, 20);
ssd1306_display_update(&display);

ssd1306_draw_rect()

Prototype:

void ssd1306_draw_rect(struct ssd1306_display *display,
                       int16_t x0,
                       int16_t y0,
                       int16_t width,
                       int16_t height);

Description:

  • Draws a rectangle starting from the specified coordinates and extending to the specified lengths.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the starting point.
  • y0: y-coordinate of the starting point.
  • width: Width of the rectangle. A positive value extends the rectangle to the right, while a negative value extends it to the left.
  • height: Height of the rectangle. A positive value extends the rectangle downward, while a negative value extends it upward.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* 
 * Draw a rectangle that:
 *     - starts at (10, 10) and extends to the right and downward
 *     - has a width of 100
 *     - has a height of 50
 */
ssd1306_draw_rect(&display, 10, 10, 100, 50);
ssd1306_display_update(&display);

ssd1306_draw_rect_fill()

Prototype:

void ssd1306_draw_rect_fill(struct ssd1306_display *display,
                       int16_t x0,
                       int16_t y0,
                       int16_t width,
                       int16_t height);

Description:

  • Draws a filled rectangle starting from the specified coordinates and extending to the specified lengths.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the starting point.
  • y0: y-coordinate of the starting point.
  • width: Width of the rectangle. A positive value extends the rectangle to the right, while a negative value extends it to the left.
  • height: Height of the rectangle. A positive value extends the rectangle downward, while a negative value extends it upward.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* 
 * Draw a filled rectangle that:
 *     - starts at (10, 10) and extends to the right and downward
 *     - has a width of 100
 *     - has a height of 50
 */
ssd1306_draw_rect(&display, 10, 10, 100, 50);
ssd1306_display_update(&display);

ssd1306_draw_rect_round()

Prototype:

void ssd1306_draw_rect_round(struct ssd1306_display *display,
                             int16_t x0,
                             int16_t y0,
                             int16_t width,
                             int16_t height,
                             int16_t r);

Description:

  • Draws a rectangle with round corners starting from the specified coordinates and extending to the specified lengths.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the starting point.
  • y0: y-coordinate of the starting point.
  • width: Width of the rectangle. A positive value extends the rectangle to the right, while a negative value extends it to the left.
  • height: Height of the rectangle. A positive value extends the rectangle downward, while a negative value extends it upward.
  • r: Radius of the corner arcs. If the given radius is too large, it will be limited to the maximum value possible. Passing zero or a negative value will result in a normal rectangle.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* 
 * Draw a round rectangle that:
 *     - starts at (10, 10) and extends to the right and downward
 *     - has a width of 100
 *     - has a height of 50
 *     - has a corner radius of 9
 */
ssd1306_draw_rect_round(&display, 10, 10, 100, 50, 9);
ssd1306_display_update(&display);

ssd1306_draw_rect_round_fill()

Prototype:

void ssd1306_draw_rect_round_fill(struct ssd1306_display *display,
                                  int16_t x0,
                                  int16_t y0,
                                  int16_t width,
                                  int16_t height,
                                  int16_t r);

Description:

  • Draws a filled rectangle with round corners starting from the specified coordinates and extending to the specified lengths.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the starting point.
  • y0: y-coordinate of the starting point.
  • width: Width of the rectangle. A positive value extends the rectangle to the right, while a negative value extends it to the left.
  • height: Height of the rectangle. A positive value extends the rectangle downward, while a negative value extends it upward.
  • r: Radius of the corner arcs. If the given radius is too large, it will be limited to the maximum value possible. Passing zero or a negative value will result in a normal rectangle.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* 
 * Draw a filled round rectangle that:
 *     - starts at (10, 10) and extends to the right and downward
 *     - has a width of 100
 *     - has a height of 50
 *     - has a corner radius of 9
 */
ssd1306_draw_rect_round(&display, 10, 10, 100, 50, 9);
ssd1306_display_update(&display);

ssd1306_draw_arc()

Prototype:

void ssd1306_draw_arc(struct ssd1306_display *display,
                      int16_t x0,
                      int16_t y0,
                      int16_t r,
                      uint8_t quadrants);

Description:

  • Draws quadrant arcs with the specified radius, centered at the specified coordinates.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the arc center.
  • y0: y-coordinate of the arc center.
  • r: Radius of the arc. Negative values are ignored.
  • quadrants: A 4-bit value where each bit represents a quadrant. Only the right most 4-bits are checked. The most significant bit (MSB) represents quadrant 4, while the least significant bit (LSB) represents quadrant 1. Set the corresponding bits to enable drawing for those quadrants. For example, 0b0101 enables drawing for quadrants 3 and 1.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/*
 * Draw the quadrants 1 and 3 of a circle centered at (64, 16) with a radius
 * of 10
 */
ssd1306_draw_arc(&display, 64, 16, 10, 0b0101);
ssd1306_display_update(&display);

ssd1306_draw_arc_fill()

Prototype:

void ssd1306_draw_arc_fill(struct ssd1306_display *display,
                           int16_t x0,
                           int16_t y0,
                           int16_t r,
                           uint8_t quadrants);

Description:

  • Draws filled quadrant arcs with the specified radius, centered at the specified coordinates.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the arc center.
  • y0: y-coordinate of the arc center.
  • r: Radius of the arc. Negative values are ignored.
  • quadrants: A 4-bit value where each bit represents a quadrant. Only the right most 4-bits are checked. The most significant bit (MSB) represents quadrant 4, while the least significant bit (LSB) represents quadrant 1. Set the corresponding bits to enable drawing for those quadrants. For example, 0b0101 enables drawing for quadrants 3 and 1.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/*
 * Draw the quadrants 1 and 3 of a filled circle centered at (64, 16) with a
 * radius of 10
 */
ssd1306_draw_arc_fill(&display, 64, 16, 10, 0b0101);
ssd1306_display_update(&display);

ssd1306_draw_circle()

Prototype:

void ssd1306_draw_circle(struct ssd1306_display *display,
                         int16_t x0,
                         int16_t y0,
                         int16_t r);

Description:

  • Draws a circle with the specified radius, centered at the specified coordinates.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the circle center.
  • y0: y-coordinate of the circle center.
  • r: Radius of the circle. Negative values are ignored.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw a circle centered at (64, 16) with a radius of 10 */
ssd1306_draw_circle(&display, 64, 16, 10);
ssd1306_display_update(&display);

ssd1306_draw_circle_fill()

Prototype:

void ssd1306_draw_circle_fill(struct ssd1306_display *display,
                              int16_t x0,
                              int16_t y0,
                              int16_t r);

Description:

  • Draws a circle with the specified radius, centered at the specified coordinates.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the circle center.
  • y0: y-coordinate of the circle center.
  • r: Radius of the circle. Negative values are ignored.

Notes:

  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw a filled circle centered at (64, 16) with a radius of 10 */
ssd1306_draw_circle_fill(&display, 64, 16, 10);
ssd1306_display_update(&display);

ssd1306_draw_bitmap()

Prototype:

void ssd1306_draw_bitmap(struct ssd1306_display *display,
                         int16_t x0,
                         int16_t y0,
                         const uint8_t *bitmap,
                         uint16_t width,
                         uint16_t height,
                         bool has_bg);

Description:

  • Draws a bitmap image starting from the specified coordinates and extending to the right and downward.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x0: x-coordinate of the top left pixel of the image.
  • y0: y-coordinate of the top left pixel of the image.
  • bitmap: Pointer to the bitmap array.
  • width: Width of the image in pixels. The value MUST match the bitmap width, or the drawing may get corrupted and random parts of the memory may be accessed. For example, for an image with a resolution of 60x40, the width value should be 60.
  • height: Height of the image in pixels. The value MUST match the bitmap height, or the drawing may get corrupted and random parts of the memory may be accessed. For example, for an image with a resolution of 60x40, the height value should be 40.
  • has_bg: true to overwrite the contents in the background; false to draw transparent.

Notes:

  • XBM is the only supported bitmap format. To convert your images to .xbm, you can use free tools like GIMP or an online converter (search for "Image to XBM converter"). For an in-depth guide, refer to Images Guide.
  • Draws the inverse of the image if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

ssd1306_draw_char()

Prototype:

void ssd1306_draw_char(struct ssd1306_display *display,
                       char c);

Description:

  • Draws a character at the current cursor location.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • c: Character to be drawn.

Notes:

  • Invalid characters are drawn as empty squares. These include characters not supported by the current font, or all characters if no font has been set up. A font can be set up with the ssd1306_set_font() function. For an in-depth guide, refer to Font Guide.
  • Cursor location can be set with the ssd1306_set_cursor() function. Cursor is automatically advanced after a character print.
  • Characters can be magnified with the ssd1306_set_font_scale() function.
  • The only supported non-printable characters are \r and \n.
  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw "HEY" at the current cursor location */
ssd1306_draw_char(&display, 'H');
ssd1306_draw_char(&display, 'E');
ssd1306_draw_char(&display, 'Y');
ssd1306_display_update(&display);

ssd1306_draw_char_custom()

Prototype:

void ssd1306_draw_char_custom(struct ssd1306_display *display,
                              const struct ssd1306_custom_char *c);

Description:

  • Draws a custom character at the current cursor location.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • c: Character to be drawn.

Notes:

  • The ssd1306_custom_char structure is used to represent custom characters. For an in-depth guide for creating custom characters, refer to Custom Characters Guide.
  • Cursor location can be set with the ssd1306_set_cursor() function. Cursor is automatically advanced after a character print.
  • Characters can be magnified with the ssd1306_set_font_scale() function.
  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

ssd1306_draw_str()

Prototype:

void ssd1306_draw_str(struct ssd1306_display *display,
                      const char *str);

Description:

  • Draws a string at the current cursor location.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • str: String to be drawn. MUST be null terminated!

Notes:

  • Invalid characters are drawn as empty squares. These include characters not supported by the current font, or all characters if no font has been set up. A font can be set up with the ssd1306_set_font() function. For an in-depth guide, refer to Font Guide.
  • Cursor location can be set with the ssd1306_set_cursor() function. Cursor is automatically advanced after a character print.
  • Characters can be magnified with the ssd1306_set_font_scale() function.
  • The only supported non-printable characters are \r and \n.
  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw "Hello!" at the current cursor location */
ssd1306_draw_str(&display, "Hello!");
ssd1306_display_update(&display);

ssd1306_draw_int32()

Prototype:

void ssd1306_draw_int32(struct ssd1306_display *display,
                        int32_t num);

Description:

  • Draws a 32-bit variable at the current cursor location.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • num: 32-bit variable to be drawn.

Notes:

  • Meant to be a lower memory alternative for ssd1306_draw_printf().
  • Characters will be drawn as empty squares if no font has been set up. A font can be set up with the ssd1306_set_font() function. For an in-depth guide, refer to Font Guide.
  • Cursor location can be set with the ssd1306_set_cursor() function. Cursor is automatically advanced after a character print.
  • Characters can be magnified with the ssd1306_set_font_scale() function.
  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw the 32-bit variable at the current cursor location */
uint32_t var = 189634;
ssd1306_draw_int32(&display, var);
ssd1306_display_update(&display);

ssd1306_draw_float()

Prototype:

void ssd1306_draw_float(struct ssd1306_display *display,
                        float num,
                        uint8_t digits);

Description:

  • Draws a float point number at the current cursor location.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • num: Float point number to be drawn.
  • digits: Number of digits after the decimal point to be drawn.

Notes:

  • Meant to be a lower memory alternative for ssd1306_draw_printf().
  • Characters will be drawn as empty squares if no font has been set up. A font can be set up with the ssd1306_set_font() function. For an in-depth guide, refer to Font Guide.
  • Cursor location can be set with the ssd1306_set_cursor() function. Cursor is automatically advanced after a character print.
  • Characters can be magnified with the ssd1306_set_font_scale() function.
  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw the float variable at the current cursor location */
float var = 3.14159f;
ssd1306_draw_float(&display, var, 5);
ssd1306_display_update(&display);

ssd1306_draw_printf()

Prototype:

void ssd1306_draw_printf(struct ssd1306_display *display,
                         const char *format,
                         ...);

Description:

  • Draws a formatted string at the current cursor location.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • format: Format string.
  • ...: Arguments for the format string.

Notes:

  • There's an adjustable maximum character limit. The SD1306_PRINTF_CHAR_LIMIT macro in the header file defines the maximum number of characters that can be printed at once (the lower the limit, the lower the memory requirement).
  • For lower memory alternatives, consider using ssd1306_draw_str(), ssd1306_draw_int32(), and ssd1306_draw_float() instead.
  • Invalid characters are drawn as empty squares. These include characters not supported by the current font, or all characters if no font has been set up. A font can be set up with the ssd1306_set_font() function. For an in-depth guide, refer to Font Guide.
  • Cursor location can be set with the ssd1306_set_cursor() function. Cursor is automatically advanced after a character print.
  • Characters can be magnified with the ssd1306_set_font_scale() function.
  • The only supported non-printable characters are \r and \n.
  • Clears the pixels instead if the buffer is in clear mode.
  • Drawing outside the border is allowed, but pixels that are out of bounds will be clipped.
  • Draw functions don't update the display. Don't forget to call the ssd1306_display_update() to push the buffer onto the display.

Example:

/* Draw the temperature and humidity levels */
int temp = 22;
int hum = 45;
ssd1306_draw_printf(&display, "Temp:%d, Hum:%d%%", temp, hum);
ssd1306_display_update(&display);

Getter/Setter Functions

ssd1306_set_draw_border()

Prototype:

void ssd1306_set_draw_border(struct ssd1306_display *display,
                             uint8_t x_min,
                             uint8_t y_min,
                             uint8_t x_max,
                             uint8_t y_max);

Description:

  • Sets the draw border of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x_min: Minimum x-coordinate before clipping.
  • y_min: Minimum y-coordinate before clipping.
  • x_max: Maximum x-coordinate before clipping.
  • y_max: Maximum y-coordinate before clipping.

Notes:

  • Any subsequent attempts to draw pixels outside of the specified coordinate ranges will be ignored. For an in-depth explanation, refer to Getting Started.

Example:

ssd1306_set_draw_border_reset()

Prototype:

void ssd1306_set_draw_border_reset(struct ssd1306_display *display);

Description:

  • Sets the draw border to display edges (full screen cover).

Parameters:

  • display: Pointer to the ssd1306_display structure.

Notes:

Example:

ssd1306_set_buffer_mode()

Prototype:

void ssd1306_set_buffer_mode(struct ssd1306_display *display,
                             enum ssd1306_buffer_mode mode);

Description:

  • Sets the buffer mode of the display (draw/clear).

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • mode: Buffer mode to be set.

Notes:

  • In draw mode, all Draw Functions turn the pixels on as expected. In clear mode, these same functions clear the pixels instead. For an in-depth explanation, refer to Getting Started.

Example:

ssd1306_set_buffer_mode_inverse()

Prototype:

void ssd1306_set_buffer_mode_inverse(struct ssd1306_display *display);

Description:

  • Inverts the buffer mode of the display (draw->clear | clear->draw).

Parameters:

  • display: Pointer to the ssd1306_display structure.

Notes:

  • In draw mode, all Draw Functions turn the pixels on as expected. In clear mode, these same functions clear the pixels instead. For an in-depth explanation, refer to Getting Started.

Example:

ssd1306_set_font()

Prototype:

void ssd1306_set_font(struct ssd1306_display *display,
                      const struct ssd1306_font *font);

Description:

  • Sets the font of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • font: Font to be assigned to the display. Pass NULL for no font.

Notes:

  • The specified font will be used for the subsequent character drawings. For an in-depth guide on setting up fonts, refer to Font Guide.

Example:

ssd1306_set_font_scale()

Prototype:

void ssd1306_set_font_scale(struct ssd1306_display *display,
                            uint8_t scale);

Description:

  • Sets the character scaling factor of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • scale: The scaling factor.

Notes:

  • The specified scaling factor will be used for the subsequent character drawings. For an in-depth explanation, refer to Font Guide.
  • The scaling is linear (new_size = original_size x scale).

Example:

ssd1306_set_cursor()

Prototype:

void ssd1306_set_cursor(struct ssd1306_display *display,
                        int16_t x,
                        int16_t y);

Description:

  • Sets the cursor to the specified coordinates on the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x: x-coordinate for the cursor.
  • y: y-coordinate for the cursor.

Notes:

  • The cursor typically represents the bottom-left corner of the next character to be drawn. Note that this isn't exact, as the characters can define offsets in any direction. For an in-depth explanation, refer to Font Guide.

Example:

ssd1306_get_display_address()

Prototype:

uint8_t ssd1306_get_display_address(struct ssd1306_display *display);

Description:

  • Returns the assigned 7-bit I2C address of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.

Returns:

  • The assigned 7-bit I2C address of the display.

Notes:

  • If ssd1306_init() hasn't been called for the specified structure at least once, the return value will be undefined.

Example:

/* Some code... */

ssd1306_init(&display,
             0x3C,
             SSD1306_DISPLAY_TYPE_64,
             display_array,
             i2c_write);

/* Some code... */

uint8_t address;
address = ssd1306_get_display_address(&display);

/* address = 0x3C */

ssd1306_get_display_type()

Prototype:

enum ssd1306_display_type
ssd1306_get_display_type(struct ssd1306_display *display);

Description:

  • Returns the assigned display type of the display (128x32 or 128x64).

Parameters:

  • display: Pointer to the ssd1306_display structure.

Returns:

  • The assigned display type of the display (128x32 or 128x64).

Notes:

  • If ssd1306_init() hasn't been called for the specified structure at least once, the return value will be undefined.

Example:

/* Some code... */

ssd1306_init(&display,
             0x3C,
             SSD1306_DISPLAY_TYPE_64,
             display_array,
             i2c_write);

/* Some code... */

enum ssd1306_display_type type;
type = ssd1306_get_display_type(&display);

/* type = SSD1306_DISPLAY_TYPE_64 */

ssd1306_get_draw_border()

Prototype:

void ssd1306_get_draw_border(struct ssd1306_display *display,
                             uint8_t *x_min,
                             uint8_t *y_min,
                             uint8_t *x_max,
                             uint8_t *y_max);

Description:

  • Returns the current draw border of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x_min: Pointer where the minimum x-coordinate before clipping will be placed.
  • y_min: Pointer where the minimum y-coordinate before clipping will be placed.
  • x_max: Pointer where the maximum x-coordinate before clipping will be placed.
  • y_max: Pointer where the maximum y-coordinate before clipping will be placed.

Notes:

  • The drawable border can be set with the ssd1306_set_draw_border() function.
  • If ssd1306_init() hasn't been called for the specified structure at least once, the return values will be undefined.

Example:

ssd1306_set_draw_border(&display, 20, 10, 100, 50);

/* Some code... */

uint8_t x_min;
uint8_t y_min;
uint8_t x_max;
uint8_t y_max;
ssd1306_get_draw_border(&display, &x_min, &y_min, &x_max, &y_max);

/* 
 * x_min = 20
 * y_min = 10
 * x_max = 100
 * y_max = 50
 */

ssd1306_get_buffer_mode()

Prototype:

enum ssd1306_buffer_mode
ssd1306_get_buffer_mode(struct ssd1306_display *display);

Description:

  • Returns the current buffer mode of the display (draw/clear).

Parameters:

  • display: Pointer to the ssd1306_display structure.

Returns:

  • The current buffer mode of the display (draw/clear).

Notes:

  • The buffer mode can be set with the ssd1306_set_buffer_mode() function.
  • If ssd1306_init() hasn't been called for the specified structure at least once, the return value will be undefined.

Example:

ssd1306_set_buffer_mode(&display, SSD1306_BUFFER_MODE_CLEAR);

/* Some code... */

enum ssd1306_buffer_mode mode;
mode = ssd1306_get_draw_border(&display);

/* mode = SSD1306_BUFFER_MODE_CLEAR */

ssd1306_get_font()

Prototype:

const struct ssd1306_font *ssd1306_get_font(struct ssd1306_display *display);

Description:

  • Returns the current font assigned to the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.

Returns:

  • The current font assigned to the display; NULL if no font is assigned.

Notes:

  • Fonts can be assigned with the ssd1306_set_font() function.
  • If ssd1306_init() hasn't been called for the specified structure at least once, the return value will be undefined.

Example:

ssd1306_set_font(&display, &FreeMonoBold9pt7b);

/* Some code... */

const struct ssd1306_font *font;
font = ssd1306_get_font(&display);

/* font = &FreeMonoBold9pt7b */

ssd1306_get_font_scale()

Prototype:

uint8_t ssd1306_get_font_scale(struct ssd1306_display *display);

Description:

  • Returns the current font scale of the display.

Parameters:

  • display: Pointer to the ssd1306_display structure.

Returns:

  • The current font scale of the display.

Notes:

  • The font scale can be set with the ssd1306_set_font_scale() function.
  • If ssd1306_init() hasn't been called for the specified structure at least once, the return value will be undefined.

Example:

ssd1306_set_font_scale(&display, 2);

/* Some code... */

uint8_t scale;
scale = ssd1306_get_font_scale(&display);

/* scale = 2 */

ssd1306_get_cursor()

Prototype:

int16_t ssd1306_get_cursor(struct ssd1306_display *display,
                           int16_t *x,
                           int16_t *y);

Description:

  • Returns the coordinates of the current cursor location.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x: Pointer where the current x-coordinate will be placed.
  • y: Pointer where the current y-coordinate will be placed.

Returns:

  • The x-coordinate where the cursor would move after a carriage return.

Notes:

  • The cursor location can be set with the ssd1306_set_cursor() function.
  • If ssd1306_init() hasn't been called for the specified structure at least once, the return values will be undefined.

Example:

ssd1306_set_cursor(&display, 10, 15);

/* Code that advances the cursor by 20 to the right... */

int16_t x0;
int16_t x;
int16_t y;
x0 = ssd1306_get_cursor(&display, &x, &y);

/* 
 * x0 = 10
 * x = 30
 * y = 15
 */

sd1306_get_buffer()

Prototype:

uint8_t *sd1306_get_buffer(struct ssd1306_display *display);

Description:

  • Returns a pointer to the assigned display buffer.

Parameters:

  • display: Pointer to the ssd1306_display structure.

Returns:

  • Pointer to the assigned display buffer.

Notes:

  • If ssd1306_init() hasn't been called for the specified structure at least once, the return value will be undefined.

Example:

/* Some code... */

ssd1306_init(&display,
             0x3C,
             SSD1306_DISPLAY_TYPE_64,
             display_array,
             i2c_write);

/* Some code... */

uint8_t* buffer;
buffer = sd1306_get_buffer(&display);

/* buffer = display_array */

ssd1306_get_buffer_pixel()

Prototype:

uint8_t ssd1306_get_buffer_pixel(struct ssd1306_display *display,
                                 int16_t x,
                                 int16_t y);

Description:

  • Returns the pixel value of the specified point.

Parameters:

  • display: Pointer to the ssd1306_display structure.
  • x: x-coordinate of the pixel.
  • y: y-coordinate of the pixel.

Returns:

  • The value of the specified pixel (0 or 1). Coordinates that are outside of the draw border will automatically return 0.

Notes:

  • The pixel value is from the internal buffer, not the display.

Example:

/* Clear everything, then draw a pixel at (10, 20) */
ssd1306_draw_clear(&display);
ssd1306_draw_pixel(&display, 10, 20);

/* Some code... */

uint8_t pixel1;
uint8_t pixel2;
pixel1 = ssd1306_get_buffer_pixel(&display, 10, 20);
pixel2 = ssd1306_get_buffer_pixel(&display, 10, 21);

/*
 * pixel1 = 1
 * pixel2 = 0
 */
Clone this wiki locally