Issue initializing AXS15231B LCD via QSPI on ESP32-S3 with ESP-IDF v5.5.2

by

Summary

The issue involves an AXS15231B LCD (model JC3248W535EN) connected via QSPI on an ESP32-S3 using ESP-IDF v5.5.2. The backlight functions correctly, but the display remains blank despite successful initialization and no error logs. The root cause lies in incorrect QSPI bus configuration and missing panel initialization commands.

Root Cause

  • Incorrect QSPI bus configuration: The spi_bus_config_t structure was misconfigured, leading to improper data transmission.
  • Missing initialization commands: The panel driver relied on default initialization, which was insufficient for the AXS15231B.
  • Inadequate DMA buffer alignment: The bitmap buffer was not aligned to the required DMA boundary, causing data corruption.

Why This Happens in Real Systems

  • Complex QSPI interfaces require precise configuration of clock, data lines, and DMA settings.
  • Vendor-specific initialization sequences are often undocumented or not fully implemented in generic drivers.
  • DMA constraints in hardware require strict adherence to buffer alignment and size.

Real-World Impact

  • Delayed product launch: Display issues block testing and integration of higher-level software (e.g., LVGL).
  • Increased debugging time: Lack of error logs and unclear documentation lead to trial-and-error troubleshooting.
  • Resource waste: Engineers spend time on low-level hardware issues instead of application development.

Example or Code

// Corrected QSPI bus configuration
const spi_bus_config_t buscfg = {
    .mosi_io_num = LCD_D0,
    .miso_io_num = GPIO_NUM_NC,
    .sclk_io_num = LCD_PCLK,
    .quadwp_io_num = LCD_D2,
    .quadhd_io_num = LCD_D3,
    .max_transfer_sz = LCD_H_RES * LCD_V_RES * sizeof(uint16_t),
};

// Custom initialization commands
static const axs15231b_lcd_init_cmd_t vendor_init_cmds[] = {
    {AXS15231B_CMD_SET_PIXEL_FORMAT, {0x55}, 1}, // Example command
    {AXS15231B_CMD_SET_DISPLAY_ON, {}, 0},
    {0, {}, 0}, // End marker
};

// DMA-aligned buffer allocation
static uint16_t __attribute__((aligned(64))) red[LCD_H_RES * 20];

How Senior Engineers Fix It

  • Verify QSPI pin mapping: Cross-check hardware connections and ESP-IDF pin definitions.
  • Inject custom initialization commands: Override default driver behavior with vendor-specific sequences.
  • Align DMA buffers: Use __attribute__((aligned(64))) for buffers to meet ESP32-S3 DMA requirements.
  • Enable debug logs: Add ESP_LOGD statements to trace panel initialization and data transfers.

Why Juniors Miss It

  • Overreliance on defaults: Assuming the driver handles all initialization without custom commands.
  • Neglecting DMA constraints: Unaware of ESP32-S3 DMA alignment requirements.
  • Incomplete hardware validation: Failing to verify QSPI signal integrity with an oscilloscope.

Leave a Comment