Tutorial complet d'Arduino CLI: instal·lació, ús i trucs

Si t'atreu la idea de controlar el teu ecosistema Arduino des de la terminal, l'Arduino CLI és el que busques: un conjunt d'utilitats per compilar, pujar, gestionar plaques i biblioteques sense obrir l'IDE. Aquesta guia pràctica reuneix allò essencial i allò avançat perquè puguis integrar-la al teu flux de treball, ja sigui a Windows, Linux, Raspberry Pi o dins del teu editor favorit.

A diferència d'un IDE gràfic, la CLI es recolza en ordres que pots encadenar, automatitzar o invocar des d'altres eines (com VS Code o scripts), i afegeix modes de servei com gRPC i mètriques Prometheus. Veuràs com crear esquetxos, detectar plaques, instal·lar cors, afegir biblioteques i fins i tot exposar serveis per a integracions més sofisticades.

Què és Arduino CLI i per què fer-la servir

Arduino CLI concentra capacitats clau de l'ecosistema oficial: gestors de plaques i llibreries, compilador d'esquetxos, detecció de maquinari i carregador de programes, tot en una eina de línia d'ordres. Tot i que no sempre té paritat 1:1 amb l'IDE, cobreix la majoria de necessitats ia més és el cor de productes oficials com Arduino IDE i Arduino Web Editor.

La CLI està organitzada com un «contenidor de comandes» (subcomandaments), cadascun amb la seva ajuda disponible via help. Aquest disseny modular facilita descobrir opcions i encaixar l'eina en automatitzacions, CI/CD o fluxos reproduïbles.

Més enllà de l'ús interactiu, es pot executar com a servei gRPC amb suport de mètriques Prometheus, cosa que obre la porta a integracions programàtiques i observabilitat. És una solució tot en un per a plaques compatibles amb Arduino i per a plataformes de tercers mitjançant índexs addicionals.

Instal·lació a Windows, Linux i Raspberry Pi (i consideracions WSL)

A Linux, una forma neta és fer servir el script oficial d'instal·lació des de la vostra carpeta d'usuari, aprofitant ~/.local/bin per evitar privilegis d'administrador. Des del teu directori personal, executa:

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

A macOS hi ha paquet via Homebrew, mentre que a Windows pots descarregar l'executable publicat per Arduino i col·locar-lo en una carpeta inclosa a PATH. Al Windows, afegiu la carpeta de l'EXE a la variable d'entorn PATH per invocar-ho des de qualsevol terminal.

A Raspberry Pi la CLI funciona especialment fluida i lleugera en comparació amb l'IDE, permetent editar amb Geany o Code OSS sense carregar Java. L'experiència a Pi sol ser millor que amb l'IDE tradicional per consum i rapidesa.

Amb WSL clàssic (WSL1) la detecció de la placa sol fallar, de manera que encara que la CLI s'instal·li, no podràs pujar fàcilment a la placa; a WSL2 el resultat pot ser similar segons la configuració USB. Per evitar problemes, executa la pujada des de Windows nadiu o Linux amb accés real al port sèrie.

Començar: ajuda integrada i arxiu de configuració

La CLI organitza les seves funcions en subordres amb ajuda contextual. Per veure l'ajuda global o d'un subordre:

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

No és obligatori un fitxer de configuració, però t'estalvia clic i fa més predictibles els comportaments. Inicialitza una configuració base amb:

arduino-cli config init

Aquest pas genera un YAML (per exemple arduino-cli.yaml o .cli-config.yml) amb claus importants. Ajusta especialment aquestes dues opcions:

• sketchbook_path: directori del teu quadern d'Arduino (on guardes esquetxos, llibreries manuals i maquinari addicional).
• arduino_data: ubicació on la CLI guarda dades de gestor de plaques i llibreries (normalment no cal canviar-la).

A més, podràs definir índexs addicionals de paquets (cores de tercers) sota board_manager i personalitzar paràmetres de mètriques si utilitzes el mode daemon. Centralitzar aquestes rutes evita inconsistències entre IDE i CLI.

Crear i editar un nou sketch

Per generar l'estructura d'un projecte, la CLI pot crear una carpeta i un .ino amb l'esquelet bàsic. Usa la variant moderna del subcomando de sketches:

arduino-cli sketch new MiPrimerSketch

També trobaràs referències a l'ordre new clàssic; en tots dos casos obtindràs un directori amb MiPrimerSketch.ino llest per editar. Obre el .ino al teu editor favorit i modifica el codi inicial segons necessitis.

Si preferiu fixar una ruta explícita, inclou el directori complet al final de l'ordre. La CLI respectarà el teu sketchbook_path quan no indiquis rutes absolutes.

Detectar la teva placa, actualitzar índexs i entendre el FQBN

Després d'una instal·lació recent convé actualitzar la memòria cau de plataformes i llibreries disponibles. executa:

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

Connecta la placa per USB i comprova si el sistema la detecta. Llista plaques connectades amb:

arduino-cli board list

Si apareix la teva placa amb el seu FQBN (Fully Qualified Board Name), ja saps quin core instal·lar i quin identificador utilitzar per compilar/pujar. El FQBN segueix el format fabricant:arquitectura:placa, per exemple arduí:avr:un.

Quan el sistema mostri Unknown com a placa, encara podràs pujar si coneixes el FQBN correcte. Per consultar totes les plaques suportades i els seus FQBN:

arduino-cli board listall

Instal·lar el core adequat (exemple arduí:samd)

Si la teva placa pertany a la família SAMD (com MKR1000), instal·la el seu core. Per exemple:

arduino-cli core install arduino:samd

Verifica que va quedar ben instal·lat llistant plataformes disponibles. Comprova la instal·lació amb:

arduino-cli core list

Un cop instal·lat el core apropiat, ja podràs compilar i pujar per a aquesta família de plaques amb el seu FQBN. Aquest pas és imprescindible abans de la primera compilació.

Afegir cors de tercers (ESP8266, ESP32, NRF52, etc.)

Per a plaques suportades per comunitats externes, afegiu URLs d'índex addicionals a la configuració de la CLI sota board_manager.additional_urls. Exemple amb ESP8266 (afegint la URL pública del core):

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

Si teniu índexs locals, podeu incloure rutes de fitxer en lloc d'URLs. Per exemple, per a un paquet NRF52832 emmagatzemat al vostre equip:

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

A partir d'aquest moment, les ordres que operen sobre aquests cors utilitzaran automàticament les fonts addicionals definides al YAML. Com a alternativa puntual, afegeix l'opció –additional-urls a cada ordre:

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

També podeu utilitzar rutes de fitxer amb –additional-urls per a paquets locals. Recorda repetir l'opció a cada ordre que afecti aquest core si no ho has posat al fitxer de configuració.

Nota útil sobre maquinari popular: la família ESP32 integra WiFi i Bluetooth de baix consum (amb variants de CPU Xtensa LX6/LX7 o RISC-V, mono o doble nucli), i incorpora frontend de RF i gestió d'energia. És un objectiu freqüent per a la CLI pel seu equilibri potència/preu.

Compilar i pujar un esquetx

Per compilar, indica el FQBN de destinació; pots compilar des de la carpeta de l'esquetx o passant la ruta. Exemple per a Arduino Un:

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

Afegeix -v per a més verbositat o defineix un directori d'artefactes amb –build-path (en Windows, ruta absoluta). Flags útils: -vy –build-path per guardar .hex i objectes.

Per pujar, especifica el port sèrie amb -p al costat del FQBN. Exemple a Windows (COM18):

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

A Linux, el port típic es veurà com a /dev/ttyACM0 o /dev/ttyUSB0. Comprova permisos del teu usuari sobre el dispositiu sèrie si apareix un error daccés.

Buscar i instal·lar llibreries

Abans de reinventar la roda, explora el gestor de llibreries: hi ha milers llistes per fer servir. Cerca per paraula clau amb:

arduino-cli lib search debouncer

Si te'n convenç una, instal·la-la per nom. Per exemple, per a un desacoblador de polsadors com FTDebouncer. Instal·la amb:

arduino-cli lib install FTDebouncer

Aquestes llibreries queden disponibles per als teus esquetxos i la CLI les integrarà durant la compilació. Mantingues els índexs actualitzats amb lib update-index per veure les novetats.

Mode daemon, gRPC i mètriques Prometheus

La CLI pot actuar com a servidor gRPC, ideal per a integracions des d'altres programes o serveis. Llança'l amb:

arduino-cli daemon

Al repositori oficial trobareu un directori client_example amb codi d'exemple per consumir l'API. La referència gRPC documenta serveis i missatges disponibles si desitges implementar el teu propi client.

El mode daemon exposa un endpoint de mètriques a http://localhost:9090/metrics llest perquè Prometheus ho reculli. Les opcions de mètriques es gestionen a la secció metrics del fitxer de configuració, de manera que les pots ajustar sense recompilar.

Integrar Arduino CLI amb VS Code

Un ús molt còmode és invocar la CLI des de VS Code amb tasques per compilar i pujar mantenint una experiència d'edició moderna. Configura tasques que truquin a compile i upload amb el teu FQBN i port, I tindràs dreceres de teclat per a tot.

Si la CLI no localitza el vostre sketchbook o els gestors de l'IDE, el fitxer de configuració YAML ajuda a resoldre rutes. Recordeu establir sketchbook_path i arduino_data perquè l'entorn quedi unificat entre l'IDE, el CLI i l'editor.

Al Windows, el binari descarregat pot tenir un nom llarg de versió; reanomena'l a arduino-cli.exe si ho prefereixes i col·loca'l en una carpeta del PATH. Evitar noms amb espais simplifica les tasques i scripts que ho invoquen.

Fonaments de Linux i Raspberry Pi útils per a Arduino CLI

Com et mouràs per terminal, convé refrescar ordres base de GNU/Linux i Raspbian (Debian per a Raspberry Pi). Aquestes dreceres et faran més àgil amb la CLI i amb ladministració del sistema.

Conceptes: GNU/Linux és un sistema lliure, multiplataforma i multitasca, amb nucli Linux i eines del projecte GNU; Raspbian (ara Raspberry Pi US) és la seva variant pensada per a la SBC Raspberry Pi. Documentació recomanada: TLDP, guies de Raspberry Pi i Wikipedia sobre jerarquia darxius.

Primers passos amb la línia de comandes (terminal): practica navegació i manipulació d'arxius. Ordres útils per començar:

• Navegació: ls, cd, pwd.
• Directoris i fitxers: mkdir, rm, mv, cp.
• Veure/llegir: cat, more, less, tail.
• Permisos i propietaris: chmod, chown.
• Sistema i info: w, free, df, ps, uname, kill.
• Editors en terminal: vaig veure, vim, emacs, nano.

Exercici recomanat: crea un info.txt amb un text breu, guarda'l i llegeix-lo des del terminal amb cat o less. Consolidaràs edició, lectura i permisos bàsics de manera pràctica.

Ordres generals i d'administració a Raspberry Pi: des de l'actualització del sistema fins al arrencada de lentorn gràfic. Alguns imprescindibles:

• apt-get update i apt-get upgrade per mantenir paquets.
• clear per netejar pantalla, dóna't per mostrar la data.
• find / -name prova.txt per localitzar fitxers.
• nano prova.txt per editar ràpidament.
• poweroff, reboot, shutdown -h now oa una hora concreta.
• raspi-config per a opcions de la Raspberry Pi.
• startx per iniciar la interfície gràfica.

Treballar amb el sistema de fitxers: entén rutes, permisos i transferència de fitxers. Ordres i exemples freqüents:

• cat prueba.txt per veure contingut.
• cd /abc/xyz per canviar de directori.
• cp fitxer.txt /home/pi/fitxer.txt per copiar.
• ls -l per llistar amb detalls i permisos.
• mkdir carpeta_prova per crear carpetes.
• mv fitxer.txt /home/pi per moure o reanomenar.
• rm prova.txt i rmdir carpeta_prova per esborrar.
• scp user@10.0.0.32:/ruta/arxiu.txt per copiar via SSH.
• touch per crear un fitxer buit.

Xarxa i connectivitat: diagnòstic d'interfícies i escaneig de xarxes. Herramientas clau:

• ifconfig/iwconfig per revisar IP i estat sense fil.
• iwlist wlan0 scan (i amb grep ESSID) per a xarxes disponibles.
• nmap per explorar dispositius i ports a la teva xarxa.
• ping 8.8.8.8 o ping http://www.google.es per comprovar connectivitat.
• wget http://www.miweb.com/prueba.txt per DESCÀRREGUES per HTTP.

Informació del sistema i paquets: supervisa recursos i versions per evitar sorpreses en compilar o pujar. Ordres de referència:

• cat /proc/meminfo, /proc/partitions i /proc/version per a detalls del sistema.
• df -hy df / per a espai al disc.
• dpkg –get-selections | grep XXX per veure paquets instal·lats relacionats.
• free per a memòria disponible, top per a processos en temps real.
• hostname -I per a IP, lsusb per a dispositius USB.
• vcgencmd measure_temp i vcgencmd get_mem arm/gpu a Raspberry Pi.
• Fletxa amunt (UP) per recuperar l'última ordre.

Usuaris i grups: controla permisos i sudo per gestionar dispositius sèrie i desplegaments. Creació d'usuaris i comprovacions:

• useradd -c «Nom Usuari» -g grup -d /home/usuari -s /bin/bash nomUsuari
• el seu – nomUsuari per iniciar sessió com aquest usuari
• whoami, who i lastlog per a auditoria bàsica

Kernel i serveis: recorda que el kernel administra memòria, CPU i perifèrics, i que a Pi el pots actualitzar segons documentació oficial. Per a serveis moderns, systemd és la referència (consulteu la guia de Raspberry Pi).

Bash per a productivitat: autocompletat amb Tab i l'historial t'estalvien molt de temps, i els scripts permeten automatitzar. history enumera ordres recents i podeu crear àlies o redireccions segons la guia TLDP.

Automatització amb cron: agenda tasques recurrents per a compilacions nocturnes o desplegaments. Important: utilitza crontab -e en lloc d'editar /etc/crontab directament; revisa logs si alguna cosa falla i segueix pràctiques recomanades.

Webmin: si us va l'administració via navegador, podeu instal·lar-lo i gestionar usuaris, Apache, PHP, MySQL, DNS, Samba, DHCP, etc. Després d'instal·lar dependències, accedeix a https:// :10000 per utilitzar la interfície.

Consells extra i recursos ràpids

• Documentació oficial: la CLI enllaça guies d'instal·lació, primers passos i referències gRPC; val la pena llegir-les per conèixer totes les banderes. La combinació d'ajuda integrada i docs en línia accelera l'aprenentatge.
• Treball a Windows: si el binari descarregat ve amb un nom llarg de versió (p. ex. arduino-cli-0.2.2-alpha…), pots reanomenar-lo a arduino-cli.exe i posar-lo a C:\Program Files\Arduino CLI o similar. Afegeix aquesta carpeta al PATH del sistema o de l'usuari.
• Entorns mixts: encara que WSL no sigui ideal per pujar a plaques, pots compilar a WSL i pujar des de Windows, o moure artefactes entre màquines. Divideix i venceràs si el teu flux ho requereix (compilar a CI, pujar localment).
• Índexs addicionals: quan treballeu amb ESP8266/ESP32/NRF52, configureu additional_urls al YAML per evitar repetir –additional-urls cada vegada. Cuida els duplicats i l'ordre dels índexs per evitar conflictes entre versions.
• Integració contínua: el mode daemon i la interfície gRPC permeten orquestrar compilacions i pujades en pipelins. Exposar mètriques a http://localhost:9090/metrics facilita monitoritzar el teu sistema i detectar colls de botella.

Amb aquesta base podràs moure't amb soltesa: des de crear i compilar esquetxos, instal·lar cors oficials o de tercers, fins a pujar per port sèrie i automatitzar fluxos complets amb gRPC i mètriques. El salt a la CLI et donarà control fi, reproductibilitat i una integració potent amb els teus editors i scripts, tant a Windows com a Linux o Raspberry Pi.