Depurando ESP32S3 com Arduino-IDE no macOS

Realizar a depuração de quaisquer aplicações e a forma mais ágil de detectar problemas em sua execução, principalmente quando pensamos no tempo gasto em re-gravar o firmware de um micro controlador apenas para exibir uma simples váriavel em uma saída serial…

Atualmente exitem muitos recursos intuitivos e práticos para realizar esse processo, no entanto para aqueles que se aventuram pela primeira vez nesse mundo podem surgir algumas duvidas nas configurações dos parâmetros de depuração.
Portanto decidi escrever esse pequeno artigo para facilitar o setup de depuração para o ESP32-S3 utilizando o Arduino-IDE para macos. Caso você utilize outro OS, os conceitos serão os mesmos no entanto deverá se atentar aos paths e outras pequenas diferenças.

ESP32-S3 + JTAG

O chip ESP32-S3 conta com conexão USB de forma nativa que conta com um adaptador JTAG (Joint Test Action Group), conforme ilustrado no diagrama abaixo.

Para mais detalhes sobre o JTAG Debugging: docs.espressif

Pré-Requisitos

• Instalar o Arduino IDE ^2.2.1
• Instalar o ESP32 no Arduino IDE ^2.0.11

USB Integrada

Se você está utilizando um modulo de desenvolvimento, certifique-se de utilizar a porta que se conecta aos terminais do USB builtin, caso esteja em duvida sobre se o modulo realmente está usando ou não os terminais corretor, é possível realizar a conexão diretamente ao pino utilizando um cabo USB qualquer.

Atente-se que o nível de tensão da porta USB é normalmente 5V enquanto o ESP é 3.3V!

ESP32-S3 Pin	USB Signal
GPIO 19	D-
GPIO 20	D+
5V	Opcional
GND	GND

Apos conectar o ESP a USB do seu computador, o adaptador JTAG deverá estar listado na lista de dispositivos USB. Para isso:  > System Settings > General > System Report… > USB

⚠️ Caso você tenha chegado até aqui e ainda não tenha aparecido o dispositivo na listagem, não se desespere. Alguns módulos não vem com a JTAG habilitada por padrão, vamos aprender a habilita-la nas próximas etapas.

Configurações Arduino IDE

Agora que o ESP está conectado ao computador, podemos iniciar as configurações no Arduino IDE. Para isso vá até: Tools e garanta que tenha as mesmas configurações da imagem a baixo:

Agora abra um código qualquer (ex: Blink) e faça o upload para o ESP32-S3. Dessa forma as configurações para uso do JTAG serão efetivamente ativadas.

Debugger

Para realizar o debug, o Arduino utiliza a extensão Maus/cortex-debug. No entanto, na data em que esse post foi publicado, por padrão o Arduino IDE não traz as configurações corretas para o debug do ESP32-S3, para isso será necessário ajustar alguns atributos (debug_attributes).

Como a IDE do Arduino é baseada no VS-Code, a forma de se configurar a extensão e o debug são muito semelhantes. Vamos precisar inicialmente gerar o arquivo launch.json para obtê-lo, deveremos pressionar o botão de Debug da barra superior e então pressionar na engrenagem na aba de debug.

Nesse momento deverá disparar alguns alertas de erro na sua IDE como na imagem abaixo, caso não apareça nenhuma mensagem de erro e o debug efetivamente tenha sido iniciado, o seu tutorial termina aqui.

Para resolver esse erro será necessário que alteremos o arquivo lauch.json , mas como vc ja deve ter percebido, ele está na configuração read-only. E para que seja possível editar-lo deveremos abrir ele com outro editor de texto. Para localizar o path deste arquivo, basta manter o mouse sobre o nome do arquivo por alguns instantes:

Aparentemente este é um bug desta versão do Arduino IDE, espero que seja corrigido em versões futuras. O correto seria que esse arquivo ficasse junto aos arquivos do programa que estamos executando…

Substitua essas configurações por estas:

// launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "cwd": "${workspaceRoot}",
      "name": "Arduino on ESP32-S3",
      "request": "attach",
      "type": "cortex-debug",
      // KEEP THE "executable" as the same value before
            "executable": "<DO NOT CHANGE THIS PATH!!>",
      "servertype": "openocd",
      "serverpath": "/Users/<YOUR-USER>/Library/Arduino15/packages/esp32/tools/openocd-esp32/v0.11.0-esp32-20221026/bin/openocd",
            "armToolchainPath": "/Users/<YOUR-USER>/Library/Arduino15/packages/esp32/tools/xtensa-esp32s3-elf-gcc/esp-2021r2-patch5-8.4.0/bin/",
      "configFiles": [
        "debug.cfg"
      ],
      "toolchainPrefix": "xtensa-esp32s3-elf",
      "svdFile": "debug.svd",
      "overrideAttachCommands": [
        "set remote hardware-watchpoint-limit 2",
        "monitor reset halt",
        "monitor gdb_sync",
        "thb setup",
        "c"
      ],
      "overrideRestartCommands": [
        "monitor reset halt",
        "monitor gdb_sync"
      ]
    }
  ]
}

Após isso vamos precisa editar uma configuração da IDE, para isso utilize o atalho ⌘⇧P e então buscar por “Open Settings (UI)”.

Então, busque por cortex-debug.gdbPath e altere o path default para: /Users/<YOUR-USER>/Library/Arduino15/packages/esp32/tools/xtensa-esp32s3-elf-gcc/esp-2021r2-patch5-8.4.0/bin/xtensa-esp32s3-elf-gdb

Uma vez feito isso, volte a pressionar o botão de Start-Debug novamente e tudo deverá ser executado com sucesso!

Continua com problemas?

Caso o tutorial acima não tenha sido suficiente para resolver o seu caso, deixo em anexo diversos links que utilizei durante a resolução do meu caso. Espero que possam lhe auxiliar:

• https://github.com/espressif/arduino-esp32/issues/8237
• https://stackoverflow.com/questions/65872178/openocd-gdb-executable-arm-none-eabi-gdb-was-not-found-please-configure-cort
• https://github.com/Marus/cortex-debug/issues/8
• https://forum.arduino.cc/t/debugging-on-the-new-nano-esp32/1153079/40
• https://stackoverflow.com/questions/18167198/using-nm-on-mac-apps-malformed-object
• https://github.com/arduino/arduino-ide/issues/866
• https://forum.arduino.cc/t/arduino-zero-debug-error-with-ide-2-0/1046036/6
• https://github.com/arduino/arduino-ide/issues/87