# ESP LCD & Touch AXS15231B
[](https://components.espressif.com/components/espressif/esp_lcd_axs15231b)
Implementation of the AXS15231B LCD & Touch controller with esp_lcd component.
| LCD controller | Communication interface | Component name | Link to datasheet |
| :------------: | :---------------------: | :------------: | :---------------: |
| AXS15231B | I80/SPI/QSPI/MIPI-DSI | esp_lcd_axs15231b | [Specification](https://dl.espressif.com/AE/esp_iot_solution/AXS15231B_Datasheet_V0.5_20230306.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.
```
idf.py add-dependency "espressif/esp_lcd_axs15231b==2.1.1~1"
```
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).
## Initialization of the LCD component.
### SPI Interface
```c
ESP_LOGI(TAG, "Initialize SPI bus");
const spi_bus_config_t buscfg = AXS15231B_PANEL_BUS_SPI_CONFIG(EXAMPLE_PIN_NUM_LCD_PCLK,
EXAMPLE_PIN_NUM_LCD_DATA0,
EXAMPLE_LCD_H_RES * 80 * sizeof(uint16_t));
ESP_ERROR_CHECK(spi_bus_initialize(EXAMPLE_LCD_HOST, &buscfg, SPI_DMA_CH_AUTO));
ESP_LOGI(TAG, "Install panel IO");
esp_lcd_panel_io_handle_t io_handle = NULL;
const esp_lcd_panel_io_spi_config_t io_config = AXS15231B_PANEL_IO_SPI_CONFIG(EXAMPLE_PIN_NUM_LCD_CS, EXAMPLE_PIN_NUM_LCD_DC,
callback, &callback_data);
ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)EXAMPLE_LCD_HOST, &io_config, &io_handle));
/**
* Uncomment these line if use custom initialization commands.
* The array should be declared as static const and positioned outside the function.
*/
// static const axs15231b_lcd_init_cmd_t lcd_init_cmds[] = {
// // {cmd, { data }, data_size, delay_ms}
// {0xFF, (uint8_t []){0x20, 0x10, 0x10}, 3, 0},
// {0x0C, (uint8_t []){0x11}, 1, 0},
// {0x10, (uint8_t []){0x02}, 1, 0},
// {0x11, (uint8_t []){0x11}, 1, 0},
// ...
// };
ESP_LOGI(TAG, "Install AXS15231B panel driver");
esp_lcd_panel_handle_t panel_handle = NULL;
const axs15231b_vendor_config_t vendor_config = {
// .init_cmds = lcd_init_cmds, // Uncomment these line if use custom initialization commands
// .init_cmds_size = sizeof(lcd_init_cmds) / sizeof(axs15231b_lcd_init_cmd_t),
.flags = {
.use_qspi_interface = 0,
},
};
const esp_lcd_panel_dev_config_t panel_config = {
.reset_gpio_num = EXAMPLE_PIN_NUM_LCD_RST,
.rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB, // Implemented by LCD command `36h`
.bits_per_pixel = 16, // Implemented by LCD command `3Ah` (16/18)
.vendor_config = &vendor_config,
};
ESP_ERROR_CHECK(esp_lcd_new_panel_axs15231b(io_handle, &panel_config, &panel_handle));
esp_lcd_panel_reset(panel_handle);
esp_lcd_panel_init(panel_handle);
esp_lcd_panel_disp_on_off(panel_handle, true);
```
### QSPI Interface
#### Refresh requirements
The current QSPI driver requires continuous full-frame transfers. Send each complete
frame either as one bitmap or as consecutive full-width strips in top-to-bottom
order. The first transfer must satisfy `y_start + y_gap == 0`. For frames starting
at logical row zero, keep the configured Y gap at zero.
In QSPI mode, `esp_lcd_panel_draw_bitmap()` does not send `LCD_CMD_RASET` to set an
independent Y-axis window. It sends `LCD_CMD_RAMWR` when the adjusted `y_start` is
zero and `LCD_CMD_RAMWRC` otherwise. A draw call with a nonzero adjusted `y_start`
therefore continues the preceding write instead of positioning an arbitrary dirty
rectangle.
When integrating LVGL, ensure the display integration sends complete frames in this
order. If each LVGL flush area is forwarded directly to
`esp_lcd_panel_draw_bitmap()`, use a full-refresh configuration. Sending only
changed rectangles to the panel is not supported by the current QSPI path and can
place pixels on the wrong rows.
This transfer sequence follows the panel manufacturer's recommendation at the time,
as described in [issue #666](https://github.com/espressif/esp-iot-solution/issues/666#issuecomment-6594439162).
#### Initialization example
```c
ESP_LOGI(TAG, "Initialize QSPI bus");
const spi_bus_config_t buscfg = AXS15231B_PANEL_BUS_QSPI_CONFIG(EXAMPLE_PIN_NUM_LCD_PCLK,
EXAMPLE_PIN_NUM_LCD_DATA0,
EXAMPLE_PIN_NUM_LCD_DATA1,
EXAMPLE_PIN_NUM_LCD_DATA2,
EXAMPLE_PIN_NUM_LCD_DATA3,
EXAMPLE_LCD_H_RES * 80 * sizeof(uint16_t));
ESP_ERROR_CHECK(spi_bus_initialize(EXAMPLE_LCD_HOST, &buscfg, SPI_DMA_CH_AUTO));
ESP_LOGI(TAG, "Install panel IO");
esp_lcd_panel_io_handle_t io_handle = NULL;
const esp_lcd_panel_io_spi_config_t io_config = AXS15231B_PANEL_IO_QSPI_CONFIG(EXAMPLE_PIN_NUM_LCD_CS, callback, &callback_data);
ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)EXAMPLE_LCD_HOST, &io_config, &io_handle));
/**
* Uncomment these line if use custom initialization commands.
* The array should be declared as static const and positioned outside the function.
*/
// static const axs15231b_lcd_init_cmd_t lcd_init_cmds[] = {
// // {cmd, { data }, data_size, delay_ms}
// {0xFF, (uint8_t []){0x20, 0x10, 0x10}, 3, 0},
// {0x0C, (uint8_t []){0x11}, 1, 0},
// {0x10, (uint8_t []){0x02}, 1, 0},
// {0x11, (uint8_t []){0x11}, 1, 0},
// ...
// };
ESP_LOGI(TAG, "Install AXS15231B panel driver");
esp_lcd_panel_handle_t panel_handle = NULL;
const axs15231b_vendor_config_t vendor_config = {
// .init_cmds = lcd_init_cmds, // Uncomment these line if use custom initialization commands
// .init_cmds_size = sizeof(lcd_init_cmds) / sizeof(axs15231b_lcd_init_cmd_t),
.flags = {
.use_qspi_interface = 1,
},
};
const esp_lcd_panel_dev_config_t panel_config = {
.reset_gpio_num = EXAMPLE_PIN_NUM_LCD_RST,
.rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB, // Implemented by LCD command `36h`
.bits_per_pixel = 16, // Implemented by LCD command `3Ah` (16/18)
.vendor_config = &vendor_config,
};
ESP_ERROR_CHECK(esp_lcd_new_panel_axs15231b(io_handle, &panel_config, &panel_handle));
esp_lcd_panel_reset(panel_handle);
esp_lcd_panel_init(panel_handle);
esp_lcd_panel_disp_on_off(panel_handle, true);
```
### I80 Interface
```c
ESP_LOGI(TAG, "Initialize Intel 8080 bus");
ESP_ERROR_CHECK(esp_lcd_new_i80_bus(&bus_config, &i80_bus));
ESP_LOGI(TAG, "Install panel IO");
esp_lcd_panel_io_handle_t io_handle = NULL;
const esp_lcd_panel_io_i80_config_t io_config = AXS15231B_PANEL_IO_I80_CONFIG(EXAMPLE_PIN_NUM_LCD_CS, EXAMPLE_PIN_NUM_LCD_DC,
example_callback, &example_callback_ctx);
ESP_ERROR_CHECK(esp_lcd_new_panel_io_i80(i80_bus, &io_config, &io_handle));
/**
* Uncomment these lines if use custom initialization commands.
* The array should be declared as static const and positioned outside the function.
*/
// static const axs15231b_lcd_init_cmd_t lcd_init_cmds[] = {
// // {cmd, { data }, data_size, delay_ms}
// {0xCF, (uint8_t []){0x00, 0xAA, 0XE0}, 3, 0},
// {0xED, (uint8_t []){0x67, 0x03, 0X12, 0X81}, 4, 0},
// {0xE8, (uint8_t []){0x8A, 0x01, 0x78}, 3, 0},
// ...
// };
ESP_LOGI(TAG, "Install AXS15231B panel driver");
esp_lcd_panel_handle_t panel_handle = NULL;
// const axs15231b_vendor_config_t vendor_config = { // Uncomment these lines if use custom initialization commands
// .init_cmds = lcd_init_cmds,
// .init_cmds_size = sizeof(lcd_init_cmds) / sizeof(axs15231b_lcd_init_cmd_t),
// };
const esp_lcd_panel_dev_config_t panel_config = {
.reset_gpio_num = EXAMPLE_PIN_NUM_LCD_RST,
.rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB, // Implemented by LCD command `36h`
.bits_per_pixel = 16, // Implemented by LCD command `3Ah` (16/18)
.vendor_config = &vendor_config,
};
ESP_ERROR_CHECK(esp_lcd_new_panel_axs15231b(io_handle, &panel_config, &panel_handle));
esp_lcd_panel_reset(panel_handle);
esp_lcd_panel_init(panel_handle);
esp_lcd_panel_disp_on_off(panel_handle, true);
```
### MIPI-DSI Interface
```c
ESP_LOGI(TAG, "MIPI DSI PHY Powered on");
esp_ldo_channel_config_t ldo_mipi_phy_config = {
.chan_id = EXAMPLE_MIPI_DSI_PHY_PWR_LDO_CHAN,
.voltage_mv = EXAMPLE_MIPI_DSI_PHY_PWR_LDO_VOLTAGE_MV,
};
ESP_ERROR_CHECK(esp_ldo_acquire_channel(&ldo_mipi_phy_config, &ldo_mipi_phy));
ESP_LOGI(TAG, "Initialize MIPI DSI bus");
esp_lcd_dsi_bus_config_t bus_config = AXS15231B_PANEL_BUS_DSI_1CH_CONFIG();
ESP_ERROR_CHECK(esp_lcd_new_dsi_bus(&bus_config, &mipi_dsi_bus));
ESP_LOGI(TAG, "Install panel IO");
esp_lcd_dbi_io_config_t dbi_config = AXS15231B_PANEL_IO_DBI_CONFIG();
ESP_ERROR_CHECK(esp_lcd_new_panel_io_dbi(mipi_dsi_bus, &dbi_config, &mipi_dbi_io));
ESP_LOGI(TAG, "Install AXS15231B panel driver");
#if ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(6, 0, 0)
esp_lcd_dpi_panel_config_t dpi_config = AXS15231B_240_960_PANEL_60HZ_DPI_CONFIG(LCD_COLOR_PIXEL_FORMAT_RGB888);
#else
esp_lcd_dpi_panel_config_t dpi_config = AXS15231B_240_960_PANEL_60HZ_DPI_CONFIG_CF(LCD_COLOR_PIXEL_FORMAT_RGB888);
#endif
axs15231b_vendor_config_t vendor_config = {
.flags = {
.use_mipi_interface = 1,
},
.mipi_config = {
.dsi_bus = mipi_dsi_bus,
.dpi_config = &dpi_config,
},
};
const esp_lcd_panel_dev_config_t panel_config = {
.reset_gpio_num = EXAMPLE_PIN_NUM_LCD_RST,
.rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB,
.bits_per_pixel = 24,
.vendor_config = &vendor_config,
};
ESP_ERROR_CHECK(esp_lcd_new_panel_axs15231b(mipi_dbi_io, &panel_config, &panel_handle));
ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_handle));
ESP_ERROR_CHECK(esp_lcd_panel_init(panel_handle));
ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true));
```
## Initialization of the touch component.
```
esp_lcd_panel_io_i2c_config_t io_config = ESP_LCD_TOUCH_IO_I2C_AXS15231B_CONFIG_EX(400000);
esp_lcd_panel_io_handle_t io_handle = NULL;
ESP_ERROR_CHECK(esp_lcd_new_panel_io_i2c(i2c_bus_handle, &io_config, &io_handle));
esp_lcd_touch_config_t tp_cfg = {
.x_max = CONFIG_LCD_HRES,
.y_max = CONFIG_LCD_VRES,
.rst_gpio_num = -1,
.int_gpio_num = -1,
.levels = {
.reset = 0,
.interrupt = 0,
},
.flags = {
.swap_xy = 0,
.mirror_x = 0,
.mirror_y = 0,
},
};
esp_lcd_touch_handle_t tp;
esp_lcd_touch_new_i2c_axs15231b(io_handle, &tp_cfg, &tp);
```
Read data from the touch controller and store it in RAM memory. It should be called regularly in poll.
```
esp_lcd_touch_read_data(tp);
```
Get one X and Y coordinates with strength of touch.
```
uint16_t touch_x[1];
uint16_t touch_y[1];
uint16_t touch_strength[1];
uint8_t touch_cnt = 0;
esp_lcd_touch_point_data_t points[1] = {0};
esp_lcd_touch_get_data(tp, points, &touch_cnt, 1);
if (touch_cnt > 0) {
touch_x[0] = points[0].x;
touch_y[0] = points[0].y;
touch_strength[0] = points[0].strength;
}
```
There is an example in ESP-IDF with this LCD controller. Please follow this [link](https://github.com/espressif/esp-idf/tree/master/examples/peripherals/lcd/spi_lcd_touch).
f721a40c032f6168844fe3bd321bc182e2593348
idf.py add-dependency "espressif/esp_lcd_axs15231b^2.1.1~1"