• Eletrônica

    Eletrônica

    Depurando a Raspberry Pi Pico em C/C++ com VS Code e MinGW para Windows (SEM Build Tools for Visual Studio!)

Raspberry Pi Pico
Raspberry Pi Pico

 

 

Introdução

Em continuação ao tutorial Raspberry Pi Pico em C/C++ com VS Code e MinGW para Windows (SEM Build Tools for Visual Studio!), este artigo pretende demonstrar como realizar a depuração de código C/C++ na Raspberry Pi Pico, usando a IDE Visual Studio Code no Microsoft Windows, e da mesma forma, sem a instalação do Build Tools for Visual Studio.

Segundo o Datasheet da Raspberry Pi Pico para o C/C++ SDK, a depuração na Raspberry Pi Pico é realizada através da utilização do protocolo SWD (Serial Wire Debug), uma variação do protocolo JTAG (Joint Test Action Group).

Para efetuar a depuração, é necessário conectar ao barramento SWD da Pico algum adaptador JTAG/SWD para USB, sendo possíveis as opções:

  • Cabo adaptador JTAG, como o Segger J-Link; ou o Olimex ARM-USB-OCD-H em conjunto com o módulo ARM-JTAG-SWD;
  • Uma Raspberry Pi 4 previamente configurada para se comunicar usando o protocolo SWD;
  • Uma outra Raspberry Pi Pico, previamente configurada com o binário (UF2) do Picoprobe.

Este tutorial se baseia na utilização de uma segunda Raspberry Pi Pico como ferramenta de depuração, configurada com o binário Picoprobe. Para utilização de qualquer outra opção JTAG/SWD relacionada acima, consulte o artigo Debugging Raspberry Pi Pico via SWD.

 

Requisitos
  • Duas Raspberry Pi Pico (uma que será usada como ferramenta de depuração Picoprobe com cabo MicroUSB para conexão ao PC; e a outra que será o alvo target da depuração);
  • Microsoft Windows 10 (64 bits de preferência). Versões anteriores, como 7 ou 8 podem até funcionar, mas não são oficialmente suportadas pela Fundação Raspberry Pi para o Pico;
  • Conexão a Internet;
  • Permissões de Administrador no Windows;
  • Ambiente de Desenvolvimento previamente configurado segundo o tutorial Raspberry Pi Pico em C/C++ com VS Code e MinGW para Windows (SEM Build Tools for Visual Studio!).

 

Sumário
  1. Compilar OpenOCD e Picotool
    • Instalar MSys2
    • Instalar Pacotes em MSys2
    • Configurar Path em MSys2
    • Compilar OpenOCD
    • Compilar Picotool
    • Copiar Binários Gerados e Configurar Path
  2. Gravar Binário do Picoprobe
  3. Instalar Driver do Picoprobe
  4. Interligar Picoprobe ao Target
  5. Depurar em Linha de Comando
  6. Configurar Visual Studio Code para Depuração
  7. Depurar Exemplo

 

Lista de Pacotes usados neste Tutorial

 

1. Compilar OpenOCD e Picotool

Para realizar a depuração via SWD/JTAG na Raspberry Pi Pico, é necessária uma versão modificada do OpenOCD, além dos utilitários Picotool e GDB.

No caso do Sistema Operacional GNU/Linux, a compilação dos utilitários OpenOCD e Picotool é facilmente realizada com o kit de ferramentas padrão GCC/Autotools/CMake.

Já para o Microsoft Windows, a compilação desses utilitários requer um ambiente de construção mais complexo, que vai além do compilador MinGW e CMake demonstrados no tutorial Raspberry Pi Pico em C/C++ com VS Code e MinGW para Windows (SEM Build Tools for Visual Studio!). Ferramentas como o GNU/Autotools não são instaladas no referido tutorial.

Para suprir essa necessidade de um ambiente de compilação mais robusto, optou-se aqui pela instalação da ferramenta MSys2, e de alguns pacotes de seus repositórios.

 

1.1. Instalar MSys2

MSys2 é uma coleção de ferramentas e bibliotecas que fornecem um ambiente fácil de usar, para construir, instalar e executar software nativo para Microsoft Windows. Ele oferece um terminal (linha de comando) semelhante ao console do GNU/Linux, diversos comandos e utilitários padrão POSIX e GNU, e um instalador de pacotes semelhante ao da distribuição Arch Linux, o Pacman.

Para instalar o MSys2, faça download da versão mais recente do pacote instalador em msys2.org. Neste tutorial, foi usada a versão msys2-x86_64-20210419.exe.

Execute o instalador. Digite a pasta de instalação desejada (caminho curto sem acentos, sem espaços, sem links simbólicos, sem subdiretórios ou unidades de rede).

MSys2 Install
Caminho de instalação do MSys2


Quando terminar, marque Run MSYS2 64bit now.

MSys2 Install
Opções de instalação do MSys2

 

1.2. Instalar Pacotes em MSys2
  1. Primeiro, atualize o banco de dados do pacote e os pacotes básicos. No console aberto, execute o comando:
    pacman -Syu
  2. Após fechar o console do MSys2, reabra através do atalho no Menu Iniciar, e execute os comandos:
    1. pacman -Sy
    2. pacman -Su
  3. Instale os pacotes para compilação, executando o comando:
    pacman -S mingw-w64-x86_64-toolchain git make libtool pkg-config autoconf automake texinfo git
  4. Ao ser questionado sobre quais membros de mingw-w64-x86_64-toolchain devem ser instalados, aperte Enter para instalar todos (default).
  5. Ao ser questionado sobre um conflito entre pkg-config e pkgconf, escolha a opção Y (Remove pkgconf).
    O download e a instalação dos pacotes levarão bastante tempo.
  6. Instale a LibUSB:
    Nota: Há um problema relatado com a versão 1.0.24 da LibUSB no MSys2. Ela provoca uma falha de segmentação ao executar o OpenOCD ou o Picotool. Desta maneira, será instalada manualmente a versão 1.0.23, e deve-se evitar a execução de pacman -Su para atualizar a LibUSB após esta instalação manual. Para maiores informações, consulte este Post no Fórum da Raspberry Pi.
    Execute os comandos:
    1. cd ~
    2. wget http://repo.msys2.org/mingw/x86_64/mingw-w64-x86_64-libusb-1.0.23-1-any.pkg.tar.xz
    3. pacman -U mingw-w64-x86_64-libusb-1.0.23-1-any.pkg.tar.xz

 

1.3. Configurar Path em MSys2

Para compilar o utilitário Picotool, é necessário que o CMake esteja previamente instalado, conforme explicado no item 6 (Instalar CMake) do tutorial Raspberry Pi Pico em C/C++ com VS Code e MinGW para Windows (SEM Build Tools for Visual Studio!). Além disso, seguindo o mesmo tutorial, item 9 (Baixar Repositório Pico C SDK e Exemplos) e item 10 (Atualizar Variáveis de Ambiente), é necessário que os fontes do repositório C SDK estejam instalados e com a variável PICO_SDK_PATH devidamente configurada.

Com o CMake instalado seguindo as instruções apresentadas, é preciso adicioná-lo à variável de ambiente PATH do MSys2. Para isso, siga os passos:

  1. No terminal do MSys2, abra o arquivo ~/.bashrc, desta forma: nano ~/.bashrc
  2. Ao final do arquivo, adicione a linha PATH=${PATH}:/c/pico/cmake/bin
  3. Salve o arquivo <Ctrl + O> e feche <Ctrl + X> o editor, e execute source ~/.bashrc
  4. Agora será possível executar e obter o retorno de cmake --version

 

1.4. Compilar OpenOCD

Para baixar o OpenOCD do repositório da Pico e compilar, feche o terminal do MSys2, e reabra outro, através do Menu Iniciar do Windows, usando o atalho MSYS2 MinGW 64-bit. Execute os comandos:

  1. cd /c/pico/
  2. git clone https://github.com/raspberrypi/openocd.git --branch picoprobe --depth=1
  3. cd openocd
  4. ./bootstrap
  5. ./configure --enable-picoprobe --disable-werror
  6. make

 

1.5. Compilar Picotool

Para baixar o Picotool do repositório da Pico e compilar, utilize o terminal aberto MSYS2 MinGW 64-bit. Execute os comandos:

  1. cd /c/pico
  2. git clone -b master https://github.com/raspberrypi/picotool.git
  3. cd picotool
  4. mkdir build
  5. cd build
  6. cmake -G "Unix Makefiles" -DPC_LIBUSB_INCLUDEDIR="/mingw64/include/libusb-1.0" ..
  7. make

 

1.6. Copiar Binários Gerados e Configurar Path

Para colocar os binários gerados em um único lugar, execute os comandos no MSys2:

  1. mkdir -p /c/pico/debug/bin
  2. cp /mingw64/bin/libusb-1.0.dll /c/pico/debug/bin/
  3. cp /mingw64/bin/libgcc_s_seh-1.dll /c/pico/debug/bin/
  4. cp /mingw64/bin/libwinpthread-1.dll /c/pico/debug/bin/
  5. cp /mingw64/bin/libstdc++-6.dll /c/pico/debug/bin/
  6. cp /c/pico/openocd/src/openocd.exe /c/pico/debug/bin/
  7. cp -Rf /c/pico/openocd/tcl /c/pico/debug/bin/
  8. cp /c/pico/picotool/build/picotool.exe /c/pico/debug/bin/

Para configurar a variável PATH e tornar esses binários acessíveis por ferramentas externas, siga as instruções:

Atualizando o MSys2:

  1. No terminal do MSys2, abra o arquivo ~/.bashrc, desta forma: nano ~/.bashrc
  2. Ao final do arquivo, altere a linha que contém PATH para PATH=${PATH}:/c/pico/cmake/bin:/c/pico/debug/bin
  3. Salve o arquivo <Ctrl + O> e feche <Ctrl + X> o editor, e execute source ~/.bashrc
  4. Agora será possível executar e obter o retorno de openocd --version e de picotool

Atualizando o PATH do Windows:

  1. Procure na Barra de Pesquisa do Windows pela palavra env. Escolha a opção Editar as variáveis de ambiente do sistema, e clique em Variáveis de Ambiente...
  2. Adicione ao Path: C:\pico\debug\bin
  3. Agora será possível abrir um Prompt de Comandos do Windows, e executar e obter o retorno de openocd --version e de picotool

 

2. Gravar Binário do Picoprobe

O download do binário do Picoprobe pode ser realizado através do link picoprobe.uf2, e deverá ser gravado na Raspberry Pi Pico que será usada como adaptador SWD/USB (JTAG) de debug.

Para transferir o binário para a Raspberry Pi Pico, se faz necessário apertar o botão BOOTSEL da placa enquanto o cabo USB é conectado entre a placa e o PC.

Ao entrar em modo de bootloader, a Raspberry Pi Pico cria uma unidade de armazenamento de massa (como se fosse um pendrive), onde o arquivo UF2 deverá ser gravado.

O Microsoft Windows mapeia a Raspberry Pi Pico então, como uma letra de unidade (que pode variar conforme o número de drives de armazenamento presentes no Sistema). Por exemplo, pode ser a unidade E:

Para gravar então o binário picoprobe.uf2, basta executar o comando no terminal do MSys2 (ou arrastar o arquivo UF2 para a janela do Windows Explorer aberta para a unidade da Pico, por exemplo, E:):

cp ~/picoprobe.uf2 /e/

 

3. Instalar Driver do Picoprobe

O Microsoft Windows não possui um driver nativo para enviar comandos via USB para a Pico através do Picotool. Por esse motivo, é necessária a instalação de um driver manualmente.

Para fazer isso, acesse Zadig, USB driver installation made easy, e faça download da útima versão. Neste tutorial, foi usada a versão zadig-2.5.exe. Siga os passos:

  1. Coloque a placa Pico no modo bootloader (pressione e segure BOOTSEL e conecte o cabo USB). Ela deve ser enumerada como uma unidade de armazenamento de massa;
  2. Execute o Zadig. Escolha o menu Options / List All Devices;
  3. O combo de seleção (menu suspenso) deve exibir dois dispositivos Pico: RP2 Boot (Interface 0) e RP2 Boot (Interface 1). Selecione RP2 Boot (Interface 1);
  4. O driver deve ser listado como (NONE) ou (WinUSB). Selecione a opção libusb-win32 como o driver de substituição. Clique em Install Driver ou Replace Driver. Quando estiver pronto, o Zadig exibirá o driver corrente como libusb-win32.

Zadig
Zadig


Feito isso, ainda com com a Pico conectada no modo bootloader, através de um console do MSys2 ou de um Prompt de Comandos do Windows, será possível executar o comando picotool info com sucesso.

Após isso, será necessário instalar o driver correto para a Picoprobe. Siga os passos:

  1. Desconecte e reconecte o cabo USB para que a Pico saia do modo bootloader;
  2. Execute o Zadig. Escolha o menu Options / List All Devices;
  3. O combo de seleção (menu suspenso) deve exibir dois dispositivos Picoprobe: Picoprobe (Interface 0) e Picoprobe (Interface 2). Selecione Picoprobe (Interface 2);
  4. O driver deve ser listado como (NONE) ou (WinUSB). Selecione a opção libusb-win32 como o driver de substituição. Clique em Install Driver ou Replace Driver. Quando estiver pronto, o Zadig exibirá o driver corrente como libusb-win32.

Zadig
Zadig


O Zadig também poderá ser usado para consertar o driver, caso o Windows atribua um driver errado ao dispositivo da Pico. Para isso, siga os passos:

  1. Coloque a Pico no modo bootloader;
  2. Abra o Gerenciador de Dispositivos do Windows, e clique em Exibir / Dispositivos por contêiner;
  3. Expanda RP2 Boot;
  4. Para todas as entradas em RP2 Boot:
    • Clique com o botão direito na entrada;
    • Selecione Desinstalar Dispositivo;
    • Marque Excluir o software do driver para este dispositivo;
    • Clique em Desinstalar.
  5. Desconecte o cabo USB da Pico;
  6. Segure o botão BOOTSEL e conecte-o novamente, para colocá-lo no modo bootloader;
  7. O Windows deve reinstalar automaticamente todos os drivers corretos.

 

4. Interligar Picoprobe ao Target

Segundo o Datasheet da Raspberry Pi Pico para o C/C++ SDK, a conexão entre a Picoprobe e a Pico Target (alvo da depuração) deve ser realizada conforme o esquema a seguir:

Picoprobe
Conexão entre Picoprobe e Target


Note que nesse caso, a placa Target (alvo da depuração) está sendo alimentada pela Picoprobe, através dos pinos 39 (VSYS) e 38 (GND), e dispensa conexão através do cabo USB. A conexão entre os pinos 39 (VSYS) poderá ser removida, caso as duas placas sejam alimentadas independentemente por dois cabos microUSB conectados ao PC (ou se o da placa Target estiver conectado a um carregador/fonte de 5V). E a conexão entre os pinos 38 (GND) pode ser substituída por uma conexão com quaisquer outros pinos GND das placas Pico.

 

5. Depurar em Linha de Comando

Para realizar a depuração de um programa C/C++ para a Pico, é necessário que o pacote de compiladores GNU ARM Embedded Toolchain esteja instalado. Isso pode ser feito seguindo o tutorial Raspberry Pi Pico em C/C++ com VS Code e MinGW para Windows (SEM Build Tools for Visual Studio!).

Para configurar a variável PATH e tornar os binários do pacote GNU ARM Embedded Toolchain acessível pelo MSys2, siga as instruções:

  1. No terminal do MSys2, abra o arquivo ~/.bashrc, desta forma: nano ~/.bashrc
  2. Ao final do arquivo, altere a linha que contém PATH para PATH=${PATH}:/c/pico/cmake/bin:/c/pico/debug/bin:"/c/pico/gcc-arm/10 2020-q4-major/bin"
  3. Salve o arquivo <Ctrl + O> e feche <Ctrl + X> o editor, e execute source ~/.bashrc
  4. Agora será possível executar e obter o retorno de arm-none-eabi-gdb --version

Partindo do programa Blink, presente no Repositório de Exemplos da Pico, já compilado e executando no Target (cujo arquivo UF2 gerado foi gravado na placa Target), para se efetuar a depuração, execute o seguinte comando, em um console do MSys2:

  1. openocd -f /c/pico/debug/bin/tcl/interface/picoprobe.cfg -f /c/pico/debug/bin/tcl/target/rp2040.cfg -s /c/pico/debug/bin/tcl

Abra outro console do MSys2 e execute:

  1. arm-none-eabi-gdb /c/pico/pico-examples/build/blink/blink.elf

Dentro do GDB, os seguintes comandos permitem a execução do código:

  1. target remote localhost:3333
  2. load
  3. monitor reset init
  4. continue

Desta forma, é possível a depuração via linha de comando, usando o GDB. Entretanto, como o objetivo do tutorial é realizar a depuração através de uma IDE, o próximo passo demonstra como configurar o Microsoft Visual Studio Code para realizar essa tarefa. Apesar disso, nada impede o uso de quaisquer outras IDE's que sejam compatíveis como frontend para o GDB.

 

6. Configurar Visual Studio Code para Depuração

Supondo que o Visual Studio Code já tenha sido instalado e configurado segundo o tutorial Raspberry Pi Pico em C/C++ com VS Code e MinGW para Windows (SEM Build Tools for Visual Studio!), é necessário instalar somente mais uma Extensão: Cortex-Debug.

Cortex-Debug
Extensão Cortex-Debug no Visual Studio Code


Em Extension Settings dessa extensão, clique em Edit in settings.json.

Cortex-Debug
Configurações da Extensão Cortex-Debug


Altere cortex-debug.gdbPath para "arm-none-eabi-gdb" e cortex-debug.openocdPath para "c:/pico/debug/bin/openocd.exe", adicione as linhas a seguir, e salve.

  1. "cmake.statusbar.advanced": {
  2.   "debug": {
  3.     "visibility": "hidden"
  4.   },
  5.   "launch": {
  6.     "visibility": "hidden"
  7.   }
  8. }

Cortex-Debug
Configurações da Extensão Cortex-Debug


Na aba Run and Debug, clique em create a launch.json file e selecione a opção Cortex-Debug no menu suspenso.

Debug
Configurações de Debug do Visual Studio Code


Adicione e/ou altere os valores dentro de configurations:

  1. "executable": "${workspaceRoot}/build/blink/blink.elf",
  2. "servertype": "openocd",
  3. "device": "Pico2040",
  4. "configFiles": [
  5.     "interface/picoprobe.cfg",
  6.     "target/rp2040.cfg"
  7. ],
  8. "searchDir": [
  9.     "c:/pico/debug/bin/tcl"
  10. ]

Debug
Configurações de Launch do Debug


 

7. Depurar Exemplo

Para depurar o exemplo Blink, basta abrir o código-fonte em pico-examples/blink/blink.c, colocar algum breakpoint onde desejar, clicar no botão Cortex Debug (pico-examples), e selecionar a opção Cortex Debug no menu suspenso. Se desejar destacar também a sintaxe dos arquivos assembly (*.s), opcionalmente poderá ser instalada alguma extensão como a ARM (que dá suporte a destaque de sintaxe de instruções/mnemônicos para processadores ARM).

Debug
Depurando Projeto Blink no Visual Studio Code


No caso de um projeto com múltiplos alvos (como é o pico-examples), para mudar o programa a ser depurado, é necessário alterar a propriedade executable em launch.json, para apontar para outro binário.

 

Considerações Finais

O ambiente de depuração proposto neste tutorial, com um pouco de esforço, fica completamente funcional e utilizável, mesmo dentro do Sistema Operacional Microsoft Windows. Como demonstrado, o Windows não possui nativamente todas as ferramentas necessárias para desenvolvimento de software em geral, quanto menos para software embarcado, cross-compiler ou depuração remota.

Por isso, por questões de performance e facilidade de configuração, ainda é fortemente recomendado o uso do Sistema Operacional GNU/Linux para esse tipo de desenvolvimento.

Apesar de tudo isso, este tutorial serve como uma demonstração do vasto uso de ferramentas de software livre (opensource), como auxílio a desenvolvedores de software embarcado, firmware e Internet das Coisas (IoT), e da aplicação da versátil placa Raspberry Pi Pico.

 

Referências e Bibliografia

ARM Developer. GNU Arm Embedded Toolchain Downloads. 2020.
https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads

CMAKE. Get the Software (CMake). 2001.
https://cmake.org/download/

HYMEL, Shawn. How to Build OpenOCD and Picotool for the Raspberry Pi Pico on Windows. 2021.
https://shawnhymel.com/2168/how-to-build-openocd-and-picotool-for-the-raspberry-pi-pico-on-windows/

MARTINS, Robson. Raspberry Pi Pico em C/C++ com VS Code e MinGW para Windows (SEM Build Tools for Visual Studio!). 2021.
https://robsonmartins.com/content/eletr/raspi/pico/csdkwin.php

MICROSOFT. Ferramentas de Build para Visual Studio 2019. 2019.
https://visualstudio.microsoft.com/pt-br/downloads/#build-tools-for-visual-studio-2019

MICROSOFT. Visual Studio Code. 2015.
https://code.visualstudio.com/

MSYS2. Software Distribution and Building Platform for Windows. 2017.
https://www.msys2.org/

RASPBERRY Pi. Getting started with Raspberry Pi Pico. 2020.
https://datasheets.raspberrypi.org/pico/getting-started-with-pico.pdf

RASPBERRY Pi. Raspberry Pi Pico: Product Home Page. 2020.
https://www.raspberrypi.org/products/raspberry-pi-pico/

RASPBERRY Pi. Raspberry Pi Pico C SDK. 2020.
https://github.com/raspberrypi/pico-sdk

RASPBERRY Pi. Raspberry Pi Pico Examples. 2020.
https://github.com/raspberrypi/pico-examples

RASPBERRY Pi. Raspberry Pi Pico OpenOCD. 2020.
https://github.com/raspberrypi/openocd

RASPBERRY Pi. Raspberry Pi Pico Picoprobe. 2020.
https://www.raspberrypi.org/documentation/rp2040/getting-started/static/fec949af3d02572823529a1b8c1140a7/picoprobe.uf2

RASPBERRY Pi. Raspberry Pi Pico Picotool. 2020.
https://github.com/raspberrypi/picotool

RASPBERRY Pi. Windows openocd/picotool segfault, in: Raspberry Pi Forum. 2021.
https://www.raspberrypi.org/forums/viewtopic.php?f=145&t=303394&p=1816920

SYSPROGS. Debugging Raspberry Pi Pico via SWD. 2021.
https://visualgdb.com/documentation/embedded/raspberry/pico/swd/

ZADIG. USB driver installation made easy. 2013.
https://zadig.akeo.ie


Todos os sites foram visitados em 14/05/2021.

 

Robson Martins - 05/2021
http://www.robsonmartins.com

 

Todos os autores e fabricantes aqui citados, com seus devidos créditos.

As marcas citadas podem ser registradas e são propriedade de seus fabricantes/detentores.

O conteúdo deste projeto/site pode ser livremente distribuído, desde que o(s) nome(s) do(s) autor(es) seja(m) mantido(s). É proibida a comercialização ou apropriação de qualquer conteúdo aqui descrito.

O(s) autor(es) dos projetos não se responsabiliza(m) por danos pessoais ou a equipamentos, provocados por mau uso das informações aqui contidas ou por imperícia dos usuários.

Qualquer projeto que envolva componentes eletrônicos deve ser realizado somente por pessoas capacitadas e conscientes dos riscos de segurança envolvidos e de como preveni-los (como choques elétricos, incêndio, explosões, queimaduras, danos a equipamentos, etc.).

As informações aqui descritas são oferecidas sem nenhuma garantia e nem suporte técnico por parte do(s) autor(es) e fabricante(s) citado(s), e devem ser usadas somente para fins educacionais/didáticos, sem nenhum compromisso com aplicações críticas (suporte de vida, por exemplo).


Política de Privacidade.
Termos e Condições.