AmazingHand PWM 로봇 손 — 전체 워크플로 튜토리얼
함께 제공되는 배포 패키지: delivery_package.zip
호스트 PC 제스처 명령부터 제스처 추적까지, 한 번에 따라 하는 사용 튜토리얼. 적용 하드웨어: ESP32-S3 + 8채널 PWM 서보(차동 구동).
버전: 2026-08-20 · 대응 펌웨어: ESP-IDF 컴포넌트화 버전(
AmazingHand_Serial)
제0장 튜토리얼 안내
본 튜토리얼은 순서대로 구성되어 있습니다. 먼저 어떤 경로로 진행할지 확인한 후 해당 장으로 이동하세요.
| 경로 | 용도 | 사전 요구 사항 | 장 |
|---|---|---|---|
| A. 호스트 PC 제스처 명령 | 버튼 클릭/명령 입력으로 로봇 손이 제스처 수행(바위/가위/보/엄지 척…) | Python + 펌웨어 플래싱 | 제1-4장 |
| B. GUI 내장 제스처 추적 | 카메라가 손 동작을 따라가고 로봇 손이 실시간 재현(간이 버전, IK 없음) | A + 64비트 Python + mediapipe | 제1-4장 + 5.1 |
| C. dora 공식 IK 추적 | 공식 전체 링크: 카메라→IK→8관절 각도→서보(완전판) | A + Rust + uv + dora | 제1-4장 + 5.2 |
권장 경로:
- 처음 사용하는 경우 → A를 선택하세요. 먼저 펌웨어와 배선에 문제가 없는지 확인하세요.
- 카메라 추종을 빠르게 확인하고 싶다면 → B(가볍고 몇 분이면 설치 완료).
- 정식이며 완전한 추적을 원한다면 → C(공식 링크, 정밀도 최고).
세 경로는 하드웨어를 공유하며, 추가로 Rust/uv/dora를 설치해야 하는 것은 경로 C뿐입니다.
제1장 환경 준비
순서대로 설치하세요. 경로 A/B는 1.1절만 필요하며, 경로 C는 1.2절도 필요합니다.
1.1 호스트 PC 환경(경로 A/B 필수)
① 64비트 Python 3.12
반드시 64비트여야 합니다. mediapipe 0.10.14는 64비트 Windows wheel만 제공하며 32비트에는 설치할 수 없습니다. 이는 GUI를 두 번 클릭해도 바로 종료되는 흔한 원인이기도 합니다.
D:\Python312-64bit에 설치하는 것을 권장합니다(본 PC에 이미 해당 경로가 있음).- 설치 시 Add to PATH를 체크하세요.
- 확인(64비트):
py -3.12-64 -c "import sys; print('64bit' if sys.maxsize > 2**32 else '32bit')"
# 输出: 64bit② 호스트 PC 의존성 설치
프로젝트 루트 디렉터리(hand_gui.py가 있는 디렉터리):
pip install -r requirements.txt # 只需 pyserial③ 추적 추가 의존성(경로 B용)
프로젝트 루트 디렉터리에서 실행:
setup_tracking.bat자동으로 다음을 수행합니다: 64비트 Python 검색 → tracking_env 가상환경 생성 → requirements-tracking.txt 설치 (mediapipe==0.10.14, numpy<2, scipy, opencv, Pillow, pyserial) → mediapipe 검증.
또는 수동 설치:
bashD:\Python312-64bit\python.exe -m pip install -r requirements-tracking.txt
1.2 dora 공식 IK 환경(경로 C 필수)
고객 설치: ..\02_hand_tracking\Demo\Windows_Scripts_CN\1-安装环境.bat(영문판은 ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\1-Install_Env.bat)를 두 번 클릭하면 모든 의존성이 자동 설치됩니다: Rust 툴체인, uv(Python 패키지 관리), dora-cli.
설치 후 터미널을 닫았다가 다시 열어 PATH가 적용되도록 하세요. 세부 의존성(버전, 수동 설치 방법)은 유지보수 문서를 참조하시면 되며, 고객이 처리할 필요는 없습니다.
제2장 하드웨어 배선
2.1 하드웨어 목록
| 하드웨어 | 설명 |
|---|---|
| ESP32-S3 개발 보드 | YX-ESP32-S3 또는 동급 |
| 8채널 PWM 서보 | 아날로그 서보, 차동 구동 |
| 서보 어댑터 보드 | 서보 → 8채널 PWM 출력 |
| 독립 5V 전원 | 최소 5V 3A, 서보 순간 전류가 큼 |
| USB 데이터 케이블 | ESP32-S3 Type-C → PC |
| 카메라 | 내장 또는 USB 카메라(추적용) |
2.2 GPIO 매핑
어댑터 보드 PWM1-8 → ESP32-S3 GPIO:
| 어댑터 보드 | GPIO | 손가락 |
|---|---|---|
| PWM1 | 4 | 검지 관절 1 |
| PWM2 | 5 | 검지 관절 2 |
| PWM3 | 6 | 중지 관절 1 |
| PWM4 | 7 | 중지 관절 2 |
| PWM5 | 15 | 약지 관절 1 |
| PWM6 | 16 | 약지 관절 2 |
| PWM7 | 17 | 엄지 관절 1 |
| PWM8 | 18 | 엄지 관절 2 |
좌우손은 동일한 GPIO를 공유합니다. 왼손/오른손은 소프트웨어로 전환하므로(제4장) 배선을 바꿀 필요가 없습니다.
2.3 전원 요구 사항
- 서보에는 독립 5V 전원(최소 3A)을 사용하고, USB 전원에만 의존하지 마세요.
- 서보의 순간 전류 충격으로 ESP32가 리셋될 수 있습니다(증상: ESP32가 반복 재시작). 이때 ESP32의 전원을 끊었다가 다시 시작하세요.
2.4 배선 단계
- 8채널 서보 → 어댑터 보드 PWM1-8
- 어댑터 보드 → ESP32-S3 해당 GPIO(위 표)
- ESP32-S3 Type-C → PC
- 카메라를 PC에 연결(추적용)
자세한 배선/회로도는
ESP32开发板电路图/디렉터리를 참조하세요.
제3장 사전 조건: 펌웨어 플래싱
서보가 응답하려면 먼저 펌웨어를 플래싱해야 합니다. 펌웨어는
esp-idf\AmazingHand_Serial\에 있습니다.
3.1 ESP-IDF 버전 컴파일(권장)
Espressif IDE로 AmazingHand_Serial 프로젝트를 엽니다:
- 대상 칩 설정(최초):
idf.py set-target esp32s3 - 컴파일:
idf.py build - 플래싱(Windows는 COM 포트 사용, 예: COM3):
idf.py -p COM3 flash
3.2 플래싱 후 확인
시리얼 모니터(보드레이트 115200):
idf.py -p COM3 monitor다음과 같은 부팅 로그가 표시되어야 합니다:
AmazingHand Serial Control Ready (ESP-IDF)
Protocol: 115200-8N1 [0xAA CMD LEN DATA CKSUM]시리얼 보드레이트는 펌웨어/스크립트에서 통일 설정되어 있으므로(115200) 고객이 수동으로 설정할 필요가 없습니다.
참고: 일반적으로 장비 납품 시 펌웨어가 이미 플래싱되어 있으며, 이 단계는 새 펌웨어/재플래싱 시에만 수행합니다.
제4장 초기 실행: 호스트 PC 제스처 명령
사전 조건: 펌웨어 플래싱 완료(제3장), ESP32 전원 공급 완료, 시리얼 케이블 연결 완료. 먼저 장치 관리자에서 COM 포트를 확인하세요.
4.1 GUI 시각화(권장)
방식 A: 패키지된 exe 실행
dist/AmazingHand控制台.exe를 두 번 클릭합니다(추적 미포함, 추적은 소스 코드 방식 필요).
방식 B: 소스 코드에서 실행
# 项目根目录,先激活追踪环境(装了 mediapipe)或任意带 pyserial 的 Python
tracking_env\Scripts\python hand_gui.pyGUI 사용 단계
- 시리얼 포트 선택: 상단 드롭다운에서 ESP32의 COM 포트를 선택.
- 「연결」 클릭: 상태등이 녹색으로 변하고 로그에 "연결됨"이 표시되며, 자동으로 NOP 링크 테스트를 전송.
- 제스처 명령: 「바위」「가위」「보」「엄지 척」「OK」「핀치」「가리키기」 등을 클릭하면 로봇 손이 실행.
- 좌우손: 「오른손」/「왼손」을 체크하여 엄지 미러 방향을 전환.
- 서보 직접 구동: 슬라이더 8개를 드래그하여 개별 서보 각도를 실시간 제어(0-180°).
- 손가락 차동 제어(권장): 손가락마다 두 개의 진행 막대——「굴곡◀▶신전」은 역방향 차동, 「오른쪽 스윙◀▶왼쪽 스윙」은 동일 방향 스윙. 두 자유도는 독립적이며 동기 구동.
- 반복/정지: 마지막 제스처 반복 / 즉시 중단.
- 통신 로그: 하단에 송수신 프레임과 응답을 실시간 표시.
4.2 명령줄 테스트(serial_test.py)
프로젝트 루트 디렉터리:
# 链路测试(先确认能通)
python serial_test.py COM3 nop
# 手势
python serial_test.py COM3 rock # 石头
python serial_test.py COM3 thumbs_up # 真棒
python serial_test.py COM3 index # 指向
python serial_test.py COM3 open # 张开
python serial_test.py COM3 close # 握拳
# 单舵机直驱
python serial_test.py COM3 servo 1 90 # 舵机1 → 90°
# 全部归中
python serial_test.py COM3 mid
# 设左右手
python serial_test.py COM3 hand L
python serial_test.py COM3 hand R
# 扫频/自检
python serial_test.py COM3 sweep 1 # 舵机1 扫频
python serial_test.py COM3 test # 全部舵机逐个测试4.3 확인
- 제스처를 클릭하면 서보가 해당 동작을 수행해야 합니다. 시리얼 로그에
ACK와DONE이 반환됩니다. - 응답 코드:
0x00=OK,0x01=유효하지 않은 명령,0x02=파라미터 오류,0x03=바쁨,0x10=완료. - 서보가 전혀 움직이지 않으면: 제6장 자주 묻는 질문을 참조하세요(먼저 전원/시리얼 확인).
제스처 명령과 시리얼 프로토콜 전체 빠른 조회는 제7장을 참조하세요.
제5장 심화 튜토리얼: 제스처 추적
사전 조건: 제1-4장 완료(펌웨어 플래싱, 시리얼 제어 가능, 카메라 준비 완료). 이 장에는 두 가지 경로가 있으니 하나를 선택해 진행하세요.
5.1 GUI 내장 추적(경량 버전)
적합: 빠른 데모용, dora 설치 불필요. 카메라 → 차동 서보에 직접 매핑, IK 없음.
사전 조건
- 64비트 Python +
setup_tracking.bat(1.1절). - 카메라 사용 가능.
실행
# 项目根目录,用追踪环境启动 GUI
tracking_env\Scripts\python hand_gui.py- 시리얼 포트 선택 → 「연결」.
- 「제스처 추적 (MediaPipe 카메라)」 패널까지 스크롤.
- 카메라 번호 선택(기본 0) → 「추적 시작」 클릭.
- 손을 화면 안에 넣으면 로봇 손이 손의 굴곡/신전을 추종.
원리
- mediapipe 0.10.14가 4개 손가락 끝의 3D 벡터를 추출(손 좌표계).
hand_tracking.py의tips_to_angles()가 각 손가락을 차동 각도로 매핑:- flex(굴곡/신전): 세 손가락은 z 성분, 엄지는 y 성분 사용.
- base(좌우 스윙): 90 고정(좌우 스윙은 아직 미구현).
- GUI 내장 EMA 평활화(alpha=0.4) + 60ms 스로틀링으로 떨림 방지.
한계
- IK 없음: 손끝을 직접 각도로 매핑하므로 정밀도가 공식 링크보다 낮음.
- 좌우 스윙 보류: base는 90 고정, 좌우 스윙은 하지 않음.
- 데모/프로토타입용이며, 정식 사용에는 5.2를 권장.
5.2 dora 공식 IK 추적(완전판)
적합: 정식 사용. 공식 링크: 카메라 → mediapipe → MuJoCo+mink IK → 8관절 각도 → AHControl(Rust) → ESP32 → PWM 서보.
사전 조건
- 전체 환경(Rust + uv + dora, 1.2절).
- 펌웨어 플래싱(제3장).
- 데이터플로 yml에 PWM 보드레이트(115200)가 이미 작성되어 있어 수동으로 수정할 필요 없음.
1단계: 배포(원클릭 스크립트 권장)
..\02_hand_tracking\Demo\Windows_Scripts_CN\3-部署代码.bat(영문판은 ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\3-Deploy_Demo.bat)를 두 번 클릭하면 자동으로 완료됩니다: Python 환경 생성, AHControl(Rust) 컴파일, AHSimulation/HandTracking(mediapipe) 설치.
최초 배포에는 몇 분이 걸립니다. 스크립트에 환경 변수 처리가 내장되어 있어 수동으로 설정할 필요가 없습니다.
2단계: 실행
..\02_hand_tracking\Demo\Windows_Scripts_CN\4-运行代码.bat(영문판은 ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\4-Run_Demo.bat)를 두 번 클릭하고 메뉴에서 선택합니다:
1 - 模拟仿真(摄像头手势追踪)
2 - 真实硬件(SCS0009 总线舵机)
3 - PWM 舵机(ESP32 直驱) ← 选 3이어서 손 유형 선택: 1 右手 / 2 左手. 스크립트가 자동으로 dora build + dora run을 실행합니다.
- 카메라 창이 열리면 손을 화면 안에 넣기 → 3D 시뮬레이션 손가락이 추종 → 로봇 손이 추종.
- 정지: Ctrl+C(또는 창 닫기).
좌우손 전환
실행 메뉴에서 손 유형을 선택하면 됩니다(5.2절 2단계): 1 右手 또는 2 左手 선택.
전환 후 스크립트가 해당 데이터플로를 자동으로 다시 빌드합니다. 빌드가 완료된 후 카메라 앞에서 동작하면 됩니다.
실행 로그 보는 방법
실행 창에서 AHControl 노드가 지속적으로 로그를 출력합니다. 다음 줄을 중점적으로 보세요:
[ACK-STATS] sent N frames, ESP32 acked M framesM ≈ N(예:sent 300 frames, ESP32 acked 300 frames) → 정상, ESP32가 모든 프레임을 수신.M = 0→ ESP32가 데이터를 받지 못함. 시리얼/전원 확인(제6장 참조).
이 줄이 정상적으로 증가하고 있다면 서보 링크는 정상이며, 남은 것은 카메라가 따라갈 수 있는지의 문제입니다.
제6장 자주 묻는 질문(실행 중)
이 절에서는 사용 중 가장 자주 발생하고 스스로 해결할 수 있는 문제만 다룹니다. 증상별로 빠르게 원인을 찾으세요.
6.1 서보가 전혀 움직이지 않음
순서대로 점검:
- 전원: 서보에 독립 전원(5V 3A 이상)이 연결되어 있나요? USB 전원만 사용하면 서보가 움직이지 않거나 ESP32가 반복 재시작할 수 있습니다. → ESP32 전원을 끊었다가 다시 시작.
- 시리얼: COM 포트를 올바르게 선택했나요? 장치 관리자 → 포트(COM 및 LPT)에서 ESP32에 해당하는 포트 확인. 다른 프로그램(시리얼 터미널 등)이 점유하고 있지 않나요? → 점유 중인 프로그램 종료.
- 배선: 어댑터 보드 PWM1-8이 올바른 GPIO에 연결되어 있나요? 서보 신호선이 단단히 꽂혀 있나요?
6.2 카메라 화면이 나오지 않음
- Windows에서 처음 실행하면 카메라 권한 팝업이 표시됩니다 → 「허용」 클릭.
- 이전에 "아니요"를 선택했다면: 설정 → 개인 정보 및 보안 → 카메라 → 데스크톱 앱이 카메라에 액세스하도록 허용한 후 다시 실행하세요.
6.3 카메라 화면은 나오지만 손을 따라오지 않음 / 추종이 둔함
- 카메라가 손을 정면으로 향하고 있는지, 조명이 충분한지, 손이 화면 안에 전체가 보이는지 확인하세요.
- 천천히, 크게 움직이세요. 너무 빠르거나 동작이 너무 작으면 추적이 따라가지 못할 수 있습니다.
- 3D 시뮬레이션 창에서 손가락이 움직였나요?
- 움직임: 추적 링크는 정상이며, 문제는 서보/시리얼에 있으니 6.1을 참조.
- 움직이지 않음: 추적 노드가 손을 인식하지 못한 것이므로 자세/조명을 조정해 재시도.
6.4 손 유형이 반대 / 엄지 방향이 반대
- 왼손/오른손을 잘못 선택했나요? 실행 메뉴에서 해당 손 유형을 선택하세요.
- 호스트 PC GUI에서 「오른손」/「왼손」을 체크하여 전환.
6.5 좌우손 전환 후 적용되지 않음
- 손 유형을 전환하면
dora가 데이터플로를 다시 빌드해야 합니다. 실행 메뉴에서 손 유형을 선택하면 자동으로dora build가 실행되므로 완료될 때까지 기다리면 됩니다.
6.6 실행 중 화면 멈춤 / 로그 정지
- 카메라가 다른 앱(화상 회의, 다른 스크립트)에 점유되어 있을 수 있습니다. 종료 후 재시도하세요.
- 또는
Ctrl+C로 중지한 후 다시 실행하세요.
6.7 USB 포트를 바꿈 / PC 재시작 후 시리얼 포트를 찾을 수 없음
- COM 포트 번호가 바뀌었을 수 있습니다. 장치 관리자에서 새 COM 번호를 확인하고
2-配置串口.bat(또는2-Setup_Serial.bat)를 다시 실행하여 포트를 한 번 선택한 후 다시 실행하세요.
6.8 그래도 해결되지 않으면
- 실행 터미널의 로그 스크린샷을 유지보수 담당자에게 보내고, 어느 단계에서 어떤 작업을 했을 때 어떤 현상이 나타났는지 설명하세요.
- 핵심 로그: 시작 시의
[CONFIG]줄, 실행 중의[ACK-STATS]줄(ESP32 acked M frames의 M이 N에 가까운지 여부).
제7장 명령 빠른 조회(부록)
전체 프로토콜 설명은 같은 디렉터리의
用户手册.md를 참조하세요. 여기서는 빠른 조회표를 제공합니다.
7.1 제스처 명령
| 제스처 | HEX | ACK | DONE |
|---|---|---|---|
| NOP | AA 00 00 00 | BB 00 00 00 | — |
| 바위 | AA 01 00 01 | BB 01 00 01 | BB 01 10 11 |
| 가위 | AA 02 00 02 | BB 02 00 02 | BB 02 10 12 |
| 보 | AA 03 00 03 | BB 03 00 03 | BB 03 10 13 |
| 엄지 척 | AA 04 00 04 | BB 04 00 04 | BB 04 10 14 |
| 도발1(검지 흔들기) | AA 05 00 05 | BB 05 00 05 | BB 05 10 15 |
| 도발2(약지) | AA 06 00 06 | BB 06 00 06 | BB 06 10 16 |
| 펼치기 | AA 07 00 07 | BB 07 00 07 | BB 07 10 17 |
| 주먹 | AA 08 00 08 | BB 08 00 08 | BB 08 10 18 |
| OK | AA 09 00 09 | BB 09 00 09 | BB 09 10 19 |
| 핀치 | AA 0A 00 0A | BB 0A 00 0A | BB 0A 10 1A |
| 가리키기 | AA 0C 00 0C | BB 0C 00 0C | BB 0C 10 1C |
7.2 제어 명령
| 명령 | HEX | 설명 |
|---|---|---|
| 반복 | AA FE 00 FE | 마지막 제스처 반복 |
| 정지 | AA FF 00 FF | 즉시 중단 |
| 오른손 설정 | AA F1 01 01 F1 | — |
| 왼손 설정 | AA F1 01 02 F2 | — |
| 직접 구동 | AA F0 08 [8×角度] CKSUM | 8바이트 각도 |
7.3 프레임 형식
帧头(0xAA) + 命令(CMD) + 长度(LEN) + 数据(DATA) + 校验和(CKSUM)
CKSUM = CMD ^ LEN ^ DATA[0] ^ ... ^ DATA[N-1]
响应: 帧头(0xBB) + CMD + STATUS + (CMD^STATUS)7.4 호스트 PC 도구
| 도구 | 명령 | 용도 |
|---|---|---|
| GUI | tracking_env\Scripts\python hand_gui.py | 제스처 시각화 + 직접 구동 + 차동 + 추적 |
| 패키지 exe | dist/AmazingHand控制台.exe | Python 설치 불필요 시각화(추적 없음) |
| 명령줄 | python serial_test.py COMx <cmd> | 자동화 테스트 |
7.5 추적 데이터플로 파일(PWM 버전)
| 용도 | 파일 |
|---|---|
| 왼손 PWM 추적 | dataflow_tracking_real_left_pwm.yml |
| 오른손 PWM 추적 | dataflow_tracking_real_right_pwm.yml |
| 왼손 PWM 설정 | AHControl/config/l_hand_pwm.toml |
| 오른손 PWM 설정 | AHControl/config/r_hand_pwm.toml |

