feat(ssd1306): Add vendor specific configuration for SSD1306

Merges https://github.com/espressif/esp-idf/pull/12450

components/esp_lcd/include/esp_lcd_panel_vendor.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -57,6 +57,33 @@ esp_err_t esp_lcd_new_panel_st7789(const esp_lcd_panel_io_handle_t io, const esp
  */
 esp_err_t esp_lcd_new_panel_nt35510(const esp_lcd_panel_io_handle_t io, const esp_lcd_panel_dev_config_t *panel_dev_config, esp_lcd_panel_handle_t *ret_panel);
 
+/**
+ * @brief SSD1306 configuration structure
+ *
+ * To be used as esp_lcd_panel_dev_config_t.vendor_config.
+ * See esp_lcd_new_panel_ssd1306().
+ */
+typedef struct {
+    /**
+     * @brief Multiplex ratio: (0..63)
+     *
+     * Display's height minus one.
+     */
+    uint8_t mux_ratio;
+
+    /**
+     * @brief Enables alternative COM pin configuration.
+     *
+     * When unset then Sequential COM pin configuration is used.
+     */
+    bool com_pin_alt;
+
+    /**
+     * @brief COM Left/Right remap.
+     */
+    bool com_lr_remap;
+} esp_lcd_panel_ssd1306_config_t;
+
 /**
  * @brief Create LCD panel for model SSD1306
  *
@@ -67,6 +94,24 @@ esp_err_t esp_lcd_new_panel_nt35510(const esp_lcd_panel_io_handle_t io, const es
  *          - ESP_ERR_INVALID_ARG   if parameter is invalid
  *          - ESP_ERR_NO_MEM        if out of memory
  *          - ESP_OK                on success
+ *
+ * @note The default panel size is 128x64.
+ * @note Use esp_lcd_panel_ssd1306_config_t to set the correct size.
+ * Example usage:
+ * @code {c}
+ *
+ * esp_lcd_panel_ssd1306_config_t ssd1306_config = {
+ *     .width = 128,
+ *     .height = 32
+ * };
+ * esp_lcd_panel_dev_config_t panel_config = {
+ *     <...>
+ *     .vendor_config = &ssd1306_config
+ * };
+ *
+ * esp_lcd_panel_handle_t panel_handle = NULL;
+ * esp_lcd_new_panel_ssd1306(io_handle, &panel_config, &panel_handle);
+ * @endcode
  */
 esp_err_t esp_lcd_new_panel_ssd1306(const esp_lcd_panel_io_handle_t io, const esp_lcd_panel_dev_config_t *panel_dev_config, esp_lcd_panel_handle_t *ret_panel);
 

components/esp_lcd/src/esp_lcd_panel_ssd1306.c

@@ -34,10 +34,12 @@ static const char *TAG = "lcd_panel.ssd1306";
 #define SSD1306_CMD_MIRROR_X_ON           0xA1
 #define SSD1306_CMD_INVERT_OFF            0xA6
 #define SSD1306_CMD_INVERT_ON             0xA7
+#define SSD1306_CMD_SET_MULTIPLEX         0xA8
 #define SSD1306_CMD_DISP_OFF              0xAE
 #define SSD1306_CMD_DISP_ON               0xAF
 #define SSD1306_CMD_MIRROR_Y_OFF          0xC0
 #define SSD1306_CMD_MIRROR_Y_ON           0xC8
+#define SSD1306_CMD_SET_COMPINS           0xDA
 
 static esp_err_t panel_ssd1306_del(esp_lcd_panel_t *panel);
 static esp_err_t panel_ssd1306_reset(esp_lcd_panel_t *panel);
@@ -58,8 +60,15 @@ typedef struct {
     int y_gap;
     unsigned int bits_per_pixel;
     bool swap_axes;
+    esp_lcd_panel_ssd1306_config_t vendor;
 } ssd1306_panel_t;
 
+static esp_lcd_panel_ssd1306_config_t default_ssd1306_config = {
+    .mux_ratio = 63,
+    .com_pin_alt = true,
+    .com_lr_remap = false
+};
+
 esp_err_t esp_lcd_new_panel_ssd1306(const esp_lcd_panel_io_handle_t io, const esp_lcd_panel_dev_config_t *panel_dev_config, esp_lcd_panel_handle_t *ret_panel)
 {
 #if CONFIG_LCD_ENABLE_DEBUG_LOG
@@ -84,6 +93,10 @@ esp_err_t esp_lcd_new_panel_ssd1306(const esp_lcd_panel_io_handle_t io, const es
     ssd1306->bits_per_pixel = panel_dev_config->bits_per_pixel;
     ssd1306->reset_gpio_num = panel_dev_config->reset_gpio_num;
     ssd1306->reset_level = panel_dev_config->flags.reset_active_high;
+    ssd1306->vendor =
+        panel_dev_config->vendor_config
+        ? *(esp_lcd_panel_ssd1306_config_t*)panel_dev_config->vendor_config
+        : default_ssd1306_config;
     ssd1306->base.del = panel_ssd1306_del;
     ssd1306->base.reset = panel_ssd1306_reset;
     ssd1306->base.init = panel_ssd1306_init;
@@ -138,6 +151,14 @@ static esp_err_t panel_ssd1306_init(esp_lcd_panel_t *panel)
 {
     ssd1306_panel_t *ssd1306 = __containerof(panel, ssd1306_panel_t, base);
     esp_lcd_panel_io_handle_t io = ssd1306->io;
+
+    ESP_RETURN_ON_ERROR(esp_lcd_panel_io_tx_param(io, SSD1306_CMD_SET_MULTIPLEX, (uint8_t[]) {
+        // set multiplex ratio
+        ssd1306->vendor.mux_ratio
+    }, 1), TAG, "io tx param SSD1306_CMD_SET_MULTIPLEX failed");
+    ESP_RETURN_ON_ERROR(esp_lcd_panel_io_tx_param(io, SSD1306_CMD_SET_COMPINS, (uint8_t[1]) {
+        0x2 | (ssd1306->vendor.com_pin_alt << 4) | (ssd1306->vendor.com_lr_remap << 5)
+    }, 1), TAG, "io tx param SSD1306_CMD_SET_COMPINS failed");
     ESP_RETURN_ON_ERROR(esp_lcd_panel_io_tx_param(io, SSD1306_CMD_DISP_OFF, NULL, 0), TAG,
                         "io tx param SSD1306_CMD_DISP_OFF failed");
     ESP_RETURN_ON_ERROR(esp_lcd_panel_io_tx_param(io, SSD1306_CMD_SET_MEMORY_ADDR_MODE, (uint8_t[]) {

examples/peripherals/lcd/i2c_oled/main/i2c_oled_example_main.c

@@ -99,6 +99,14 @@ void app_main(void)
         .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
     };
 #if CONFIG_EXAMPLE_LCD_CONTROLLER_SSD1306
+#if EXAMPLE_LCD_V_RES != 64
+    esp_lcd_panel_ssd1306_config_t ssd1306_config = {
+        .mux_ratio = EXAMPLE_LCD_V_RES - 1,
+        .com_pin_alt = false
+    };
+    panel_config.vendor_config = &ssd1306_config;
+#endif
+
     ESP_ERROR_CHECK(esp_lcd_new_panel_ssd1306(io_handle, &panel_config, &panel_handle));
 #elif CONFIG_EXAMPLE_LCD_CONTROLLER_SH1107
     ESP_ERROR_CHECK(esp_lcd_new_panel_sh1107(io_handle, &panel_config, &panel_handle));