Como depurar com o ESP-Prog

Tenho escrito diversos artigos sobre gravadores e depuradores de código, como o artigo do JTAG J-LINK, também como fazer um debugger com uma BluePill, uma sequência de comandos para depuração com o firmware ou hardware Black Magic Probe, finalizando até o momento com o Laboratório Maker 09: Gravadores, no qual citei o ESP-Prog. Dando sequência à série, veremos nesse artigo a configuração e como depurar com o ESP-Prog.

O que é a ESP-Prog?

No vídeo "Debug com SWD" demonstrei a interface do firmware Black Magic Probe com uma ARM Cortex-M3, usando GDB. Outras plataformas também têm seus depuradores, e claro, não poderia faltar para o ESP32.

A ESP-Prog é uma ferramenta de desenvolvimento e depuração, com funções especiais como: download automático de firmware, comunicação serial e depuração JTAG online. O download automático de firmware e a comunicação serial são funções suportadas tanto em ESP8266 quanto em ESP32, mas a depuração com JTAG é suportado somente no ESP32.

Apresentação da placa

Apesar de pequena, a placa tem recursos de interação que precisam ser esclarecidos.

USB Bridge

O ESP-Prog usa o FT2232H, que é fornecido pela FTDI, como ponte controladora. A placa pode ser configurada para converter USB 2.0 para interfaces serial e paralela, que suportam uma larga faixa de padrões da indústria. A placa utiliza o modo padrão de interface serial dupla-assíncrona, que depende do driver FT2232HL.

Assim como no Black Magic Probe, o computador identificará duas portas seriais do ESP-Prog. O número de porta maior representa a interface do programa, enquanto a outra representa a interface JTAG.

Interface de comunicação

Podemos nos conectar ao ESP32 com ambas as interfaces do ESP-Prog.

Interface de programação

A interface de programação tem 6 pinos, incluindo a UART (TX e RX), pino de seleção do modo de boot (ESPIO0) e pino de reset (ESPEN). O pinout da interface de programa deve ser o da imagem a seguir:

Interface JTAG

A interface JTAG na board deve seguir a referência abaixo:

Função de download automático

Como já citado, o ESP-Prog suporta download automático. Após conectar a interface de programa do ESP-Prog à placa, o download do programa pode ser feito automaticamente, assim como a execução, controlando os estados de inicialização no pino ESPIO0 e ESPEN, que poupam o usuário de reinicialização manual do dispositivo. De qualquer modo, tem os botões onboard para interação manual, caso desejado.

LEDs indicadores de status

Próximo ao processador temos 3 LEDs. O vermelho acende quando o sistema está conectado ao 3v3. O verde acende quando o ESP-Prog está baixando dados para o ESP32. O azul acende quando o ESP-Prog está recebendo dados do ESP32.

Pinos dos headers

O fornecimento de alimentação pode ser escolhido entre 3v3 ou 5V, conforme demonstrado na imagem mais abaixo.

Bem ao lados dos headers temos a seleção de alimentação. Conecte o ESP32 ou ESP8266 somente após aferir a tensão de entrada.

Depuração com ESP-Prog

Na imagem a seguir, vamos as duas interfaces: a JTAG para debugging e a da aplicação, para carga e monitoramento.

Quando depurando, o processo inicia pela xtensa-esp32-elf-gdb, então passa pelo OpenOCD antes de entrar no ESP-Prog. Já o ESP-Prog estará conectado ao alvo.

Do lado da interface de aplicação temos o make do firmware, seguido pela ferramenta de upload esptool.py. Do mesmo modo, o terceiro passo é a entrada na interface do ESP-Prog, pela mesma USB, com o mesmo alvo.

Na imagem temos o mais alto nível do lado esquerdo, que é a IDE utilizada para a programação - no exemplo, o Eclipse. Repare que os primeiros 4 blocos estão envoltos em um quadrado maior, representando o computador onde se está desenvolvendo para o ESP. Em seguida temos a representação da conexão USB, e então dois blocos representando o ESP-Prog. O solitário do lado direito é o ESP32, recebendo a conexão das interfaces JTAG e UART, mas ambas entram pela única conexão USB, graças ao FT2232H.

Seleção do adaptador

O ESP-Prog não é o único que funcionará. Atendendo aos critérios de nível lógico e compatibilidade com OpenOCD, deve ser possível usar outro adaptador.

O porte JTAG no ESP32 é um padrão industrial JTAG que não tem (e não precisa) do pino TRST.

As principais características a considerar são o transporte, tensão, pinout, conexão e arquitetura, onde nesse último caso podemos considerar o RTCK para placas ARM.

No site http://openocd.org/doc/html/Debug-Adapter-Hardware.html (sem SSL, portanto, chamado de "site não seguro") tem muitas das informações necessárias para determinar o adaptador a usar com o OpenOCD, apesar de ser uma lista incompleta, inclusive os adaptadores que suportam SWD, necessário para debug na RP Pico, BluePill etc. O ESP32 não suporta SWD.

A sinalização mínima necessária para usar um JTAG com ESP32 são: TDI, TDO, TCK, TMS e GND. Alguns adaptadores também precisam de uma conexão de referência chamada de Vtar, para definir o nível lógico.

Configurar o ESP-Prog no PlatformIO

Quando usando PlatformIO, por exemplo, com VS Code, as definições de projeto ficam no arquivo platformio.ini. Nesse arquivo devemos adicionar na seção principal o parâmetro debug_tool:

[env:esp32doit-devkit-v1]
platform = espressif32
board = esp32doit-devkit-v1
framework = arduino
debug_tool = esp-prog
lib_deps = knolleary/PubSubClient@^2.8

Do mesmo modo, se quisermos utilizar o ESP-Prog como ferramenta de upload de firmware, devemos adicionar o mesmo indicador ao parâmetro upload_protocol.

[env:esp32doit-devkit-v1]
platform = espressif32
board = esp32doit-devkit-v1
framework = arduino
debug_tool = esp-prog
upload_protocol = esp-prog
lib_deps = knolleary/PubSubClient@^2.8

A velocidade padrão da serial usando PlatformIO é 9600. Para mudar a velocidade serial, adicione o parâmetro monitor_speed = 115200.

No Linux, devemos instalar também as regras para udev, para esse arquivo. Basta fazer essa série:

#1 - entrar no diretório
cd /etc/udev/rules.d
#2 - baixar o arquivo de regras
sudo wget -c https://raw.githubusercontent.com/platformio/platformio-core/master/scripts/99-platformio-udev.rules
#3 - aplicar as regras sem reiniciar.
udevadm control --reload-rules && udevadm trigger 

No subtópico JTAG dispus o pinout do barramento. Essa é a tabela e descrição, conforme a documentação do PlatformIO:

O PlatformIO sempre detecta a porta serial sozinho, mas no caso do debugger, teremos 2 portas. Por isso, devemos adicionar o parâmetro upload_port indicando a porta de upload.

Para o debug, devemos abrir um terminal e digitar pio upgrade --dev, caso necessário.

Mais um parâmetro que já pode ser útil de cara é o debug_init_break, que permite selecionar breakpoints previamente. Por exemplo: debug_init_break = tbreak setup teste. Veja alguns exemplos importantes:

;desabilita
debug_init_break =
;pára no setup
debug_init_break = tbreak setup
;para na linha 25 do arquivo main.cpp
debug_init_break =  break main.cpp:25

A partir desse ponto já podemos iniciar o debug. Leva um tempinho até compilar e iniciar o debug, mas após isso já podemos adicionar brakepoints em pontos específicos e fazer todo o processo demonstrado nesse vídeo. Só que agora de uma maneira mais tranquila ainda!

Podemos também mudar o valor de uma variável do programa em execução. Isso ainda não mostrei, mas é simples: só clicar na variável em variables quando o valor estiver aparente. Devo demonstrar no vídeo.

Nesse link tem uma lista dos comandos iniciais padrão para cada dispositivo.

A documentação oficial também foi referência para esse artigo.

Todos os parâmetros de debug que podem ir ao arquivo platformio.ini estão descritos nesse link da documentação.

Se acontecer de falhar o upload em algum momento, desconecte o cabo JTAG e faça o upload, então reconecte o cabo.

Os pinos do ESP32 devem ser sempre os mesmos; 12, 13, 14 e 15.

Usando o JTAG, fica claro que não podemos usar o LED onboard para debug. Mas para que precisaremos dele agora? Adeus, LED!

Vídeo

No vídeo demonstro algumas situações nas quais o JTAG pode ser extremamente útil, mas pode ser que o vídeo não saia no mesmo dia desse artigo. Se não é inscrito no canal ainda, aproveite para inscrever-se e deixe seu like!

Revisão: Ricardo Amaral de Andrade

Inscreva-se no nosso canal Manual do Maker no YouTube.

Também estamos no Instagram.