개발자 가이드

소개

RBQ 시뮬레이션, 명령 및 배포/업데이트 매뉴얼에 오신 것을 환영합니다

이 매뉴얼은 RBQ 로봇을 시뮬레이션하고 명령을 보내며, 실제 로봇에 직접 개발한 알고리즘을 배포하는 과정을 종합적으로 설명합니다.

개발자를 위한 시뮬레이터와 운용 앱

• RBQ 로봇은 MuJoCo를 사용해 정밀하게 시뮬레이션할 수 있습니다. 📝 시뮬레이션 환경 "playground"는 다음 파일을 편집하여 수정할 수 있습니다: resources/model/rbq_environment.xml
• 로봇에 명령을 보내고 상태를 보는 일은 RBQ 앱으로 합니다. 실제 로봇에 쓰는 앱과 같은 앱이라, 시뮬레이터에서 익힌 절차가 실기에서 그대로 통합니다.
  • 로봇 상태와 센서 상태를 보여 주고, 터치·게임패드·키보드 입력을 받습니다.
  • 다운로드 페이지에서 받을 수 있습니다. 앱 전체 설명은 RBQ 앱에 있습니다.

i

참고

이 저장소에는 PC 에서 도는 제어 GUI 가 들어 있지 않습니다. 예전 버전에는 정비용 bin/GUI 가 함께 들어 있었지만 더는 배포하지 않으며, 이 가이드의 모든 작업은 RBQ 앱으로 대신합니다.

설치

• 이 섹션에서는 RBQ 로봇 시뮬레이션 및 개발 환경을 처음부터 설치하고 구성하는 방법을 설명합니다.

시스템 요구사항

원활한 시뮬레이션 및 개발 환경 구동을 위해 다음 사양을 권장합니다:

• 운영 체제: Ubuntu 22.04 (x86)

• 최소 PC 사양:

  • CPU: Intel Core i7 12세대
  • RAM: 16 GB
  • 저장 공간: 25 GB

• 제어 장치

  • 키보드: W, A, S, D, Q, E 키와 방향키
  • 조이스틱: Logitech Wireless Gamepad F710 (권장)

  

1. RBQ 저장소 다운로드

• 아래 명령어로 저장소를 클론하세요:

git clone https://github.com/RainbowRobotics/RBQ.git
cd RBQ

모든 스크립트, 바이너리, SDK 코드는 RBQ/ 아래에 있습니다. 모든 명령어는 이 디렉토리에서 실행하세요.

참고: 사전 빌드된 바이너리는 bin-x86_64/(arm64는 bin-aarch64/)에 들어 있으므로 별도 빌드 단계는 필요하지 않습니다.

▶ 시뮬레이션

• 시뮬레이터는 도커 안에서 실행됩니다. 도커 외에는 설치할 것이 없고, 도커가 없으면 스크립트가 설치를 제안합니다. 처음 실행할 때 이미지를 만드느라 몇 분 걸립니다. MuJoCo를 참조하세요.
• 아래 스크립트로 RBQ 제어 모듈과 MuJoCo 시뮬레이터를 한 번에 실행합니다.

참고: 인자:

• --help : 도움말 메시지를 출력하고 종료합니다.
• --vision : 비전 모듈을 함께 실행합니다 (예: 비전 센서, 계단 오르기 활성화).
• --no-gui : 로봇 웹 UI 를 열지 않습니다. 이 인자가 없으면 로봇이 뜬 뒤 브라우저에서 http://127.0.0.1:8080 이 열립니다 — rb / rainbow2026 으로 로그인합니다.

bash scripts/sim.bash --vision

• 이 터미널에서 계속 실행되며, Ctrl-C 로 멈춥니다. 이 PC 에서 도커에 sudo 가 필요하면 비밀번호를 묻습니다. 입력하면 계속 진행됩니다.

초기화 - 시뮬레이션 로봇 연결 및 시작

시뮬레이터를 띄운 그 PC 에서 RBQ 데스크탑 앱을 켭니다. 주변에 로봇망이 없으면 앱이 이 PC 의 MuJoCo 시뮬레이터를 스스로 찾아 붙습니다 — 연결을 참고하세요.

1. 허브에서 컨트롤을 눌러 제어 홈을 엽니다.
2. 초록색 자동 기동 버튼을 누르고, 창에서 자동 기동을 눌러 시퀀스가 완료로 바뀔 때까지 기다린 뒤 닫기를 누릅니다.
3. 모션 카드의 STAND 를 누릅니다. 로봇이 일어서고, 이후 명령을 받을 준비가 됩니다.

• 📝 직전 자세에 따라 일어서는 데 1초쯤 걸릴 수 있습니다.

로봇 조종하기

모션 카드에 SIT, STAND, WALK, STAIRS 가 있고, 점선 모션 버튼을 누르면 Wave·Run 이 들어 있는 전체 그리드가 열립니다. 조이스틱이 무엇을 하는지는 지금 어떤 모션인지에 따라 달라집니다 — 서 있으면 자세를 다듬고, 걸으면 로봇을 몹니다.

→ 모션 명령 에 게이트별 축 표가 있고, 제어 홈 에 PC 키보드 조종을 포함한 나머지 화면 설명이 있습니다.

실제 로봇

이 섹션에서는 실제 RBQ 로봇 작동 방법을 설명합니다.

📖 상세한 작동 절차는 작동 가이드를 참고하세요

1. 로봇에 연결하기

• PC를 로봇 Wi-Fi에 연결합니다. 📝 Wi-Fi SSID: RBQ_xxxx.

2. 앱에서 로봇 제어 시작하기

RBQ 앱을 켜고 로봇 목록에서 로봇을 고릅니다 — 연결 참고. 로봇과 통신이 시작되면 상태줄이 연결됨 과 경로를 표시합니다.

• 컨트롤을 눌러 제어 홈을 엽니다.
• 자동 기동을 누르고, 창에서 자동 기동을 눌러 완료가 뜰 때까지 기다립니다. 이제 로봇이 활성화되어 조작할 준비가 됐습니다.

3. 명령은 시뮬레이션과 동일합니다

• 📝 실제 로봇을 조작하기 전에 먼저 시뮬레이터에서 충분히 연습해 보세요.

웹 UI

로봇은 8080 포트로 웹 브라우저용 페이지도 직접 띄웁니다. 앱 없이 노트북에서 로봇 상태를 빠르게 살펴볼 때 씁니다. 시뮬레이터도 같은 페이지를 띄웁니다.

로봇	주소
이 PC 의 시뮬레이터	http://127.0.0.1:8080
실제 로봇 (PC 가 로봇 Wi-Fi 에 연결된 상태)	http://192.168.0.10:8080

브라우저가 로그인을 요청합니다. 기본 계정은 다음과 같습니다.

• 사용자 이름: rb
• 비밀번호: rainbow2026

페이지	하는 일
Dashboard	로봇 정보, 상태 점검, 주행 기록, PC 상태, 다리 관절 12개의 실시간 표(상태·에러·온도·각도·토크·전류), 소프트웨어 업데이트, 로봇 프로세스별 상태
Control	모션 버튼(Model Walking, AI Motions), 화면 조이스틱, Auto Start, 비상 정지, 게임패드 소유권. PC 에 꽂은 게임패드(브라우저가 알아보도록 버튼을 한 번 누릅니다)나 키보드로도 조종합니다 — W/S 전진·후진, A/D 옆걸음, Q/E 또는 ←/→ 회전, ↑/↓ 오른쪽 스틱 위아래
Configuration	로봇 설정 파일(motion.ini, hal-config.ini, Vision.ini, Streamer.ini)을 보고 고칩니다
System Log	실시간 로그, 고른 날짜의 로그, 블랙박스 세션 재생과 zip 다운로드

⚠

주의

Control 은 앱과 똑같이 로봇을 움직입니다. Configuration 은 로봇 설정 파일을 바로 고칩니다 — 무엇을 하는 값인지 알 때만 바꾸세요.

로봇 업데이트

로봇 소프트웨어는 앱에서 갱신합니다. 소프트웨어 업데이트 화면에서 로봇 소프트웨어 전송 을 누르면 앱이 새 버전을 보내고, 전송이 끝나는 즉시 로봇이 배포한 뒤 재부팅 여부를 묻습니다.

→ 로봇 소프트웨어 업데이트

앱 자체도 같은 화면의 이 앱 절에서 업데이트합니다.

→ 앱 업데이트

앱 없이 하려면 웹 UI Dashboard 의 Software 카드를 씁니다. 릴리스를 고르고(받아 둔 RBQ-<버전>.zip 이면 Install a file…) Update 를 누른 뒤, 설치됐다고 나오면 Reboot now 를 누릅니다. 릴리스는 브라우저가 직접 받으므로, PC 가 로봇 Wi-Fi 와 함께 인터넷에도 연결돼 있어야 합니다.

⚠

주의

재시작 전에 로봇을 앉은 자세로 두고, 재시작이 끝날 때까지 움직이지 마세요. 바이너리와 스크립트 버전이 맞지 않으면 예상치 못한 동작이 생길 수 있습니다.

scripts/deploy.bash는 로컬 개발용입니다. 방금 빌드한 바이너리를 실행한 PC의 ~/rbq_ws/로 복사합니다:

bash scripts/deploy.bash --local

인자	설명
--help	도움말 메시지를 출력하고 종료
--local	동일 PC의 ~/rbq_ws/에 배포
--rbh	휴머노이드: ~/rbq_ws/ 대신 ~/rbh_ws/ 로 배포 (--local 과 함께도). 로봇의 런처 ~/RBH.bash 는 없을 때만 설치하고 덮어쓰지 않는다
--pro [FILES...]	지정한 바이너리만 배포