sigrok-cli: Download, Instalação e Como Capturar e Decodificar pelo Terminal

O sigrok-cli é a versão de linha de comando do PulseView: o mesmo motor de captura e os mesmos decodificadores de protocolo, mas sem janela nenhuma. Você digita um comando, o analisador lógico USB de 8 canais grava o barramento da placa, e os bytes de UART, I²C ou SPI aparecem direto no terminal ou num arquivo. Instalamos o pacote hoje, abrimos o instalador oficial de Windows peça por peça e decodificamos duas capturas de verdade; abaixo, o download certo, a instalação por sistema e os cinco problemas mais comuns. Última verificação: 10 de outubro de 2026.

O que é o sigrok-cli e quando ele vale mais que o PulseView

O projeto sigrok tem três camadas: a libsigrok conversa com o hardware (171 drivers na versão que o Ubuntu instala, contados por nós), a libsigrokdecode traduz os sinais em protocolos (111 decoders), e por cima ficam os dois programas, PulseView para quem quer ver a forma de onda e sigrok-cli para quem quer o resultado em texto. Os dois são GPL e usam os mesmos arquivos .sr, então uma captura feita no terminal abre no PulseView e vice-versa.

A analogia é a do multímetro com registro: o PulseView é o display, o sigrok-cli é o datalogger. Ele vale mais quando a captura precisa rodar por minutos sem ninguém olhando, quando o computador é um Raspberry Pi sem interface gráfica, ou quando a mesma captura vai se repetir dez vezes e dá para deixar o comando num script. A página oficial resume: ele “não mostra saída gráfica, mas é suficiente para rodar o processo inteiro de inicialização do hardware, aquisição, decodificação de protocolo e gravação da sessão”.

Download oficial do sigrok-cli

Baixe só da página Downloads do sigrok.org; não hospedamos nenhum arquivo. Como no PulseView, há duas linhas, e a oficial recomenda a nightly (“recomendada, sempre atualizada”). A diferença aqui é maior do que parece: a release 0.7.2 foi lançada em 1º de março de 2021 (arquivo NEWS do código-fonte) e carrega a libsigrok 0.5.2, de dezembro de 2019. A nightly é recompilada toda madrugada; a de hoje saiu às 4h25 pelo horário de Greenwich.

Há versões de 32 bits do Windows e do AppImage. O sigrok não publica checksum nem assina os binários: lemos o instalador nightly de 64 bits e o sigrok-cli.exe de dentro dele com o pefile, e a tabela de assinatura Authenticode dos dois tem zero bytes; o Windows vai mostrar o aviso de editor desconhecido, e isso é esperado. Para o código-fonte da 0.7.2, que não muda mais, o SHA-256 do tarball que baixamos hoje é 71d0443f36897bf565732dec206830dbea0f2789b6601cf10536b286d1140ab8. A nightly muda todo dia, então baixar do domínio sigrok.org, e nunca de espelhos, é a única garantia que existe.

Instalação passo a passo por sistema

Windows: o instalador já traz o Zadig

Abrimos o instalador nightly de 64 bits com o 7-Zip: são 359 arquivos e 56,1 MB instalados, e dentro vêm zadig.exe e zadig_xp.exe, 19 arquivos de firmware (o fx2lafw do clone de Saleae, do Hantek 6022BE e outros), 132 pastas de decoders, 15 capturas de exemplo e um Python 3.4 embutido para rodar os decoders. Instale com o padrão e depois faça o passo que a página Windows da wiki trata como obrigatório: o driver do fabricante “não vai funcionar em quase todos os casos”, é preciso trocar para o WinUSB com o Zadig, que fica no menu Iniciar, na pasta do sigrok. O clone de 8 canais aparece como USB ID 0925:3881; selecione-o, escolha WinUSB e clique em Replace Driver.

Linux: apt ou AppImage, e as regras do udev

No Ubuntu 24.04 e no Debian 13, sudo apt install sigrok-cli sigrok-firmware-fx2lafw baixa 984 kB e ocupa 3,9 MB. Esse pacote é a 0.7.2 sobre a libsigrok 0.5.2 de 2019; se o seu analisador for mais novo que isso (medimos a diferença adiante), use o AppImage da nightly (chmod +x e rodar). Nos dois caminhos, o README.devices da libsigrok é claro: para acessar o analisador sem sudo, precisa das regras do udev. O apt já instala as três: 60-libsigrok.rules (88 pares de VID e PID, incluindo o 0925:3881 do clone de Saleae), 61-libsigrok-plugdev.rules (libera o grupo plugdev) e 61-libsigrok-uaccess.rules (libera quem está logado na sessão). Com o AppImage, copie os arquivos do pacote fonte para /etc/udev/rules.d/ mantendo os nomes e rode sudo udevadm control --reload-rules && sudo udevadm trigger.

macOS

Só há o DMG da nightly, para Mac com processador Intel; a página oficial se contradiz sobre a versão mínima (cita macOS 11 Big Sur num ponto e Mojave em outro). Não há passo de driver: o libusb conversa direto com o analisador.

O primeiro uso: achar, capturar e decodificar

Três comandos resolvem 80% da bancada. O primeiro é a varredura:

sigrok-cli --scan

Sem hardware, ele lista só o “demo”, um dispositivo simulado de 13 canais que serve para treinar a sintaxe. Com o analisador de 8 canais ligado, aparece o driver fx2lafw, e o firmware livre é carregado no chip Cypress FX2 a cada conexão. O segundo comando captura e grava:

sigrok-cli -d fx2lafw -c samplerate=24m -C D0,D1,D2,D3,D4,D5,D6,D7 --samples 1000000 -o captura.sr

Testamos a mesma linha no dispositivo demo: um milhão de amostras em 8 canais viraram um .sr de 43 kB em 0,45 segundo, porque o formato é um zip e sinal digital comprime muito. O terceiro comando decodifica, e pode rodar sobre o arquivo salvo, sem o analisador ligado:

sigrok-cli -i captura.sr -P uart:rx=D0:baudrate=115200:format=ascii -A uart=rx-data

Rodamos isso em duas capturas oficiais do repositório de exemplos do projeto. O “Hello World” a 115200 bps saiu como texto limpo, com retorno de carro e nova linha marcados como [0D][0A]. O relógio DS1307 em I²C mostrou o poder dos decoders empilhados: -P i2c:scl=SCL:sda=SDA,ds1307 -A ds1307 devolveu “Second: 30”, “Minute: 35”, “Hour: 23”, “Weekday: Sunday”, ou seja, não os bytes do barramento, mas o que eles significam. A opção --protocol-decoder-samplenum acrescenta em que amostra cada byte começou e terminou, útil para medir tempo entre eventos; -O csv e -O vcd exportam para planilha e para visualizadores de forma de onda.

O que o apt não te dá (medido hoje)

Comparamos o código-fonte da libsigrok 0.5.2, a do pacote, com o ramo principal do projeto: são 1.849 commits de diferença e 18 pastas de driver a mais, entre elas kingst-la2016, raspberrypi-pico, rdtech-um e greatfet. O caso Kingst é o que mais pega o técnico brasileiro: o driver da família LA1010 e LA2016 só entrou no sigrok em junho de 2020, seis meses depois da release, e a página oficial do aparelho recomenda “software recente, pelo menos de meados de novembro de 2021, melhor de fevereiro de 2022”. Quem instala pelo apt e liga um Kingst recebe “No devices found” e acha que o aparelho veio com defeito. Nos decoders, a conta é 111 no pacote contra 132 na nightly; nos firmwares, 13 contra 19. O sigrok-cli.exe da nightly se identifica como 0.8.0-git-f44dd91, o último commit do programa, de agosto de 2024: o sigrok-cli em si quase não muda, quem evolui é a biblioteca embaixo dele.

Os 5 problemas mais comuns e a correção

1. “No devices found” no Linux, mas o lsusb vê o aparelho. É permissão. O README.devices da libsigrok manda usar o arquivo de regras do udev com o nome original, “senão a interação entre as regras da libsigrok e as do sistema quebra”. Confira se o seu usuário está no grupo plugdev (groups) ou use a regra uaccess, e reconecte o analisador. Rodar com sudo funciona, mas esconde o problema.

2. No Windows, o analisador aparece no Gerenciador de Dispositivos e o sigrok-cli não acha. Está com o driver do fabricante. A wiki oficial diz que ele não serve e que o WinUSB via Zadig é obrigatório; se o Zadig não listar o aparelho, marque Options e List All Devices. Para o Hantek 6022BE, que troca de USB ID depois do firmware, a wiki manda aplicar o Zadig duas vezes.

3. Analisador Kingst, Pico ou outro recente não é reconhecido. É a versão de 2019 do apt. Troque pelo AppImage nightly (Linux) ou pelo instalador nightly (Windows); o executável que você chama precisa ser o novo.

4. O decoder devolve lixo ou avisa “No channel with name RX found”. Dois erros nossos, reproduzidos hoje. Se a captura chamou o canal de TX, use rx=TX; com o nome errado o aviso aparece e o sigrok-cli assume o primeiro canal, que pode não ser o certo. E baud rate errado produz bytes sem sentido sem nenhum erro: o mesmo “Hello World” decodificado a 9600 bps virou 04 AC 30. Na dúvida, abra o .sr no PulseView e meça a largura de um bit.

5. A captura para sozinha em amostragem alta. A página oficial explica que o sigrok-cli é single-threaded, e “carga demais o sobrecarrega, resultando em término precoce”. A orientação é capturar em formato binário (-O binary) direto para arquivo e decodificar depois; os outros formatos “impõem sobrecarga grande demais” durante a aquisição. O clone de 8 canais não tem memória própria, então porta USB direta na placa-mãe, sem hub, também conta.

Perguntas frequentes

Preciso instalar o PulseView para usar o sigrok-cli? Não. São pacotes independentes que compartilham a libsigrok e a libsigrokdecode; no Windows, cada instalador traz a sua cópia das bibliotecas e do Zadig.

O arquivo .sr do sigrok-cli abre no PulseView? Sim, é o mesmo formato: um zip com version, metadata e os dados de cada canal. A captura do DS1307 que usamos tem 620 bytes e abre nos dois.

Funciona no Raspberry Pi? O Debian tem o sigrok-cli 0.7.2 nas suítes bookworm e trixie, e o Raspberry Pi OS deriva do Debian; vale a mesma ressalva da versão de 2019. É o cenário em que o sigrok-cli brilha, porque não precisa de tela.

Qual analisador comprar para começar? O clone “24MHz 8CH” é o que o fx2lafw atende e custa pouco; a página oficial dele lista o chip FX2, entrada de −0,5 V a 5,25 V e nível alto a partir de 2,0 V. Se precisar de mais de 24 MHz ou de 16 canais, o Kingst LA2016 (200 MHz, memória própria) é suportado, mas só pela nightly.

Veredito honesto

O sigrok-cli não substitui o PulseView no dia a dia de olhar forma de onda, e ninguém deve começar por ele. Mas, assim que a bancada precisa de uma captura longa, de um registro repetível ou de um Raspberry Pi vigiando um barramento, ele é a ferramenta certa: um comando captura, outro decodifica, e o resultado é texto. A armadilha real é a versão: o apt entrega uma biblioteca de 2019 que não conhece o Kingst e deixa 21 decoders e 6 firmwares de fora, e a nightly resolve isso ao custo de um instalador sem assinatura. No próximo guia, vamos usar o mesmo sigrok-cli para ler um multímetro UNI-T pelo cabo USB e registrar tensão por horas num arquivo, sem câmera apontada para o display.

Se a captura mostrar o barramento conversando mas a placa continuar sem funcionar, o passo seguinte é saber o que cada estágio dela deveria estar fazendo: o Mapa da Placa é o nosso material de leitura de placa; vale conhecer.