O que é o ILI9881C
O ILI9881C é um driver da Ilitek para painéis TFT MIPI DSI, tipicamente painéis retrato de 720×1280 ou 800×1280. Ele não possui interface de pixels SPI ou RGB: comandos e pixels trafegam ambos pelo DSI. A Ilitek não publica seu datasheet abertamente, então a referência prática é o driver mainline do Linux, panel-ilitek-ili9881c.c, além da tabela de init do fabricante do seu painel.
Um controlador, muitas tabelas de init
O driver do Linux não é uma única configuração. Ele carrega uma tabela de init, um timing de display e uma contagem de lanes separados para cada painel que suporta. Os painéis listados no mainline incluem:
- Raspberry Pi Touch Display 2, 5″ e 7″ (
raspberrypi,dsi-5inch,raspberrypi,dsi-7inch): 720×1280, 2 data lanes. - Waveshare 7.0″ DSI Touch A: 2 data lanes.
- Painéis da Banana Pi, Startek, TDO, Feixin, Bestar, Wanchanglong e Ampire: 720×1280 ou 800×1280, em 2 ou 4 lanes dependendo do painel.
Dois painéis com o mesmo controlador ainda podem precisar de tabelas de init e timings diferentes. Se você copiar uma tabela de init de outra placa, a tela pode ficar preta ou exibir listras mesmo com o link DSI ativo. Parta da tabela do seu painel exato.
O Linux mainline tem um driver para o ILI9881C, mas nenhuma entrada para o ILI9881D. Trate um painel ILI9881D, como o nosso PJ5015B14 (IPS de 4,99″ 720×1280), como algo que precisa de sua própria tabela de init e timing extraídos do datasheet do painel.
Sequência de power-on no driver do Linux
O driver mainline inicializa um painel nesta ordem:
- Habilita a IOVCC, espera 5 ms, então habilita a alimentação principal e espera 5 ms.
- Ativa o reset por 20 ms, o libera e espera 20 ms.
- Envia a tabela de init do painel. O ILI9881C usa comandos de troca de página para acessar seus registradores do fabricante.
- Retorna à página 0, habilita a saída de tearing-effect e envia Exit Sleep.
- Espera 120 ms e envia Display On.
Raspberry Pi: Touch Display 2
A documentação do Raspberry Pi carrega o Touch Display 2 com estes overlays:
dtoverlay=vc4-kms-dsi-ili9881-5inchdtoverlay=vc4-kms-dsi-ili9881-7inch
Adicione ,dsi0 para usar a outra porta DSI. Tanto o modelo de 5″ quanto o de 7″ são 720×1280 com touch de cinco pontos. O modelo de 10″ usa um controlador e um overlay diferentes (vc4-kms-dsi-ili79600-10-1inch) e precisa de quatro lanes DSI.
Um painel ILI9881C ou ILI9881D personalizado em um Pi precisa de um device-tree overlay que aponte para uma entrada de painel correspondente. Reutilizar o overlay do Touch Display 2 só funciona se o painel realmente corresponder a essa tabela de init e a esse timing.
ESP32-P4 e o M5Stack Tab5
O driver mipi_dsi do ESPHome opera painéis ILI9881C no ESP32-P4, com 1 ou 2 data lanes (2 por padrão). O M5Stack Tab5 mostra o quão frágil é essa escolha. O ESPHome documenta três versões de hardware:
- Fabricado antes de 14 de outubro de 2025: driver de display ILI9881C com um controlador de touch GT911 separado. Use o modelo
M5STACK-TAB5. - Unidades posteriores: um controlador integrado de display e touch, seja um ST7123 (
M5STACK-TAB5-ST7123) ou um ST7121 (M5STACK-TAB5-ST7121).
As três sequências de init não são intercambiáveis. Se você escolher o modelo de display errado, a tela simplesmente fica escura e nada relevante é registrado no log. Um driver de touch errado gera um erro no log, então o ESPHome sugere identificar a placa primeiro pelo driver de touch.
Checklist de bring-up
- Confirme a contagem de lanes e o modo DSI (vídeo, sync-pulse ou burst) no datasheet do painel; as configurações do host devem corresponder.
- Use a tabela de init do seu painel exato, não apenas do nome do controlador.
- Verifique a sequência de reset e alimentação. Algumas placas controlam o reset ou a alimentação por meio de um IO expander.
- Backlight aceso sem imagem geralmente significa tabela de init errada, contagem de lanes errada ou incompatibilidade de timing DSI, não um painel queimado.
Para escolhas de interface, veja MIPI DSI vs LVDS vs eDP e a página da interface MIPI DSI.
Guias e comparativos
ILI9881C: solução de problemas e perguntas frequentes
Posso reutilizar o overlay do Raspberry Pi Touch Display 2 para outro painel ILI9881C?
Somente se o painel corresponder a essa tabela de init, a esse timing e a essa configuração de 2 lanes. O driver mainline do Linux mantém uma tabela de init, um modo e uma contagem de lanes separados para cada painel suportado, então um painel ILI9881C diferente geralmente precisa de sua própria entrada de painel e de seu próprio overlay.
Minha tela do M5Stack Tab5 fica escura no ESPHome. Qual modelo devo escolher?
O ESPHome documenta três versões do Tab5: unidades fabricadas antes de 14 de outubro de 2025 usam o ILI9881C com um controlador de touch GT911 (M5STACK-TAB5); unidades posteriores usam um ST7123 (M5STACK-TAB5-ST7123) ou ST7121 (M5STACK-TAB5-ST7121). Um modelo de display errado falha silenciosamente, enquanto um driver de touch errado gera um erro no log, então identifique a placa primeiro pelo driver de touch.
O ILI9881D é o mesmo que o ILI9881C?
Não presuma isso. O Linux mainline tem um driver ILI9881C, mas nenhuma entrada para o ILI9881D, então um painel ILI9881D precisa de sua própria tabela de inicialização e dos timings do datasheet do painel.
Quantas lanes DSI um painel ILI9881C usa?
Depende do painel. No driver mainline do Linux, as entradas do Raspberry Pi 5″/7″ e do Waveshare 7″ usam 2 lanes, enquanto vários painéis de 720×1280 e 800×1280 usam 4. Ajuste a configuração do host conforme o datasheet do seu painel.