Qué es el ILI9881C
El ILI9881C es un controlador de Ilitek para paneles TFT MIPI DSI, típicamente paneles verticales de 720×1280 u 800×1280. No tiene interfaz de píxeles SPI ni RGB: tanto los comandos como los píxeles viajan por DSI. Ilitek no publica su datasheet abiertamente, así que la referencia práctica es el driver del kernel principal de Linux, panel-ilitek-ili9881c.c, junto con la tabla de inicialización del fabricante de tu panel.
Un controlador, muchas tablas de inicialización
El driver de Linux no es una única configuración. Incluye una tabla de inicialización, unos tiempos de pantalla y un número de lanes independientes para cada panel que soporta. Los paneles incluidos en el kernel principal son:
- Raspberry Pi Touch Display 2, 5″ y 7″ (
raspberrypi,dsi-5inch,raspberrypi,dsi-7inch): 720×1280, 2 data lanes. - Waveshare 7.0″ DSI Touch A: 2 data lanes.
- Paneles de Banana Pi, Startek, TDO, Feixin, Bestar, Wanchanglong y Ampire: 720×1280 u 800×1280, con 2 o 4 lanes según el panel.
Dos paneles con el mismo controlador pueden necesitar tablas de inicialización y tiempos distintos. Si copias una tabla de inicialización de otra placa, la pantalla puede quedarse en negro o mostrar rayas aunque el enlace DSI esté activo. Parte de la tabla de tu panel exacto.
El kernel principal de Linux tiene un driver para el ILI9881C pero ninguna entrada para el ILI9881D. Trata un panel ILI9881D, como nuestro PJ5015B14 (IPS de 4,99″ 720×1280), como si necesitara su propia tabla de inicialización y sus propios tiempos extraídos del datasheet del panel.
Secuencia de encendido en el driver de Linux
El driver del kernel principal pone en marcha un panel en este orden:
- Habilitar IOVCC, esperar 5 ms y luego habilitar la alimentación principal y esperar 5 ms.
- Activar el reset durante 20 ms, liberarlo y después esperar 20 ms.
- Enviar la tabla de inicialización del panel. El ILI9881C usa comandos de cambio de página para acceder a sus registros del fabricante.
- Volver a la página 0, habilitar la salida de tearing-effect y enviar Exit Sleep.
- Esperar 120 ms y después enviar Display On.
Raspberry Pi: Touch Display 2
La documentación de Raspberry Pi configura el Touch Display 2 con estos overlays:
dtoverlay=vc4-kms-dsi-ili9881-5inchdtoverlay=vc4-kms-dsi-ili9881-7inch
Añade ,dsi0 para usar el otro puerto DSI. Tanto el modelo de 5″ como el de 7″ son 720×1280 con touch de cinco puntos. El modelo de 10″ usa otro controlador y otro overlay (vc4-kms-dsi-ili79600-10-1inch) y necesita cuatro lanes DSI.
Un panel ILI9881C o ILI9881D personalizado en una Pi necesita un overlay de device-tree que nombre una entrada de panel compatible. Reutilizar el overlay del Touch Display 2 solo funciona si el panel realmente coincide con esa tabla de inicialización y esos tiempos.
ESP32-P4 y el M5Stack Tab5
El driver mipi_dsi de ESPHome maneja paneles ILI9881C en el ESP32-P4, con 1 o 2 data lanes (2 por defecto). El M5Stack Tab5 muestra lo delicada que es esta elección. ESPHome documenta tres versiones de hardware:
- Fabricadas antes del 14 de octubre de 2025: controlador de pantalla ILI9881C con un controlador touch GT911 independiente. Usa el modelo
M5STACK-TAB5. - Unidades posteriores: un controlador integrado de pantalla y touch, ya sea un ST7123 (
M5STACK-TAB5-ST7123) o un ST7121 (M5STACK-TAB5-ST7121).
Las tres secuencias de inicialización no son intercambiables. Si eliges el modelo de pantalla equivocado, la pantalla simplemente se queda oscura y no se registra nada relevante en el log. Un driver touch equivocado sí genera un error en el log, por lo que ESPHome sugiere identificar la placa a partir del driver touch primero.
Lista de comprobación para la puesta en marcha
- Confirma el número de lanes y el modo DSI (video, sync-pulse o burst) en el datasheet del panel; los ajustes del host deben coincidir.
- Usa la tabla de inicialización de tu panel exacto, no solo la del nombre del controlador.
- Verifica la secuencia de reset y alimentación. Algunas placas controlan el reset o la alimentación mediante un IO expander.
- Retroiluminación encendida pero sin imagen suele significar una tabla de inicialización equivocada, un número de lanes incorrecto o una discrepancia en los tiempos DSI, no un panel averiado.
Para elegir interfaz, consulta MIPI DSI vs LVDS vs eDP y la página de interfaz MIPI DSI.
Guías y comparativas
ILI9881C: resolución de problemas y preguntas frecuentes
¿Puedo reutilizar el overlay del Raspberry Pi Touch Display 2 para otro panel ILI9881C?
Solo si el panel coincide con esa tabla de inicialización, esos tiempos y esa configuración de 2 lanes. El driver de Linux del kernel principal guarda una tabla de inicialización, un modo y un número de lanes independientes para cada panel soportado, por lo que un panel ILI9881C distinto normalmente necesita su propia entrada de panel y su propio overlay.
Mi pantalla del M5Stack Tab5 se queda oscura en ESPHome. ¿Qué modelo elijo?
ESPHome documenta tres versiones del Tab5: las unidades fabricadas antes del 14 de octubre de 2025 usan el ILI9881C con un controlador touch GT911 (M5STACK-TAB5); las unidades posteriores usan un ST7123 (M5STACK-TAB5-ST7123) o un ST7121 (M5STACK-TAB5-ST7121). Un modelo de pantalla equivocado falla en silencio, mientras que un driver touch equivocado genera un error en el log, así que identifica la placa a partir del driver touch primero.
¿Es el ILI9881D lo mismo que el ILI9881C?
No lo dé por sentado. El kernel principal de Linux incluye un driver para el ILI9881C, pero no hay ninguna entrada para el ILI9881D, por lo que un panel ILI9881D necesita su propia tabla de inicialización y su temporización según la hoja de datos del panel.
¿Cuántos lanes DSI usa un panel ILI9881C?
Depende del panel. En el driver del kernel principal de Linux, las entradas de las pantallas de 5″/7″ de Raspberry Pi y de Waveshare 7″ usan 2 lanes, mientras que varios paneles de 720×1280 y 800×1280 usan 4. Ajuste la configuración del host según la hoja de datos de su panel.