espressif/esp_lcd_ssd1681

readme

# SSD1681 e-Paper Driver [![Component Registry](https://components.espressif.com/components/espressif/esp_lcd_ssd1681/badge.svg)](https://components.espressif.com/components/espressif/esp_lcd_ssd1681) Implementation of the SSD1681 e-Paper controller with esp_lcd component. | LCD controller | Communication interface | Component name | Link to datasheet | | :------------: | :---------------------: | :------------: | :---------------: | | SSD1681 | SPI | esp_lcd_ssd1681| [Specification](https://cdn-learn.adafruit.com/assets/assets/000/099/573/original/SSD1681.pdf) | ## Add to project Packages from this repository are uploaded to [Espressif's component service](https://components.espressif.com/). You can add them to your project via `idf.py add-dependency`, e.g. ```bash compote manifest add-dependency espressif/esp_lcd_ssd1681==0.1.0 ``` Alternatively, you can create `idf_component.yml`. More is in [Espressif's documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html). ## Additional Description for `esp_lcd_panel_interface` The SSD1681 e-Paper driver fully implements the `esp_lcd_panel_interface` interface. Due to the specificity of this hardware, please carefully read the description for the following API. ### `esp_lcd_panel_mirror` Original function prototype: ```c /** * @brief Mirror the LCD panel on specific axis * * @note Combined with `esp_lcd_panel_swap_xy()`, one can realize screen rotation * * @param[in] panel LCD panel handle, which is created by other factory API like `esp_lcd_new_panel_st7789()` * @param[in] mirror_x Whether the panel will be mirrored about the x axis * @param[in] mirror_y Whether the panel will be mirrored about the y axis * @return * - ESP_OK on success * - ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel */ esp_err_t esp_lcd_panel_mirror(esp_lcd_panel_handle_t panel, bool mirror_x, bool mirror_y); ``` Please note that `mirror_y` has to be false if you enabled the `non_copy_mode` when constructing the panel, otherwise the function will return `ESP_ERR_INVALID_ARG`. ### `esp_lcd_panel_swap_xy` Original function prototype: ```c /** * @brief Swap/Exchange x and y axis * * @note Combined with `esp_lcd_panel_mirror()`, one can realize screen rotation * * @param[in] panel LCD panel handle, which is created by other factory API like `esp_lcd_new_panel_st7789()` * @param[in] swap_axes Whether to swap the x and y axis * @return * - ESP_OK on success * - ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel */ esp_err_t esp_lcd_panel_swap_xy(esp_lcd_panel_handle_t panel, bool swap_axes); ``` Please note that `swap_axes` has to be false if you enabled the `non_copy_mode` when constructing the panel, otherwise the function will return `ESP_ERR_INVALID_ARG`. ### `esp_lcd_panel_draw_bitmap` Original function prototype: ```c /** * @brief Draw bitmap on LCD panel * * @param[in] panel LCD panel handle, which is created by other factory API like `esp_lcd_new_panel_st7789()` * @param[in] x_start Start index on x-axis (x_start included) * @param[in] y_start Start index on y-axis (y_start included) * @param[in] x_end End index on x-axis (x_end not included) * @param[in] y_end End index on y-axis (y_end not included) * @param[in] color_data RGB color data that will be dumped to the specific window range * @return * - ESP_OK on success */ esp_err_t esp_lcd_panel_draw_bitmap(esp_lcd_panel_handle_t panel, int x_start, int y_start, int x_end, int y_end, const void *color_data); ``` Please note that this function will draw the bitmap but do not refresh the panel. You have to call the `epaper_panel_refresh_screen()` manually to refresh the bitmaps to the panel. ### `esp_lcd_panel_disp_on_off` Original function prototype: ```c /** * @brief Turn on or off the display * * @param[in] panel LCD panel handle, which is created by other factory API like `esp_lcd_new_panel_st7789()` * @param[in] on_off True to turns on display, False to turns off display * @return * - ESP_OK on success * - ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel */ esp_err_t esp_lcd_panel_disp_on_off(esp_lcd_panel_handle_t panel, bool on_off); ``` Call with parameter `on_off` set to false will have the e-paper panel enter sleep mode. BUSY pin will stay HIGH in sleep mode and a `esp_lcd_panel_init()` call is needed to resume the panel. Call with parameter `on_off` set to true will load the panel built-in waveform LUT, it is useful if you had set a custom waveform LUT. ## Service Life Optimization - The screen should not be powered on for extended periods of time. Please use the `disp_on_off` API to put the screen into sleep mode or cut down the power when the screen is not refreshing. - Do not refresh the screen at maximum speed for a long time. E-Paper panels are not made to show dynamic contents quickly. The refresh interval should be at least 3 minutes if you want to refresh the screen continuously.

readme of epaper_demo example

# e-Paper Example

The SSD1681 e-paper display drive uses [esp_lcd](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/lcd.html) APIs and provides some additional APIs because of the specificity of e-paper panel.

This example shows how to use SSD1681 e-paper display driver from Component manager and will draw a few bitmaps to the e-paper panel using the SSD1681 e-paper display driver.

## How to use the example

### Hardware Required

* An ESP development board
* An SSD1681 e-paper panel, with SPI interface
* An USB cable for power supply and programming

### Hardware Connection

The connection between ESP Board and the LCD is as follows:

```
ESP Board SSD1681 e-Paper Panel
┌──────────────────────────────┐ ┌────────────────────┐
│ GND ├─────────────►│ GND │
│ │ │ │
│ 3V3 ├─────────────►│ VCC │
│ │ │ │
│ EXAMPLE_PIN_NUM_SCLK ├─────────────►│ CLK │
│ │ │ │
│ EXAMPLE_PIN_NUM_MOSI ├─────────────►│ DIN │
│ │ │ │
│ EXAMPLE_PIN_NUM_EPD_RST ├─────────────►│ RST │
│ │ │ │
│ EXAMPLE_PIN_NUM_EPD_DC ├─────────────►│ DC │
│ │ │ │
│ EXAMPLE_PIN_NUM_EPD_CS ├─────────────►│ CS │
│ │ │ │
│ EXAMPLE_PIN_NUM_EPD_BUSY│◄─────────────│ BUSY │
└──────────────────────────────┘ └────────────────────┘
```

The GPIO number used by this example can be changed in [main.c](main/main.c).

### Software configuration

- Change all the `EXAMPLE_PIN` macro definition according to your hardware connection.
- If you are not using waveshare 1.54 inch V2 e-paper panel, please use the waveform lut provided by your panel vendor instead of using the demo built-in ones, or just simply comment the `epaper_panel_set_custom_lut` call and use the panel built-in waveform lut.

### Build and Flash

Run `idf.py -p PORT build flash monitor` to build, flash and monitor the project.

The first time you run `idf.py` for the example will cost extra time as the build system needs to address the component dependencies and downloads the missing components from registry into `managed_components` folder.

(To exit the serial monitor, type ``Ctrl-]``.)

See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.

### Example Output

## Show Custom Bitmap

As you could see from the demo, each bitmap is stored as an array. If you want to display your custom image, you need to convert your image to a bitmap array first.

Monochrome as the panel is, every bit (not byte) of the array corresponds to a pixel of the e-paper panel.

You could convert your image to bitmap array by the following steps:
- Resize your image to the size you want.
- Go to the [LVGL Online Image Converter website](https://lvgl.io/tools/imageconverter)
- Upload your resized image.
- Select the Color format to `CF_ALPHA_1_BIT`, select the Output format to `C array`.
- You could select the `Dither images (can improve quality)` to get better (gray-scale like) image quality
- Do not select the `Output in big-endian format` option.
- Click `Convert` and you get a `.c` file containing the bitmap array.

There are plenty of software alternative with such functionality, please pay attention to the scan mode if you prefer to use them.

The driver writes bitmap array to the vram in the sequence below by default:

![scan_mode](scan_mode.svg)

Please make sure that the scan mode identical to the image above. Otherwise you might have to mirror or rotate the bitmap using software implemented functions.

## Troubleshooting

* Why the e-paper is not displaying properly?
* Maybe your GPIO pin num is not correctly set, check in [main.c](main/main.c).
* Maybe your waveform lut is incorrect, try stop using your custom waveform lut.

readme of epaper_lvgl_demo example

                                        
                                        # e-Paper Example using LVGL

[esp_lcd](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/lcd.html) allows user to add their own panel drivers in the project scope (i.e. panel driver can live outside of esp-idf), so that the upper layer code like LVGL porting code can be reused without any modifications, as long as user-implemented panel driver follows the interface defined in the `esp_lcd` component.

This example shows how to use SSD1681 e-paper display driver from Component manager in esp-idf project. This example will draw a clock widget using the LVGL library. 

## How to use the example

### Hardware Required

* An ESP development board
* An SSD1681 e-paper panel, with SPI interface
* An USB cable for power supply and programming

### Hardware Connection

The connection between ESP Board and the LCD is as follows:

```
       ESP Board                              SSD1681 e-Paper Panel
┌──────────────────────────────┐              ┌────────────────────┐
│      GND                     ├─────────────►│ GND                │
│                              │              │                    │
│      3V3                     ├─────────────►│ VCC                │
│                              │              │                    │
│      EXAMPLE_PIN_NUM_SCLK    ├─────────────►│ CLK                │
│                              │              │                    │
│      EXAMPLE_PIN_NUM_MOSI    ├─────────────►│ DIN                │
│                              │              │                    │
│      EXAMPLE_PIN_NUM_EPD_RST ├─────────────►│ RST                │
│                              │              │                    │
│      EXAMPLE_PIN_NUM_EPD_DC  ├─────────────►│ DC                 │
│                              │              │                    │
│      EXAMPLE_PIN_NUM_EPD_CS  ├─────────────►│ CS                 │
│                              │              │                    │
│      EXAMPLE_PIN_NUM_EPD_BUSY│◄─────────────│ BUSY               │
└──────────────────────────────┘              └────────────────────┘
```

The GPIO number used by this example can be changed in [main.c](main/main.c).

### Software Configuration

- Change all the `EXAMPLE_PIN` macro definition according to your hardware connection.
- If you are not using waveshare 1.54 inch V2 e-paper panel, please use the waveform lut provided by your panel vendor instead of using the demo built-in ones, or just simply comment the `epaper_panel_set_custom_lut` call and use the panel built-in waveform lut.
- You could go to `menuconfig / Component config / LVGL configuration / Feature configuration / Others` and unselect `Show CPU usage and FPS count` to hide the CPU usage and FPS count window. 

### Build and Flash

Run `idf.py -p PORT build flash monitor` to build, flash and monitor the project. A clock widget will show up on the e-paper as expected.

The first time you run `idf.py` for the example will cost extra time as the build system needs to address the component dependencies and downloads the missing components from registry into `managed_components` folder.

(To exit the serial monitor, type ``Ctrl-]``.)

See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.

### Example Output

```bash
...
I (338) example: Initialize SPI bus
I (348) example: Install panel IO
I (348) gpio: GPIO[9]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 
I (358) gpio: GPIO[4]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 
I (368) lcd_panel.epaper: Add handler for GPIO 18
I (378) gpio: GPIO[18]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 0| Pulldown: 1| Intr:2 
I (378) example: Resetting e-Paper display...
I (508) example: Initializing e-Paper display...
I (628) example: Turning e-Paper display on...
I (748) example: Initialize LVGL library
I (748) example: Register display driver to LVGL
I (748) example: Install LVGL tick timer
I (748) example: Display LVGL Meter Widget
...
```

## Performance Notice

- LVGL library does not refresh the e-paper panel unless the content of the panel changes. However, the panel is kept refreshing when enabling `Show CPU usage and FPS count`, so do not forget to disable it to avoid unnecessary refresh.
- If you want to set a different screen rotation permanently, modifying the buffer conversion code in `example_lvgl_flush_cb` is better than using rotation API provided by LVGL. This is because converting `lv_color_t` to `uint8_t[]` needs a data copy, if using software-based rotation, we'll need another copy. Then convert the traversal sequence while converting `lv_color_t` to `uint8_t[]` might be a better idea.
- You should not set the latency of `vTaskDelay()` in the main loop too short. This demo only refresh the screen every tens of seconds, and during the interval of refreshes, the `lv_timer_handler()` is non-blocking and returns immediately, so please keep a reasonable `vTaskDelay()` latency to yield CPU for other tasks. The `vTaskDelay()` uses a busy-wait if the latency you set is too short and this may cause watchdog timeout error.

## Troubleshooting

* Why the e-paper doesn't respond?
  * Maybe your GPIO pin num is not correctly set, check in [main.c](main/main.c).
  * Maybe your waveform lut is incorrect, try stop using your custom waveform lut.

Examples:

epaper_demo

more details

To create a project from this example, run:

idf.py create-project-from-example "espressif/esp_lcd_ssd1681^0.1.0:epaper_demo"

or download archive

epaper_lvgl_demo

more details

To create a project from this example, run:

idf.py create-project-from-example "espressif/esp_lcd_ssd1681^0.1.0:epaper_lvgl_demo"

or download archive

readme

readme of epaper_demo example

readme of epaper_lvgl_demo example

Links

Supports all targets

License: Apache-2.0

Dependencies

Examples:

epaper_demo

epaper_lvgl_demo

Stats

Badge