Arduino CLI 튜토리얼 전체: 설치, 사용 및 팁

터미널에서 아두이노 생태계를 제어하는 ​​데 관심이 있다면, 아두이노 CLI가 바로 당신이 찾던 것입니다. 아두이노 CLI는 IDE를 열지 않고도 보드와 라이브러리를 컴파일, 업로드, 관리할 수 있는 유틸리티 모음입니다. 이 실용적인 가이드는 필수 기능부터 고급 기능까지 모두 다루므로 Windows, Linux, Raspberry Pi 또는 선호하는 에디터를 사용하든 관계없이 워크플로에 아두이노 CLI를 통합할 수 있습니다.

그래픽 IDE와 달리 CLI는 명령어를 기반으로 작동하며 , 이러한 명령어는 연결하거나 자동화하거나 VS Code 또는 스크립트와 같은 다른 도구에서 호출할 수 있습니다. 또한 gRPC 및 Prometheus 메트릭과 같은 서비스 모드도 제공합니다. 스케치 생성, 보드 검색, 코어 설치, 라이브러리 추가, 더 정교한 통합을 위한 서비스 노출 방법까지 배우게 됩니다 .

Arduino CLI란 무엇이고 왜 사용해야 하나요?

아두이노 CLI는 보드 및 라이브러리 관리자, 스케치 컴파일러, 하드웨어 감지 , 프로그램 로더 등 공식 생태계의 핵심 기능을 하나의 명령줄 도구에 통합했습니다. IDE와 모든 기능을 1:1로 완벽하게 제공하지는 않지만 , 대부분의 요구 사항을 충족하며 아두이노 IDE 및 아두이노 웹 에디터와 같은 공식 제품의 핵심 구성 요소이기도 합니다.

CLI는 "명령 컨테이너"(하위 명령) 형태로 구성되어 있으며, 각 컨테이너는 도움말 기능을 통해 자체 도움말을 제공합니다. 이러한 모듈식 설계 덕분에 옵션을 쉽게 찾고 자동화, CI/CD 또는 재현 가능한 워크플로에 도구를 통합할 수 있습니다.

대화형 사용 외에도 Prometheus 메트릭을 지원하는 gRPC 서비스로 실행될 수 있어 프로그래밍 방식 통합 및 관찰 가능성을 열어줍니다. 추가 인덱스를 통해 Arduino 호환 보드 및 타사 플랫폼을 위한 올인원 솔루션입니다 .

Windows, Linux 및 Raspberry Pi에 설치(및 WSL 고려 사항)

리눅스에서는 관리자 권한 없이 공식 설치 스크립트를 사용자 폴더에 실행하는 것이 깔끔한 방법입니다 . 이때 ~/.local/bin 디렉토리를 활용하세요. 홈 디렉토리에서 다음 명령어를 실행하십시오.

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

macOS에서는 Homebrew를 통해 패키지를 설치할 수 있으며, Windows에서는 Arduino에서 제공하는 실행 파일을 다운로드하여 PATH 환경 변수에 포함된 폴더에 넣으면 됩니다. Windows에서 터미널을 통해 실행하려면 EXE 폴더를 PATH 환경 변수에 추가하세요 .

라즈베리 파이에서 CLI는 IDE에 비해 훨씬 부드럽고 가벼워서 Java를 설치하지 않고도 Geany나 Code OSS로 편집할 수 있습니다. 리소스 사용량과 속도 면에서 라즈베리 파이를 사용하는 환경은 일반적으로 기존 IDE보다 우수합니다 .

기존 WSL(WSL1)에서는 보드 감지가 자주 실패하므로 CLI가 설치되어 있더라도 보드에 쉽게 업로드할 수 없습니다. WSL2에서도 USB 구성에 따라 비슷한 문제가 발생할 수 있습니다 . 이러한 문제를 방지하려면 Windows 또는 Linux 환경에서 시리얼 포트에 직접 접근하여 업로드를 진행하십시오.

시작하기: 내장 도움말 및 구성 파일

CLI는 기능을 하위 명령으로 구성하고 상황에 맞는 도움말을 제공합니다. 전체 도움말 또는 하위 명령에 대한 도움말을 보려면 다음을 수행하십시오.

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

설정 파일은 필수 사항은 아니지만, 입력량을 줄이고 동작을 더욱 예측 가능하게 만듭니다. 다음 명령 으로 기본 설정을 초기화하세요.

arduino-cli config init

이 단계에서는 중요한 키가 포함된 YAML 파일(예: arduino-cli.yaml 또는 .cli-config.yml)이 생성됩니다. 특히 다음 두 가지 옵션에 주의하십시오.

• 스케치북 경로: Arduino 노트북 디렉토리(스케치, 매뉴얼 라이브러리, 추가 하드웨어를 보관하는 곳).
• 아두이노_데이터: CLI가 보드 관리자와 라이브러리 데이터를 저장하는 위치입니다(일반적으로 변경할 필요가 없습니다).

또한, 데몬 모드를 사용하는 경우 `board_manager` 아래에 추가 패키지 인덱스(타사 코어)를 정의하고 메트릭 매개변수를 사용자 지정할 수 있습니다. 이러한 경로를 중앙 집중화하면 IDE와 CLI 간의 불일치를 방지할 수 있습니다.

새 스케치를 만들고 편집합니다

프로젝트 구조를 생성하기 위해 CLI는 기본 골격이 담긴 폴더와 .ino 파일을 생성할 수 있습니다. 이는 최신 버전의 sketch 하위 명령을 사용합니다.

arduino-cli sketch new MiPrimerSketch

또한 기존의 `new` 명령어에 대한 참조도 찾을 수 있습니다. 두 경우 모두 `MyFirstSketch.ino` 파일이 포함된 디렉토리가 생성되어 바로 편집할 수 있습니다. 원하는 편집기에서 `.ino` 파일을 열고 초기 코드를 필요에 따라 수정하세요.

명시적인 경로를 지정하려면 명령 끝에 전체 디렉터리 경로를 포함하세요. 절대 경로를 지정하지 않으면 CLI는 `sketchbook_path`를 따릅니다 .

차량 번호판 감지, 인덱스 업데이트 및 FQBN 파악

최근 설치 후에는 사용 가능한 플랫폼 및 라이브러리 캐시를 업데이트하는 것이 좋습니다. 다음 명령을 실행하세요.

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

USB를 통해 보드를 연결하고 시스템에서 인식하는지 확인하십시오. 연결 가능한 보드 목록은 다음과 같습니다.

arduino-cli board list

보드에 FQBN(완전 보드 이름)이 표시되면 설치해야 할 코어와 컴파일/업로드에 사용할 식별자를 이미 알고 있는 것입니다. FQBN은 제조업체:아키텍처:보드 형식이며 , 예를 들어 arduino:avr:uno와 같습니다.

시스템에 마더보드가 "알 수 없음"으로 표시되더라도 정확한 FQBN을 알고 있다면 업로드할 수 있습니다. 지원되는 모든 마더보드와 해당 FQBN을 보려면 다음 링크를 참조하십시오.

arduino-cli board listall

적절한 코어를 설치하세요(예: arduino:samd)

메인보드가 SAMD 제품군(예: MKR1000)에 속하는 경우 해당 코어를 설치하십시오. 예를 들면 다음과 같습니다.

arduino-cli core install arduino:samd

설치가 올바르게 되었는지 확인하려면 사용 가능한 플랫폼 목록을 확인하세요. 다음 명령으로 설치를 확인하십시오.

arduino-cli core list

적절한 코어가 설치되면 해당 마더보드 제품군의 FQBN을 사용하여 컴파일하고 업로드할 수 있습니다. 이 단계는 첫 번째 컴파일 전에 필수적입니다.

타사 코어(ESP8266, ESP32, NRF52 등)를 추가합니다.

외부 커뮤니티에서 지원하는 보드의 경우, CLI 구성에서 board_manager.additional_urls 아래에 추가 인덱스 URL을 추가하세요. ESP8266의 예(공개 코어 URL 추가):

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

로컬 인덱스가 있는 경우 URL 대신 파일 경로를 포함할 수 있습니다. 예를 들어, 컴퓨터에 저장된 NRF52832 패키지의 경우 다음과 같습니다.

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

그 시점부터 해당 코어에서 작동하는 명령은 YAML에 정의된 추가 소스를 자동으로 사용하게 됩니다. 임시 대안으로 각 명령에 `--additional-urls` 옵션을 추가하십시오.

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

로컬 패키지의 경우 `--additional-urls` 옵션을 사용하여 파일 경로를 지정할 수도 있습니다. 구성 파일에 해당 옵션을 포함하지 않은 경우, 해당 코어에 영향을 미치는 모든 명령에서 이 옵션을 반복해서 사용해야 합니다 .

인기 하드웨어에 대한 유용한 참고 사항: ESP32 제품군은 저전력 Wi-Fi 및 Bluetooth를 통합하고(싱글 또는 듀얼 코어 Xtensa LX6/LX7 또는 RISC-V CPU 변형 포함) RF 프런트엔드 및 전력 관리 기능을 내장하고 있습니다. 전력 효율이 뛰어나 가격 대비 성능이 우수하기 때문에 CLI(명령줄 인터페이스) 개발에 자주 사용됩니다.

스케치를 컴파일하고 업로드하세요

컴파일하려면 대상 FQBN을 지정하세요. 스케치 폴더에서 컴파일하거나 경로를 전달하여 컴파일할 수 있습니다. 아두이노 우노 예시:

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

자세한 정보를 보려면 -v 옵션을 추가하거나, --build-path 옵션을 사용하여 빌드 결과물을 저장할 디렉토리를 지정할 수 있습니다(Windows의 경우 절대 경로). 유용한 플래그로는 -vy --build-path <폴더>를 사용하여 .hex 파일과 오브젝트 파일을 저장할 수 있습니다.

업로드하려면 FQBN 옆에 -p를 붙여 시리얼 포트를 지정하세요. Windows 예시(COM18):

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

리눅스에서 일반적인 포트는 /dev/ttyACM0 또는 /dev/ttyUSB0과 같습니다. 접근 오류가 발생하는 경우 시리얼 장치에 대한 사용자 권한을 확인하십시오 .

라이브러리 검색 및 설치

바퀴를 새로 발명하기 전에 라이브러리 관리 도구를 살펴보세요. 이미 사용 가능한 수천 개의 도구가 있습니다. 키워드로 검색해 보세요.

arduino-cli lib search debouncer

마음에 드는 플러그인이 있다면 이름으로 설치하세요. 예를 들어, FTDebouncer와 같은 푸시 버튼 디커플러를 설치하려면 다음과 같이 하세요.

arduino-cli lib install FTDebouncer

이 라이브러리들은 스케치에서 사용할 수 있으며, CLI는 컴파일 중에 이를 통합합니다. 새로운 라이브러리가 추가되었는지 확인하려면 `lib update-index` 명령어를 사용하여 인덱스를 최신 상태로 유지하세요 .

데몬 모드, gRPC 및 Prometheus 메트릭

CLI는 gRPC 서버 역할을 할 수 있으므로 다른 프로그램이나 서비스와의 통합에 이상적입니다. 다음 명령 으로 실행하세요.

arduino-cli daemon

공식 저장소에는 API 사용 예제 코드가 포함된 `client_example` 디렉토리가 있습니다. 자체 클라이언트를 구현하려는 경우 gRPC 참조 문서에서 사용 가능한 서비스 및 메시지를 확인할 수 있습니다.

데몬 모드는 Prometheus가 수집할 수 있도록 http://localhost:9090/metrics에 메트릭 엔드포인트를 노출합니다. 메트릭 옵션은 구성 파일의 `metrics` 섹션에서 관리되므로 재컴파일 없이 조정할 수 있습니다.

VS Code와 Arduino CLI 통합

VS Code에서 CLI를 호출하여 컴파일 및 업로드 작업을 실행하는 것은 매우 편리한 사용 사례이며, 최신 편집 환경을 유지할 수 있습니다. `compile` 및 `upload` 작업을 FQBN과 포트 번호로 구성하면 모든 작업에 대한 키보드 단축키를 사용할 수 있습니다.

CLI가 스케치북이나 IDE의 관리자 파일을 찾지 못하는 경우, YAML 설정 파일을 통해 경로를 확인할 수 있습니다. IDE, CLI, 에디터에서 동일한 환경을 사용하려면 `sketchbook_path`와 `arduino_data`를 반드시 설정해야 합니다 .

Windows에서는 다운로드한 실행 파일의 버전 이름이 길 수 있습니다. 원하시면 파일 이름을 arduino-cli.exe로 변경하고 PATH에 포함된 폴더에 넣어주세요. 이름에 공백이 없으면 해당 파일을 호출하는 작업이나 스크립트가 더 간편해집니다.

Arduino CLI에 유용한 Linux 및 Raspberry Pi 기본 사항

터미널을 사용하게 될 테니 기본적인 GNU/Linux 및 Raspbian(Raspberry Pi의 경우 Debian) 명령어를 다시 익히는 것이 좋습니다. 이러한 단축키를 사용하면 CLI 및 시스템 관리를 더욱 효율적으로 수행할 수 있습니다.

개념: GNU/Linux는 GNU 프로젝트의 Linux 커널과 도구를 기반으로 하는 무료 크로스 플랫폼 멀티태스킹 운영 체제입니다. Raspbian(현재 Raspberry Pi OS)은 Raspberry Pi 싱글보드 컴퓨터용으로 설계된 GNU/Linux의 변형입니다. 권장 자료 : TLDP, Raspberry Pi 가이드, 파일 계층 구조에 대한 Wikipedia.

명령줄(터미널) 시작하기: 파일 탐색 및 조작 연습. 시작하는 데 유용한 명령어 :

• 탐색: ls, cd, pwd.
• 디렉토리 및 파일: mkdir, rm, mv, cp.
• 보기/읽기: 고양이, 더, 덜, 꼬리.
• 권한 및 소유자: chmod, chown.
• 시스템 및 정보: w, free, df, ps, uname, kill.
• 터미널 편집기: vi, vim, emacs, nano.

권장 연습: 짧은 텍스트가 포함된 info.txt 파일을 생성하고 저장한 다음, 터미널에서 `cat` 또는 `less` 명령어를 사용하여 내용을 읽어보세요. 이를 통해 기본적인 편집, 읽기 및 권한 관리 능력을 실질적으로 다질 수 있습니다 .

라즈베리 파이의 일반 및 관리 명령: 시스템 업데이트부터 그래픽 환경 부팅 까지. 몇 가지 필수 명령은 다음과 같습니다.

• 패키지를 유지 관리하기 위한 apt-get update 및 apt-get upgrade.
• clear는 화면을 지우고, date는 날짜를 표시합니다.
• 파일을 찾으려면 find / -name test.txt를 사용합니다.
• 빠른 편집을 위한 nano test.txt.
• poweroff, reboot, shutdown -h 지금 또는 특정 시간에.
• Raspberry Pi 옵션을 위한 raspi-config.
• 그래픽 인터페이스를 시작하려면 startx를 입력하세요.

파일 시스템 작업: 경로, 권한 및 파일 전송 이해. 일반적인 명령어 및 예제 :

• cat prueba.txt를 입력하여 내용을 확인하세요.
• 디렉토리를 변경하려면 cd /abc/xyz를 입력하세요.
• cp file.txt /home/pi/file.txt를 복사합니다.
• ls -l을 사용하면 세부 정보와 권한을 나열할 수 있습니다.
• mkdir test_folder 명령어를 사용하여 폴더를 생성합니다.
• mv file.txt /home/pi로 이동하거나 이름을 변경합니다.
• rm test.txt와 rmdir test_folder를 사용하여 삭제합니다.
• scp [이메일 보호]:/path/file.txt를 통해 복사합니다. SSH.
• 빈 파일을 만들려면 터치하세요.

네트워크 및 연결성: 인터페이스 진단 및 네트워크 스캔. 주요 도구 :

• ifconfig/iwconfig를 사용하여 IP 및 무선 상태를 확인합니다.
• iwlist wlan0을 사용하여 사용 가능한 네트워크를 검색합니다(grep ESSID도 함께 사용).
• nmap을 사용하여 네트워크의 장치와 포트를 스캔합니다.
• ping 8.8.8.8 또는 ping http://www.google.es를 실행하여 연결 상태를 확인하세요.
• wget http://www.miweb.com/prove.txt로 descargas HTTP를 통해.

시스템 및 패키지 정보: 컴파일 또는 업로드 시 예상치 못한 문제를 방지하기 위해 리소스 및 버전을 모니터링합니다. 참조 명령어 :

• 시스템 세부 정보는 cat /proc/meminfo, /proc/partitions 및 /proc/version을 참조하세요.
• df -hy df / 디스크 공간을 의미합니다.
• dpkg –get-selections | grep XXX를 입력하면 설치된 관련 패키지를 볼 수 있습니다.
• 사용 가능한 메모리는 free이고, 실시간 프로세스는 top입니다.
• IP의 경우 hostname -I, USB 장치의 경우 lsusb입니다.
• Raspberry Pi에서 vcgencmd measure_temp 및 vcgencmd get_mem arm/gpu.
• 위쪽 화살표(UP)를 눌러 마지막 명령을 호출합니다.

사용자 및 그룹: 시리얼 장치 및 배포 관리를 위한 권한 및 sudo 제어. 사용자 생성 및 확인 :

• useradd -c "사용자 이름" -g 그룹 -d /home/user -s /bin/bash 사용자 이름
• su – 해당 사용자로 로그인할 사용자 이름
• 기본 감사를 위한 whoami, who 및 lastlog

커널 및 서비스: 커널은 메모리, CPU 및 주변 장치를 관리하며, 라즈베리 파이에서는 공식 문서를 참조하여 커널을 업데이트할 수 있습니다. 최신 서비스의 경우 systemd가 표준입니다 (라즈베리 파이 가이드 참조).

생산성을 높이는 Bash: 탭 자동 완성 및 히스토리 기능으로 시간을 크게 절약할 수 있으며, 스크립트를 통해 자동화도 가능합니다. `history` 명령은 최근 명령어를 보여주고 , TLDP 가이드에 따라 별칭이나 리디렉션을 생성할 수도 있습니다.

cron을 이용한 자동화: 매일 밤 빌드 또는 배포를 위한 반복 작업을 예약하세요. 중요: `/etc/crontab` 파일을 직접 편집하는 대신 `crontab -e` 명령어를 사용하세요 . 오류가 발생하면 로그를 확인 하고 모범 사례를 따르세요.

Webmin: 브라우저 기반 관리를 선호하는 경우 설치하여 사용자, Apache, PHP, MySQL, DNS, Samba, DHCP 등을 관리할 수 있습니다. 필요한 구성 요소를 설치한 후 https://<IP>:10000에 접속하여 인터페이스를 사용하세요.

추가 팁과 빠른 리소스

• 공식 문서: CLI는 설치 가이드, 시작하기, gRPC 참조에 대한 링크를 제공합니다. 모든 플래그를 알아보려면 읽어볼 만합니다. 내장된 도움말과 온라인 문서의 조합으로 학습이 가속화됩니다..
• Windows에서 작업: 다운로드한 바이너리의 버전 이름이 긴 경우(예: arduino-cli-0.2.2-alpha…) arduino-cli.exe로 이름을 바꾸고 C:\Program Files\Arduino CLI 또는 이와 유사한 위치에 넣을 수 있습니다. 해당 폴더를 시스템 또는 사용자 PATH에 추가합니다..
• 혼합 환경: WSL은 보드에 업로드하기에 적합하지 않지만 WSL을 빌드하여 Windows에서 업로드하거나 컴퓨터 간에 아티팩트를 이동할 수 있습니다. 흐름에 따라 필요하다면 분할하여 정복하세요 (CI에서 빌드하고 로컬에 업로드).
• 추가 인덱스: ESP8266/ESP32/NRF52를 사용할 때 YAML에 additional_urls를 설정하면 –additional-urls를 매번 반복하지 않아도 됩니다. 중복 및 인덱스 순서를 관리하세요 버전 간 충돌을 피하기 위해서입니다.
• 지속적인 통합: 데몬 모드와 gRPC 인터페이스를 사용하면 파이프라인에서 빌드와 업로드를 조정할 수 있습니다. http://localhost:9090/metrics에서 메트릭을 공개하면 시스템을 모니터링하기가 더 쉬워집니다. 병목 현상을 감지합니다.

이러한 기반을 바탕으로 스케치 생성 및 컴파일, 공식 또는 타사 코어 설치, 시리얼 포트를 통한 업로드, gRPC 및 메트릭을 활용한 완벽한 워크플로 자동화에 이르기까지 손쉽게 작업할 수 있습니다. CLI로 전환하면 Windows, Linux 또는 Raspberry Pi 등 어떤 운영체제에서든 세밀한 제어, 재현성, 그리고 에디터 및 스크립트와의 강력한 통합 기능을 활용할 수 있습니다 .