제4부 프로그래밍 가이드

4.4 Wi-Fi·Bluetooth 통신

UNO Q는 듀얼밴드 Wi-Fi 5(802.11a/b/g/n/ac, 2.4/5GHz)와 Bluetooth 5.1을 지원하는 무선 모듈(WCBN3536A, Qualcomm WCN3980)을 온보드에 갖췄다(2.1). 이 장은 "어느 프로세서가 무선을 다루는가"부터 정리하고, Wi-Fi·Bluetooth를 커맨드라인으로 설정하는 법, 그리고 MPU Python에서 HTTP 요청과 로컬 웹 대시보드를 만드는 예제까지 다룬다. 이 마지막 예제는 12.1(IoT 대시보드 실전 프로젝트)의 축소판이다.

4.4.1 무선은 MPU(Linux)가 담당한다

공식 데이터시트는 "무선 모듈이 Wi-Fi 데이터에는 SDIO를, Bluetooth 제어에는 UART를 쓴다"고만 밝히고 어느 프로세서에 배선되는지는 명시하지 않는다. 다만 실제 사용 사례는 일관되게 하나를 가리킨다 — Wi-Fi·Bluetooth 둘 다 Debian Linux(MPU, QRB2210) 쪽에서 NetworkManager(nmcli)와 BlueZ(bluetoothctl)로 관리된다는 점이다(App Lab 최초 설정 화면의 Wi-Fi 자격증명 입력, 커뮤니티의 UNO Q Bluetooth 스트리밍 서버 구축 사례 등). STM32U585(MCU) 쪽에는 무선 스택이 없다 — Zephyr 기반 Arduino Core에 Wi-Fi나 BLE API가 노출되지 않으며, MCU가 직접 전파를 쏘거나 받는 경로는 없다.

이 구조는 Nano 33 BLE 같은 보드(MCU가 직접 ArduinoBLE 라이브러리로 BLE를 구동)와 근본적으로 다르다. UNO Q에서 MCU가 "무선으로 데이터를 보내고 싶다"면, 답은 언제나 Bridge를 거쳐 MPU의 네트워크 스택을 빌려 쓰는 것이다(4.2). 반대로 MCU 자체는 UART·SPI·I2C·CAN(FDCAN1, D4/~D5) 같은 유선 인터페이스를 직접 갖고 있어, 외부 무선 모듈(예: 별도 ESP 계열 AT-커맨드 모듈)을 유선으로 연결하는 것도 이론적으로는 가능하지만, 이미 온보드에 Wi-Fi/BT가 있는데 중복 모듈을 추가할 이유는 거의 없다.

4.4.2 Wi-Fi 설정

4.4.2.1 App Lab로 설정(GUI)

가장 쉬운 경로는 4.1.3.2에서 본 최초 설정 흐름이다.

App Lab을 실행하고 보드를 연결(또는 SBC 모드로 부팅)한다.
최초 설정 마법사에서 기기 이름·비밀번호를 지정한다.
Wi-Fi 자격증명(SSID·비밀번호)을 입력한다.
연결이 확인되면 이후에는 USB 없이 Network 타깃(같은 네트워크상의 IP/호스트명)으로 App Lab이 보드에 접속한다.

4.4.2.2 커맨드라인으로 설정(ADB + nmcli)

App Lab 없이, 또는 이미 부팅된 보드를 헤드리스로 재설정할 때는 ADB로 셸에 들어가 nmcli를 직접 쓴다(커뮤니티 절차, kevsrobots.com 기준).

# 1. 보드가 ADB로 인식되는지 확인
adb devices

# 2. 셸 진입
adb shell

# --- 이하는 보드 안에서 실행 ---

# 3. 주변 Wi-Fi 네트워크 검색
nmcli device wifi list

# 4. 연결
sudo nmcli dev wifi connect "YOUR_SSID" password "YOUR_PASSWORD"

# 5. 연결 확인
nmcli
hostname -I

# 6. (선택) SSH 활성화 — 5.2에서 이어서 다룬다
sudo apt install openssh-server -y
sudo systemctl enable ssh
sudo systemctl start ssh

# 7. 네트워크를 바꿔야 할 때
nmcli device disconnect wlan0
sudo nmcli dev wifi connect "NEW_SSID" password "NEW_PASSWORD"

연결은 nmcli가 자동으로 저장하므로, 재부팅 후에도 같은 네트워크가 있으면 자동 재접속한다. hostname -I로 확인한 IP가 이후 SSH·App Lab Network 타깃·웹 대시보드 접속에 쓰인다.

⚠️ 확인 필요: Arduino 포럼에는 "UNO Q Wi-Fi suddenly DEAD"류의 스레드가 여럿 보고되어 있다. 원인·재현 조건은 이 조사로 확정하지 못했다 — 연결이 갑자기 끊기면 nmcli device status로 인터페이스 상태를 먼저 확인하고, 필요하면 sudo systemctl restart NetworkManager를 시도한다. 재발하면 보드 패키지·펌웨어를 최신으로 갱신했는지(4.1.2.1) 확인한다.

4.4.3 Bluetooth 설정

Bluetooth도 Linux 쪽 표준 도구인 bluetoothctl(BlueZ)로 스캔·페어링한다.

bluetoothctl
power on
scan on
# 원하는 장치가 목록에 표시되면 scan off, 그 MAC 주소를 기록
devices
agent on
pair <MAC주소>
trust <MAC주소>
connect <MAC주소>

실제로 커뮤니티가 이 경로로 UNO Q를 Bluetooth 스피커용 오디오 스트리밍 서버로 구성한 사례가 보고되어 있다(xda-developers, 2026년) — MPU가 Debian이므로 일반 리눅스 데스크톱에서 하던 Bluetooth 오디오·페어링 절차가 그대로 통한다는 뜻이다.

BLE(Bluetooth Low Energy) 주변기기(peripheral) 역할이 필요한 프로젝트(예: 스마트폰 앱과 직접 BLE로 통신)라면, ArduinoBLE 같은 MCU 전용 라이브러리는 UNO Q에서 쓸 수 없다 — 무선 스택이 MCU에 없기 때문이다(4.4.1). 대신 Linux BlueZ의 D-Bus API나 bluetoothctl을 Python에서 감싸는 방식(예: bleak 같은 파이썬 BLE 라이브러리, 검증 필요)으로 MPU 쪽에서 BLE 역할을 구현하고, 필요하면 Bridge로 MCU와 값을 주고받는다.

4.4.4 MPU Python에서 HTTP 요청 예제

MPU는 표준 Debian이므로 일반적인 Python 네트워킹이 그대로 된다. App Lab App의 python/requirements.txt에 requests를 추가하면 실행 시 자동 설치된다(4.2.1).

# python/main.py
import requests

def fetch_weather():
    url = "https://api.open-meteo.com/v1/forecast"
    params = {"latitude": 37.5, "longitude": 127.0, "current_weather": True}
    resp = requests.get(url, params=params, timeout=5)
    resp.raise_for_status()
    return resp.json()["current_weather"]

if __name__ == "__main__":
    weather = fetch_weather()
    print(f"기온 {weather['temperature']}°C, 풍속 {weather['windspeed']}km/h")

이 예제는 UNO Q에 특별한 API가 없다 — 일반 Debian에서 Python requests를 쓰는 것과 완전히 동일하다. UNO Q가 특별한 지점은 이 결과를 Bridge로 MCU에 넘겨 LED 매트릭스에 날씨 아이콘을 표시하거나, MCU가 읽은 센서값을 반대로 클라우드로 업로드하는 등 MCU 실시간성과 MPU 네트워킹을 결합할 때다 — App Lab로 MPU-MCU 앱을 조립하는 구체적 절차는 4.2에서 다룬다.

4.4.5 로컬 웹 대시보드 — WebUI Brick

4.2.8에서 소개한 WebUI Brick으로, MCU가 읽은 센서값을 브라우저에서 실시간으로 보는 최소 대시보드를 만들어본다. 4.2.5의 HC-SR04 거리 센서 App을 확장한다.

# python/main.py
from arduino.app_utils import App, Bridge
from arduino.app_bricks.web_ui import WebUI
import time

web_ui = WebUI()
latest_distance = -1.0

def loop():
    global latest_distance
    distance = Bridge.call("get_distance")
    if distance is not None and distance > 0:
        latest_distance = distance
        web_ui.send_message("distance", {"cm": round(distance, 1)})
    time.sleep(0.2)

# REST로도 최신 값을 조회할 수 있게 노출
web_ui.expose_api("GET", "/distance", lambda: {"cm": round(latest_distance, 1)})

App.run(user_loop=loop)

WebUI Brick은 기본적으로 7000번 포트에서 수신 대기한다(공식 저장소 코드 기준). 보드가 Wi-Fi에 연결된 상태라면 http://<UNO_Q_IP>:7000/distance로 최신 값을 바로 확인할 수 있고, WebSocket으로 send_message를 구독하는 프론트엔드 HTML/JS를 추가하면 실시간 그래프도 가능하다.

⚠️ 확인 필요: app.yaml에서 이 Brick을 정식으로 선언하는 정확한 문법(bricks: 항목에 무엇을 적는지, requirements.txt에 어떤 패키지명을 넣는지)은 이번 조사에서 실제 예제 파일로 확인하지 못했다. 위 Python 코드(from arduino.app_bricks.web_ui import WebUI 이하)는 공식 저장소 코드를 근거로 삼았지만, App Lab에서 Brick을 App에 "추가"하는 GUI 절차나 매니페스트 세부사항은 App Lab의 Bricks 패널에서 직접 확인한 뒤 진행한다. 완전한 대시보드(프론트엔드 포함, 이력 저장, 다중 센서)는 12.1에서 처음부터 끝까지 다시 다룬다.

4.4.6 MCU 측 통신 옵션 정리

MCU(STM32U585)가 무선은 못 하지만, JDIGITAL1/JSPI1 헤더로 아래 유선 인터페이스를 직접 갖고 있다는 점은 실전에서 자주 쓰인다.

인터페이스	핀(JDIGITAL1 기준)	용도 예시
UART	D0(RX)/D1(TX)	외부 MCU·GPS·MAVLink 장치와 직결(8.5에서 PX4/ArduPilot 연동에 사용)
I2C(표준)	A4(SDA)/A5(SCL)	센서(4.3.6). `Wire` 이슈 시 Qwiic(`Wire1`)로 대체
SPI	D11(MOSI)/D12(MISO)/D13(SCK) 또는 JSPI1 전용 헤더	고속 주변장치, 디스플레이 등
CAN(FDCAN1)	D4(TX)/~D5(RX)	차량·로봇용 CAN 버스 장치

무선이 꼭 필요한데 MPU를 거치고 싶지 않은 특수한 경우(예: MPU 재부팅 중에도 끊기지 않는 통신)라면, 위 UART/SPI에 별도 무선 모듈(ESP-AT, nRF24L01 등)을 유선으로 연결하는 방법도 있다 — 다만 이 경우 MCU가 그 모듈의 프로토콜 스택을 스케치 안에서 직접 구현해야 하므로 복잡도가 크게 늘고, 대부분의 프로젝트에서는 Bridge + MPU 네트워킹(4.2)이 더 실용적이다.

4.4.7 다음 장으로

이 장에서는 UNO Q의 무선이 어느 프로세서 책임인지, nmcli/bluetoothctl로 어떻게 다루는지, 그리고 MCU 센서값을 브라우저에 표시하는 최소 대시보드까지 만들어봤다. 제4부는 여기서 마무리되며, 제5부(운영체제 다루기, 5.1~5.5)에서 Debian 자체의 부팅·서비스·SSH·저장소·전력 관리를 더 깊이 다룬다.

교차참조: 2.1(무선 모듈 하드웨어) · 3.2(Zephyr 기반 Arduino Core — 무선 스택 부재) · 3.4(Bridge 내부) · 4.2(Bridge·Bricks 기초, HC-SR04 예제 출처) · 5.2(SSH 원격 접속) · 8.5(MCU UART로 PX4/ArduPilot MAVLink 연동) · 10.3(Qwiic·Wire1) · 12.1(IoT 대시보드 실전 프로젝트)