pyOCD: Download, Instalação e Como Gravar e Depurar Cortex-M sem OpenOCD

O pyOCD é o servidor de depuração que faz o mesmo trabalho do OpenOCD para microcontroladores Arm Cortex-M, mas se instala com um único comando do Python e dispensa arquivos de configuração: você liga o ST-Link, digita pyocd list e ele já diz qual sonda e qual chip estão na bancada. Instalamos a versão atual hoje e medimos o que ela traz de fábrica. Aqui está o download certo, a instalação por sistema, os comandos de gravar e depurar, e os cinco problemas mais comuns com a correção de cada um. Última verificação: 9 de outubro de 2026.

O que é o pyOCD e para que ele serve na bancada

O pyOCD nasceu dentro da Arm, no projeto Mbed, para falar com as placas de sonda DAPLink embutida; hoje é um projeto aberto, licença Apache 2.0, e uma das ferramentas oficiais de gravação do sistema Zephyr. Ele faz três coisas: grava firmware na flash do chip, abre um servidor GDB na porta 3333 para o GDB parar e ler a placa, e lê e escreve memória e registradores direto da linha de comando, sem GDB nenhum.

A diferença prática para o OpenOCD está em quem decide o que fazer. No OpenOCD, você escolhe o arquivo da interface e o do alvo. No pyOCD, a sonda é detectada sozinha, e o chip vem de um CMSIS-Pack, o pacote que o próprio fabricante publica para o Keil, com o mapa de memória e o algoritmo de gravação de praticamente qualquer Cortex-M do mercado. Para quem repara, é a ferramenta mais rápida de pôr em pé quando chega um chip que o OpenOCD do repositório ainda não conhece.

Download oficial: três caminhos e o que cada um entrega

Existem três lugares honestos para pegar o pyOCD. Medimos cada um hoje:

Três detalhes que custam tempo. Primeiro: o pacote do PyPI é um único wheel de 14,8 MB, igual para Windows, Linux e macOS, com SHA-256 bf3f35d6…dae73b30 publicado na página do projeto. Segundo: os .zip do GitHub não são o código-fonte, são builds prontos, gerados pela esteira do projeto com PyInstaller: 36,5 MB para Windows, 49,5 MB para Linux x86-64, 42,4 MB para macOS e um quarto para Linux Arm64, caso do Raspberry Pi. Juntos somavam 1.185 downloads na data da verificação, contra 27,6 mil instalações pelo pip só no dia anterior, segundo as estatísticas do PyPI; quase ninguém sabe que existem. Terceiro: o apt do Ubuntu 24.04 e do Debian 13 entrega a 0.36.0, de 2024; só o Debian sid já tem a 0.45.0. Como a lista de chips e sondas cresce a cada versão, vale o pip.

Instalação passo a passo por sistema

Windows 10 e 11

Instale o Python pela loja da Microsoft ou pelo site python.org, marcando a opção de adicionar ao PATH. Depois, num Prompt de Comando:

python -m pip install -U pyocd
pyocd --version

A resposta deve ser 0.45.1. Driver é a parte que confunde, então vamos por sonda. ST-Link V2 ou V3: a documentação oficial diz que “nenhum driver residente precisa ser instalado para usar sondas STLink; só a libusb é necessária”, e a libusb já vem no pacote. No Windows, o driver oficial da ST (o STSW-LINK009, do nosso guia do ST-Link V2) é WinUSB, exatamente o que a libusb usa; instale-o e não troque por Zadig, senão o STM32CubeProgrammer para de enxergar a sonda. CMSIS-DAP v2 (DAPLink novo, Raspberry Pi Debug Probe, MCU-Link): sem driver no Windows 8 em diante. CMSIS-DAP v1: dispositivo HID, também sem driver, mas mais lento. J-Link: aí sim precisa do pacote da Segger instalado antes.

Linux (Ubuntu, Debian, Mint)

sudo apt install python3-pip python3-venv
python3 -m venv ~/pyocd-venv
~/pyocd-venv/bin/pip install -U pyocd
~/pyocd-venv/bin/pyocd --version

Medimos aqui, num Ubuntu 24.04: 4,5 segundos de instalação, 26 pacotes e 79 MB no disco. O ambiente virtual evita o erro externally-managed-environment que o Ubuntu novo devolve ao pip install solto. A parte que ninguém pode pular é a permissão USB: sem ela, o pyOCD vê a sonda mas não consegue abri-la. O projeto distribui sete arquivos de regras na pasta udev do repositório, cobrindo ST-Link V2, V2-1 e V3, DAPLink, Picoprobe, WCH-Link e os CMSIS-DAP da Cypress, NXP e Keil. Copie todos para /etc/udev/rules.d/, rode sudo udevadm control --reload e sudo udevadm trigger, e reconecte a sonda.

macOS

python3 -m pip install -U pyocd

A documentação é explícita: “no macOS, instalar com sudo nunca deveria ser necessário”; se o pip reclamar de permissão, o problema é a pasta do Python. ST-Link e CMSIS-DAP funcionam sem driver; J-Link pede o pacote da Segger.

O primeiro uso: listar, gravar e abrir o GDB

Com a sonda no USB e a placa ligada nela por SWD (SWDIO, SWCLK, GND e 3,3 V), o primeiro comando é sempre o mesmo:

pyocd list

Ele mostra a sonda, o número de série e, nas placas Nucleo e Discovery, até o nome da placa, porque o ST-Link embutido informa o modelo. Sem sonda, a resposta que vimos foi No available debug probes are connected. Em seguida, diga qual é o chip. Para os 205 alvos embutidos, o nome basta; para os demais, instale o pacote do fabricante uma única vez:

pyocd pack update
pyocd pack find stm32f103c8
pyocd pack install stm32f103c8

Medimos a sequência: a atualização baixou 1.820 descritores em 39 segundos, e o pack install trouxe o Keil.STM32F1xx_DFP 2.4.1, de 50,2 MB, em 4 segundos. Depois disso, pyocd list --targets passa a mostrar o stm32f103c8 com origem pack. Gravar e depurar são dois comandos:

pyocd flash -t stm32f103c8 firmware.hex
pyocd gdbserver -t stm32f103c8

O flash aceita .hex, .elf e .bin; no caso do .bin, o endereço vai colado no nome, como app.bin@0x08000000. O gdbserver abre a porta 3333; no GDB, target remote localhost:3333 conecta, load grava o ELF e monitor reset halt para o chip na primeira instrução. Para ler a placa sem GDB, o pyocd commander -t stm32f103c8 abre um console onde halt, reg e read32 0x08000000 64 param o processador, mostram os registradores e despejam o começo da flash. Essa última linha é a que resolve o reparo mais comum: ler o firmware de uma placa boa para gravar na ruim, quando o chip não está protegido contra leitura.

O que a versão 0.45.1 traz de fábrica (medido hoje)

A página inicial do projeto ainda anuncia “suporte embutido para mais de 70 dispositivos”. Contamos na instalação de hoje: 205 alvos embutidos de 19 fabricantes, sendo 59 da HDSC, 58 da NXP, 22 da Cypress, 18 da ST e 9 da Nordic, além de RP2040 e RP2350 da Raspberry Pi. Pelo índice de packs, o pyocd pack find encontra cerca de 11.300 números de peça. Os plugins de sonda são cinco: CMSIS-DAP, J-Link, Picoprobe, ST-Link e um cliente remoto, para usar a sonda de outro computador pela rede; os de sistema em tempo real são FreeRTOS, Zephyr, RTX5, ThreadX e Argon. A 0.45.0, de 15 de julho de 2026, abandonou o Python 3.8 e passou a aceitar o 3.14; quem ainda roda Windows 7 com Python antigo fica na 0.44.1.

O limite também é claro: pyOCD é só Cortex-M. O pack find esp32 devolveu “No matching devices”, porque ESP32 não é Arm; para ele, o caminho continua sendo o esptool.

Os 5 problemas mais comuns e a correção

1. “No available debug probes are connected” com a sonda no USB (Linux). É a regra udev faltando. Com pyocd list -vv aparece a linha reveladora, copiada de um chamado de janeiro de 2026: “[Errno 13] Access denied (insufficient permissions) while trying to interrogate a USB device … This can probably be remedied with a udev rule”. Instale as regras, recarregue e reconecte. Clone com ID fora da lista: o dmesg mostra o idVendor e o idProduct para você acrescentar uma linha.

2. “No backend available” (Windows ou Linux). O pyOCD não achou a libusb. Nas versões atuais ela vem no pacote libusb-package, instalado junto; o erro aparece quando o pyOCD veio dentro de outra ferramenta, caso de um chamado antigo do Mbed Studio, ou num Python de 32 bits. Reinstale com pip install -U pyocd libusb-package num Python de 64 bits.

3. “Generic ‘cortex_m’ target type is selected by default; is this intentional?” Você esqueceu o -t. Sem alvo, o pyOCD conecta no modo genérico, que, nas palavras da documentação, “permite depurar, mas não gravar a flash”, e sem mapa de memória. Passe -t nome_do_chip; se o nome não existir, pyocd pack install primeiro.

4. O ST-Link conecta, mas não enxerga o chip que não é STM32. A documentação avisa: “versões recentes do firmware do STLink só permitem acesso a alvos STM32”. É uma trava da própria ST. Para gravar um Nordic, NXP ou GigaDevice, use uma sonda CMSIS-DAP, como a Raspberry Pi Debug Probe. O firmware mínimo aceito no ST-Link é o V2J24; mais antigo, atualize pelo STM32CubeProgrammer.

5. Funcionava e parou depois do pip install -U. Acontece. Em setembro de 2026 um usuário relatou que gravação e reset de um ATSAM4L quebraram a partir da 0.44.0, e em abril outro mostrou que o pack install por prefixo parcial deixou de funcionar na mesma versão. A correção é a de qualquer ferramenta Python: pip install pyocd==0.43.1 fixa a versão que funcionava, num ambiente virtual só para isso, e você reporta o problema no GitHub com a saída de -vv.

Perguntas frequentes

pyOCD ou OpenOCD: qual usar? Se o chip é Cortex-M e você quer resultado em cinco minutos, pyOCD. Se o alvo é RISC-V, ESP32, um Arm antigo (ARM7, ARM9) ou um FPGA por JTAG, só o OpenOCD serve. Muita bancada tem os dois.

Preciso do Python para usar o pyOCD no Windows? Não, se baixar o .zip da página de releases do GitHub: é um executável empacotado que já traz o Python dentro. Com o pip, sim, Python 3.9 ou mais novo.

Dá para gravar um chip com proteção de leitura ativada? Dá para apagar: pyocd erase --chip -t nome_do_chip faz o apagamento completo e, na maioria das famílias, remove a proteção junto, perdendo o conteúdo. Ler o firmware protegido, não: nem o pyOCD nem nenhum outro programa honesto faz isso.

Veredito honesto

Para a bancada de reparo, o pyOCD é a forma mais rápida de ler, apagar e regravar um Cortex-M: um pip install, um pack install e três comandos. Ele não substitui o OpenOCD, porque para de servir fora da família Arm, e a trava de firmware do ST-Link o deixa dependente de uma sonda CMSIS-DAP para os chips que não são da ST. Quem já grava STM32 pelo STM32CubeIDE e quer o passo seguinte, parar a placa e ler o que o firmware está fazendo, tem no pyOCD mais GDB o caminho de menor atrito. No próximo guia, vamos ao sigrok-cli, o irmão de linha de comando do PulseView, para capturar o barramento da placa sem abrir janela nenhuma.

Se a sua dúvida seguinte for por onde começar a ler a placa que está esperando na bancada, o Mapa da Placa é o nosso material de leitura de placa; vale conhecer.