5장 Arduino UNO Q를 SSH로 원격 접속하는 방법과 파일 전송 가이드

개요

Arduino UNO Q는 기존의 마이크로컨트롤러 보드와 달리 Debian 기반 운영체제를 탑재한 마이크로프로세서를 갖춘 보드로, 작은 싱글보드 컴퓨터처럼 사용할 수 있습니다. 기본적으로는 Arduino App Lab이라는 데스크톱 애플리케이션을 통해 앱을 설치하고 실행하지만, SSH(Secure Shell)를 이용하면 모니터와 키보드 없이도 네트워크를 통해 보드의 리눅스 셸에 직접 접속할 수 있습니다.

SSH로 접속하면 보드의 파일 시스템을 다루거나, 리눅스 명령을 실행하고, arduino-app-cli 도구를 사용해 앱을 터미널에서 직접 실행·제어할 수 있습니다. 또 SCP(Secure Copy)를 이용하면 개발 PC에서 UNO Q로 파일과 폴더를 전송하거나, 반대로 보드에 저장된 데이터를 가져오는 작업도 가능합니다.

이 지식 노트에서는 UNO Q에 SSH로 접속하기 위해 필요한 준비 사항부터, 각 운영체제별 SSH 클라이언트 확인 방법, 실제 접속 절차, SCP를 이용한 파일 전송 방법, 그리고 접속이 안 될 때 확인해야 할 문제 해결 팁까지 순서대로 정리합니다.

강사과정 모집 -> 아두이노 강의 | Arduino Uno로 배우는 임베디드 개발 | Arduino Uno Club

UNO Q와 SSH: 개념 이해

UNO Q의 마이크로프로세서는 Debian OS를 실행하며, 여기에 Arduino App Lab과 arduino-app-cli 도구가 기본으로 설치되어 있습니다. App Lab은 GUI 기반으로 앱을 설치·실행하는 도구이고, arduino-app-cli는 같은 기능을 명령줄에서 쓸 수 있게 해주는 CLI 도구입니다. SSH로 접속하면 이 Debian 셸에 직접 들어가서 CLI 환경에서 보드를 다루게 됩니다.

SSH(Secure Shell)는 네트워크를 통해 원격 시스템의 터미널에 접속하는 암호화된 프로토콜입니다. UNO Q와 PC가 같은 로컬 네트워크(주로 같은 Wi‑Fi)에 연결되어 있으면, PC의 터미널에서 UNO Q로 안전하게 접속할 수 있습니다. 이 방식은 모니터·키보드가 없는 상태에서 설정 변경, 로그 확인, 파일 관리, 앱 실행 등을 하기에 매우 유용합니다.

준비 사항

하드웨어 준비

• Arduino UNO Q 보드

• 안정적인 5 V DC / 3 A 전원 (스마트폰 충전기, 고전류 지원 USB 포트 등 권장)

• UNO Q와 동일한 네트워크에 연결된 컴퓨터(노트북, 데스크톱 등)

소프트웨어 준비

• UNO Q 첫 설정(First setup) 완료

  • 초기 설정 과정에서 Wi‑Fi SSID와 비밀번호를 입력하고, 보드를 네트워크에 연결합니다.

  • 이 첫 설정을 완료하면 보드에서 SSH가 자동으로 활성화됩니다.

  • 이 과정을 하지 않았다면 SSH로는 접속할 수 없고, 별도의 방법으로 수동 활성화를 해야 합니다.

• PC에 SSH 클라이언트

  • macOS, Windows 10 이상, 대부분의 Linux(Ubuntu 등)는 기본적으로 SSH 클라이언트를 포함합니다.

  • 아주 오래된 Windows나 특이한 환경이 아니라면 별도 설치 없이 바로 사용할 수 있습니다.

• 같은 로컬 네트워크

  • UNO Q와 PC가 같은 Wi‑Fi 또는 같은 유선 LAN에 연결되어 있어야 합니다.

  • 서로 다른 네트워크(예: PC는 회사망, UNO Q는 개인 핫스팟)에 있으면 일반적으로 SSH 접속이 되지 않습니다.

PC에 SSH 클라이언트 준비하기

SSH는 프로토콜 이름이고, 실제로는 ssh라는 클라이언트 프로그램을 사용합니다. 각 운영체제에서 ssh가 잘 설치되어 있는지만 확인하면 됩니다.

macOS

macOS에는 OpenSSH 기반 SSH 클라이언트가 기본 탑재되어 있어, 보통 추가 설치가 필요 없습니다.

1. 터미널을 엽니다.

2. 다음 명령으로 버전을 확인합니다.

   ssh -V

3. OpenSSH_9.xp...와 비슷한 출력이 나오면 정상입니다.

만약 command not found가 뜨는 특이한 환경이라면 Homebrew 같은 패키지 매니저를 사용해 OpenSSH와 LibreSSL을 설치할 수 있습니다.

Windows 10 이상

Windows 10 이후 버전에는 OpenSSH 클라이언트가 포함되어 있는 경우가 많습니다.

1. PowerShell 또는 명령 프롬프트를 엽니다.

2. 다음 명령을 실행합니다.

   ssh -V

3. OpenSSH_for_Windows_...와 비슷한 메시지가 나오면 이미 설치된 것입니다.

아주 오래된 Windows에서는 Chocolatey 같은 패키지 매니저를 사용해 OpenSSH/LibreSSL을 수동 설치해야 할 수 있습니다.

Linux (Ubuntu 등)

대부분의 Linux 배포판도 기본적으로 SSH 클라이언트를 포함합니다.

1. 터미널을 열고 다음을 실행합니다.

   ssh -V

2. OpenSSH_... Ubuntu-...와 같은 출력이 보이면 준비 완료입니다.

3. 설치되어 있지 않은 경우에는 다음과 같이 설치할 수 있습니다.

   sudo apt install openssh-client openssh-server libressl-dev

UNO Q에서 SSH 활성화 조건

UNO Q에서 SSH가 켜져 있는지 여부는 주로 첫 설정(First setup) 과정에 의해 결정됩니다.

• 첫 설정을 완료한 경우

  • 초기 설정 중에 Wi‑Fi 정보를 입력하면, 보드가 해당 네트워크에 연결되며 SSH가 자동 활성화됩니다.

  • 이 상태라면 추가 설정 없이 바로 SSH로 접속할 수 있습니다.

• 첫 설정을 하지 않은 경우

  • 이 경우 SSH는 기본적으로 비활성화되어 있습니다.

  • SSH로 접속하려면 먼저 UNO Q를 ADB(안드로이드 디버그 브리지)로 연결하거나, SBC 모드 등 다른 방법으로 셸에 들어간 뒤, 다음 명령을 실행해 네트워크 모드를 활성화해야 합니다.

    arduino-app-cli system network-mode enable

  • ADB 사용법과 SBC 모드 사용법은 별도의 UNO Q/Arduino 문서를 참조해야 합니다.

일반적인 사용 시에는 Arduino에서 안내하는 첫 설정 절차를 따라 Wi‑Fi를 연결하면 자동으로 SSH가 활성화된다고 생각하면 됩니다.

UNO Q에 SSH로 접속하는 기본 절차

UNO Q에 SSH로 접속하려면 보드 이름과 비밀번호를 알아야 합니다. 이 값들은 첫 설정 과정에서 정합니다. 계정 이름은 보통 arduino로 고정이고, 호스트 이름(보드 이름)만 사용자가 정한 값이 되는 구조입니다.

1. UNO Q 전원 켜기

   • 전원 어댑터나 USB를 연결해 보드를 켜고, 네트워크에 연결될 때까지 잠시 기다립니다.

2. PC에서 터미널 열기

   • macOS: 터미널

   • Windows: PowerShell 또는 명령 프롬프트

   • Linux: 기본 터미널

3. SSH 명령 실행

   ssh arduino@<보드이름>.local

   예를 들어, 첫 설정 때 보드 이름을 unoq-01로 지정했다면:

   ssh arduino@unoq-01.local

4. 처음 접속 시 fingerprint 확인

   • 첫 접속 시 "이 호스트에 접속할 것인지(yes/no)"를 묻는 메시지가 나오면 yes를 입력합니다.

   • 이는 보드의 공개 키를 신뢰하겠다는 의미로, 한 번 수락하면 이후에는 같은 키를 자동으로 사용합니다.

5. 비밀번호 입력

   • 첫 설정 때 설정한 비밀번호를 입력합니다.

   • 화면에 입력 내용은 보이지 않지만 정상입니다. 입력 후 Enter를 누릅니다.

6. 셸 접속 확인

   • 접속에 성공하면 프롬프트가 다음과 비슷한 형태로 바뀝니다.

     arduino@unoq-01:~$

   • 이제 UNO Q의 Debian 셸에 접속한 상태이며, 일반적인 리눅스 명령과 arduino-app-cli 명령 등을 실행할 수 있습니다.

mDNS 문제와 IP 주소로 접속하기

UNO Q에 접속할 때 기본적으로 unoq-01.local처럼 mDNS 이름을 사용합니다. 하지만 일부 네트워크 환경에서는 mDNS가 제대로 동작하지 않아 접속이 실패할 수 있습니다.

대표적인 오류는 다음과 같이 나타날 수 있습니다.

• ssh: connect to host <boardname>.local port 22: Connection refused

• 또는 <boardname>.local을 해석하지 못하는 메시지

이처럼 이름 기반 접속이 되지 않을 때는 다음 방법들을 활용할 수 있습니다.

1. UNO Q의 IP 주소로 직접 접속

먼저 보드의 IP 주소를 알아야 합니다. 얻는 방법은 여러 가지가 있습니다.

• Arduino IDE 2 사용

  • Zephyr 코어를 설치한 상태에서 Arduino IDE 2의 보드/포트 목록에서 UNO Q의 IP 주소를 확인할 수 있습니다.

• Arduino CLI 사용

  arduino-cli board list

  이 명령의 출력에서 UNO Q 항목에 표시된 IP 주소를 확인합니다.

• 보드 셸에서 hostname -I 실행

  • 이미 ADB로 보드에 접속했거나, SBC 모드에서 터미널에 접근할 수 있다면:

    hostname -I

    를 실행해 현재 UNO Q가 사용하는 IP 주소를 확인할 수 있습니다.

IP 주소를 알았다면, mDNS 이름 대신 IP를 사용해 접속합니다.

ssh arduino@10.0.20.138

이처럼 .local 없이 숫자 IP를 직접 쓰면 mDNS 문제와 관계없이 접속이 가능합니다.

2. /etc/hosts에 수동 매핑 (고급)

mDNS가 계속 잘 안 되는 환경에서는, PC의 /etc/hosts 파일에 UNO Q의 IP와 이름을 직접 매핑할 수도 있습니다(주로 Linux, macOS에서 사용).

1. 터미널에서 다음을 실행합니다.

   sudo nano /etc/hosts

2. 파일 맨 아래에 다음과 같이 한 줄을 추가합니다.

   10.0.20.138 unoq-01.local

   • 10.0.20.138 : UNO Q의 실제 IP 주소

   • unoq-01.local : 첫 설정 때 지정한 보드 이름 + .local

3. 저장 후에는 다시 다음과 같이 접속할 수 있습니다.

   ssh arduino@unoq-01.local

SSH 접속이 안 될 때 점검 목록

SSH가 잘 안 될 때는 다음 항목들을 순서대로 점검해 보는 것이 좋습니다.

1. 첫 설정(First setup)을 완료했는가?

   • Wi‑Fi 정보를 입력하는 최초 설정 과정을 거치지 않았다면 SSH가 비활성화 상태일 수 있습니다.

   • 이 경우 ADB 등을 통해 arduino-app-cli system network-mode enable을 실행해 네트워크 모드를 켜야 합니다.

2. 보드와 PC가 같은 네트워크인가?

   • UNO Q는 집 Wi‑Fi, PC는 휴대폰 테더링처럼 서로 다른 네트워크에 있다면 접속이 안 됩니다.

   • 반드시 같은 라우터(같은 SSID)의 네트워크에 두 장치를 연결합니다.

3. mDNS 문제 여부

   • ssh arduino@<보드이름>.local이 안 되는데, IP로는 접속이 된다면 mDNS가 차단된 네트워크일 가능성이 큽니다.

   • 이 경우 IP 직접 접속이나 /etc/hosts 편집 방법을 사용합니다.

4. 보드가 실제로 네트워크에 연결되어 있는지

   • UNO Q의 상태 LED나, App Lab/IDE에서 보드가 온라인으로 보이는지 확인합니다.

   • 전원을 다시 뺐다 꽂아서 재부팅하는 것도 도움이 될 수 있습니다.

5. SSH 호스트 키 충돌 여부

   • 보드를 다시 플래시 했거나, 같은 IP를 다른 장치가 사용했던 적이 있다면, 다음과 같은 경고가 뜰 수 있습니다.

     • "REMOTE HOST IDENTIFICATION HAS CHANGED!" 등

   • 이 경우 PC에서 해당 IP에 대한 기존 키를 삭제해야 합니다.

     ssh-keygen -R <보드 IP 주소>

     그 후 다시 SSH 접속을 시도하면 새 키를 등록할 수 있습니다.

SCP(Secure Copy)로 파일 전송하기

SCP는 SSH를 이용해서 파일과 폴더를 복사하는 도구입니다. 중요한 점은 SCP 명령은 항상 PC의 터미널에서 실행해야 한다는 것입니다. (UNO Q에 SSH로 로그인한 셸 안이 아니라, 로컬 PC의 터미널에서 실행합니다.)

SCP의 기본 형태는 다음과 같습니다.

scp [옵션] <원본 경로> <목적지 경로>

• 로컬 → 보드: 원본은 로컬 경로, 목적지는 arduino@보드주소:경로

• 보드 → 로컬: 원본은 arduino@보드주소:경로, 목적지는 로컬 경로

여기서 보드 주소는 <보드이름>.local 또는 IP 주소(예: 10.0.20.138)를 사용할 수 있습니다.

로컬에서 UNO Q로 파일 보내기 (Push)

현재 디렉토리에 있는 test-transfer.txt를 UNO Q의 /home/arduino/ 디렉토리로 복사하는 예입니다.

scp test-transfer.txt arduino@<보드이름>.local:/home/arduino/

예를 들어 보드 이름이 unoq-01이라면:

scp test-transfer.txt arduino@unoq-01.local:/home/arduino/

• 첫 실행 시에는 SSH 접속과 마찬가지로 비밀번호를 물을 수 있습니다.

• 전송이 끝나면 UNO Q 셸에서 /home/arduino/를 확인하여 파일이 복사되었는지 확인할 수 있습니다.

UNO Q에서 로컬로 파일 가져오기 (Pull)

이번에는 UNO Q에 있는 파일을 PC로 가져오는 예입니다.

scp arduino@<보드이름>.local:/home/arduino/test-transfer.txt ./

• 위 예시는 UNO Q에 있는 test-transfer.txt를 현재 PC 디렉토리(./)로 복사합니다.

• ./ 대신 /Users/username/Documents/ 같은 절대 경로를 지정할 수도 있습니다.

폴더 통째로 복사하기

폴더(디렉토리)를 복사할 때는 -r(재귀) 옵션을 사용합니다. 문서에서는 권한과 시간을 유지하기 위해 -rp 형태로 사용합니다.

로컬 → UNO Q (폴더 push)

my-folder라는 폴더를 UNO Q의 ArduinoApps 폴더로 복사하는 예입니다.

scp -rp my-folder arduino@<보드이름>.local:/home/arduino/ArduinoApps/

• -r : 하위 디렉토리를 포함해 재귀적으로 복사

• -p : 파일 권한과 타임스탬프를 보존

UNO Q → 로컬 (폴더 pull)

UNO Q의 ArduinoApps/my-folder를 현재 디렉토리로 가져오는 예입니다.

scp -rp arduino@<보드이름>.local:/home/arduino/ArduinoApps/my-folder ./

SCP 사용 시 자주 하는 실수와 팁

• 공백이 있는 경로

  • 예: "My Folder/file.txt"처럼 공백이 있을 경우 경로 전체를 큰따옴표로 감싸야 합니다.

• 현재 위치 헷갈리지 않기

  • SCP 명령은 항상 PC의 터미널에서 실행해야 합니다. UNO Q에 SSH로 접속한 셸에서 실행하면 안 됩니다.

• 큰 파일 전송 시 네트워크 상태

  • Wi‑Fi 신호가 약하면 전송이 중간에 끊어질 수 있으므로, 안정적인 네트워크 환경에서 전송하는 것이 좋습니다.

SSH 접속 후 arduino-app-cli 활용하기

UNO Q에는 Arduino App Lab이 포함되어 있고, 이는 내부적으로 arduino-app-cli라는 CLI 도구를 기반으로 합니다. SSH를 통해 UNO Q 셸에 접속하면 이 도구를 직접 사용할 수 있습니다.

예를 들어, 특정 앱을 터미널에서 바로 실행하고 싶다면 다음과 같이 할 수 있습니다.

arduino-app-cli app start <앱이름>

• <앱이름>에는 실제 설치된 앱의 이름을 넣습니다.

• 이 명령을 통해 데스크톱 App Lab을 열지 않고도 앱을 실행할 수 있습니다.

arduino-app-cli는 이 외에도 다양한 서브 명령을 제공하며, 앱 목록 조회, 시스템 네트워크 모드 설정 등 여러 기능을 포함합니다. 더 자세한 기능과 사용법은 Arduino에서 제공하는 Arduino App CLI 가이드를 참고하는 것이 좋습니다.

보안 및 실제 활용 팁

SSH는 기본적으로 암호화된 통신을 사용하므로 비교적 안전하지만, 몇 가지 기본적인 보안 습관을 지키면 더 안심하고 사용할 수 있습니다.

• 비밀번호 관리

  • 첫 설정에서 지정하는 비밀번호는 다른 사람에게 알려지지 않도록 관리해야 합니다.

  • 공용 공간이나 여러 사람이 함께 쓰는 네트워크에서 사용한다면 비밀번호를 주기적으로 변경하는 것도 도움이 됩니다.

• 네트워크 환경 주의

  • 가능하면 신뢰할 수 있는 집/랩 네트워크에서만 UNO Q를 사용하고, 공용 개방형 Wi‑Fi에 그대로 연결하는 것은 피하는 것이 좋습니다.

  • SSH 포트(22번)를 외부 인터넷으로 직접 노출시키는 구성은 가급적 지양합니다.

• 실전 활용 예

  • UNO Q를 로봇이나 설치형 장치 내부에 넣고, Wi‑Fi만 연결해 둔 상태에서:

    • SSH로 접속해 로그를 확인하고,

    • SCP로 새 버전 앱 파일이나 설정 파일을 올린 뒤,

    • arduino-app-cli로 새 앱을 실행하는 식으로 원격 유지보수가 가능합니다.

  • 이를 통해 물리적으로 접근하기 어렵거나, 디스플레이가 없는 환경에서도 UNO Q를 편리하게 관리할 수 있습니다.

이 노트의 내용을 순서대로 따라가면,

1. PC에 SSH 클라이언트가 준비되어 있는지 확인하고,

2. UNO Q의 첫 설정을 통해 Wi‑Fi와 SSH를 활성화한 뒤,

3. ssh arduino@<보드이름>.local 또는 IP 주소로 접속하고,

4. 필요할 때는 scp로 파일과 폴더를 주고받으며,

5. SSH 셸에서 arduino-app-cli를 활용해 앱을 제어

하는 전체 흐름을 실전에 바로 적용할 수 있습니다.