Tutorial completo do Arduino CLI: instalação, uso e dicas

Se você estiver interessado em controlar seu ecossistema Arduino pelo terminal, o Arduino CLI é exatamente o que você está procurando: um conjunto de utilitários para compilar, carregar e gerenciar placas e bibliotecas sem abrir o IDE. Este guia prático reúne o essencial e o avançado para que você possa integrá-lo ao seu fluxo de trabalho, seja no Windows, Linux, Raspberry Pi ou no seu editor favorito.

Ao contrário de um IDE gráfico, o CLI depende de comandos que você pode encadear, automatizar ou invocar de outras ferramentas (como VS Code ou scripts) e adiciona modos de serviço como métricas gRPC e Prometheus. Você verá como criar esboços, detectar placas, instalar núcleos, adicionar bibliotecas e até mesmo expor serviços. para integrações mais sofisticadas.

O que é Arduino CLI e por que usá-lo?

O Arduino CLI concentra os principais recursos do ecossistema oficial: gerenciadores de placa e biblioteca, compilador de esboços, detecção de erros, Hardwares e carregador de programas, tudo em uma ferramenta de linha de comando. Embora nem sempre tenha paridade 1:1 com o IDE, cobre a maioria das necessidades e também é o coração de produtos oficiais, como o Arduino IDE e o Arduino Web Editor.

A CLI é organizada como um “contêiner de comandos” (subcomandos), cada um com ajuda disponível via help. Este design modular facilita a descoberta de opções e encaixar a ferramenta em automações, CI/CD ou fluxos reproduzíveis.

Além do uso interativo, ele pode ser executado como um serviço gRPC com suporte a métricas do Prometheus, abrindo portas para integrações programáticas e observabilidade. É uma solução completa para placas compatíveis com Arduino e para plataformas de terceiros por meio de índices adicionais.

Instalação no Windows, Linux e Raspberry Pi (e considerações sobre WSL)

No Linux, uma maneira limpa é usar o escrita instalação oficial da sua pasta de usuário, aproveitando ~/.local/bin para evitar privilégios de administrador. No seu diretório inicial, execute:

cd ~/.local
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

No macOS, há um pacote via Homebrew, enquanto no Windows, você pode baixar o executável publicado pelo Arduino e colocá-lo em uma pasta incluída no seu PATH. No Windows, adicione a pasta EXE à variável de ambiente PATH para invocá-lo de qualquer terminal.

No Raspberry Pi, a CLI funciona de forma particularmente suave e leve em comparação ao IDE, permitindo que você edite com o Geany ou o Code OSS sem carregar o Java. A experiência no Pi geralmente é melhor do que com o IDE tradicional para consumo e velocidade.

Com o WSL clássico (WSL1), a detecção da placa geralmente falha, então mesmo que a CLI esteja instalada, você não conseguirá fazer upload facilmente para a placa; no WSL2, o resultado pode ser semelhante, dependendo da configuração. USB. Para evitar problemas, execute o upload do Windows ou Linux nativo com acesso real à porta serial.

Introdução: ajuda integrada e arquivo de configuração

A CLI organiza suas funções em subcomandos com ajuda sensível ao contexto. Para visualizar a ajuda global ou de subcomando:

arduino-cli help
arduino-cli <comando> --help

Um arquivo de configuração não é necessário, mas economiza digitação e torna o comportamento mais previsível. Inicialize uma configuração base com:

arduino-cli config init

Esta etapa gera um YAML (por exemplo, arduino-cli.yaml ou .cli-config.yml) com chaves importantes. Ajuste estas duas opções especificamente:

• caminho do caderno de esboços: seu diretório de notebook Arduino (onde você mantém esboços, bibliotecas de manuais e hardware adicional).
• dados_arduino: local onde a CLI armazena os dados do gerenciador de placa e da biblioteca (normalmente isso não precisa ser alterado).

Além disso, você pode definir índices de pacotes adicionais (núcleos de terceiros) no board_manager e personalizar parâmetros métricos se usar o modo daemon. A centralização dessas rotas evita inconsistências entre IDE e CLI.

Crie e edite um novo esboço

Para gerar a estrutura de um projeto, a CLI pode criar uma pasta e um .ino com o esqueleto básico. Use a variante moderna do subcomando sketch:

arduino-cli sketch new MiPrimerSketch

Você também encontrará referências ao comando new clássico; em ambos os casos, você obterá um diretório com MyFirstSketch.ino pronto para edição. Abra o .ino no seu editor favorito e modifique o código inicial conforme necessário.

Se preferir definir um caminho explícito, inclua o diretório completo no final do comando. A CLI respeitará seu sketchbook_path quando você não especifica caminhos absolutos.

Detecte sua placa, atualize índices e entenda o FQBN

Após uma instalação recente, é aconselhável atualizar o cache das plataformas e bibliotecas disponíveis. Corre:

arduino-cli core update-index
arduino-cli lib update-index

Conecte a placa via USB e verifique se o sistema a detecta. Liste as placas conectadas com:

arduino-cli board list

Se sua placa aparecer com seu FQBN (Nome Totalmente Qualificado da Placa), você já sabe qual núcleo instalar e qual identificador usar para compilar/carregar. O FQBN segue o formato fabricante:arquitetura:placa, por exemplo arduino:avr:uno.

Quando o sistema exibir Desconhecido como placa, você ainda poderá embarcar se souber o FQBN correto. Para ver todas as placas suportadas e seus FQBNs:

arduino-cli board listall

Instale o núcleo apropriado (exemplo arduino:samd)

Se sua placa pertence à família SAMD (como a MKR1000), instale seu núcleo. Por exemplo:

arduino-cli core install arduino:samd

Verifique se ele está instalado corretamente listando as plataformas disponíveis. Verifique a instalação com:

arduino-cli core list

Depois que o núcleo apropriado estiver instalado, você pode compilar e fazer upload para aquela família de placas com seu FQBN. Esta etapa é essencial antes da primeira compilação.

Adicionar núcleos de terceiros (ESP8266, ESP32, NRF52, etc.)

Para quadros suportados por comunidades externas, adicione URLs de índice adicionais na configuração da CLI em board_manager.additional_urls. Exemplo com ESP8266 (adicionando a URL pública do núcleo):

board_manager:
  additional_urls:
    - https://arduino.esp8266.com/stable/package_esp8266com_index.json

Se você tiver índices locais, poderá incluir caminhos de arquivo em vez de URLs. Por exemplo, para um pacote NRF52832 armazenado em seu computador:

board_manager:
  additional_urls:
    - file:///ruta/a/tu/package_nrf52_index.json

A partir desse ponto, os comandos que operam nesses núcleos usarão automaticamente as fontes adicionais definidas no YAML. Como alternativa pontual, adicione a opção –additional-urls a cada comando:

arduino-cli core install esp8266:esp8266 --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.json

Você também pode usar caminhos de arquivo com –additional-urls para pacotes locais. Lembre-se de repetir a opção em cada comando que afeta esse núcleo. se você não o colocou no arquivo de configuração.

Nota útil sobre hardware popular: A família ESP32 integra WiFi de baixo consumo de energia e Bluetooth (com variantes de CPU Xtensa LX6/LX7 ou RISC-V, núcleo único ou duplo) e incorpora front-end de RF e gerenciamento de energia. É um alvo frequente do CLI devido ao seu equilíbrio poder/preço..

Compilar e enviar um esboço

Para compilar, especifique o FQBN de destino; você pode compilar a partir da pasta do esboço ou passando o caminho. Exemplo para Arduino Uno:

arduino-cli compile --fqbn arduino:avr:uno "C:/Users/tu.usuario/Documents/Arduino/cli_test"

Adicione -v para maior verbosidade ou defina um diretório de artefato com –build-path (no Windows, caminho absoluto). Bandeiras úteis: -vy –build-path para salvar .hex e objetos.

Para fazer upload, especifique a porta serial com -p ao lado do FQBN. Exemplo no Windows (COM18):

arduino-cli upload -p COM18 --fqbn arduino:avr:uno "C:/Users/tu.usuario/Documents/Arduino/cli_test"

No Linux, a porta típica será semelhante a /dev/ttyACM0 ou /dev/ttyUSB0. Verifique as permissões do seu usuário no dispositivo serial se ocorrer um erro de acesso.

Pesquisar e instalar bibliotecas

Antes de reinventar a roda, explore o gerenciador de biblioteca — há milhares prontos para usar. Pesquisar por palavra-chave com:

arduino-cli lib search debouncer

Se gostar de um, instale-o pelo nome. Por exemplo, para um desacoplador de botão como o FTDebouncer. Instalar com:

arduino-cli lib install FTDebouncer

Essas bibliotecas serão então disponibilizadas para seus esboços e serão integradas pela CLI durante a compilação. Mantenha os índices atualizados com lib update-index para ver o que há de novo.

Modo daemon, gRPC e métricas do Prometheus

A CLI pode atuar como um servidor gRPC, ideal para integrações de outros programas ou serviços. Jogue com:

arduino-cli daemon

No repositório oficial, você encontrará um diretório client_example com código de exemplo para consumir a API. Os documentos de referência do gRPC disponibilizam serviços e mensagens se você quiser implementar seu próprio cliente.

O modo daemon expõe um ponto de extremidade de métricas em http://localhost:9090/metrics pronto para o Prometheus coletar. As opções de métricas são gerenciadas na seção de métricas do arquivo de configuração., para que você possa ajustá-los sem recompilar.

Integrar Arduino CLI com VS Code

Um uso muito conveniente é invocar a CLI do VS Code com tarefas para compilar e carregar, mantendo uma experiência de edição moderna. Configure tarefas que chamam compilar e fazer upload com seu FQBN e porta, e você terá atalhos de teclado para tudo.

Se a CLI não conseguir localizar seu sketchbook ou gerenciadores de IDE, o arquivo de configuração YAML ajuda a resolver os caminhos. Lembre-se de definir sketchbook_path e arduino_data para que o ambiente seja unificado entre IDE, CLI e editor.

No Windows, o binário baixado pode ter um nome de versão longo; renomeie-o para arduino-cli.exe se preferir e coloque-o em uma pasta no seu PATH. Evitar nomes com espaços simplifica tarefas e scripts que o invocam.

Noções básicas de Linux e Raspberry Pi úteis para Arduino CLI

Como você usará um terminal, é uma boa ideia atualizar os comandos básicos para GNU/Linux e Raspbian (Debian para Raspberry Pi). Esses atalhos tornarão você mais ágil com a CLI e com a administração do sistema.

Conceitos: GNU/Linux é um sistema operacional livre, multiplataforma e multitarefa com o kernel Linux e ferramentas do Projeto GNU; Raspbian (agora Raspberry Pi OS) é sua variante projetada para o Raspberry Pi SBC. Documentação recomendada: TLDP, guias do Raspberry Pi e Wikipedia na hierarquia de arquivos.

Introdução à linha de comando (Terminal): pratique navegação e manipulação de arquivos. Comandos úteis para começar:

• Navegação: ls, cd, pwd.
• Diretórios e arquivos: mkdir, rm, mv, cp.
• Ver/ler: gato, mais, menos, rabo.
• Permissões e proprietários: chmod, chown.
• Sistema e informações: w, free, df, ps, uname, kill.
• Editores de terminal: vi, vim, emacs, nano.

Exercício recomendado: crie um info.txt com um texto curto, salve-o e leia-o no terminal com cat ou menos. Você consolidará permissões de edição, leitura e básicas de uma forma prática.

Comandos gerais e administrativos no Raspberry Pi: da atualização do sistema até Bota do ambiente gráfico. Alguns itens essenciais:

• apt-get update e apt-get upgrade para manter pacotes.
• clear para limpar a tela, date para exibir a data.
• find / -name test.txt para localizar arquivos.
• nano test.txt para edição rápida.
• desligar, reiniciar, desligar -h agora ou em um horário específico.
• raspi-config para opções do Raspberry Pi.
• startx para iniciar a interface gráfica.

Trabalhando com o sistema de arquivos: entenda caminhos, permissões e transferências de arquivos. Comandos e exemplos comuns:

• cat prueba.txt para ver o conteúdo.
• cd /abc/xyz para alterar diretórios.
• cp file.txt /home/pi/file.txt para copiar.
• ls -l para listar com detalhes e permissões.
• mkdir test_folder para criar pastas.
• mv file.txt /home/pi para mover ou renomear.
• rm test.txt e rmdir test_folder para excluir.
• scp user@10.0.0.32:/path/file.txt para copiar via SSH.
• toque para criar um arquivo vazio.

Rede e conectividade: diagnóstico de interface e varredura de rede. Chave Herramientas:

• ifconfig/iwconfig para verificar o status do IP e da rede sem fio.
• iwlist wlan0 scan (e com grep ESSID) para redes disponíveis.
• nmap para escanear dispositivos e portas na sua rede.
• faça ping em 8.8.8.8 ou faça ping em http://www.google.es para verificar a conectividade.
• wget http://www.miweb.com/prove.txt para Download via HTTP.

Informações do sistema e do pacote: monitore recursos e versões para evitar surpresas ao compilar ou fazer upload. Comandos de referência:

• cat /proc/meminfo, /proc/partitions e /proc/version para detalhes do sistema.
• df -hy df / para espaço em disco.
• dpkg –get-selections | grep XXX para visualizar os pacotes instalados relacionados.
• livre para memória disponível, superior para processos em tempo real.
• hostname -I para IP, lsusb para dispositivos USB.
• vcgencmd measure_temp e vcgencmd get_mem arm/gpu no Raspberry Pi.
• Seta para cima (UP) para recuperar o último comando.

Usuários e grupos: controle permissões e sudo para gerenciar dispositivos seriais e implantações. Criação e verificações de usuários:

• useradd -c "Nome de usuário" -g grupo -d /home/usuário -s /bin/bash nome de usuário
• su – nome de usuário para efetuar login como esse usuário
• whoami, who e lastlog para auditoria básica

Kernel e serviços: Lembre-se de que o kernel gerencia memória, CPU e periféricos, e você pode atualizá-lo no Pi de acordo com a documentação oficial. Para serviços modernos, systemd é a referência (veja o guia do Raspberry Pi).

Bash para produtividade: a conclusão de tabulações e o histórico economizam muito tempo, e os scripts permitem automação. histórico lista comandos recentes e você pode criar aliases ou redirecionamentos de acordo com o guia TLDP.

Automação Cron: agende tarefas recorrentes para compilações ou implantações noturnas. Importante: Use crontab -e em vez de editar /etc/crontab diretamente; verificar toras se algo der errado e seguir as melhores práticas.

Webmin: Se você gosta de administração de navegadores, pode instalá-lo e gerenciar usuários, Apache, PHP, MySQL, DNS, Samba, DHCP, etc. Após instalar as dependências, acesse https:// :10000 para usar a interface.

Dicas extras e recursos rápidos

• Documentação oficial: a CLI contém links para guias de instalação, primeiros passos e referências do gRPC; vale a pena ler para aprender todos os sinalizadores. A combinação de ajuda integrada e documentos on-line acelera o aprendizado.
• Trabalhando no Windows: Se o binário baixado vier com um nome de versão longo (por exemplo, arduino-cli-0.2.2-alpha…), você pode renomeá-lo para arduino-cli.exe e colocá-lo em C:\Arquivos de Programas\Arduino CLI ou similar. Adicione essa pasta ao PATH do sistema ou do usuário.
• Ambientes mistos: embora o WSL não seja ideal para fazer upload para placas, você pode criar no WSL e fazer upload do Windows ou mover artefatos entre máquinas. Divida e conquiste se o seu fluxo exigir (construir em CI, carregar localmente).
• Índices adicionais: Ao trabalhar com ESP8266/ESP32/NRF52, defina additional_urls no YAML para evitar repetir –additional-urls todas as vezes. Cuide das duplicatas e da ordem do índice para evitar conflitos entre versões.
• Integração contínua: o modo daemon e a interface gRPC permitem que você orquestre compilações e uploads em pipelines. Expor métricas em http://localhost:9090/metrics facilita o monitoramento do seu sistema. e detectar gargalos.

Com essa base, você poderá avançar com facilidade: desde a criação e compilação de esboços, instalação de núcleos oficiais ou de terceiros, até o upload via porta serial e a automação de fluxos inteiros com gRPC e métricas. Pular para a CLI lhe dará controle refinado, reprodutibilidade e integração poderosa com seus editores e scripts., tanto no Windows quanto no Linux ou Raspberry Pi.