Depurando ESP32S3 com Arduino-IDE no macOS
Tags: debug, esp32, arduino, osx
Published: 2023-09-26 19:42:59

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. 

![ESP32-S3 USB Diagram](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kx92sbtahebhdybz42f0.png)

Para mais detalhes sobre o JTAG Debugging: [docs.espressif](https://docs.espressif.com/projects/esp-idf/en/v4.4/esp32s3/api-guides/jtag-debugging/index.html#configuring-esp32-s3-target)

## 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`

![JTAG plugued to MAC-OS](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0bcitvpt54va24yrk6eu.png)

> :warning: 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:

![Arduino-IDE Tools Config](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/h0paukot4u25k9ipxmt2.png)

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](https://github.com/Marus/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](https://github.com/Marus/cortex-debug/blob/master/debug_attributes.md)). 

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.

![Arduino-IDE generate lauch.json](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ueixojzhmsa25v33tenb.png)

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.

![Arduino-IDE error on open debug](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/f039c5m1cojpl6h4ykwv.png)

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…

![Arduino-IDE lauch.json path hack](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9l1vq50ulr93ryjpbtty.png)

Substitua essas configurações por estas:

```json
// 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)”.

![Arduino-IDE open settings UI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1om1h67g322yfp0248qx.png)

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`

![Arduino-IDE config gdbPath](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/m9nq9vbo2vt7vn1eo1g3.png)

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