SCS0009 손 추적(공식 dora Demo)

이 페이지는 SCS0009 버스 서보 버전의 공식 손 추적 체인을 소개합니다: 카메라 → MediaPipe → MuJoCo IK → AHControl(Rust) → SCS0009. PWM 버전 추적은 PWM 손 추적을 참고하세요.

아래 스크립트 1 → 4는 Windows 원클릭 스크립트를 예로 들며, 스크립트는 AmazingHand-main/Demo/Windows_Deploy_Scripts/에 있습니다; Linux와 macOS의 스크립트 위치와 차이는 문서 끝을 참고하세요. 번호 순서대로 실행하면 됩니다.

---

하드웨어 준비

하드웨어	요구 사항
로봇 손 본체	오른손 / 왼손 / 양손
서보 드라이버 보드	외장, USB로 PC 연결
전원	외장 전원, 최소 5V 4A(또는 드라이버 보드 요구에 따라 7–12V 입력); USB 전원은 부족
카메라	PC 내장 또는 USB 카메라

모델 파일은 Onshape에서 보거나 직접 다운로드할 수 있습니다(URDF 포함).

로봇 손의 MuJoCo 모델

---

환경 설치(스크립트 1)

1-Install_Env.bat을 더블 클릭하면 자동으로 완료합니다:

1. MSVC 빌드 도구 확인(cl.exe) — Rust 컴파일 필수. 없으면 설치를 안내합니다 Visual Studio 2022 Build Tools, "C++를 사용한 데스크톱 개발" 체크, 설치 후 터미널 다시 열기.

2. Rust 설치(rustup + stable-msvc 툴체인)

3. cargo Tsinghua 미러 소스 설정(C:\Users\<사용자 이름>\.cargo\config.toml), crate 다운로드 가속

4. uv 설치(Python 패키지 관리자)

5. dora-cli 0.5.0 설치(cargo install, 첫 컴파일 약 10~20분, 기다리세요)

6. dora-rs pip 패키지 설치(선택, 가상 환경에 설치됨)

중요: 스크립트 종료 후 터미널을 닫았다가 다시 열어 환경 변수를 적용하세요. 설치 과정은 네트워크가 느리면 오래 걸릴 수 있으니 중간에 닫지 마세요.

환경 설치 대안(스크립트를 사용할 수 없을 때)

• Rust: https://www.rust-lang.org/tools/install

  • Windows는 rustup-init.exe 사용, 기본 MSVC 툴체인 선택

  • 환경 변수: %USERPROFILE%\.cargo\bin을 PATH에 추가

• uv: PowerShell에서 irm https://astral.sh/uv/install.ps1 | iex 실행.

  • 환경 변수: %USERPROFILE%\.local\bin을 PATH에 추가

• dora-cli: cargo install dora-cli --version 0.5.0

cargo Tsinghua 미러 설정(~/.cargo/config.toml)

[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

[registries.tuna]
index = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

[http]
check-revoke = false

sparse 희소 인덱스를 사용하세요(위와 같이). git 저장소 미러를 사용하지 마세요 — git 방식은 첫 회에 약 1GB 인덱스를 받아 Updating 'tuna' index에서 멈추기 쉽습니다.

---

배선 방식

• 서보 드라이버 보드 USB를 PC에 연결, 외부 전원(최소 5V 4A, 또는 드라이버 보드 요구에 따라 7–12V)

• PC에서 포트 번호 확인: 장치 관리자 → 포트(COM 및 LPT), 예: COM11

---

시리얼 포트 설정(스크립트 2)

2-Setup_Serial.bat 더블 클릭(실제 로직은 2-Setup_Serial.ps1):

1. "서보 드라이버 보드를 PC에 연결하세요" → Enter로 감지 시작

2. 감지된 COM 포트 목록 자동 표시(장치 이름 포함)

3. 포트가 하나면 Enter로 확인, 여러 개면 번호 입력

4. dataflow yml 3개의 --serialport와 AHControl\src\main.rs의 기본 포트에 자동 기록

5. 원본 파일은 자동으로 .bak으로 백업

USB를 다시 꽂으면 포트 번호가 바뀔 수 있으므로 이 스크립트를 다시 실행해야 합니다.

---

코드 배포(스크립트 3)

3-Deploy_Demo.bat 더블 클릭 시 자동 완료:

1. dora 데몬 시작(dora up)

2. Python 3.12 가상 환경 생성(uv venv --python 3.12)

3. 가상 환경 활성화

4. AHControl Rust 노드 컴파일(cargo build --release, 첫 회 약 10분)

5. AHSimulation, HandTracking 의존성 동기화(uv sync)

6. mediapipe==0.10.14 강제 설치

배포는 한 번만 실행하면 됩니다. 이후 다시 실행하면 가상 환경 재생성 여부를 묻습니다.

---

코드 실행(스크립트 4)

4-Run_Demo.bat 더블 클릭 시 대화형 메뉴가 나타납니다:

============================================
   请选择运行模式：
============================================
    1 - 模拟仿真（摄像头手势追踪）
    2 - 真实硬件
    q - 退出
============================================
  请输入序号 [1/2/q]:

• 1 선택: 시뮬레이션 환경, 카메라 제스처가 시뮬레이션 손 두 개를 구동

• 2 선택: 하위 메뉴로 들어가 오른손 / 왼손 / 양손 선택

============================================
   真实硬件 - 请选择灵巧手：
============================================
    1 - 右手
    2 - 左手
    3 - 左右双手
    b - 返回上级菜单
============================================

선택 후 자동으로 dora build + dora run을 실행합니다. 카메라 창이 뜨면 카메라를 향해 제스처를 취하고 로봇 손이 실시간으로 따라갑니다. Ctrl+C로 중지하며, 데이터 스트림 종료 후 Enter를 누르면 메인 메뉴로 돌아가 다른 모드를 선택하거나 q로 종료할 수 있습니다.

처음 실행하면 Windows가 카메라 권한을 차단할 수 있으니 "허용"을 클릭하세요.

---

프로젝트 정리(스크립트 0)

0-Cleanup_Project.bat 더블 클릭, Y를 입력해 확인하면 자동 정리:

1. dora 데몬 중지

2. 가상 환경 3개 삭제(.venv)

3. Rust 빌드 산출물 삭제(AmazingHand-main/Demo/target)

4. pycache, .bak 백업, 로그, AmazingHand-main/Demo/out(dora 로그 디렉터리) 삭제

5. 기본 포트 복원(--serialport /dev/ttyACM0), 이 컴퓨터의 시리얼 포트 잔여물 제거

정리 후 AmazingHand-main 폴더 전체를 다른 사람에게 복사해 줄 수 있으며 잔여물이 없습니다. 새 컴퓨터에서는 1 → 2 → 3 → 4 순서로 실행하면 됩니다.

---

Linux와 macOS 차이

원클릭 스크립트는 Linux와 macOS 버전도 제공하며, 디렉터리는 각각 AmazingHand-main/Demo/Linux_Deploy_Scripts/와 AmazingHand-main/Demo/Mac_Deploy_Scripts/입니다. 1–4단계 흐름은 Windows와 같으며, 아래에는 시스템 차이만 정리합니다.

스크립트 실행 권한(Linux / macOS)

Windows 또는 압축 파일에서 복사하면 스크립트의 +x 실행 비트가 사라지므로, 처음 실행 전에:

cd "AmazingHand-main/Demo/Linux_Deploy_Scripts"   # macOS는 Mac_Deploy_Scripts로 변경
chmod +x *.sh

이후 ./스크립트이름으로 실행하세요; bash 스크립트이름을 사용하면 스크립트 내 대화형 프롬프트를 건너뜁니다.

Linux(Ubuntu)

• 시리얼 권한: sudo usermod -aG dialout $USER, 로그아웃 후 다시 로그인; 임시로 sudo chmod 666 /dev/ttyACM* 사용 가능.
• 장치 이름: /dev/ttyUSB*(CH340 / CP2102) 또는 /dev/ttyACM*(온보드 USB 시리얼).
• 카메라: 설정 → 개인정보 → 카메라, 앱 접근 허용; 다른 프로그램이 카메라를 점유하지 않는지 확인.
• 가상 머신: 먼저 USB 카메라를 가상 머신에 연결; OpenCV가 can't open camera by index 또는 select() timeout을 보고하면 가상 머신 설정에서 USB 컨트롤러 2.0 / 3.1을 전환하고 재시작; 필요하면 sudo usermod -aG video $USER.
• 중국어 경로: 프로젝트 경로는 가능한 한 영문을 사용해 MuJoCo / MediaPipe 모델 로딩 실패를 피하세요.

macOS

• 시리얼: /dev/cu.*를 사용하고 /dev/tty.*는 사용하지 마세요; ls /dev/cu.*로 장치 이름 확인.
• 시리얼 권한: sudo chmod 666 /dev/cu.usbmodem*, 또는 "시스템 설정 → 개인정보 보호 및 보안 → 입력 모니터링"에서 터미널 허용.
• 카메라: 첫 실행 시 터미널의 카메라 접근 허용; "시스템 설정 → 개인정보 보호 및 보안 → 카메라"에서도 변경 가능.
• Apple Silicon: 첫 cargo build에서 dora 의존성 컴파일이 느린 것은 정상; "개발자를 확인할 수 없음"이 뜨면 "개인정보 보호 및 보안"에서 "그래도 열기" 클릭.

수동 설치(원클릭 스크립트 미사용)

스크립트를 사용할 수 없으면 공식 Demo 방식으로 수동 배포할 수 있습니다:

1. 코드 받기: 저장소를 클론하거나 AmazingHand.zip을 다운로드해 AmazingHand-main/Demo/로 이동.

   

2. 환경 설치: Rust(rustup), uv, dora-cli; PowerShell/Bash를 다시 열어 PATH 적용. 설치 세부 사항은 위 환경 설치(스크립트 1) 참고.

3. 환경 생성 및 의존성 설치:

   uv venv --python 3.12
   # Windows: .venv\Scripts\activate
   # Linux/macOS: source .venv/bin/activate
   
   cd AHControl
   cargo build --release
   cd ..
   cd AHSimulation
   uv sync
   cd ..
   cd HandTracking
   uv sync
   cd ..

   

4. 시리얼 포트 설정: dataflow_tracking_real_right.yml / _left.yml / _2hands.yml의 --serialport를 실제 COM 포트 또는 /dev/ttyUSB0, /dev/cu.usbserial-*로 수정.

   

   

5. 빌드 및 실행:

   # 시뮬레이션
   dora build dataflow_tracking_simu.yml --uv
   dora run dataflow_tracking_simu.yml --uv
   
   # 실제 하드웨어(오른손; 왼손/양손은 파일명 교체)
   dora build dataflow_tracking_real_right.yml --uv
   dora run dataflow_tracking_real_right.yml --uv
   
   # 간단한 각도 예시
   dora build dataflow_angle_simu.yml --uv
   dora run dataflow_angle_simu.yml --uv

   

   

6. 자주 묻는 질문: mediapipe는 0.10.14(Python 3.12) 필요; dora 버전 비호환 시 pyproject.toml/로그에 맞춰 정렬; OpenCV 누락 시 opencv-contrib-python 설치; 카메라 권한, 가상 머신 USB 패스스루, 중국어 경로 모두 모델 로딩에 영향을 줍니다. 구체적 문제 해결은 자주 묻는 질문과 주의 사항 참고.

더 자세한 공식 Demo 설명은 AmazingHand-main/Demo/README.md 참고; 각 시스템의 원클릭 배포 절차는 이 페이지에 통합되었습니다.

코드 구조 설명

Demo 디렉터리

AmazingHand-main/Demo/
├── AHControl/                Rust 노드: 시리얼로 서보 제어, config/ 아래에 서보 ID와 오프셋
├── AHSimulation/             Python 노드: MuJoCo 시뮬레이션과 역운동학
├── HandTracking/             Python 노드: MediaPipe 손 랜드마크 인식
├── dataflow_*.yml            dora 데이터플로 오케스트레이션
├── Windows_Deploy_Scripts/   Windows 원클릭 배포 스크립트
├── Linux_Deploy_Scripts/     Linux 원클릭 배포 스크립트
├── Mac_Deploy_Scripts/       macOS 원클릭 배포 스크립트
└── docs/                     공식 다국어 배포 튜토리얼

각 dataflow 대응 관계

데이터플로 파일	용도
dataflow_tracking_simu.yml	카메라 제스처 추적, MuJoCo 시뮬레이션 손만 구동
dataflow_tracking_real_right.yml	카메라 제스처 추적, 실제 오른손 구동
dataflow_tracking_real_left.yml	카메라 제스처 추적, 실제 왼손 구동
dataflow_tracking_real_2hands.yml	카메라 제스처 추적, 왼손/오른손 동시 구동
dataflow_angle_simu.yml	관절 각도를 직접 주어 시뮬레이션과 역운동학 검증

데이터플로 원리

카메라 → HandTracking(MediaPipe 제스처 인식)
              ↓ 손 랜드마크 좌표
         AHSimulation(MuJoCo 시뮬레이션 + 역운동학)
              ↓ 관절 목표 각도
         AHControl(시리얼 → 서보 드라이버 보드 → 로봇 손)

포트 설정 위치

• 세 dataflow_tracking_real_*.yml의 args: 줄: --serialport COMxx

• AHControl\src\main.rs의 default_value = "COMxx"(시리얼 파라미터 기본값)

• AHControl\config\*.toml: 서보 모델, ID, 오프셋(보통 수정 불필요)

---

자주 묻는 질문과 주의 사항

1. cargo가 Updating 'tuna' index에서 멈춤

• 원인: 미러 설정이 git 저장소 방식(.../git/crates.io-index.git)이라 첫 회에 1GB+ 인덱스를 다운로드

• 해결: C:\Users\<사용자 이름>\.cargo\config.toml을 sparse 희소 인덱스로 변경(위 "cargo Tsinghua 미러 설정" 참고), 또는 1-Install_Env.bat 재실행

2. mediapipe solutions 하위 모듈 누락 / 설치 손상

uv pip uninstall mediapipe

uv pip install mediapipe==0.10.14

• 반드시 가상 환경이 활성화된 상태에서 실행(Demo 디렉터리)

• 3-Deploy_Demo.bat이 이미 이 단계를 자동으로 처리

3. dora 버전 비호환(message v0.8.0 vs v0.7.0)

• 증상: version mismatch: message format v0.8.0 is not compatible with expected message format v0.7.0

• 원인: dora-cli 버전과 dora-node-api 불일치. 반드시 0.5.0으로 통일

  • 확인: dora --version이 dora-cli 0.5.0, dora-message: 0.8.0을 출력해야 함

  • 수정: cargo install dora-cli --version 0.5.0 --force

  • PATH에 여러 dora가 있으면(예: C:\Users\<사용자 이름>\.dora\bin의 구버전) .cargo\bin이 앞에 오도록 하거나 구버전 삭제

  

  

4. MuJoCo / mediapipe 모델 로딩 실패(중국어 경로)

• 증상: ParseXML: Error opening file '...\scene.xml' 또는 Can't find file: ....tflite

• 원인: MuJoCo 3.x / mediapipe의 C++ 로더가 Windows에서 중국어가 포함된 절대 경로를 열지 못함(예: D:\中文目录...)

• 이 프로젝트에는 수정 사항이 내장되어 있음:

  • AHSimulation\AHSimulation\mj_mink_*.py 모델 로딩 전 작업 디렉터리 전환

  • HandTracking\mediapipe_patch.py 8.3 짧은 경로 + 상대 경로로 우회

• 이 수정 코드를 삭제하지 마세요

5. 카메라 권한

• 첫 실행 팝업에서 "허용" 선택

• 설정 → 개인정보 → 카메라 → 데스크톱 앱 접근 허용

  

  

  

6. 포트 번호가 매번 바뀜

• USB를 다시 꽂으면 COM 번호가 바뀔 수 있으니 2-Setup_Serial.bat 재실행

7. OpenCV 누락

python -m pip install opencv-contrib-python numpy mediapipe -i https://mirrors.aliyun.com/pypi/simple/

(HandTracking 디렉터리에서 가상 환경 활성화 후 실행)

---

관련 페이지

• SCS0009 빠른 시작
• SCS0009 웹 제어
• SCS0009 서보 디버깅과 캘리브레이션
• PWM 손 추적