Unreal 차량 ↔ 웹 MQTT
AI 작업 가이드

Vehicle Template · 로컬 Mosquitto · 키보드/모바일 터치 양방향 제어

목표
웹 WASD/터치로 Unreal 차량을 제어하고, Unreal WASD 상태를 웹에 표시한다. 현재는 실제 로버 없이 같은 Mac·같은 Wi-Fi에서 실행한다.

환경 선택

공통 기준	macOS 기준	Windows 기준
Vehicle Template, MQTT 토픽, JSON, 차량 제어, 안전 타임아웃	Homebrew, `python3`, `ipconfig getifaddr en0`	Mosquitto 설치본, `py`, `ipconfig`, Defender Firewall

AI는 먼저 운영체제를 확인하고, 해당 운영체제의 명령만 사용한다.

아키텍처

웹 또는 휴대폰 → MQTT WebSocket :9001 → Mosquitto ← MQTT TCP :1883 ← Unreal 차량

방향	토픽	역할
웹 → Unreal	`testvi/web/input`	W/A/S/D JSON 입력
Unreal → 웹	`testvi/unreal/input`	Unreal 키 상태 표시

참고 파일 선택표

파일	언제 참고하는가
`ch12_mqtt.pdf`	MQTT/디지털 트윈 구조를 설명하거나 설계할 때
`mqtt_1_publish.py`	상태 발행(Publish) 흐름을 만들 때
`mqtt_2_subscribe.py`	수신(Subscribe)과 명령 처리를 만들 때
`mqtt_3_subscribe_try.py`	연결 복구 뒤 재구독을 설계할 때
`mqtt_4_motor.py`	실제 로버의 FORWARD/STOP 명령 확장 시에만
`MqttVehicleBridgeSubsystem.cpp`	Unreal MQTT·차량 제어를 수정할 때
`index.html`	웹/모바일 터치 UI를 수정할 때
`mosquitto.local.conf`	macOS 브로커·Wi-Fi IP를 바꿀 때
`mosquitto.windows.conf.template`	Windows 브로커 설정을 시작할 때

교재 Python 파일은 설계 참고용이다. 현재 웹·Unreal 테스트 토픽에는 그대로 복사해 사용하지 않는다.

AI가 수행할 작업

UE Vehicle Template을 만들고 기본 차량 조작을 먼저 검증한다.
MQTT 플러그인과 Runtime C++ 모듈을 활성화한다.
게임 월드에서만 MQTT TCP 1883에 연결한다.
웹 JSON을 구독해 Throttle=W−S, Steering=D−A로 차량에 적용한다.
Unreal WASD 상태를 0.1초 간격으로 웹 토픽에 발행한다.
웹은 키보드·멀티터치·현재 입력·마지막 송신 상태를 제공한다.
웹 신호가 0.35초 끊기면 차량을 정지한다.

C++에서는 MQTT Blueprint wrapper가 아니라 IMQTTCoreModule / IMQTTClient 인터페이스를 사용한다.

사람이 해야 하는 부분

사람 확인 필요

Unreal Editor의 C++ 컴파일 승인
Editor에서 ▶ Play 실행
Mosquitto 설치 승인
Mac 방화벽의 Python 웹 서버 수신 연결 허용
Mac과 휴대폰이 같은 Wi-Fi인지 확인

실행 순서

/opt/homebrew/opt/mosquitto/sbin/mosquitto -c web-controller/mosquitto.local.conf -v
cd web-controller && npm install
python3 -m http.server 5173

Mac 웹: http://localhost:5173
휴대폰 웹: http://192.168.0.21:5173
휴대폰 MQTT: ws://192.168.0.21:9001

Windows 실행 기준

REM Mosquitto: Windows Wi-Fi IPv4를 설정 파일에 입력
mosquitto -c web-controller\mosquitto.windows.conf -v

cd web-controller
npm install
py -m http.server 5173

Windows에서는 ipconfig의 Wi-Fi IPv4를 사용한다. Windows Defender Firewall에서 Python과 Mosquitto의 사설 네트워크 수신 연결을 허용한다.

완료 기준

웹에 MQTT 연결됨이 보인다.
Unreal Output Log에 구독 성공 메시지가 보인다.
웹/휴대폰 입력으로 차량이 움직인다.
Unreal WASD가 웹에 표시된다.
웹 연결이 끊기면 0.35초 내 차량이 멈춘다.

상세 규칙·문제 해결·확장 지침은 WEB_UNREAL_MQTT_GUIDE.md를 기준 문서로 사용한다.