O OpenOCD é o programa livre que faz a ponte entre o seu computador e o microcontrolador soldado na placa: com ele e um ST-Link V2 de trinta reais você lê a memória de um STM32, grava firmware novo e para o processador no meio da execução. Baixamos o código oficial, conferimos a assinatura, instalamos o pacote pronto e medimos a diferença entre os dois — ela é maior do que qualquer tutorial em português avisa. Aqui está o download oficial, a instalação por sistema, o primeiro serviço de verdade e os cinco problemas que mais travam a bancada. Última verificação: 7 de outubro de 2026.
O que é o OpenOCD e para que ele serve
O nome é a descrição: Open On-Chip Debugger, depurador aberto de dentro do chip. Ele conversa com o adaptador plugado no USB — ST-Link, J-Link, CMSIS-DAP, uma plaquinha FTDI, até os pinos de um Raspberry Pi — e por meio dele fala com o núcleo do microcontrolador por JTAG ou SWD, abrindo duas portas na sua máquina: a 4444, para comandos por telnet, e a 3333, para o GDB.
Na bancada isso vale por três coisas: backup do firmware antes de mexer, gravação sem o programa do fabricante e diagnóstico de placa travada. É também o motor escondido de várias IDEs: quando o STM32CubeIDE grava a sua placa, quem fala com o ST-Link ali embaixo é um OpenOCD adaptado.
Download oficial: a versão que ninguém te conta
Aqui começa a parte que nenhum tutorial brasileiro conta. O último lançamento estável do OpenOCD é a versão 0.12.0, de 14 de janeiro de 2023, e a última notícia no site oficial é o anúncio dessa mesma versão, em 3 de março de 2023. Olhando só para isso, qualquer um conclui que o projeto morreu.
Não morreu — e esse é o ponto. Medimos hoje, pela API do GitHub: o ramo principal está 1.728 commits à frente da 0.12.0, e o último deles é de 23 de setembro de 2026. O projeto está vivo e andando rápido; o que ele não faz há quase quatro anos é lançar uma versão numerada. Quem instala pelo caminho óbvio fica com o código de 2023.
| De onde vem | O que você recebe | Para quem |
|---|---|---|
apt install openocd (Ubuntu 24.04 LTS) |
0.12.0, código de jan/2023 | quem quer resolver em 10 segundos |
| openocd-0.12.0.tar.bz2 (código oficial) | o mesmo código, com assinatura | quem vai compilar |
| xPack OpenOCD (binários prontos) | Windows, macOS e Linux — e código de set/2025 | a maioria das bancadas |
| openocd-esp32 (Espressif) | versão de 31/08/2026, só para ESP32 | quem trabalha com ESP32 |
git clone https://github.com/openocd-org/openocd |
o que está sendo escrito agora | quem precisa de chip novo na lista |
Repare na terceira linha: é a armadilha mais bem-disfarçada da lista. O pacote chamado “xPack OpenOCD 0.12.0-7” não é a 0.12.0. O próprio anúncio de lançamento, de 5 de outubro de 2025, declara que ele é construído “a partir do commit de desenvolvimento e5888bda38f4952e2ae92f7dc5b25fc9a2d1c2b3, de 30 de setembro de 2025” — o número diz 2023, o código é de 2025. Quem descarta esse pacote pelo “0.12.0” no nome joga fora dois anos e meio de correções.
A segunda surpresa é o que o projeto publica por conta própria: o único binário oficial é um pacote Windows de 32 bits. O instantâneo mais recente, de 4 de outubro de 2026, chama-se openocd-8da0578-i686-w64-mingw32.tar.gz, tem 6.113.573 bytes e havia sido baixado 32 vezes quando olhamos. Para Linux e macOS não existe binário oficial nenhum — por isso o próprio site lista os empacotadores de terceiros.
Como conferir que o arquivo é legítimo
O código-fonte oficial vem com SHA-256 publicado e com assinatura digital. Fizemos o caminho inteiro hoje, e ele tem uma pegadinha:
curl -LO https://downloads.sourceforge.net/project/openocd/openocd/0.12.0/openocd-0.12.0.tar.bz2
curl -LO https://downloads.sourceforge.net/project/openocd/openocd/0.12.0/openocd-0.12.0.tar.bz2.sig
sha256sum openocd-0.12.0.tar.bz2
gpg --keyserver hkps://pgpkeys.eu --recv-keys 3E8D4B26AADC9DA108082673AA2DC2AEA5F3DB56
gpg --verify openocd-0.12.0.tar.bz2.sig openocd-0.12.0.tar.bz2O número que medimos — af254788…075afa — bateu com o arquivo .sha256 publicado ao lado do pacote. A assinatura respondeu Good signature em nome de Paul Fertser, um dos mantenedores históricos. A pegadinha: essa chave não está nos dois servidores que todo mundo usa — nem keys.openpgp.org nem keyserver.ubuntu.com a devolvem; só achamos no pgpkeys.eu, o endereço da linha acima. E, por honestidade, é uma chave DSA de 1024 bits criada em 2007, tamanho hoje considerado fraco: a conferência que vale sempre é a do SHA-256. Que quase ninguém faz, aliás — os três formatos do código-fonte somam 301.555 downloads, e os arquivos de checksum ao lado deles, 193.
O que o “apt install” deixa de fora
Instalar pela distribuição funciona — mas convém saber o que fica de fora. Contamos os arquivos de configuração da 0.12.0 e do ramo atual, e conferimos com o que o pacote instalou aqui.
São 96 alvos a mais (de 306 para 402), 24 adaptadores e 81 placas a mais no código atual — e a lista do que falta não é exótica. Faltam os ESP32-C3, C6, C2 e H2, justamente os ESP32 de núcleo RISC-V que estão em tudo hoje; faltam os clones chineses de STM32 das placas baratas, Geehy APM32 e Artery AT32F4x; faltam os Bouffalo BL602, BL616 e BL702. O arquivo de permissões do Linux também cresceu: de 100 para 125 identificadores de adaptadores USB.
Traduzindo: STM32 original, ESP32 clássico ou Cortex-M comum, o pacote da distribuição resolve; chip novo, ESP32-C3 ou clone chinês, você precisa do xPack ou do código atual. Vale a lição do NeoProgrammer e do flashrom: “não reconhece o chip” quase nunca é defeito da placa, é idade do programa.
Instalação, sistema por sistema
Linux (Debian, Ubuntu e derivados). Um comando resolve, e o segundo é o que ninguém faz:
sudo apt install openocd
sudo cp /usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d/
sudo udevadm control --reload
sudo usermod -aG plugdev $USER # saia e entre na sessão depois distoSem a segunda linha, o adaptador só funciona com sudo: no Ubuntu 24.04 o pacote traz o arquivo de regras e não o instala por você.
Windows. Não existe instalador: baixe o .zip do xPack, descompacte numa pasta sem acentos nem espaços (C:openocd) e acrescente a subpasta bin ao PATH. Falta ainda o driver — e aqui o manual oficial faz algo raro: desiste. A frase está lá, em inglês: “MS-Windows needs complex and confusing driver configuration for every peripheral” (“o MS-Windows precisa de configuração de driver complexa e confusa para cada periférico”), e avisa que não vai detalhar o assunto. Na prática: ST-Link usa o driver da ST, e adaptadores genéricos exigem trocar o driver para WinUSB com o Zadig.
macOS. Também pelo xPack ou pelo Homebrew, com pacote para Intel e Apple Silicon. Compilar o código atual, para quem precisa de chip novo: git clone, ./bootstrap, ./configure --enable-stlink, make -j4 e sudo make install.
O primeiro serviço: ler e gravar um STM32 com ST-Link V2
São quatro fios, do ST-Link para o conector lateral da placa: SWDIO com SWDIO, SWCLK com SWCLK, GND com GND e 3,3 V com 3,3 V. Nunca ligue o 5 V do ST-Link no 3,3 V da placa. Com os fios no lugar, o teste de vida é uma linha só:
openocd -f interface/stlink.cfg -f target/stm32f1x.cfgSe aparecer o código de identificação do chip e a palavra halted, está conversando. Deixe a janela aberta — ela é o servidor — e, em outro terminal, telnet localhost 4444 abre a linha de comando do OpenOCD. O primeiro comando de qualquer serviço honesto é o backup:
reset halt
dump_image backup.bin 0x08000000 0x10000
flash write_image erase novo.bin 0x08000000
reset runPara gravar um arquivo compilado sem abrir o telnet, há o atalho que o manual chama de ajudante:
openocd -f interface/stlink.cfg -f target/stm32f1x.cfg
-c "program firmware.elf verify reset exit"Ele grava, confere, reinicia a placa e sai. Troque stm32f1x.cfg pelo arquivo do seu chip — stm32f4x.cfg, stm32g0x.cfg, nrf52.cfg; a lista inteira está na pasta target.
Os cinco problemas que mais aparecem
1. “Error: open failed”. É a mensagem exata que reproduzimos com o adaptador fora do USB — está na captura acima. O OpenOCD não achou o adaptador: ou não está plugado, ou falta permissão (Linux, as regras udev acima), ou falta driver (Windows). Rodar com sudo confirma o diagnóstico em dois segundos: se funciona com sudo e não funciona sem, é permissão, não hardware.
2. “interface/stlink-v2.cfg is deprecated”. O aviso aparece porque metade dos tutoriais ainda manda usar stlink-v2.cfg. Use interface/stlink.cfg, que serve para V1, V2, V2-1 e V3. Detalhe que importa: na 0.12.0 esse arquivo usa o driver antigo, o HLA — nossa saída mostra o programa escolhendo sozinho o transporte hla_swd. No código atual ele passou ao driver nativo do ST-Link, e o arquivo do modo antigo avisa que “o suporte ao transporte HLA será removido em breve”, pedindo firmware V2J24 (2015) ou mais novo no adaptador.
3. “unable to connect to the target”. O adaptador foi encontrado, o chip não respondeu: BOOT0 na posição errada, placa sem alimentação, fio de SWD longo demais — ou, caso clássico de STM32, firmware que desliga os pinos de depuração logo no início. Para esse último o manual indica conectar com o chip já em reset, citando o STM32 nominalmente: -c "reset_config srst_only srst_nogate connect_assert_srst". Antes disso, tente -c "adapter speed 100".
4. “Error: stm32x device protected”. A proteção de leitura está ligada — foi o fabricante do aparelho que a ativou para você não copiar o firmware. O comando stm32f1x unlock 0 destrava, mas apaga a memória inteira: sem o firmware para regravar, não mexa.
5. ESP32-C3 (e parentes) não reconhecidos. Não é erro seu: esses alvos não existem na 0.12.0, como medimos. Use a versão da Espressif, com binário pronto para os três sistemas e lançada em 31 de agosto de 2026. Para só gravar firmware em ESP32, sem depurar, continua mais simples o esptool.
Onde comprar: para começar, o trio é adaptador, fios e uma placa de treino — e vale aprender num STM32 barato antes de encostar na placa do cliente.
Como Associados da Amazon, recebemos por compras qualificadas feitas pelos links acima — você não paga nada a mais por isso, e ajuda o site a continuar gratuito.
Perguntas frequentes
O OpenOCD é gratuito mesmo? É software livre sob GPL v2: sem versão paga, sem cadastro, sem limite de uso comercial.
Devo usar a 0.12.0 ou o código atual? Comece pelo xPack, fácil de instalar e já com código de setembro de 2025. Só compile o ramo atual se o seu chip não aparecer na lista.
Funciona com ST-Link clone de 30 reais? Funciona, e é o que a maioria usa. O que atrapalha não é o preço, é firmware antigo no adaptador.
Serve para gravar BIOS de notebook? Não. BIOS é memória SPI externa, e o programa certo é o flashrom. O OpenOCD fala com o núcleo do processador, não com memória solta na placa.
O resumo que cabe na bancada
O OpenOCD transforma um adaptador de trinta reais num gravador e num depurador de verdade, em qualquer sistema, sem licença. O que confunde todo mundo é o número da versão — e agora você sabe a história inteira: a última versão numerada é de 2023, o código continua andando todo dia, e o binário que vale a pena baixar é o que diz “0.12.0” no nome mas foi compilado dois anos e meio depois.
A regra prática é curta: pacote da distribuição para chip comum, xPack para o resto, backup antes de qualquer gravação, SHA-256 conferido. No próximo guia, o outro lado da mesma mesa: o GDB na bancada — como parar um firmware travado no ponto exato e ler o que a placa estava fazendo na hora da pane.
Veja também
- ST-Link V2: driver e STM32CubeProgrammer — o caminho oficial da ST, e como atualizar o firmware do adaptador.
- STM32CubeIDE: download, instalação e o primeiro projeto — a IDE que usa o OpenOCD por baixo.
- flashrom no Linux: gravar BIOS e EEPROM — a ferramenta irmã, para memória externa.
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.
