SSD1309 Public API

Public functions to interact with the SSD1309 display subsystem. More...

Collaboration diagram for SSD1309 Public API:

Functions
ERR_te	ssd1309_init_subsys (void)
	Initializes the SSD1309 subsystem.
ERR_te	ssd1309_deinit_subsys (void)
	Deinitializes the SSD1309 subsystem.
ERR_te	ssd1309_start_subsys (void)
	Starts the SSD1309 subsystem.
ERR_te	ssd1309_stop_subsys (void)
	Stops the SSD1309 subsystem.
ERR_te	ssd1309_get_def_cfg (SSD1309_CFG_ts *ssd1309_cfg_o)
	Populates a configuration structure with sensible default values.
ERR_te	ssd1309_init_handle (SSD1309_CFG_ts *ssd1309_cfg, SSD1309_HANDLE_ts **ssd1309_handle_o)
	Initializes the SSD1309 display and sends the full configuration sequence over I2C.
ERR_te	ssd1309_draw_text (char const *text, uint8_t text_len, uint8_t line, bool force)
	Draws a text string into the framebuffer at the specified line.
ERR_te	ssd1309_draw_rect (uint8_t x_src, uint8_t y_src, uint8_t x_dest, uint8_t y_dest, bool force)
	Draws a filled rectangle into the framebuffer.
ERR_te	ssd1309_clear_line (uint8_t line, bool force)
	Clears a single display line in the framebuffer (sets all pixels off).
ERR_te	ssd1309_invert_line (uint8_t line, bool force)
	Inverts all pixels in a single display line in the framebuffer.
ERR_te	ssd1309_clear_rect (uint8_t x_src, uint8_t y_src, uint8_t x_dest, uint8_t y_dest, bool force)
	Clears a rectangular region in the framebuffer (sets all pixels off).
ERR_te	ssd1309_invert_rect (uint8_t x_src, uint8_t y_src, uint8_t x_dest, uint8_t y_dest, bool force)
	Inverts all pixels in a rectangular region of the framebuffer.
ERR_te	ssd1309_update (bool force)
	Flushes the internal framebuffer to the display over I2C.

Detailed Description

Public functions to interact with the SSD1309 display subsystem.

Function Documentation

ssd1309_init_subsys()

ERR_te ssd1309_init_subsys

(

void

)

Initializes the SSD1309 subsystem.

Resets the internal state, initializes the logging dependency, and registers the CLI commands.

Must be called before any other SSD1309 API function.

Returns

• ERR_OK on success
• ERR_MODULE_ALREADY_INITIALIZED if the subsystem is already initialized
• Propagated error from cmd_register on failure

See also

ssd1309_init_subsys

Definition at line 488 of file ssd1309.c.

                                 {
    ERR_te err;
    
    if(internal_state.initialized) {
        return ERR_MODULE_ALREADY_INITIALIZED;
    }
 
    internal_state = (struct internal_state_s){ 0 };
    internal_state.log_level = LOG_LEVEL_INFO;
    internal_state.subsys = MODULES_SSD1309;
    internal_state.initialized = true;
    internal_state.started = false;
 
    init_log();
 
    err = cmd_register(&ssd1309_cmd_client_info);
    if(err != ERR_OK) {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "ssd1309_init_subsys: cmd_register error"
        );
 
        return err;
    }
    LOG_INFO(
        internal_state.subsys, 
        internal_state.log_level,
        "ssd1309_init_subsys: subsys initialized"
    );
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

ssd1309_deinit_subsys()

ERR_te ssd1309_deinit_subsys

(

void

)

Deinitializes the SSD1309 subsystem.

Resets the internal state to zero and deregisters the CLI commands. The subsystem must be stopped before calling this function.

Returns

• ERR_OK on success
• ERR_DEINITIALIZATION_FAILURE if the subsystem is not initialized or still running
• Propagated error from cmd_deregister on failure

See also

ssd1309_deinit_subsys

Definition at line 523 of file ssd1309.c.

                                   {
    if(internal_state.initialized && !internal_state.started) {
        internal_state = (struct internal_state_s){ 0 };
 
        ERR_te err = cmd_deregister(&ssd1309_cmd_client_info);
        if(err != ERR_OK) {
            return err;
        }
    }
    else {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "ssd1309_deinit_subsys: subsys is not initialized or stopped"
        );
 
        return ERR_DEINITIALIZATION_FAILURE;
    }
 
    LOG_INFO(
        internal_state.subsys, 
        internal_state.log_level,
        "ssd1309_deinit_subsys: subsystem deinitialized"
    );
    return ERR_OK;
}

Here is the call graph for this function:

ssd1309_start_subsys()

ERR_te ssd1309_start_subsys

(

void

)

Starts the SSD1309 subsystem.

Returns

• ERR_OK on success
• ERR_UNKNOWN if the subsystem is not initialized or already started

See also

ssd1309_start_subsys

Definition at line 551 of file ssd1309.c.

                                  {
    if(internal_state.initialized && !internal_state.started) {
        internal_state.started = true;
 
        LOG_INFO(
            internal_state.subsys, 
            internal_state.log_level,
            "ssd1309_start_subsys: subsys started"
        );
    }
    else {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "ssd1309_start_subsys: subsys not initialized or already started"
        );
 
        return ERR_UNKNOWN;
    }
 
    return ERR_OK;
}

Here is the caller graph for this function:

ssd1309_stop_subsys()

ERR_te ssd1309_stop_subsys

(

void

)

Stops the SSD1309 subsystem.

Returns

• ERR_OK on success
• ERR_UNKNOWN if the subsystem is not initialized or already stopped

See also

ssd1309_stop_subsys

Definition at line 575 of file ssd1309.c.

                                 {
    if(internal_state.initialized && internal_state.started) {
        internal_state.started = false;
 
        LOG_INFO(
            internal_state.subsys, 
            internal_state.log_level,
            "ssd1309_stop_subsys: subsys stopped"
        );
    }
    else {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "ssd1309_stop_subsys: subsys not initialized or already already stopped"
        );
        
        return ERR_UNKNOWN;
    }
 
    return ERR_OK;    
}

ssd1309_get_def_cfg()

ERR_te ssd1309_get_def_cfg

(

SSD1309_CFG_ts *

ssd1309_cfg_o

)

Populates a configuration structure with sensible default values.

The default configuration uses:

• Horizontal addressing mode (HAM), full 128×64 column and page range
• Contrast level 10, both horizontal and vertical flip enabled
• Multiplex ratio 64, no display offset, clock divide ratio 1
• Clock speed level 15, phase 1 and phase 2 precharge of 2 DCLKs
• VCOMH deselect level: medium (0.78 × Vcc)

The I2C instance and GPIO fields are not set and must be filled in by the caller before passing to ssd1309_init_handle.

Parameters

[out]

ssd1309_cfg_o

Pointer to the configuration structure to populate.

Returns

• ERR_OK always

See also

ssd1309_get_def_cfg

Definition at line 599 of file ssd1309.c.

                                                          {
    ssd1309_cfg_o->mem_addr_mode = SSD1309_MEM_ADDR_MODE_HAM;
    ssd1309_cfg_o->col_addr_start_ham_vam = SSD1309_COL_ADDR_START_HAM_VAM_0;
    ssd1309_cfg_o->col_addr_end_ham_vam = SSD1309_COL_ADDR_END_HAM_VAM_127;
    ssd1309_cfg_o->page_addr_start_ham_vam = SSD1309_PAGE_ADDR_START_HAM_VAM_0;
    ssd1309_cfg_o->page_addr_end_ham_vam = SSD1309_PAGE_ADDR_END_HAM_VAM_7;
    ssd1309_cfg_o->start_line = SSD1309_START_LINE_0;
    ssd1309_cfg_o->contrast = SSD1309_CONTRAST_10;
    ssd1309_cfg_o->horizontal_flip = SSD1309_HORIZONTAL_FLIP_TRUE;
    ssd1309_cfg_o->inverse_mode = SSD1309_INVERSE_MODE_FALSE;
    ssd1309_cfg_o->multiplex_ratio = SSD1309_MULTIPLEX_RATIO_64;
    ssd1309_cfg_o->vertical_flip = SSD1309_VERTICAL_FLIP_TRUE;
    ssd1309_cfg_o->offset = SSD1309_OFFSET_0;
    ssd1309_cfg_o->clk_div_ratio = SSD1309_CLK_DIV_RATIO_1;
    ssd1309_cfg_o->clk_speed_lvl = SSD1309_CLK_SPEED_LVL_LVL_15;
    ssd1309_cfg_o->phase1_precharge_dclk = SSD1309_PHASE1_PRECHARGE_DCLK_2;
    ssd1309_cfg_o->phase2_precharge_dclk = SSD1309_PHASE2_PRECHARGE_DCLK_2;
    ssd1309_cfg_o->vcomh_deselect_lvl = SSD1309_VCOMH_DESELECT_LVL_MED;
 
    return ERR_OK;
}

Here is the caller graph for this function:

ssd1309_init_handle()

ERR_te ssd1309_init_handle	(	SSD1309_CFG_ts *	ssd1309_cfg,
		SSD1309_HANDLE_ts **	ssd1309_handle_o )

Initializes the SSD1309 display and sends the full configuration sequence over I2C.

Configures the SCL and SDA GPIO pins in open-drain alternate function mode, initializes the I2C peripheral at 400 kHz, and transmits the complete SSD1309 initialization command sequence derived from ssd1309_cfg.

The display is turned off during configuration and turned on at the end.

Note

Only one handle instance is supported. Calling this function a second time without deinitialization returns an error.

Parameters

[in]	ssd1309_cfg	Pointer to the display configuration structure.
[out]	ssd1309_handle_o	Pointer to a handle pointer that will be set to the initialized display instance.

Returns

• ERR_OK on success
• ERR_INITIALIZATION_FAILURE if a handle is already initialized, or if the I2C or GPIO pointers in ssd1309_cfg are NULL

Initializes the SSD1309 display and sends the full configuration sequence over I2C.

See also

ssd1309_init_handle

Definition at line 622 of file ssd1309.c.

                                                                                              {
    if(internal_state.ssd1309_handle.initialized == true) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "ssd1309_init_handle: handle already initialized"
        );
 
        return ERR_INITIALIZATION_FAILURE;
    }
 
    if(ssd1309_cfg->i2c_instance == (void*)0) {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "ssd1309_init_handle: No I2C peripheral given"
        );
 
        return ERR_INITIALIZATION_FAILURE;
    }
    else if(ssd1309_cfg->scl_gpio_port == (void*)0 || ssd1309_cfg->sda_gpio_port == (void*)0) {
        LOG_ERROR(
            internal_state.subsys, 
            internal_state.log_level,
            "ssd1309_init_handle: No GPIO peripheral given"
        );  
        
        return ERR_INITIALIZATION_FAILURE;
    }
 
    internal_state.ssd1309_handle.i2c_instance = ssd1309_cfg->i2c_instance;
    internal_state.ssd1309_handle.scl_gpio_port = ssd1309_cfg->scl_gpio_port;
    internal_state.ssd1309_handle.scl_gpio_pin = ssd1309_cfg->scl_gpio_pin;
    internal_state.ssd1309_handle.sda_gpio_port = ssd1309_cfg->sda_gpio_port;
    internal_state.ssd1309_handle.sda_gpio_pin = ssd1309_cfg->sda_gpio_pin;
    internal_state.ssd1309_handle.gpio_alternate_function = ssd1309_cfg->gpio_alternate_function;
    internal_state.ssd1309_handle.low_col_start_addr_pam = ssd1309_cfg->low_col_start_addr_pam;
    internal_state.ssd1309_handle.high_col_start_addr_pam = ssd1309_cfg->high_col_start_addr_pam;
    internal_state.ssd1309_handle.mem_addr_mode = ssd1309_cfg->mem_addr_mode;
    internal_state.ssd1309_handle.col_addr_start_ham_vam = ssd1309_cfg->col_addr_start_ham_vam;
    internal_state.ssd1309_handle.col_addr_end_ham_vam = ssd1309_cfg->col_addr_end_ham_vam;
    internal_state.ssd1309_handle.page_addr_start_ham_vam = ssd1309_cfg->page_addr_start_ham_vam;
    internal_state.ssd1309_handle.page_addr_end_ham_vam = ssd1309_cfg->page_addr_end_ham_vam;
    internal_state.ssd1309_handle.start_line = ssd1309_cfg->start_line;
    internal_state.ssd1309_handle.contrast = ssd1309_cfg->contrast;
    internal_state.ssd1309_handle.horizontal_flip = ssd1309_cfg->horizontal_flip;
    internal_state.ssd1309_handle.inverse_mode = ssd1309_cfg->inverse_mode;
    internal_state.ssd1309_handle.multiplex_ratio = ssd1309_cfg->multiplex_ratio;
    internal_state.ssd1309_handle.page_start_addr_pam = ssd1309_cfg->page_start_addr_pam;
    internal_state.ssd1309_handle.vertical_flip = ssd1309_cfg->vertical_flip;
    internal_state.ssd1309_handle.offset = ssd1309_cfg->offset;
    internal_state.ssd1309_handle.clk_div_ratio = ssd1309_cfg->clk_div_ratio;
    internal_state.ssd1309_handle.clk_speed_lvl =ssd1309_cfg->clk_speed_lvl;
    internal_state.ssd1309_handle.phase1_precharge_dclk = ssd1309_cfg->phase1_precharge_dclk;
    internal_state.ssd1309_handle.phase2_precharge_dclk = ssd1309_cfg->phase2_precharge_dclk;
    internal_state.ssd1309_handle.vcomh_deselect_lvl = ssd1309_cfg->vcomh_deselect_lvl;
 
    GPIO_CFG_ts ssd1309_scl = { 0 };
    GPIO_CFG_ts ssd1309_sda = { 0 };
 
    ssd1309_scl.port = ssd1309_cfg->scl_gpio_port;
    ssd1309_scl.pin = ssd1309_cfg->scl_gpio_pin;
    ssd1309_scl.mode = GPIO_MODE_ALTERNATE_FUNCTION;
    ssd1309_scl.alternate_function = ssd1309_cfg->gpio_alternate_function;
    ssd1309_scl.output_type = GPIO_OUTPUT_TYPE_OPENDRAIN;
 
    ssd1309_sda.port = ssd1309_cfg->sda_gpio_port;
    ssd1309_sda.pin = ssd1309_cfg->sda_gpio_pin;
    ssd1309_sda.mode = GPIO_MODE_ALTERNATE_FUNCTION;
    ssd1309_sda.alternate_function = ssd1309_cfg->gpio_alternate_function;
    ssd1309_sda.output_type = GPIO_OUTPUT_TYPE_OPENDRAIN;
 
    gpio_init(&ssd1309_scl);
    gpio_init(&ssd1309_sda);
 
    I2C_CFG_ts ssd1309_i2c = { 0 };
    ssd1309_i2c.clock_strech = I2C_CLOCK_STRETCH_ON;
    ssd1309_i2c.instance = internal_state.ssd1309_handle.i2c_instance;
    ssd1309_i2c.speed = I2C_SPEED_400kHz;
 
    i2c_init(&ssd1309_i2c); 
 
    i2c_master_set_comm(internal_state.ssd1309_handle.i2c_instance, ENABLE);
    
    uint8_t cmd_buf[64]; 
    uint8_t idx = 0;
 
    // Control byte: commands
    cmd_buf[idx++] = 0x00;
 
    // SSD1309 OFF
    cmd_buf[idx++] = 0xAE;
 
    // Memory addressing mode
    cmd_buf[idx++] = 0x20;
    cmd_buf[idx++] = ssd1309_cfg->mem_addr_mode;
 
    // Addressing mode dependent setup
    if (ssd1309_cfg->mem_addr_mode == SSD1309_MEM_ADDR_MODE_HAM ||
        ssd1309_cfg->mem_addr_mode == SSD1309_MEM_ADDR_MODE_VAM) {
 
        // Column start/end
        cmd_buf[idx++] = 0x21;
        cmd_buf[idx++] = ssd1309_cfg->col_addr_start_ham_vam;
        cmd_buf[idx++] = ssd1309_cfg->col_addr_end_ham_vam;
 
        // Page start/end
        cmd_buf[idx++] = 0x22;
        cmd_buf[idx++] = ssd1309_cfg->page_addr_start_ham_vam;
        cmd_buf[idx++] = ssd1309_cfg->page_addr_end_ham_vam;
    }
    else {
        // Page start (PAM)
        cmd_buf[idx++] = 0xB0 | ssd1309_cfg->page_start_addr_pam;
 
        // Column start (PAM)
        cmd_buf[idx++] = ssd1309_cfg->low_col_start_addr_pam;
        cmd_buf[idx++] = 0x10 | ssd1309_cfg->high_col_start_addr_pam;
    }
 
    // SSD1309 start line 
    cmd_buf[idx++] = 0x40 | ssd1309_cfg->start_line;
 
    // Contrast
    cmd_buf[idx++] = 0x81;
    cmd_buf[idx++] = ssd1309_cfg->contrast;
 
    // Horizontal flip 
    cmd_buf[idx++] = 0xA0 | ssd1309_cfg->horizontal_flip;
 
    // Inverse mode
    cmd_buf[idx++] = 0xA6 | ssd1309_cfg->inverse_mode;
 
    // Multiplex ratio
    cmd_buf[idx++] = 0xA8;
    cmd_buf[idx++] = ssd1309_cfg->multiplex_ratio;
 
    // Vertical flip
    cmd_buf[idx++] = 0xC0 | ssd1309_cfg->vertical_flip;
 
    // SSD1309 offset 
    cmd_buf[idx++] = 0xD3;
    cmd_buf[idx++] = ssd1309_cfg->offset;
 
    // Clock divide + oscillator frequency
    cmd_buf[idx++] = 0xD5;
    cmd_buf[idx++] =
        (ssd1309_cfg->clk_div_ratio & 0x0F) |
        (ssd1309_cfg->clk_speed_lvl << 4);
 
    // Pre-charge period
    cmd_buf[idx++] = 0xD9;
    cmd_buf[idx++] =
        (ssd1309_cfg->phase1_precharge_dclk & 0x0F) |
        (ssd1309_cfg->phase2_precharge_dclk << 4);
 
    // VCOMH deselect level
    cmd_buf[idx++] = 0xDB;
    cmd_buf[idx++] = ssd1309_cfg->vcomh_deselect_lvl;
 
    // Turn on SSD1309
    cmd_buf[idx++] = 0xAF;
 
    // Output follows RAM content
    cmd_buf[idx++] = 0xA4;
 
    i2c_master_send(internal_state.ssd1309_handle.i2c_instance, SSD1309_ADDR_W, cmd_buf, idx);
 
    i2c_master_set_comm(internal_state.ssd1309_handle.i2c_instance, DISABLE);
 
    internal_state.ssd1309_handle.initialized = true;
 
    *ssd1309_handle_o = &internal_state.ssd1309_handle;
 
    LOG_INFO(
        internal_state.subsys, 
        internal_state.log_level,
        "ssd1309_init_handle: ssd1309 handle initialized"
    );
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

ssd1309_draw_text()

ERR_te ssd1309_draw_text	(	char const *	text,
		uint8_t	text_len,
		uint8_t	line,
		bool	force )

Draws a text string into the framebuffer at the specified line.

Renders characters from the built-in 8×8 font table into the framebuffer. Each character occupies 8 columns; characters wrap to the next line if they exceed the display width. The framebuffer is not flushed to the display; call ssd1309_update to make the changes visible.

Supports printable ASCII characters (0x20–0x7E).

Parameters

[in]	text	Pointer to the text string to render.
[in]	text_len	Number of characters to render from text.
[in]	line	Display line (1–8, top to bottom) where text begins.
[in]	force	If true, bypasses the initialized/started guard.

Returns

• ERR_OK on success
• ERR_INITIALIZATION_FAILURE if not initialized/started and force is false
• ERR_INVALID_ARGUMENT if line is out of range

See also

ssd1309_draw_text

Definition at line 806 of file ssd1309.c.

                                                                                       {
    if((!internal_state.ssd1309_handle.initialized || !internal_state.started) && !force) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "ssd1309_draw_text: handle not initialized or subsystem not started"
        );
 
        return ERR_INITIALIZATION_FAILURE;
    }
 
    if (line > SSD1309_PAGE_NUM || line == 0) {
        return ERR_INVALID_ARGUMENT; // invalid line
    }
 
    line--;
 
    uint8_t x = 0; // start at left-most column
    for (uint8_t i = 0; i < text_len; i++) {
        // check if character fits horizontally
        if (x + 8 > SSD1309_WIDTH && line < SSD1309_PAGE_NUM) {
            line++; // stop drawing if we run out of columns
            x = 0;
        }
 
        // draw 8x8 character
        for (uint8_t col = 0; col < 8; col++) {
            internal_state.fb[line][x + col] = fonts8x8[text[i] - 32][col];
        }
 
        x += 8; // move to next character position
    }
 
    return ERR_OK;
}

Here is the caller graph for this function:

ssd1309_draw_rect()

ERR_te ssd1309_draw_rect	(	uint8_t	x_src,
		uint8_t	y_src,
		uint8_t	x_dest,
		uint8_t	y_dest,
		bool	force )

Draws a filled rectangle into the framebuffer.

Sets all pixels within the rectangle defined by (x_src, y_src) to (x_dest, y_dest) in the framebuffer. Coordinates are 1-based. The framebuffer is not flushed; call ssd1309_update to display the result.

Parameters

[in]	x_src	Left edge of the rectangle (1–128).
[in]	y_src	Top edge of the rectangle (1–64).
[in]	x_dest	Right edge of the rectangle (1–128, must be ≥ x_src).
[in]	y_dest	Bottom edge of the rectangle (1–64, must be ≥ y_src).
[in]	force	If true, bypasses the initialized/started guard.

Returns

• ERR_OK on success
• ERR_INITIALIZATION_FAILURE if not initialized/started and force is false
• ERR_INVALID_ARGUMENT if coordinates are out of range or x_src > x_dest

See also

ssd1309_draw_rect

Definition at line 843 of file ssd1309.c.

                                                                                                   {
    if((!internal_state.ssd1309_handle.initialized || !internal_state.started) && !force) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "ssd1309_draw_rect: handle not initialized or subsystem not started"
        );
 
        return ERR_INITIALIZATION_FAILURE;
    }
 
    if(x_src > x_dest || y_src > y_dest || x_src < 1 || x_dest > SSD1309_WIDTH ||
    y_src < 1 || y_dest > SSD1309_HEIGHT) {
        // Invalid arguments
        return ERR_INVALID_ARGUMENT;
    }
 
    // Convert to 0-based coordinates
    uint8_t xs = x_src  - 1;
    uint8_t ys = y_src  - 1;
    uint8_t xd = x_dest - 1;
    uint8_t yd = y_dest - 1;
 
    uint8_t page_src = ys / SSD1309_BITS_IN_PAGE;
    uint8_t bit_src  = ys % SSD1309_BITS_IN_PAGE;
 
    uint8_t page_dest = yd / SSD1309_BITS_IN_PAGE;
    uint8_t bit_dest  = yd % SSD1309_BITS_IN_PAGE;
 
    for (uint8_t p = page_src; p <= page_dest; p++) {
        for (uint8_t x = xs; x <= xd; x++) {
 
            if (p == page_src && p == page_dest) {
                /* Single page */
                uint8_t mask = (uint8_t)((0xFFu << bit_src) & ((1u << (bit_dest + 1)) - 1));
                internal_state.fb[p][x] |= mask;
            }
            else if (p == page_src) {
                /* First page */
                uint8_t mask = (uint8_t)(0xFFu << bit_src);
                internal_state.fb[p][x] |= mask;
            }
            else if (p == page_dest) {
                /* Last page */
                uint8_t mask = (uint8_t)((1u << (bit_dest + 1)) - 1);
                internal_state.fb[p][x] |= mask;
            }
            else {
                /* Full pages in between */
                internal_state.fb[p][x] = 0xFF;
            }
        }
    }
 
    return ERR_OK;
}

Here is the caller graph for this function:

ssd1309_clear_line()

ERR_te ssd1309_clear_line	(	uint8_t	line,
		bool	force )

Clears a single display line in the framebuffer (sets all pixels off).

Equivalent to calling ssd1309_clear_rect over the full width of the given line. The framebuffer is not flushed; call ssd1309_update afterwards.

Parameters

[in]	line	Display line to clear (1–8).
[in]	force	If true, bypasses the initialized/started guard.

Returns

• ERR_OK on success
• ERR_INITIALIZATION_FAILURE if not initialized/started and force is false
• ERR_INVALID_ARGUMENT if line is out of range

Clears a single display line in the framebuffer (sets all pixels off).

See also

ssd1309_clear_line

Definition at line 901 of file ssd1309.c.

                                                    {
    if((!internal_state.ssd1309_handle.initialized || !internal_state.started) && !force) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "ssd1309_clear_line: handle not initialized or subsystem not started"
        );
 
        return ERR_INITIALIZATION_FAILURE;
    }
 
    if (line > SSD1309_PAGE_NUM || line == 0) {
        return ERR_INVALID_ARGUMENT; // invalid line
    }
 
    line--;
 
    ssd1309_clear_rect(1, line * SSD1309_BITS_IN_PAGE + 1, 128, line * SSD1309_BITS_IN_PAGE + 8, force);
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

ssd1309_invert_line()

ERR_te ssd1309_invert_line	(	uint8_t	line,
		bool	force )

Inverts all pixels in a single display line in the framebuffer.

Equivalent to calling ssd1309_invert_rect over the full width of the given line. Used by the menu module to simulate a selection highlight. The framebuffer is not flushed; call ssd1309_update afterwards.

Parameters

[in]	line	Display line to invert (1–8).
[in]	force	If true, bypasses the initialized/started guard.

Returns

• ERR_OK on success
• ERR_INITIALIZATION_FAILURE if not initialized/started and force is false
• ERR_INVALID_ARGUMENT if line is out of range

See also

ssd1309_invert_line

Definition at line 924 of file ssd1309.c.

                                                     {
    if((!internal_state.ssd1309_handle.initialized || !internal_state.started) && !force) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "ssd1309_invert_line: handle not initialized or subsystem not started"
        );
 
        return ERR_INITIALIZATION_FAILURE;
    }
 
    if (line > SSD1309_PAGE_NUM || line == 0) {
        return ERR_INVALID_ARGUMENT; // invalid line
    }
 
    line--;
 
    ssd1309_invert_rect(1, line * SSD1309_BITS_IN_PAGE + 1, 128, line * SSD1309_BITS_IN_PAGE + 8, force);
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function:

ssd1309_clear_rect()

ERR_te ssd1309_clear_rect	(	uint8_t	x_src,
		uint8_t	y_src,
		uint8_t	x_dest,
		uint8_t	y_dest,
		bool	force )

Clears a rectangular region in the framebuffer (sets all pixels off).

Clears all pixels within the rectangle defined by (x_src, y_src) to (x_dest, y_dest). Coordinates are 1-based. The framebuffer is not flushed; call ssd1309_update to display the result.

Parameters

[in]	x_src	Left edge (1–128).
[in]	y_src	Top edge (1–64).
[in]	x_dest	Right edge (1–128, must be ≥ x_src).
[in]	y_dest	Bottom edge (1–64, must be ≥ y_src).
[in]	force	If true, bypasses the initialized/started guard.

Returns

• ERR_OK on success
• ERR_INITIALIZATION_FAILURE if not initialized/started and force is false
• ERR_INVALID_ARGUMENT if coordinates are out of range or x_src > x_dest

Clears a rectangular region in the framebuffer (sets all pixels off).

See also

ssd1309_clear_rect

Definition at line 947 of file ssd1309.c.

                                                                                                    {
    if((!internal_state.ssd1309_handle.initialized || !internal_state.started) && !force) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "ssd1309_clear_rect: handle not initialized or subsystem not started"
        );
 
        return ERR_INITIALIZATION_FAILURE;
    }
 
    if(x_src > x_dest || y_src > y_dest || x_src < 1 || x_dest > SSD1309_WIDTH ||
    y_src < 1 || y_dest > SSD1309_HEIGHT) {
        // Invalid arguments
        return ERR_INVALID_ARGUMENT;
    }
 
    // Convert to 0-based coordinates
    uint8_t xs = x_src  - 1;
    uint8_t ys = y_src  - 1;
    uint8_t xd = x_dest - 1;
    uint8_t yd = y_dest - 1;
 
    uint8_t page_src = ys / SSD1309_BITS_IN_PAGE;
    uint8_t bit_src  = ys % SSD1309_BITS_IN_PAGE;
 
    uint8_t page_dest = yd / SSD1309_BITS_IN_PAGE;
    uint8_t bit_dest  = yd % SSD1309_BITS_IN_PAGE;
 
    for (uint8_t p = page_src; p <= page_dest; p++) {
        for (uint8_t x = xs; x <= xd; x++) {
 
            if (p == page_src && p == page_dest) {
                /* Single page */
                uint8_t mask = (uint8_t)((0xFFu << bit_src) & ((1u << (bit_dest + 1)) - 1));
                internal_state.fb[p][x] &= ~mask;
            }
            else if (p == page_src) {
                /* First page */
                uint8_t mask = (uint8_t)(0xFFu << bit_src);
                internal_state.fb[p][x] &= ~mask;
            }
            else if (p == page_dest) {
                /* Last page */
                uint8_t mask = (uint8_t)((1u << (bit_dest + 1)) - 1);
                internal_state.fb[p][x] &= ~mask;
            }
            else {
                /* Full pages in between */
                internal_state.fb[p][x] = 0x00;
            }
        }
    }
 
    return ERR_OK;
}

Here is the caller graph for this function:

ssd1309_invert_rect()

ERR_te ssd1309_invert_rect	(	uint8_t	x_src,
		uint8_t	y_src,
		uint8_t	x_dest,
		uint8_t	y_dest,
		bool	force )

Inverts all pixels in a rectangular region of the framebuffer.

XORs all pixels within the rectangle defined by (x_src, y_src) to (x_dest, y_dest). Coordinates are 1-based. The framebuffer is not flushed; call ssd1309_update to display the result.

Parameters

[in]	x_src	Left edge (1–128).
[in]	y_src	Top edge (1–64).
[in]	x_dest	Right edge (1–128, must be ≥ x_src).
[in]	y_dest	Bottom edge (1–64, must be ≥ y_src).
[in]	force	If true, bypasses the initialized/started guard.

Returns

• ERR_OK on success
• ERR_INITIALIZATION_FAILURE if not initialized/started and force is false
• ERR_INVALID_ARGUMENT if coordinates are out of range or x_src > x_dest

See also

ssd1309_invert_rect

Definition at line 1005 of file ssd1309.c.

                                                                                                     {
    if((!internal_state.ssd1309_handle.initialized || !internal_state.started) && !force) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "ssd1309_invert_rect: handle not initialized or subsystem not started"
        );
 
        return ERR_INITIALIZATION_FAILURE;
    }
 
    if(x_src > x_dest || y_src > y_dest || x_src < 1 || x_dest > SSD1309_WIDTH ||
    y_src < 1 || y_dest > SSD1309_HEIGHT) {
        // Invalid arguments
        return ERR_INVALID_ARGUMENT;
    }   
 
// Convert to 0-based coordinates
    uint8_t xs = x_src  - 1;
    uint8_t ys = y_src  - 1;
    uint8_t xd = x_dest - 1;
    uint8_t yd = y_dest - 1;
 
    uint8_t page_src = ys / SSD1309_BITS_IN_PAGE;
    uint8_t bit_src  = ys % SSD1309_BITS_IN_PAGE;
 
    uint8_t page_dest = yd / SSD1309_BITS_IN_PAGE;
    uint8_t bit_dest  = yd % SSD1309_BITS_IN_PAGE;
 
 
    for (uint8_t p = page_src; p <= page_dest; p++) {
        for (uint8_t x = xs; x <= xd; x++) {
 
            if (p == page_src && p == page_dest) {
                /* Single page */
                uint8_t mask = (uint8_t)((0xFFu << bit_src) & ((1u << (bit_dest + 1)) - 1));
                internal_state.fb[p][x] ^= mask;
            }
            else if (p == page_src) {
                /* First page */
                uint8_t mask = (uint8_t)(0xFFu << bit_src);
                internal_state.fb[p][x] ^= mask;
            }
            else if (p == page_dest) {
                /* Last page */
                uint8_t mask = (uint8_t)((1u << (bit_dest + 1)) - 1);
                internal_state.fb[p][x] ^= mask;
            }
            else {
                /* Full pages in between */
                internal_state.fb[p][x] ^= 0xFF;
            }
        }
    }
 
    return ERR_OK;
}

Here is the caller graph for this function:

ssd1309_update()

ERR_te ssd1309_update

(

bool

force

)

Flushes the internal framebuffer to the display over I2C.

Transmits the full 128×8-page framebuffer to the SSD1309 over I2C, making all pending framebuffer changes visible on the display.

Parameters

[in]

force

If true, bypasses the initialized/started guard.

Returns

• ERR_OK on success
• ERR_INITIALIZATION_FAILURE if not initialized/started and force is false

See also

ssd1309_update

Definition at line 1064 of file ssd1309.c.

                                  {
    if((!internal_state.ssd1309_handle.initialized || !internal_state.started) && !force) {
        LOG_ERROR(
            internal_state.subsys,
            internal_state.log_level,
            "ssd1309_update: handle not initialized or subsystem not started"
        );
 
        return ERR_INITIALIZATION_FAILURE;
    }
 
    i2c_master_set_comm(internal_state.ssd1309_handle.i2c_instance, ENABLE);
 
    uint8_t cmd = 0x40 ;
    i2c_master_send(internal_state.ssd1309_handle.i2c_instance,
                    SSD1309_ADDR_W, &cmd, 1);
 
    /* Framebuffer */
    i2c_master_send_continue(internal_state.ssd1309_handle.i2c_instance,
                    (uint8_t *)internal_state.fb,
                    SSD1309_WIDTH * SSD1309_PAGE_NUM);
 
    i2c_master_set_comm(internal_state.ssd1309_handle.i2c_instance, DISABLE);
 
    return ERR_OK;
}

Here is the call graph for this function:

Here is the caller graph for this function: