부록 부록
A.1 부록 A — 트러블슈팅
이 부록은 이 책 전체(특히 1.4 초기 셋업, 4.4 Wi-Fi·BLE, 5.2 SSH, 7.1 ROS2 Jazzy, 8.5 MAVLink 실시간 제어, 10.2 실드 호환성)를 집필하며 실제로 커뮤니티에서 반복적으로 보고된 문제들을 forum.arduino.cc·Arduino 공식 Help Center·GitHub 이슈 등에서 조사해 정리한 것이다. 각 항목은 증상 → 원인 → 해결의 표 형식이며, 관련 본문 장을 교차참조로 붙였다.
⚠️ 표기 원칙: 이 부록의 내용은 대부분 공식 문서 또는 커뮤니티 포럼 스레드를 근거로 한다. 출처가 공식 문서(docs.arduino.cc, support.arduino.cc)인 항목은 "공식"으로, 포럼·GitHub 등 커뮤니티 보고에 근거한 항목은 "커뮤니티 방법(비공식)"으로 표기한다. 참고 링크는 A.4(부록 D)에 정리했다.
A.1.1 이 부록 사용법 — 진단 흐름
문제가 발생하면 아래 순서로 원인 범주를 좁혀 나간 뒤, 해당 절의 표를 확인한다.
A.1.2 초기 설정·연결 문제 (App Lab 인식, Wi-Fi, SSH)
| 증상 | 원인 | 해결 | 근거·교차참조 |
|---|---|---|---|
| App Lab이 보드를 전혀 인식하지 못함 | 충전 전용(데이터 라인 없는) USB 케이블 사용, 또는 보드가 아직 부팅 중(로고 스월 애니메이션 단계) | USB-C to USB-C 데이터 케이블로 PC에 직결. LED 매트릭스가 로고 스월 → 하트비트 애니메이션으로 바뀔 때까지 대기(부팅 완료 신호). 허브를 거치지 말고 PC 포트에 직결 | 공식(Arduino Help Center "If your Arduino UNO Q is not detected by Arduino App Lab") · 1.4 |
Windows에서 App Lab이 보드를 못 찾음(qdl도 실패) | Windows Defender/보안 소프트웨어가 mdns-discovery.exe의 네트워크 접근을 차단 | App Lab 최초 실행 시 표시되는 방화벽 허용 팝업에서 반드시 "허용" 선택. 이미 차단했다면 Windows 방화벽 설정에서 mdns-discovery.exe 인바운드/아웃바운드 규칙을 수동 추가 | 커뮤니티(포럼 스레드 "Arduino UNO Q not detected on Windows10", "App Lab and qdl cannot find Uno-q board") · 1.4 |
| Wi-Fi 프로비저닝이 App Lab에서 반복적으로 "연결 실패" | ① 신호가 약한 위치, ② 이전에 저장된 Wi-Fi 자격 증명이 손상/구버전, ③ 최근 Linux 이미지 재설치 직후 업데이트 절차 오류 | 보드를 라우터 가까이 두고 재시도. 그래도 실패하면 (a) 보드를 SBC 모드로 부팅해 화면에서 직접 네트워크 설정을 다시 입력하거나, (b) USB로 ADB 셸 진입 후 nmcli connection delete로 기존 Wi-Fi 프로필을 지우고 App Lab에서 재설정. App Lab을 완전히 종료 후 최소 2회 재시작 | 공식+커뮤니티(포럼 "Uno Q wont connect to wifi using App Lab", "UNO Q WiFi failed") · 1.4, 4.4 |
| SSH 접속이 "보드에 연결하는 중 오류 발생"에서 멈춤 | PC와 보드가 다른 네트워크(게스트 Wi-Fi·회사망·VPN 분리)에 있거나, 방화벽이 mDNS(UDP 5353)를 막음 | PC와 보드를 동일 서브넷에 연결. 회사망·게스트망은 기기 간 mDNS를 차단하는 경우가 많으므로 가정용 공유기 등 단순한 망에서 먼저 시도. mDNS 호스트명(<board>.local) 대신 App Lab에서 확인한 IP 주소로 직접 ssh arduino@<IP> 시도 | 공식(docs.arduino.cc/tutorials/uno-q/ssh) + 커뮤니티(포럼 "Connecting to UNO Q via network fails") · 5.2 |
| 최초 셋업을 건너뛴 채 SSH를 시도하면 접속 자체가 안 됨 | SSH는 App Lab 최초 셋업 마법사를 완료해야 활성화됨(공장 초기 상태에서는 비활성) | App Lab으로 최초 셋업(Wi-Fi 설정 포함)을 먼저 완료. 이미 셋업을 마쳤는데도 안 되면 ADB/USB 콘솔로 진입해 systemctl status ssh로 서비스 상태 확인 | 공식 · 1.4, 5.2 |
| App Lab이 "Error checking for updates" 메시지만 표시되고 진행 안 됨 | App Lab 자체가 로컬 개발에도 인터넷 접속(업데이트 확인)을 요구하는데, 네트워크·DNS·프록시 문제로 실패 | PC의 인터넷 연결·DNS 확인. 사내망이면 프록시·방화벽이 Arduino 업데이트 서버 접근을 막는지 확인 | 공식(Arduino Help Center) · 3.3 |
Blinky 예제 실행 시 method set_led_state not available 오류 | MCU에 업로드된 스케치와 MPU 쪽 앱이 기대하는 RPC 메서드가 어긋남(펌웨어 미스매치) 또는 Bridge 라우터 서비스가 재시작되지 않음 | 스케치를 MCU에 재업로드. MPU에서 arduino-router 서비스(브리지 라우팅 담당)를 재시작하거나 보드를 재부팅. App Lab·펌웨어 버전을 최신으로 맞춤 | 커뮤니티(포럼 "UNO Q Blinky (App Lab) not working") · 3.4, 4.2 |
A.1.3 소프트웨어·미들웨어 문제 (ROS2 등)
| 증상 | 원인 | 해결 | 근거·교차참조 |
|---|---|---|---|
| ROS2 Jazzy 소스 빌드 중 RViz2/Qt 관련 패키지에서 실패 | rviz2를 비롯한 ros-visualization 계열 패키지가 요구하는 Qt·GPU 라이브러리 스택이 QRB2210의 (헤드리스 상황의) 드라이버 구성과 충돌 | UNO Q 자체에서 GUI 도구를 실행할 계획이 없다면, ros2.repos를 내려받은 뒤 ros-visualization·rviz 관련 저장소 항목을 빌드 대상에서 제외하고 colcon build. RViz2로 시각화가 필요하면 같은 네트워크의 별도 PC에 ROS2를 설치해 원격으로 토픽을 구독·시각화 | 커뮤니티(GitHub mjs513/Arduino-Uno-Q-and-ROS2-Implementation "Install RViz2.md") · 7.1 |
| ROS2 소스 빌드 중 프로세스가 죽거나 시스템이 멈춤(OOM) | colcon build가 기본적으로 가용 코어 수만큼 병렬 빌드를 시도하는데, UNO Q의 2GB/4GB RAM(+스왑 없음)으로는 대형 패키지(특히 rviz·rclcpp 관련)에서 메모리가 고갈됨 | ① 스왑 파일을 추가(fallocate/dd로 스왑 생성 후 mkswap·swapon, 예: 4GB 스왑) — 커뮤니티 보고 기준 4GB 스왑을 추가하면 빌드가 끝까지 완료되지만 30분 이상 소요될 수 있음. ② 병렬도를 제한: colcon build --executor sequential --parallel-workers 1 또는 MAKEFLAGS="-j1"로 코어당 메모리 사용을 줄임 | 커뮤니티(ROS Answers "Build of ROS2 package: Out of memory", 포럼 "ROS2 on UNO Q. Making good progress!") · 5.4, 7.1 |
rmw_zenoh 사용 시 노드가 서로를 못 찾음 | zenoh 라우터(zenohd) 미실행, 또는 여러 노드가 서로 다른 ROS_DOMAIN_ID/zenoh 설정을 사용 | RMW_IMPLEMENTATION=rmw_zenoh_cpp 지정 확인, 필요 시 zenohd 라우터를 별도로 기동, 모든 노드의 도메인·네임스페이스 설정 일치 확인 | 커뮤니티(ros2/rmw_zenoh 이슈 트래커 일반 패턴) · 7.2 |
| eMMC 저장 공간이 예상보다 빨리 참(특히 2GB/16GB 모델) | Docker 이미지, ROS2 소스 빌드 산출물(build/·log/ 디렉터리), AI 모델 캐시가 16GB eMMC를 빠르게 잠식 | df -h로 확인 후 docker system prune, ROS2 워크스페이스의 build/·log/ 정리, 대용량 워크스페이스는 USB 외장 스토리지로 이전. 4GB/32GB 모델이 ROS2·AI 개발에는 여유가 큼 | 일반 임베디드 리눅스 운영 지식(개별 포럼 스레드로 특정하지 못함, 확인 필요 라벨) · 5.4 |
A.1.4 하드웨어·전원 문제 (실드, 발열)
| 증상 | 원인 | 해결 | 근거·교차참조 |
|---|---|---|---|
| 5V 기반 UNO 실드를 장착한 뒤 보드가 정지하거나 오작동 | UNO Q의 GPIO 로직 레벨은 3.3V인데, UNO 헤더의 VIN·AREF·IOREF·BOOT·GND는 실드에서 직결 관통된다. 실드가 5V 신호선을 데이터 핀에 연결하면 UNO Q 쪽 3.3V 회로에 과전압이 인가되어 영구 손상 가능 | 실드를 장착하기 전 해당 실드의 로직 레벨(3.3V/5V)을 반드시 확인. 5V 전용 센서·실드가 필요하면 레벨시프트 실드(예: 서드파티 3.3V↔5V I2C/SPI/UART 레벨시프터 보드)를 사이에 삽입한다. USB·외부 전원을 분리한 상태에서 실드를 탈부착 | 공식 경고 취지 + 커뮤니티(포럼 "UNO Q and Arduino Shields, initial findings") · 2.2, 10.2 |
| 특정 UNO 실드(예: Motor Shield Rev3)가 UNO Q에서 예상대로 동작하지 않음 | 구형 실드가 5V 전제로 설계돼 있거나, 전류 요구·핀 배치가 UNO Q 관통 핀과 완전히 일치하지 않는 경우가 보고됨 | 사용 전 커뮤니티 호환성 보고(포럼 "Arduino Uno Q and Motor Shield Rev3 Connection and Compatibility", "Arduino UNO Q compatibility")를 검색해 동일 실드 사례 확인, 가능하면 저전류로 먼저 테스트 | 커뮤니티(포럼) · 10.2 |
| SBC 모드(데스크톱 화면 출력)로 장시간 사용 시 발열·화면 글리치 | 방열판·통풍이 없는 상태에서 QRB2210이 지속 고부하(데스크톱 GUI) 상태로 장시간 구동 | 인클로저에 통풍구를 두거나 방열판/팬을 추가(11.1 인클로저 설계 참조), 장시간 SBC 데스크톱 사용은 피하고 필요한 작업만 헤드리스로 수행. 발열이 심하면 /sys/class/thermal/thermal_zone*/temp로 온도 모니터링 | 커뮤니티(포럼 "Overheating Arduino Uno Q") · 2.4, 11.1 |
A.1.5 실시간 제어·MAVLink 연동 문제 (8.5 관련)
STM32(MCU)에서 MAVLink로 PX4/ArduPilot 비행 컨트롤러(FC)에 오프보드·가이디드 setpoint를 보내는 구성(8.5)에서 흔히 겪는 문제다. 이 항목들은 PX4/MAVLink 공식 문서의 일반적 요구사항에서 도출한 것으로, UNO Q 특정 포럼 사례를 직접 확인하지는 못했다 — 확인 필요 라벨.
| 증상 | 원인 | 해결 | 근거·교차참조 |
|---|---|---|---|
| FC가 오프보드/가이디드 setpoint를 받고도 모드 진입을 거부하거나 즉시 이탈 | PX4는 오프보드 모드 유지에 지속적인 "생존 신호"(setpoint 스트림)를 요구하며, 스트림이 일정 시간(COM_OF_LOSS_T 등) 끊기면 자동으로 모드를 이탈 | STM32 쪽 실시간 루프가 setpoint를 끊김 없이 일정 주기로 계속 보내는지 확인(8.2 타이밍 설계). 최초 진입 전에 몇 사이클 미리 스트리밍을 시작해야 하는 FC 요구사항도 확인 | 공식(MAVLink 오프보드 제어 가이드, PX4 오프보드 모드 문서) · 8.2, 8.5 |
| MAVLink 하트비트가 전혀 수신되지 않음(FC와 통신 자체가 안 됨) | UART 배선(TX/RX 교차 여부), 보레이트 불일치, GND 공통 연결 누락이 흔한 원인 | STM32 UART 보레이트와 FC 텔레메트리 포트 보레이트 일치 확인, TX↔RX 교차 배선 확인, 두 보드의 GND를 반드시 공통으로 연결 | 일반 MAVLink/시리얼 통신 상식(UNO Q 특정 사례 미확인, 확인 필요) · 8.5 |
| ArduPilot에서 가이디드 모드 진입은 되지만 즉시 다시 원래 모드로 전환됨 | ArduPilot Guided 모드도 PX4 오프보드와 유사하게 외부 제어 신호가 끊기면 안전상 자동 복귀하도록 설계됨 | PX4와 동일하게 STM32 쪽에서 setpoint 스트림이 끊기지 않는지, 워치독·인터럽트 우선순위 설계(8.2)에 결함이 없는지 점검 | 공식(ArduPilot Guided 모드가 PX4 Offboard와 동등 개념이라는 점은 확인, 세부 파라미터명은 확인 필요) · 8.5 |
A.1.6 그래도 해결이 안 될 때
forum.arduino.cc의 UNO Q 전용 카테고리(App Lab, 하드웨어, 소프트웨어 하위 포럼)에서 증상 키워드로 먼저 검색 — 신제품이라 최근 스레드일수록 최신 펌웨어 기준으로 유효할 가능성이 높다.- 공식 Help Center(
support.arduino.cc)에서 "UNO Q" 검색. - 위 두 곳에서도 못 찾으면 새 글을 게시하되, App Lab 버전, 보드 RAM 모델(2GB/4GB), PC 운영체제, 정확한 오류 메시지 전문을 함께 첨부하면 답변 속도가 빨라진다(포럼 관례).
- 부록 D(A.4)의 링크 모음도 함께 참고.