02-제스처 추적 튜토리얼

제스처 추적 — 사용 튜토리얼(PWM 서보 버전)

이 디렉터리는 제스처 추적을 제공합니다: 카메라가 당신의 손을 인식하고 로봇 손이 실시간으로 추종합니다(완전한 IK 링크).

링크: 카메라 → mediapipe 손 골격 → MuJoCo+IK → 8개 관절 각도 → ESP32 → PWM 서보

적용 대상: ESP32-S3 + 8채널 PWM 서보. 펌웨어 플래싱은 ..\03_firmware_docs를 참조하세요.

1. 사전 조건

1. 하드웨어: ESP32-S3 + 8채널 PWM 서보에 전원 공급, USB 연결 완료, 카메라 사용 가능.

2. 펌웨어: 플래싱 완료( ..\03_firmware_docs의 사용자 매뉴얼 참조).

3. 최초 배포(한 번만 필요, 아래 참조).

2. 최초 배포

2.1 환경 설치

Demo\Windows_Scripts_CN\로 이동하여(영문 시스템은 Windows_Deploy_Scripts\), 번호 순서대로 두 번 클릭합니다:

1-安装环境.bat   → 安装 Rust / uv / dora(几分钟)

설치가 끝나면 터미널을 닫고 다시 열어 주세요.

2.2 Demo 배포

3-部署代码.bat   → 创建 Python 环境 + 编译 AHControl + 安装依赖(几分钟)

3. 제스처 추적 실행(매번)

3.1 실행 스크립트 두 번 클릭

Demo\Windows_Scripts_CN\로 이동하여 4-运行代码.bat를 두 번 클릭합니다:

Select a run mode:
   1 - 模拟仿真（摄像头手势追踪）
   2 - 真实硬件（SCS0009 总线舵机）
   3 - PWM 舵机（ESP32 直驱）    ← 选 3

이어서 손 유형을 선택합니다:

PWM 舵机（ESP32 直驱）- 请选择灵巧手：
   1 - 右手          ← 选 1
   2 - 左手          ← 选 2

3.2 사용 시작

1. 스크립트가 자동으로 dora build + dora run을 실행합니다.

2. 카메라 창이 열리고 3D 시뮬레이션 손가락이 나타납니다.

3. 손을 화면 안에 넣고 손가락을 움직입니다 → 3D 시뮬레이션이 추종 → 로봇 손이 추종.

4. 정지: Ctrl+C(또는 창 닫기).

Linux 시스템: Demo\Linux_Scripts_CN\(중국어) 또는 Linux_Deploy_Scripts\(영문)를 사용하며, 스크립트 이름에 .sh가 붙고 bash 스크립트이름으로 실행하거나 실행 권한을 추가해야 합니다.

4. 정상 실행 확인 방법

실행 창에서 AHControl 노드가 다음을 출력합니다:

[ACK-STATS] sent N frames, ESP32 acked M frames

• M ≈ N(예: sent 300 frames, ESP32 acked 300 frames)→ 정상, 서보 링크 정상.

• M = 0 → ESP32가 데이터를 받지 못함, 시리얼/전원 확인(아래 참조).

이 줄이 증가하고 있다면 서보 링크가 정상이라는 뜻이며, 남은 것은 카메라가 따라가는지의 문제입니다.

5. 좌우손 전환

실행 메뉴에서 손 유형을 선택하면 됩니다. 전환 후 스크립트가 자동으로 다시 빌드되므로, 빌드가 완료될 때까지 기다린 후 조작하세요.

6. 자주 묻는 질문

증상	조치
서보가 전혀 움직이지 않음	전원(5V 3A), COM 포트, 배선 확인; 로그의 acked M frames가 0인지 확인
카메라 화면이 안 나옴	카메라 권한 허용(설정→개인 정보→카메라)
손이 따라오지 않음 / 둔함	조명을 충분히, 손 전체를 화면 안에, 천천히 크게 움직이기
손 모양이 반대 / 엄지 방향이 반대	메뉴에서 좌/우손을 올바르게 선택했는지 확인? 다른 쪽으로 시도
USB 포트를 바꾼 후 시리얼 포트를 못 찾음	2-配置串口.bat를 다시 실행하고 새 COM 포트를 한 번 선택

7. SCS0009 버스 서보 사용자

이 Demo는 공식 SCS0009 버스 서보도 함께 지원합니다. 메뉴에서 2 - 真实硬件(SCS0009 总线舵机)를 선택하고, 구성과 설명은 Demo\双版本舵机并存说明.md 및 공식 튜토리얼을 참조하세요.

디렉터리 설명

경로	내용
Demo\AHControl	Rust 서보 제어 프로그램(소스, 배포 시 자동 컴파일)
Demo\AHSimulation	MuJoCo 시뮬레이션 + IK 솔버
Demo\HandTracking	MediaPipe 손 추적
Demo\Windows_Scripts_CN / Windows_Deploy_Scripts	Windows 원클릭 스크립트(중국어/영문)
Demo\Linux_Scripts_CN / Linux_Deploy_Scripts	Linux 원클릭 스크립트(중국어/영문)
Demo\dataflow_*_pwm.yml	PWM 버전 데이터플로우(보드레이트 115200 내장)