Arduino UNO Q에서 CLI 사용 방법

빠르게 시작하기 문서로 만들고 보니, 튜토리얼 아래의 링크가 중요해 보여 다시 블로그에 옮긴다. 같은 작업을 반복하니 좀 마음에 들지 않지만 아쩔 수 없다. 원래 일이라는 게 그렇다. 한글 문서를 카피해 빈줄을 없애고, 한 줄을 추가하는 대신 p 태그를 하나 붙였더니 문서가 깔끔하다. 이 방법도 괜찮다.

Arduino App Lab은 여전히 초보자에게 가장 적합한 접근 방식이지만, 숙련된 개발자에게는 CLI 또는 VS Code 기반 환경을 권장합니다.

아두이노 UNO Q를 사용해 보셨다면, 아두이노 공식 개발 환경이 UNO Q에서 실행되는 서버 기반 개발 환경인 App Lab을 사용하도록 권장한다는 것을 아셨을 겁니다. App Lab은 초보자에게는 좋은 시작점이지만, 저는 다소 제한적이라고 느꼈습니다.

이 장에서는 명령줄 인터페이스(CLI Command Line Interface)와 여러분이 선호하는 로컬 개발 도구를 사용하여 아두이노 UNO Q용 개발 환경을 만드는 방법을 안내해 드리겠습니다.

이 장을 마치면 UNO Q에서 작동하는 LED 깜빡임 프로젝트를 완성할 수 있을 뿐 아니라, 향후 프로젝트를 구성하는 방법도 이해하게 될 것입니다.

바로 본론으로 들어가고 싶으시다면, CLI를 사용하여 실행하는 방법이 설명된 깜빡임 예제는 다음 링크에서 확인하실 수 있습니다:

* 예제 링크 https://github.com/ShawnHymel/arduino_uno_q_blink_cli

App Lab 대신 CLI를 선택해야 하는 이유는 무엇일까요?

기술적인 세부 사항을 살펴보기 전에, App Lab을 아예 사용하지 않거나 최소한으로 사용하는 것이 더 나은 이유에 대해 이야기해 보겠습니다. App Lab은 웹 기반 IDE에 종속되어 아두이노에 내장된 도구만 사용할 수 있도록 제한합니다.

반면 CLI 방식을 사용하면 VS Code에서 인텔리센스, GitHub Copilot, 그리고 즐겨 사용하는 모든 확장 프로그램과 린터를 활용하여 작업할 수 있습니다. VS Code가 마음에 들지 않는다면 원하는 편집기를 사용해도 됩니다.

App Lab에서 개발할 때 코드는 UNO Q에 저장되므로 백업이나 버전 관리(예: Git)가 필요한 경우 접근이 어려울 수 있습니다. CLI 방식은 전문 개발자들이 기대하는 제어 및 자동화 기능을 제공합니다. 빌드 및 배포 프로세스를 스크립트로 작성하고, 지속적 통합 파이프라인을 설정하며, 버전이 고정된 종속성을 사용하여 재현 가능한 빌드를 생성할 수 있습니다.

블랙박스 추상화 대신 빌드 및 배포 과정에서 발생하는 모든 상황을 완벽하게 파악하고, 빌드 구성을 사용자 지정하며, 프로젝트 구조를 원하는 대로 자유롭게 구성할 수 있습니다. 초기 설정에 몇 분 정도 추가 시간이 소요될 수 있지만, 생산성 향상과 개발 유연성을 고려하면 충분히 가치가 있습니다.

1.1. 아두이노 UNO Q 아키텍처 이해하기

아두이노 UNO Q는 하나의 보드에 두 개의 프로세서가 내장되어 있다는 점에서 독특합니다.

1. MPU(마이크로프로세서 유닛) : 퀄컴 드래곤윙™ QRB2210은 데비안 리눅스를 실행하며 USB 통신, 네트워킹, AI 워크로드와 같은 고성능 처리 작업을 담당합니다. 이쪽은 파이썬으로 프로그래밍합니다.

2. MCU(마이크로컨트롤러 유닛) : 실시간 핀 제어 및 하드웨어와의 저수준 상호 작용을 위한 기존 아두이노 스타일 마이크로컨트롤러(STM32U585)입니다. 이 부분은 기존 아두이노 라이브러리를 사용하여 C++로 프로그래밍합니다. 모든 아두이노 라이브러리가 이 프로세서에서 작동하는 것은 아니라는 점에 유의하십시오!

대부분의 UNO Q 프로젝트는 복잡한 로직 처리를 위해 MPU에서 Python을 사용하고, 하드웨어 제어를 위해 MCU에서 Arduino 코드를 사용하는 두 가지 방식을 결합합니다. App Lab CLI는 UNO Q에서 이 두 부분을 함께 빌드, 배포 및 실행하는 작업을 통합 관리합니다.

1.2. UNO Q를 구성하세요

UNO Q는 출시된 지 얼마 되지 않았기 때문에 처음 개봉했을 때 몇 가지 업데이트를 설치해야 할 가능성이 높습니다. 다음 지침에 따라 CLI를 사용하여 업데이트할 수도 있지만, 개인적으로는 App Lab을 설치하고 실행한 다음 UNO Q에 연결하고 안내에 따라 펌웨어를 업데이트하는 것이 가장 쉽습니다 . 설정 과정에서 사용자 이름과 비밀번호를 설정하고 Wi-Fi 설정을 구성하게 됩니다. 이렇게 하면 UNO Q에 연결할 수 있는 SSH 서버가 활성화됩니다.

App Lab에서 UNO Q에 연결되면 왼쪽 하단에 있는 명령줄 아이콘(>_)을 클릭합니다. 그러면 명령 프롬프트가 열립니다. 이전에 설정한 비밀번호를 입력합니다. 로그인 프롬프트에 IP 주소가 표시됩니다(예: arduino@). 표시되지 않으면 다음을 입력합니다.

ip addr show

wlan0 태그 아래에서 IP 주소를 찾아보세요.

아두이노 UNO Q에서 IP 주소를 가져오는 방법

네트워크에서 DHCP로 인해 IP 주소가 변경되는 것이 마음에 들지 않으면, wlan0 태그에 할당된 MAC 주소를 사용하여 라우터에서 선호하는 IP 주소를 설정할 수 있습니다.

SSH를 통해 로그인할 수 있게 되면 App Lab을 닫으셔도 됩니다.

1.3. 프로젝트 구조

UNO Q 프로젝트는 기존의 아두이노(MCU만 사용) 프로젝트보다 조금 더 복잡합니다. 일반적으로 MPU에서 실행되는 데비안 리눅스 기반의 파이썬 스크립트(USB, 네트워킹, AI 등 고부하 처리 작업용)와 MCU에서 실행되는 경량 아두이노 스케치(핀 제어 등)를 결합하여 사용합니다.

호스트 컴퓨터에서 다음과 같이 프로젝트 구조를 생성하십시오.

uno_q_blink/

├── README.md

├── app.yaml

├── python/

│ ├── main.py

│ └── requirements.txt

└── sketch/

├── sketch.ino

└── sketch.yaml

각 파일을 하나씩 살펴보겠습니다. UNO Q 런타임 환경은 지정된 디렉터리에서 이러한 파일 이름을 찾기 때문에 파일 이름 지정이 중요하다는 점에 유의하세요!

● README.md 파일은 필수는 아니지만, 프로젝트와 실행 방법을 설명하는 데 유용할 수 있습니다.

● app.yaml 은 Linux 측 App Lab 앱 매니페스트입니다. 이 파일은 Python 진입점(python/main.py), App Lab "브릭"/서비스, 그리고 MCU 스케치와의 연결을 포함하여 App Lab/CLI가 UNO Q에서 두 부분을 함께 빌드, 배포 및 관리할 수 있도록 합니다.

● python/main.py 는 MPU에서 실행되는 파이썬 스케치입니다.

● python/requirements.txt 파일에는 Python 스케치에 필요한 Python 라이브러리 목록이 있습니다. 프로젝트를 실행하면 이러한 라이브러리가 자동으로 다운로드되어 설치됩니다.

● sketch/sketch.ino 는 MCU에서 실행되는 아두이노 스케치입니다.

● sketch/skecth.yaml 은 Arduino CLI 스케치 프로젝트 파일입니다. 이 파일에는 보드(FQBN), 필요한 코어/플랫폼 버전, 라이브러리, 그리고 (선택적으로) 재현 가능한 MCU 빌드를 위한 여러 빌드 프로필이 선언됩니다.

1.4. 블링크 재현

자, 이제 앱랩에서 보여드렸던 깜빡이는 효과 예제를 다시 만들어 보겠습니다.

README.md

사용자를 위한 지침이나 설명을 입력하세요. 지금은 비워두셔도 괜찮습니다.

앱.yaml

이 항목에는 프로젝트 이름, 버전, 설명, 선택 사항인 아이콘 등을 포함하여 프로젝트에 대한 전체 정보를 입력할 수 있습니다. 또한 노출된 포트와 "브릭" 목록을 표시할 수도 있습니다. 브릭은 UNO Q 전용 특수 라이브러리로, 웹 서버, 컴퓨터 비전, 인공지능과 같은 고급 기능을 제공합니다. 브릭에 대한 자세한 내용은 여기에서 확인하세요.

YAML 구문이 처음이시라면 이 가이드를 읽어보시는 것을 권장합니다.

* 가이드 링크 https://spacelift.io/blog/yaml

name: LED Control Demo
description: "Simple LED control app demonstrating Bridge communication between Python (MPU) and Arduino (MCU)"
icon: 🔴
version: "1.0.0"

# Optional: Define any exposed ports (not needed for this simple example)
ports: []

# Optional: Define bricks if using pre-built components
bricks: []

파이썬/main.py

이 코드는 MPU에서 실행되는 메인 파이썬 프로그램입니다(MCU에서 실행되는 Arduino 스케치와 병렬로 실행됨). 맨 위에 arduino.app_utils를 임포트하는 것을 볼 수 있습니다. 이 라이브러리는 UNO Q에 기본적으로 설치되어 있으며, 내장 원격 프로시저 호출(RPC) 라이브러리인 Bridge 에 접근할 수 있도록 해줍니다. Bridge를 사용하면 MCU에서 실행되는 Arduino 스케치의 함수를 쉽게 호출할 수 있습니다.

MCU 측에서 함수를 호출하려면 Bridge.call() 함수를 사용하고 등록된 함수와 관련된 문자열(및 모든 인수)을 제공하기만 하면 됩니다.

# SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA <http://www.arduino.cc>
#
# SPDX-License-Identifier: MPL-2.0

from arduino.app_utils import *
import time

led_state = False

def loop():
    global led_state
    time.sleep(1)
    led_state = not led_state
    Bridge.call("set_led_state", led_state)
    print("boop")
    
App.run(user_loop=loop)

python/requirements.txt

이 파일은 표준 pip 요구 사항 파일입니다 . 모든 종속성(및 관련 버전)은 프로젝트를 실행할 때 자동으로 설치됩니다. 지금은 이 부분을 비워 두세요.

sketch/sketch.ino

이 파일에는 C++로 작성된 표준 아두이노 스케치가 들어 있습니다. 이 스케치는 MCU에서 실행되며 (MPU에서 실행되는 Python 프로그램과 병렬로 실행됩니다). Python 코드에서 가져온 `app_utils` 와 마찬가지로, 여기에도 `Arduino_RouterBridge` 라이브러리를 포함합니다. 이 라이브러리를 통해 MCU 측에서 동일한 브리지 에 접근할 수 있습니다.

브릿지를 초기화한 후 set_led_state 함수를 "제공"하는 점에 유의하십시오. 이 함수는 Python 측에서 호출하여 LED를 깜빡이게 할 수 있습니다.

// SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA <http://www.arduino.cc>
//
// SPDX-License-Identifier: MPL-2.0

#include "Arduino_RouterBridge.h"

void setup() {
    pinMode(LED_BUILTIN, OUTPUT);

    Bridge.begin();
    Bridge.provide("set_led_state", set_led_state);
}

void loop() {
}

void set_led_state(bool state) {
    // LOW state means LED is ON
    digitalWrite(LED_BUILTIN, state ? LOW : HIGH);
}

sketch/sketch.yaml

이 파일에는 프로젝트의 아두이노 스케치 부분과 필요한 종속성에 대한 정보가 나열되어 있습니다. 수정해야 할 부분은 라이브러리 섹션뿐입니다. 등록된 아두이노 라이브러리 이름을 여기에 나열할 수 있습니다(아두이노 라이브러리 관리자에서 찾을 수 있는 타사 라이브러리도 사용 가능합니다). 런타임 환경에서 라이브러리를 찾고 다운로드 및 설치하려면 철자를 정확하게 입력해야 합니다. 등록된 라이브러리 이름을 찾으려면 App Lab을 사용하는 것이 좋습니다.

예를 들어 Servo 라이브러리를 사용하고 싶다고 가정해 보겠습니다. App Lab에서 새 프로젝트를 시작하고 "라이브러리 추가" 버튼을 클릭한 다음 "Servo"를 검색합니다. Servo 라이브러리를 프로젝트에 추가합니다. 이제 프로젝트의 sketch/sketch.yaml 파일을 열어 라이브러리의 정확한 이름(이 경우 "Servo")을 찾습니다. 현재 App Lab에서는 sketch.yaml 파일 편집을 지원하지 않으므로 로컬 프로젝트로 돌아가 라이브러리 항목 아래에 적절한 항목 (예: " - Servo (1.3.0) ")을 추가해야 합니다.

profiles:
  default:
    fqbn: arduino:zephyr:unoq
    platforms:
      - platform: arduino:zephyr
    libraries:
      - MsgPack (0.4.2)
      - DebugLog (0.8.4)
      - ArxContainer (0.7.0)
      - ArxTypeTraits (0.3.1)
default_profile: default

1.5. 프로젝트 실행하기

모든 작업을 저장했는지 확인하세요. 이제 SCP(Secure Copy Protocol)를 사용하여 전체 프로젝트를 UNO Q로 복사하겠습니다. 그 전에 UNO Q에 파일을 저장할 디렉토리를 생성해야 합니다. 로컬 컴퓨터에서 명령 프롬프트 창을 엽니다. Windows를 사용하는 경우 PowerShell 또는 WSL(Windows Subsystem for Linux)을 사용하세요. macOS 또는 Linux를 사용하는 경우 ssh와 scp(secure copy)가 기본적으로 설치되어 있습니다.

UNO Q에 SSH로 접속하려면 다음을 입력하십시오.

ssh arduino@<UNO_Q_IP_ADDRESS>

SSH 지문을 저장할지 묻는 메시지가 나타나면 'y'를 입력하십시오. 메시지가 나타나면 UNO Q 암호를 입력하십시오. 데비안 셸에 접속되면 다음을 입력하십시오.

mkdir ~/ArduinoApps/uno_q_blink

exit

UNO Q에서 폴더를 초기화하려면 프로젝트당 한 번만 이 작업을 수행하면 됩니다. 아래 이미지 하단의 터미널을 참고하세요,

호스트 컴퓨터로 돌아가서 로컬 디렉터리의 파일을 방금 UNO Q에 생성한 폴더로 복사합니다(암호를 입력하라는 메시지가 나타나면 암호를 입력하십시오).

scp -r * arduino@<UNO_Q_IP_ADDRESS>:~/ArduinoApps/uno_q_blink

이제 프로젝트를 실행할 준비가 되었습니다! UNO Q에 SSH로 다시 접속하세요.

ssh arduino@<UNO_Q_IP_ADDRESS>

암호를 입력하라는 메시지가 나타나면 암호를 입력하십시오. 데비안 셸에서 다음 명령을 실행하여 프로그램을 시작하십시오. 이 명령은 MPU와 MCU에 각각 Python 스케치와 Arduino 스케치를 로드하고 실행합니다. 특히 Python 또는 Arduino 라이브러리를 설치해야 하는 경우 처음 실행할 때 시간이 다소 걸릴 수 있습니다.

arduino-app-cli app start ~/ArduinoApps/uno_q_blink

지금은 EOL 오류를 무시하셔도 됩니다. UNO Q의 LED가 깜빡이는 것을 보실 수 있을 겁니다.

참고로 파이썬 코드는 콘솔이 아닌 로그 파일에 출력합니다. 로그를 보려면 다음 명령어를 실행하세요.

arduino-app-cli app logs ~/ArduinoApps/uno_q_blink

앱이 백그라운드에서 실행 중입니다. 다음 명령어를 사용하여 중지할 수 있습니다.

arduino-app-cli app stop ~/ArduinoApps/uno_q_blink

1.6. VS 코드

UNO Q의 파일을 쉽게 탐색하려면 VS Code 와 Remote-SSH 확장 프로그램을 설치하는 것이 좋습니다. VS Code 왼쪽 하단의 연결 아이콘을 클릭하고 호스트에 연결…을 선택하세요. arduino@를 입력하고 서버 운영 체제를 묻는 메시지가 나타나면 Linux를 선택한 다음 UNO Q 암호를 입력합니다. 그런 다음 파일 > 폴더 열기…를 선택하여 ~/ArduinoApps 디렉터리 에 접근할 수 있습니다.

문제 해결

다음과 같은 상황이 발생하면:

ERRO[0052] Stopped decode loop: EOF discovery="builtin:serial-discovery"

Progress[sketch updated]: 10%

ERRO[0052] Stopped decode loop: EOF discovery="builtin:mdns-discovery"

[INFO] python provisioning

Progress[python provisioning]: 10%

이는 아마도 Python 코드에 App.run()이 없기 때문일 것입니다. 이 줄은 Python 앱을 시작하고 Arduino UNO Q 컨텍스트에서 실행되도록 보장하기 위해 필요합니다(예: Bridge 함수를 호출하고 로그 파일에 기록할 수 있도록). Python 스크립트에 다음과 같은 내용이 있는지 확인하세요:

App.run(user_loop=loop)

1.7. 결론

App Lab은 Arduino UNO Q 개발을 빠르게 시작할 수 있도록 지원하지만, CLI 방식을 사용하면 전문 개발 도구와 워크플로의 모든 기능을 활용할 수 있습니다. 로컬 개발의 유연성, 선호하는 IDE의 강력한 기능, 그리고 명령줄 도구의 제어 기능을 모두 누릴 수 있습니다.

UNO Q에 대해 더 자세히 알아보시려면 다음 자료들을 참고해 보세요.