Touch GT911 não funciona? Endereço I2C, timing de reset, configuração e correções de coordenadas

Comece por aqui: identifique o sintoma

Siga os passos em ordem. Os endereços de registrador e os timings abaixo vêm do driver goodix do Linux, do componente esp_lcd_touch_gt911 da Espressif e da documentação do ESPHome; os links estão na seção Fontes.

1. Confirme que o GT911 está alimentado e respondendo no I2C

Alimentação e pull-ups

O device-tree binding do Linux para controladores Goodix define duas alimentações: AVDD28 (analógica) e VDDIO (trilhas de E/S lógicas). Em um módulo ou FPC, ambas geralmente são alimentadas pelo conector do host, então meça-as no conector antes de suspeitar do firmware. SDA e SCL também precisam de resistores de pull-up em algum ponto do barramento; muitos módulos de display não os incluem.

Faça a varredura do barramento

Execute um sketch de varredura I2C ou o i2cdetect. Um GT911 responde em um de dois endereços de 7 bits:

Os pares de 8 bits vêm de um comentário no código de reset do driver do Linux. Se uma folha do fornecedor diz "endereço 0xBA", trata-se do mesmo dispositivo que o 0x5D de 7 bits; use 0x5D no Arduino, ESP-IDF e Linux.

Leia o product ID

Os registradores do GT911 usam endereços de 16 bits. O driver do Linux lê 6 bytes a partir de 0x8140: os primeiros 4 bytes são o product ID em texto ASCII e os últimos 2 são a versão do firmware (little-endian). Um GT911 reporta a string 911. Se você obter 911, o barramento, a alimentação e o endereço estão todos corretos e o problema está mais adiante nesta lista.

Se nada responder em nenhum dos endereços, verifique se a linha de reset não está sendo mantida em nível baixo. Em muitos módulos, o RST é uma entrada do GT911 e precisa ser acionado em nível alto pelo host (ou com pull-up na placa) antes que o controlador funcione.

2. Acerte a sequência de reset e seleção de endereço

O GT911 escolhe seu endereço I2C a partir do nível do pino INT no momento em que o reset é liberado. Nas palavras do binding do Linux, a linha INT "é amostrada pelo dispositivo na desassertuação do reset para selecionar o endereço do cliente I2C".

A sequência que o driver Linux utiliza

1. Acione RST em nível baixo e aguarde mais de 10 ms (o driver espera 20 ms).
2. Acione INT no nível correspondente ao endereço desejado: alto para 0x14, baixo para 0x5D.
3. Aguarde mais de 100 µs.
4. Acione RST em nível alto e aguarde mais de 5 ms (o driver espera de 6 a 10 ms).
5. Mantenha INT em nível baixo por 50 ms e, em seguida, configure INT como entrada.

Se INT ficar flutuando durante a etapa 4, o endereço pode variar de uma inicialização para outra. Esse é o clássico relato de "funciona após gravar o firmware, falha após um cold boot".

ESP-IDF: esp_lcd_touch_gt911

O componente da Espressif define ESP_LCD_TOUCH_IO_I2C_GT911_ADDRESS como 0x5D e ESP_LCD_TOUCH_IO_I2C_GT911_ADDRESS_BACKUP como 0x14. Ele só executa a sequência de seleção de endereço quando todas estas três condições são atendidas:

• rst_gpio_num é um GPIO real (não GPIO_NUM_NC),
• int_gpio_num é um GPIO real,
• driver_data aponta para uma estrutura esp_lcd_touch_io_gt911_config_t cujo dev_addr é o endereço desejado.

Caso contrário, ele registra I2C address initialization procedure skipped - using default GT9xx setup e faz um reset simples. Nesse caso, o endereço será o que a fiação da placa determinar, e o endereço I2C do panel-IO que você passar deve corresponder ao resultado da varredura. O clock I2C padrão do componente em ESP_LCD_TOUCH_IO_I2C_GT911_CONFIG() é 100 kHz.

Placas em que o host não controla o INT

Se o INT não estiver conectado ao host, o host não pode escolher o endereço, então faça a varredura nos dois endereços e use aquele que responder. Na Sunton ESP32-8048S043C, por exemplo, a interrupção do GT911 não é conectada a um GPIO por padrão (consulte a página da placa). A página do GT911 do ESPHome observa que, quando o INT passa por um expansor de IO, o pino ainda é usado para definir o endereço na inicialização, mas o toque é feito por polling em vez de por interrupção.

3. Detectado, mas sem eventos de toque

Leia e limpe o registro de status

Os dados de toque começam em 0x814E. O primeiro byte é um byte de status:

• Bit 7 (0x80): buffer pronto. Novos dados são válidos apenas quando este bit está definido.
• Bits 0–3: número de pontos de toque. O driver Linux rejeita contagens acima do máximo configurado.
• Bit 4: uma tecla (botão) está pressionada.

Cada ponto de toque subsequente ocupa 8 bytes: um track ID, seguido de X, Y e tamanho como valores de 16 bits little-endian.

Após a leitura, tanto o driver Linux quanto o esp_lcd_touch_gt911 gravam 0 em 0x814E. Se você escrever seu próprio driver, faça o mesmo; omitir essa gravação é um motivo comum de um driver feito à mão detectar apenas o primeiro toque.

Ajuste a borda da interrupção

O tipo de gatilho está na própria configuração do GT911: bits 0–1 do byte de configuração em 0x804D (offset 6 a partir do início da configuração em 0x8047). O driver Linux faz o mapeamento assim:

Configure sua interrupção de GPIO para corresponder. Em esp_lcd_touch_gt911, levels.interrupt = 1 seleciona uma interrupção de borda de subida e 0 uma borda de descida.

Sem linha INT? Faça polling

O polling funciona bem para uso em HMI. O ESPHome faz polling a cada 50 ms por padrão (update_interval) quando nenhum interrupt_pin é definido. O driver Linux, quando tem uma interrupção, aguarda até 20 ms pelo bit de pronto antes de desistir de um frame.

4. O toque aparece no lugar errado

Verifique a resolução armazenada no GT911

O GT911 reporta coordenadas na resolução gravada em sua configuração, não na resolução do seu display. Segundo o driver Linux, o X máximo é o valor de 16 bits little-endian em 0x8048 e o Y máximo em 0x804A. Leia esses valores. Se o controlador estiver configurado para 1024×600 e o seu painel for 800×480, os toques aparecerão à direita e abaixo do seu dedo, e as bordas extremas cairão fora da tela. A solução é fazer a escala (ou definir os limites do driver com os valores do controlador).

De onde cada stack obtém os limites:

Calibre a partir dos valores brutos

A página de touchscreen do ESPHome sugere registrar touch.x_raw e touch.y_raw em uma lambda on_touch, tocar os cantos nos pixels de borda algumas vezes e inserir os valores brutos mínimo e máximo como calibração. O mesmo método funciona em qualquer plataforma: imprima o X e o Y brutos, toque nos quatro cantos e mapeie a faixa na tela.

Corrija a orientação nesta ordem: primeiro coloque X e Y nos eixos corretos (swap_xy), depois inverta o eixo que estiver ao contrário (mirror_x / mirror_y). O (0, 0) lógico do display deve ser o canto superior esquerdo.

5. Reescrever a configuração do GT911: último recurso

O bloco de configuração começa em 0x8047. No GT911, o driver Linux o trata como 186 bytes:

• Byte 0 (0x8047): versão da configuração.
• Bytes 1–4: resolução X e Y (veja o passo 4).
• Byte 5 (0x804C): número máximo de pontos de toque, 4 bits baixos.
• Byte 6 (0x804D): tipo de gatilho de interrupção, 2 bits baixos.
• Byte 184 (0x80FF): checksum, o complemento de dois de 8 bits da soma dos bytes 0–183.
• Byte 185 (0x8100): config_fresh, que deve ser 1.

O próprio driver Linux só grava uma configuração quando tem tanto os GPIOs INT e RST quanto encontra um arquivo de firmware (nome padrão goodix_911_cfg.bin, ou o nome em uma propriedade goodix,config-name). Sem esse arquivo, ele usa a configuração já armazenada no chip.

Antes de gravar qualquer coisa, leia os 186 bytes e salve-os. Corrija resolução e orientação em software sempre que possível. Um bloco de configuração feito para outro painel touch pode fazer o toque parar de funcionar no seu, por isso obtenha o arquivo do fornecedor do painel se realmente precisar alterá-lo.

Escolhendo um módulo com touch capacitivo

Se você está escolhendo um display CTP para um novo projeto, pergunte três coisas ao fornecedor antes de solicitar amostras: qual controlador de touch ele usa, em qual endereço I2C ele é enviado e se INT e RST chegam ao conector. Envie o tamanho, a interface e o processador host do seu projeto pelo Ask an Engineer, e incluiremos essas três respostas nos módulos que sugerirmos.