스파이더봇 MJLab 학습과 육각 보행 로봇 실물 배포 안내

자료와 버전

인도 BITS Goa 전자·로봇 동아리 ERC-BPGC의 Spiderbot 육각 보행 로봇 학습·배포 저장소 안내입니다. Ritwik Sharma, Vimarsh Shah, Saransh Agrawal의 연구 프로젝트로, MJLab을 기반으로 닫힌 링크 구조의 로봇 모델과 속도 추종 과제를 추가했습니다. 이 글은 2026년 9월 24일 공개된 고정 커밋의 README 주요 사용 절을 한국어로 번역·설명한 자료입니다. 8쪽 연구 논문의 전문 번역이 아니며 논문·웹사이트 사진은 첨부하지 않았습니다.

포함 자료와 기구 설계

Spiderbot 모델에는 등식 제약과 텐던 스프링 요소가 포함됩니다. 비교·개발용 Spider3d 모델은 다리당 3자유도를 갖습니다. 두 모델에는 평지·험지 속도 추종 과제가 있고, Spiderbot에 맞춘 지형·행동·접촉·제약 설정이 제공됩니다. sim2real 폴더에는 하드웨어 배포 스크립트, ONNX 정책, 서보 SDK, 독립 시뮬레이션 자산이 있습니다. sim2real/cpg는 tripod·ripple·wave 보행 시험용입니다. Mechanical Design/Hexapod Assembly에는 SolidWorks 조립품·부품과 STEP 내보내기 파일이 있으며 Assem1.SLDASM을 열 때 참조 부품을 찾도록 원래 폴더 구조를 유지해야 합니다. 원래 MJLab 안내는 README_mjlab.md, 이전 동아리 코드·기록은 V1 브랜치에 보존돼 있습니다.

설치와 빠른 시뮬레이션 확인

학습에는 NVIDIA GPU가 필요하며 원문은 uv 사용을 권장합니다. 공식 저장소를 git clone한 뒤 SpiderBot 폴더에서 uv sync --extra cu128 --group dev를 실행합니다. 과제 ID는 Mjlab-Velocity-Flat-Spiderbot, Mjlab-Velocity-Rough-Spiderbot, Mjlab-Velocity-Flat-Spider3d, Mjlab-Velocity-Rough-Spider3d입니다. uv run play Mjlab-Velocity-Flat-Spiderbot --agent zero는 행동을 0으로 둔 시험이며 --agent random으로 바꾸면 임의 행동을 시험합니다. 험지는 과제 이름의 Flat을 Rough로 바꿉니다. 이는 시뮬레이션 확인 절이며 실물 로봇을 안전하게 운용했음을 보증하는 절차가 아닙니다.

강화학습 실행

험지 학습 예시는 uv run train Mjlab-Velocity-Rough-Spiderbot --env.scene.num-envs 4096입니다. 첫 실행 규모를 줄이려면 환경 수를 1024로 바꿉니다. 평지는 Mjlab-Velocity-Flat-Spiderbot 과제를 사용합니다. 4096과 1024는 원문 명령의 환경 수 예시이며 사용자 GPU에서의 처리 속도나 메모리 적합성을 보장하는 수치가 아닙니다.

독립 MuJoCo 정책 검증

sim2sim은 MJLab 과제 스택 밖에서 내보낸 정책을 검증하는 독립 MuJoCo 환경입니다. 기본 XML은 sim2sim/xmls/Hexapod_test.xml입니다. SPIDERBOT_POLICY_PATH에 실제 ONNX 경로를 지정해 uv run python sim2sim/test.py를 실행합니다. 예시 경로 /path/to/exported/policy.onnx는 실제 파일로 교체해야 합니다. XML 기본 경로는 스크립트 위치 기준으로 찾고 SPIDERBOT_XML_PATH로 다른 장면을 선택할 수 있습니다. 기본 정책 경로 sim2sim/policies/spiderbot.onnx는 자리표시자이며 프로젝트 웹사이트에는 바로 실행할 수 있는 브라우저 시연이 있습니다. 이 버전 스크립트는 40Hz 제어, 행동 배율 0.25와 관측 이력을 사용합니다. 정책·관측 배열·XML·행동 설정을 일치시켜야 하며 SPIDERBOT_OUTPUT_DIR로 데이터 저장 경로를 지정합니다. 기본값은 logs/locomotion_data입니다.

실물 배포 준비와 제어

sim2real/hardware_deploy.py는 키보드 제어, hardware_deploy_fc.py는 고정 속도 명령을 받습니다. 폴더의 rough.onnx, rough_noimu.onnx, track_good_20.onnx 중 호환 정책을 SPIDERBOT_POLICY_PATH로 명시하고 입력 배열과 보정을 먼저 확인해야 합니다. 독립 제어기는 NumPy·ONNX Runtime·pyserial을 사용합니다. sim2real/scservo_sdk의 SDK는 실행 위치와 무관하게 찾도록 구성돼 있으며 다른 복사본은 그 상위 폴더를 SPIDERBOT_SERVO_SDK_PATH로 지정합니다. 원문 예제는 SC 포트 /dev/ttyACM0과 ST 포트 /dev/ttyACM1을 사용하지만 실제 연결에 맞춰 SPIDERBOT_SC_PORT와 SPIDERBOT_ST_PORT를 설정해야 합니다. uv run --no-project --with numpy --with onnxruntime --with pyserial python sim2real/hardware_deploy.py로 실행하는 형식입니다. 스크립트 상단 서보 ID·홈 위치·틱 변환·한계를 자기 조립품에 맞춰 점검하고 대화형 터미널에서 실행합니다. sim2real 시뮬레이션 스크립트도 XML·정책 환경변수를 지원하며 기본값은 해당 폴더의 장면과 rough.onnx입니다.

CPG 시험·테스트·출처

기본 CPG 시험은 ONNX 정책 없이 서보를 직접 구동합니다. 저장소 루트에서 uv run --no-project --with numpy --with pyserial python sim2real/cpg/CPG_tripod.py를 실행하는 형식이며 다른 패턴은 CPG_ripple.py 또는 CPG_wave.py를 선택합니다. 같은 SC·ST 포트와 선택적인 SDK 경로 환경변수를 사용하고 서보 ID·홈 위치·보행 매개변수를 확인해야 합니다. 속도 과제의 기본 동작 시험은 uv run pytest tests/test_velocity_task.py입니다. 프로젝트 이용 시 위 세 저자의 Spiderbot 논문(arXiv:2609.26989)을 인용하도록 안내합니다. 기반 프로젝트는 MJLab·MuJoCo·MuJoCo Warp이며 상위 프로젝트 이용 안내는 README_mjlab.md에 있습니다.

첨부와 이용 조건

공식 저장소의 Apache 2.0 LICENSE와 원본 README, 한국어 안내를 로컬 첨부합니다. LICENSE의 The mjlab Developers 저작권 고지를 보존합니다. 번역·설명 파일은 원문과 별도로 표시하며 원본 파일은 수정하지 않았습니다. 이 허가를 논문(CC BY-NC-SA 4.0)이나 외부 미디어의 이용 조건으로 확대하지 않습니다. CAD·체크포인트·서보 SDK 전체를 복제한 자료가 아니므로 필요한 원본은 출처 저장소의 해당 버전에서 확인해야 합니다.

목록보기