Tutorial completo de Arduino CLI: instalación, uso y trucos

Si te atrae la idea de controlar tu ecosistema Arduino desde la terminal, la Arduino CLI es justo lo que buscas: un conjunto de utilidades para compilar, subir, gestionar placas y bibliotecas sin abrir el IDE. Esta guía práctica reúne lo esencial y lo avanzado para que puedas integrarla en tu flujo de trabajo, ya sea en Windows, Linux, Raspberry Pi o dentro de tu editor favorito.

A diferencia de un IDE gráfico, la CLI se apoya en comandos que puedes encadenar, automatizar o invocar desde otras herramientas (como VS Code o scripts), y añade modos de servicio como gRPC y métricas Prometheus. Verás cómo crear sketches, detectar placas, instalar cores, añadir bibliotecas y hasta exponer servicios para integraciones más sofisticadas.

Qué es Arduino CLI y por qué usarla

Arduino CLI concentra capacidades clave del ecosistema oficial: gestores de placas y librerías, compilador de sketches, detección de hardware y cargador de programas, todo en una herramienta de línea de comandos. Aunque no siempre tiene paridad 1:1 con el IDE, cubre la mayoría de necesidades y además es el corazón de productos oficiales como Arduino IDE y Arduino Web Editor.

La CLI está organizada como un «contenedor de comandos» (subcomandos), cada uno con su ayuda disponible vía help. Este diseño modular facilita descubrir opciones y encajar la herramienta en automatizaciones, CI/CD o flujos reproducibles.

Más allá del uso interactivo, puede ejecutarse como servicio gRPC con soporte de métricas Prometheus, lo que abre la puerta a integraciones programáticas y observabilidad. Es una solución todo en uno para placas compatibles con Arduino y para plataformas de terceros mediante índices adicionales.

Instalación en Windows, Linux y Raspberry Pi (y consideraciones WSL)

En Linux, una forma limpia es usar el script oficial de instalación desde tu carpeta de usuario, aprovechando ~/.local/bin para evitar privilegios de administrador. Desde tu directorio personal, ejecuta:

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

En macOS existe paquete vía Homebrew, mientras que en Windows puedes descargar el ejecutable publicado por Arduino y colocarlo en una carpeta incluida en PATH. En Windows, añade la carpeta del EXE a la variable de entorno PATH para invocarlo desde cualquier terminal.

En Raspberry Pi la CLI funciona especialmente fluida y ligera en comparación con el IDE, permitiéndote editar con Geany o Code OSS sin cargar Java. La experiencia en Pi suele ser mejor que con el IDE tradicional por consumo y rapidez.

Con WSL clásico (WSL1) la detección de la placa suele fallar, de modo que aunque la CLI se instale, no podrás subir fácilmente a la placa; en WSL2 el resultado puede ser similar según la configuración USB. Para evitar problemas, ejecuta la subida desde Windows nativo o Linux con acceso real al puerto serie.

Empezar: ayuda integrada y archivo de configuración

La CLI organiza sus funciones en subcomandos con ayuda contextual. Para ver la ayuda global o de un subcomando:

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

No es obligatorio un archivo de configuración, pero te ahorra tecleo y hace más predecibles los comportamientos. Inicializa una configuración base con:

arduino-cli config init

Este paso genera un YAML (por ejemplo arduino-cli.yaml o .cli-config.yml) con claves importantes. Ajusta especialmente estas dos opciones:

• sketchbook_path: directorio de tu cuaderno de Arduino (donde guardas sketches, librerías manuales y hardware adicional).
• arduino_data: ubicación donde la CLI guarda datos de gestor de placas y librerías (normalmente no hace falta cambiarla).

Además, podrás definir índices adicionales de paquetes (cores de terceros) bajo board_manager y personalizar parámetros de métricas si usas el modo daemon. Centralizar estas rutas evita inconsistencias entre IDE y CLI.

Crear y editar un sketch nuevo

Para generar la estructura de un proyecto, la CLI puede crear una carpeta y un .ino con el esqueleto básico. Usa la variante moderna del subcomando de sketches:

arduino-cli sketch new MiPrimerSketch

También encontrarás referencias al comando new clásico; en ambos casos obtendrás un directorio con MiPrimerSketch.ino listo para editar. Abre el .ino en tu editor favorito y modifica el código inicial según necesites.

Si prefieres fijar una ruta explícita, incluye el directorio completo al final del comando. La CLI respetará tu sketchbook_path cuando no indiques rutas absolutas.

Detectar tu placa, actualizar índices y entender el FQBN

Tras una instalación reciente conviene actualizar la caché de plataformas y librerías disponibles. Ejecuta:

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

Conecta la placa por USB y comprueba si el sistema la detecta. Lista placas conectadas con:

arduino-cli board list

Si aparece tu placa con su FQBN (Fully Qualified Board Name), ya sabes qué core instalar y qué identificador usar para compilar/subir. El FQBN sigue el formato fabricante:arquitectura:placa, por ejemplo arduino:avr:uno.

Cuando el sistema muestre Unknown como placa, aún podrás subir si conoces el FQBN correcto. Para consultar todas las placas soportadas y sus FQBN:

arduino-cli board listall

Instalar el core adecuado (ejemplo arduino:samd)

Si tu placa pertenece a la familia SAMD (como MKR1000), instala su core. Por ejemplo:

arduino-cli core install arduino:samd

Verifica que quedó bien instalado listando plataformas disponibles. Comprueba la instalación con:

arduino-cli core list

Una vez instalado el core apropiado, ya podrás compilar y subir para esa familia de placas con su FQBN. Este paso es imprescindible antes de la primera compilación.

Añadir cores de terceros (ESP8266, ESP32, NRF52, etc.)

Para placas soportadas por comunidades externas, añade URLs de índices adicionales en la configuración de la CLI bajo board_manager.additional_urls. Ejemplo con ESP8266 (añadiendo la URL pública del core):

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

Si tienes índices locales, puedes incluir rutas de archivo en lugar de URLs. Por ejemplo, para un paquete NRF52832 almacenado en tu equipo:

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

A partir de ese momento, los comandos que operan sobre esos cores usarán automáticamente las fuentes adicionales definidas en el YAML. Como alternativa puntual, añade la opción –additional-urls en cada comando:

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

También puedes usar rutas de archivo con –additional-urls para paquetes locales. Recuerda repetir la opción en cada comando que afecte a ese core si no lo has puesto en el archivo de configuración.

Nota útil sobre hardware popular: la familia ESP32 integra WiFi y Bluetooth de bajo consumo (con variantes de CPU Xtensa LX6/LX7 o RISC-V, mono o doble núcleo), e incorpora front-end de RF y gestión de energía. Es un objetivo frecuente para la CLI por su equilibrio potencia/precio.

Compilar y subir un sketch

Para compilar, indica el FQBN de destino; puedes compilar desde la carpeta del sketch o pasando la ruta. Ejemplo para Arduino Uno:

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

Añade -v para mayor verbosidad o define un directorio de artefactos con –build-path (en Windows, ruta absoluta). Flags útiles: -v y –build-path <carpeta> para guardar .hex y objetos.

Para subir, especifica el puerto serie con -p junto al FQBN. Ejemplo en Windows (COM18):

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

En Linux, el puerto típico se verá como /dev/ttyACM0 o /dev/ttyUSB0. Comprueba permisos de tu usuario sobre el dispositivo serie si aparece un error de acceso.

Buscar e instalar librerías

Antes de reinventar la rueda, explora el gestor de librerías: hay miles listas para usar. Busca por palabra clave con:

arduino-cli lib search debouncer

Si te convence una, instálala por nombre. Por ejemplo, para un desacoplador de pulsadores como FTDebouncer. Instala con:

arduino-cli lib install FTDebouncer

Estas librerías quedan disponibles para tus sketches y la CLI las integrará durante la compilación. Mantén los índices actualizados con lib update-index para ver las novedades.

Modo daemon, gRPC y métricas Prometheus

La CLI puede actuar como servidor gRPC, ideal para integraciones desde otros programas o servicios. Lánzalo con:

arduino-cli daemon

En el repositorio oficial encontrarás un directorio client_example con código de ejemplo para consumir la API. La referencia gRPC documenta servicios y mensajes disponibles si deseas implementar tu propio cliente.

El modo daemon expone un endpoint de métricas en http://localhost:9090/metrics listo para que Prometheus lo recoja. Las opciones de métricas se gestionan en la sección metrics del archivo de configuración, de manera que puedes ajustarlas sin recompilar.

Integrar Arduino CLI con VS Code

Un uso muy cómodo es invocar la CLI desde VS Code con tareas para compilar y subir, manteniendo una experiencia de edición moderna. Configura tareas que llamen a compile y upload con tu FQBN y puerto, y tendrás atajos de teclado para todo.

Si la CLI no localiza tu sketchbook o los gestores del IDE, el archivo de configuración YAML ayuda a resolver rutas. Recuerda establecer sketchbook_path y arduino_data para que el entorno quede unificado entre IDE, CLI y editor.

En Windows, el binario descargado puede tener un nombre largo de versión; renómbralo a arduino-cli.exe si lo prefieres y colócalo en una carpeta del PATH. Evitar nombres con espacios simplifica las tareas y scripts que lo invocan.

Fundamentos de Linux y Raspberry Pi útiles para Arduino CLI

Como vas a moverte por terminal, conviene refrescar comandos base de GNU/Linux y Raspbian (Debian para Raspberry Pi). Estos atajos te harán más ágil con la CLI y con la administración del sistema.

Conceptos: GNU/Linux es un sistema libre, multiplataforma y multitarea, con kernel Linux y herramientas del proyecto GNU; Raspbian (ahora Raspberry Pi OS) es su variante pensada para la SBC Raspberry Pi. Documentación recomendada: TLDP, guías de Raspberry Pi y Wikipedia sobre jerarquía de archivos.

Primeros pasos con la línea de comandos (terminal): practica navegación y manipulación de archivos. Comandos útiles para empezar:

• Navegación: ls, cd, pwd.
• Directorios y archivos: mkdir, rm, mv, cp.
• Ver/leer: cat, more, less, tail.
• Permisos y propietarios: chmod, chown.
• Sistema e info: w, free, df, ps, uname, kill.
• Editores en terminal: vi, vim, emacs, nano.

Ejercicio recomendado: crea un info.txt con un texto breve, guárdalo y léelo desde el terminal con cat o less. Consolidarás edición, lectura y permisos básicos de forma práctica.

Comandos generales y de administración en Raspberry Pi: desde la actualización del sistema hasta el arranque del entorno gráfico. Algunos imprescindibles:

• apt-get update y apt-get upgrade para mantener paquetes.
• clear para limpiar pantalla, date para mostrar la fecha.
• find / -name prueba.txt para localizar archivos.
• nano prueba.txt para editar rápidamente.
• poweroff, reboot, shutdown -h now o a una hora concreta.
• raspi-config para opciones de la Raspberry Pi.
• startx para iniciar la interfaz gráfica.

Trabajar con el sistema de archivos: entiende rutas, permisos y transferencia de ficheros. Comandos y ejemplos frecuentes:

• cat prueba.txt para ver contenido.
• cd /abc/xyz para cambiar de directorio.
• cp fichero.txt /home/pi/fichero.txt para copiar.
• ls -l para listar con detalles y permisos.
• mkdir carpeta_prueba para crear carpetas.
• mv fichero.txt /home/pi para mover o renombrar.
• rm prueba.txt y rmdir carpeta_prueba para borrar.
• scp user@10.0.0.32:/ruta/archivo.txt para copiar vía SSH.
• touch para crear un archivo vacío.

Red y conectividad: diagnóstico de interfaces y escaneo de redes. Herramientas clave:

• ifconfig/iwconfig para revisar IP y estado inalámbrico.
• iwlist wlan0 scan (y con grep ESSID) para redes disponibles.
• nmap para explorar dispositivos y puertos en tu red.
• ping 8.8.8.8 o ping http://www.google.es para comprobar conectividad.
• wget http://www.miweb.com/prueba.txt para descargas por HTTP.

Información del sistema y paquetes: supervisa recursos y versiones para evitar sorpresas al compilar o subir. Comandos de referencia:

• cat /proc/meminfo, /proc/partitions y /proc/version para detalles del sistema.
• df -h y df / para espacio en disco.
• dpkg –get-selections | grep XXX para ver paquetes instalados relacionados.
• free para memoria disponible, top para procesos en tiempo real.
• hostname -I para IP, lsusb para dispositivos USB.
• vcgencmd measure_temp y vcgencmd get_mem arm/gpu en Raspberry Pi.
• Flecha arriba (UP) para recuperar el último comando.

Usuarios y grupos: controla permisos y sudo para gestionar dispositivos serie y despliegues. Creación de usuarios y comprobaciones:

• useradd -c «Nombre Usuario» -g grupo -d /home/usuario -s /bin/bash nombreUsuario
• su – nombreUsuario para iniciar sesión como ese usuario
• whoami, who y lastlog para auditoría básica

Kernel y servicios: recuerda que el kernel administra memoria, CPU y periféricos, y que en Pi puedes actualizarlo según documentación oficial. Para servicios modernos, systemd es la referencia (consulta la guía de Raspberry Pi).

Bash para productividad: autocompletado con Tab y el historial te ahorran mucho tiempo, y los scripts permiten automatizar. history enumera comandos recientes y puedes crear alias o redirecciones según la guía TLDP.

Automatización con cron: agenda tareas recurrentes para compilaciones nocturnas o despliegues. Importante: usa crontab -e en lugar de editar /etc/crontab directamente; revisa logs si algo falla y sigue prácticas recomendadas.

Webmin: si te va la administración vía navegador, puedes instalarlo y gestionar usuarios, Apache, PHP, MySQL, DNS, Samba, DHCP, etc. Tras instalar dependencias, accede a https://<IP>:10000 para usar la interfaz.

Consejos extra y recursos rápidos

• Documentación oficial: la CLI enlaza guías de instalación, primeros pasos y referencias gRPC; merece la pena leerlas para conocer todas las banderas. La combinación de ayuda integrada y docs online acelera el aprendizaje.
• Trabajo en Windows: si el binario descargado viene con un nombre largo de versión (p. ej. arduino-cli-0.2.2-alpha…), puedes renombrarlo a arduino-cli.exe y ponerlo en C:\Program Files\Arduino CLI o similar. Añade esa carpeta al PATH del sistema o del usuario.
• Entornos mixtos: aunque WSL no sea ideal para subir a placas, puedes compilar en WSL y subir desde Windows, o mover artefactos entre máquinas. Divide y vencerás si tu flujo lo requiere (compilar en CI, subir localmente).
• Índices adicionales: cuando trabajes con ESP8266/ESP32/NRF52, configura additional_urls en el YAML para evitar repetir –additional-urls cada vez. Cuida los duplicados y el orden de los índices para evitar conflictos entre versiones.
• Integración continua: el modo daemon y la interfaz gRPC permiten orquestar compilaciones y subidas en pipelines. Exponer métricas en http://localhost:9090/metrics facilita monitorizar tu sistema y detectar cuellos de botella.

Con esta base podrás moverte con soltura: desde crear y compilar sketches, instalar cores oficiales o de terceros, hasta subir por puerto serie y automatizar flujos completos con gRPC y métricas. El salto a la CLI te dará control fino, reproducibilidad y una integración potente con tus editores y scripts, tanto en Windows como en Linux o Raspberry Pi.