Che cos'è l'ILI9881C
L'ILI9881C è un driver Ilitek per pannelli TFT MIPI DSI, tipicamente pannelli in portrait da 720×1280 o 800×1280. Non ha interfaccia pixel SPI o RGB: comandi e pixel viaggiano entrambi sul bus DSI. Ilitek non pubblica apertamente il datasheet, quindi il riferimento pratico è il driver Linux mainline, panel-ilitek-ili9881c.c, più la tabella di inizializzazione fornita dal produttore del pannello.
Un controller, molte tabelle di init
Il driver Linux non è un'unica configurazione. Porta con sé una tabella di init, un timing di visualizzazione e un numero di lane distinti per ciascun pannello supportato. I pannelli presenti nel mainline includono:
- Raspberry Pi Touch Display 2, 5″ e 7″ (
raspberrypi,dsi-5inch,raspberrypi,dsi-7inch): 720×1280, 2 data lane. - Waveshare 7.0″ DSI Touch A: 2 data lane.
- Pannelli di Banana Pi, Startek, TDO, Feixin, Bestar, Wanchanglong e Ampire: 720×1280 o 800×1280, su 2 o 4 lane a seconda del pannello.
Due pannelli con lo stesso controller possono comunque richiedere tabelle di init e timing diversi. Se copiate una tabella di init da un'altra board, lo schermo può rimanere nero o mostrare striature anche se il link DSI è attivo. Partite dalla tabella del vostro pannello esatto.
Il Linux mainline ha un driver per l'ILI9881C ma nessuna voce per l'ILI9881D. Trattate un pannello ILI9881D, come il nostro PJ5015B14 (IPS da 4,99″ 720×1280), come un pannello che richiede la propria tabella di init e il proprio timing dal datasheet del pannello.
Sequenza di accensione nel driver Linux
Il driver mainline accende il pannello in questo ordine:
- Abilita IOVCC, attende 5 ms, poi abilita l'alimentazione principale e attende 5 ms.
- Mantiene il reset per 20 ms, lo rilascia, quindi attende 20 ms.
- Invia la tabella di init del pannello. L'ILI9881C usa comandi di cambio pagina per raggiungere i propri registri vendor.
- Torna alla pagina 0, abilita l'uscita tearing-effect e invia Exit Sleep.
- Attende 120 ms, quindi invia Display On.
Raspberry Pi: Touch Display 2
La documentazione di Raspberry Pi carica il Touch Display 2 con questi overlay:
dtoverlay=vc4-kms-dsi-ili9881-5inchdtoverlay=vc4-kms-dsi-ili9881-7inch
Aggiungete ,dsi0 per usare l'altro porta DSI. Sia il modello da 5″ che quello da 7″ sono 720×1280 con touch a cinque punti. Il modello da 10″ usa un controller e un overlay diversi (vc4-kms-dsi-ili79600-10-1inch) e richiede quattro lane DSI.
Un pannello ILI9881C o ILI9881D personalizzato su un Pi richiede un device-tree overlay che richiami una voce di pannello corrispondente. Riutilizzare l'overlay del Touch Display 2 funziona solo se il pannello corrisponde davvero a quella tabella di init e a quel timing.
ESP32-P4 e M5Stack Tab5
Il driver mipi_dsi di ESPHome gestisce pannelli ILI9881C sull'ESP32-P4, con 1 o 2 data lane (2 per impostazione predefinita). L'M5Stack Tab5 mostra quanto fragile sia questa scelta. ESPHome documenta tre versioni hardware:
- Prodotti prima del 14 ottobre 2025: driver display ILI9881C con controller touch GT911 separato. Usate il modello
M5STACK-TAB5. - Unità successive: un controller integrato display e touch, sia ST7123 (
M5STACK-TAB5-ST7123) sia ST7121 (M5STACK-TAB5-ST7121).
Le tre sequenze di init non sono intercambiabili. Se scegliete il modello display sbagliato, lo schermo resta semplicemente spento e nulla di rilevante viene loggato. Un driver touch errato invece genera un errore nel log, quindi ESPHome suggerisce di identificare prima la board dal driver touch.
Checklist di bring-up
- Confermate dal datasheet del pannello il numero di lane e la modalità DSI (video, sync-pulse o burst); le impostazioni dell'host devono corrispondere.
- Usate la tabella di init del vostro pannello esatto, non solo il nome del controller.
- Verificate la sequenza di reset e alimentazione. Alcune board controllano reset o alimentazione tramite un IO expander.
- Retroilluminazione accesa ma nessuna immagine di solito significa tabella di init errata, numero di lane errato o timing DSI non corrispondente, non un pannello guasto.
Per la scelta dell'interfaccia, vedere MIPI DSI vs LVDS vs eDP e la pagina sull'interfaccia MIPI DSI.
Guide e confronti
ILI9881C: risoluzione dei problemi e FAQ
Posso riutilizzare l'overlay del Raspberry Pi Touch Display 2 per un altro pannello ILI9881C?
Solo se il pannello corrisponde a quella tabella di init, a quel timing e alla configurazione a 2 lane. Il driver Linux mainline mantiene una tabella di init, una modalità e un numero di lane distinti per ogni pannello supportato, quindi un pannello ILI9881C diverso di solito richiede la propria voce di pannello e il proprio overlay.
Il mio schermo M5Stack Tab5 resta nero in ESPHome. Quale modello scelgo?
ESPHome documenta tre versioni del Tab5: le unità prodotte prima del 14 ottobre 2025 usano l'ILI9881C con controller touch GT911 (M5STACK-TAB5); le unità successive usano un ST7123 (M5STACK-TAB5-ST7123) o un ST7121 (M5STACK-TAB5-ST7121). Un modello display errato fallisce silenziosamente, mentre un driver touch errato genera un errore nel log, quindi identificate prima la board dal driver touch.
L'ILI9881D è uguale all'ILI9881C?
Non date per scontato che lo sia. Il kernel Linux mainline include un driver per l'ILI9881C ma nessuna voce per l'ILI9881D: un pannello ILI9881D richiede quindi una propria init table e i timing riportati nel datasheet del pannello.
Quante lane DSI usa un pannello ILI9881C?
Dipende dal pannello. Nel driver Linux mainline le voci per i display da 5″/7″ di Raspberry Pi e 7″ di Waveshare usano 2 lane, mentre diversi pannelli 720×1280 e 800×1280 ne usano 4. Configurate l'host in base al datasheet del vostro pannello.