G1 Docent Spatial Console

G1 도슨트 프로젝트의 첫 번째 단계인 SLAM & Navigation을 위한 로봇 로컬 웹 콘솔입니다.

Unitree에서 배포한 원본 SLAM C++ 예제와 RViz 설정은 vendor/unitree_slam에 설치되어 있습니다. 원본 ZIP은 vendor/unitree_slam_example.zip으로 보관합니다.

현재 제공 기능

• 실내 매핑 시작
• 매핑 중 안전한 웹 텔레옵(전/후/좌/우/회전 및 즉시 정지)
• PointCloud2 기반 2D 지도 시각화
• Odometry 기반 로봇 위치, 궤적, 방향 표시
• PCD 맵 저장
• 저장된 맵을 이용한 재위치 추정
• 지도 클릭을 통한 목표 좌표 지정 및 이동
• Waypoint 저장 및 재사용
• Navigation 일시정지·재개
• API 응답, SLAM 상태, 도착 및 오류 이벤트 표시
• 고해상도 화면용 100%·115%·125% UI 배율 전환 및 설정 저장
• 향후 LiveKit·LLM 음성 모듈을 위한 독립 화면과 API 경계

빠른 실행: 시뮬레이션

외부 패키지 없이 Python 3.8 이상에서 실행됩니다.

chmod +x scripts/*.sh
./scripts/run_mock.sh

브라우저에서 http://<G1-PC-IP>:8080을 엽니다. 현재 장비에서는 http://192.168.123.164:8080입니다.

실제 G1 실행

Python 3.8 환경에 공식 unitree_sdk2_python을 설치한 후 실행합니다. 장비에 설치된 CycloneDDS는 Python 바인딩 빌드에 필요한 IDLC 헤더가 빠져 있으므로, 설정 스크립트가 프로젝트 내부에 CycloneDDS 0.10.x와 Python SDK를 격리 설치합니다.

./scripts/setup_unitree_sdk.sh
./scripts/run_unitree.sh

기본값은 eth0, /home/unitree/maps, 포트 8080입니다. 필요하면 DOCENT_INTERFACE, DOCENT_MAP_DIRECTORY, DOCENT_PORT 환경 변수로 변경할 수 있습니다.

실제 모드에서는 Unitree Python SDK의 DDS 채널로 PointCloud2와 Odometry를 직접 구독하므로 별도의 ROS2 노드가 없어도 지도 시각화가 동작합니다.

외부 ROS2 PC에서 지도 데이터를 전달해야 하는 경우에만 별도 터미널에서 보조 브리지를 실행합니다. G1 PC의 ROS Foxy와 /usr/local에 설치된 CycloneDDS 버전이 충돌할 수 있으므로 이 경로는 직접 DDS 구독보다 우선하지 않습니다.

source /opt/ros/foxy/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
python3.8 -m app.ros2_bridge \
  --interface eth0 \
  --target 127.0.0.1:8766

기본 시나리오

1. 매핑 시작을 누릅니다.
2. 지도 데이터가 들어오는지 확인합니다.
3. 웹 텔레옵 또는 리모컨으로 G1을 천천히 이동시킵니다.
4. 충분한 영역을 스캔한 뒤 맵 이름을 입력하고 맵 저장을 누릅니다.
5. 저장한 맵을 선택하고 초기 위치를 입력해 재위치 추정을 시작합니다.
6. 지도에서 목적지를 클릭하고 이동 시작을 누릅니다.
7. 이동 상태, 현재 위치, 궤적과 도착 이벤트를 확인합니다.

안전

• 텔레옵 속도는 백엔드에서도 제한됩니다.
• 텔레옵 버튼을 놓으면 정지 명령을 전송합니다.
• 브라우저가 명령 갱신을 중단해도 짧은 duration 이후 속도 명령이 끝납니다.
• Navigation 일시정지와 SLAM 종료는 다른 동작입니다.
• 첫 실제 시험은 장애물이 없는 넓은 공간에서 비상 정지 수단을 준비하고 진행하세요.

구조

Browser UI
  ├─ REST commands
  └─ SSE telemetry
         │
Spatial Controller
  ├─ Mock adapter
  ├─ Unitree SDK2 RPC adapter
  └─ ROS2 UDP bridge
         │
G1 slam_operate / sport / PointCloud2 / Odometry

음성 시스템은 app/modules/voice.py의 계약을 통해 나중에 LiveKit room, LLM session, transcript와 latency 상태를 추가할 수 있습니다. SLAM 모듈과 음성 모듈은 서로 직접 호출하지 않고 향후 Orchestrator가 둘을 조정합니다.