🧪 새 튜토리얼이 계속 업데이트 중 — 로봇 팔부터 센서까지
본문으로 건너뛰기

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비트):
bash
py -3.12-64 -c "import sys; print('64bit' if sys.maxsize > 2**32 else '32bit')"
# 输出: 64bit

② 호스트 PC 의존성 설치 ​

프로젝트 루트 디렉터리(hand_gui.py가 있는 디렉터리):

bash
pip install -r requirements.txt     # 只需 pyserial

③ 추적 추가 의존성(경로 B용) ​

프로젝트 루트 디렉터리에서 실행:

bash
setup_tracking.bat

자동으로 다음을 수행합니다: 64비트 Python 검색 → tracking_env 가상환경 생성 → requirements-tracking.txt 설치 (mediapipe==0.10.14, numpy<2, scipy, opencv, Pillow, pyserial) → mediapipe 검증.

또는 수동 설치:

bash
D:\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손가락
PWM14검지 관절 1
PWM25검지 관절 2
PWM36중지 관절 1
PWM47중지 관절 2
PWM515약지 관절 1
PWM616약지 관절 2
PWM717엄지 관절 1
PWM818엄지 관절 2

좌우손은 동일한 GPIO를 공유합니다. 왼손/오른손은 소프트웨어로 전환하므로(제4장) 배선을 바꿀 필요가 없습니다.

2.3 전원 요구 사항 ​

  • 서보에는 독립 5V 전원(최소 3A)을 사용하고, USB 전원에만 의존하지 마세요.
  • 서보의 순간 전류 충격으로 ESP32가 리셋될 수 있습니다(증상: ESP32가 반복 재시작). 이때 ESP32의 전원을 끊었다가 다시 시작하세요.

2.4 배선 단계 ​

  1. 8채널 서보 → 어댑터 보드 PWM1-8
  2. 어댑터 보드 → ESP32-S3 해당 GPIO(위 표)
  3. ESP32-S3 Type-C → PC
  4. 카메라를 PC에 연결(추적용)

자세한 배선/회로도는 ESP32开发板电路图/ 디렉터리를 참조하세요.


제3장 사전 조건: 펌웨어 플래싱 ​

서보가 응답하려면 먼저 펌웨어를 플래싱해야 합니다. 펌웨어는 esp-idf\AmazingHand_Serial\에 있습니다.

3.1 ESP-IDF 버전 컴파일(권장) ​

Espressif IDE로 AmazingHand_Serial 프로젝트를 엽니다:

  1. 대상 칩 설정(최초):
    idf.py set-target esp32s3
  2. 컴파일:
    idf.py build
  3. 플래싱(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: 소스 코드에서 실행 ​

bash
# 项目根目录,先激活追踪环境(装了 mediapipe)或任意带 pyserial 的 Python
tracking_env\Scripts\python hand_gui.py

GUI 사용 단계 ​

  1. 시리얼 포트 선택: 상단 드롭다운에서 ESP32의 COM 포트를 선택.
  2. 「연결」 클릭: 상태등이 녹색으로 변하고 로그에 "연결됨"이 표시되며, 자동으로 NOP 링크 테스트를 전송.
  3. 제스처 명령: 「바위」「가위」「보」「엄지 척」「OK」「핀치」「가리키기」 등을 클릭하면 로봇 손이 실행.
  4. 좌우손: 「오른손」/「왼손」을 체크하여 엄지 미러 방향을 전환.
  5. 서보 직접 구동: 슬라이더 8개를 드래그하여 개별 서보 각도를 실시간 제어(0-180°).
  6. 손가락 차동 제어(권장): 손가락마다 두 개의 진행 막대——「굴곡◀▶신전」은 역방향 차동, 「오른쪽 스윙◀▶왼쪽 스윙」은 동일 방향 스윙. 두 자유도는 독립적이며 동기 구동.
  7. 반복/정지: 마지막 제스처 반복 / 즉시 중단.
  8. 통신 로그: 하단에 송수신 프레임과 응답을 실시간 표시.

4.2 명령줄 테스트(serial_test.py) ​

프로젝트 루트 디렉터리:

bash
# 链路测试(先确认能通)
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절).
  • 카메라 사용 가능.

실행 ​

bash
# 项目根目录,用追踪环境启动 GUI
tracking_env\Scripts\python hand_gui.py
  1. 시리얼 포트 선택 → 「연결」.
  2. 「제스처 추적 (MediaPipe 카메라)」 패널까지 스크롤.
  3. 카메라 번호 선택(기본 0) → 「추적 시작」 클릭.
  4. 손을 화면 안에 넣으면 로봇 손이 손의 굴곡/신전을 추종.

원리 ​

  • 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 frames
  • M ≈ N(예: sent 300 frames, ESP32 acked 300 frames) → 정상, ESP32가 모든 프레임을 수신.
  • M = 0 → ESP32가 데이터를 받지 못함. 시리얼/전원 확인(제6장 참조).

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


제6장 자주 묻는 질문(실행 중) ​

이 절에서는 사용 중 가장 자주 발생하고 스스로 해결할 수 있는 문제만 다룹니다. 증상별로 빠르게 원인을 찾으세요.

6.1 서보가 전혀 움직이지 않음 ​

순서대로 점검:

  1. 전원: 서보에 독립 전원(5V 3A 이상)이 연결되어 있나요? USB 전원만 사용하면 서보가 움직이지 않거나 ESP32가 반복 재시작할 수 있습니다. → ESP32 전원을 끊었다가 다시 시작.
  2. 시리얼: COM 포트를 올바르게 선택했나요? 장치 관리자 → 포트(COM 및 LPT)에서 ESP32에 해당하는 포트 확인. 다른 프로그램(시리얼 터미널 등)이 점유하고 있지 않나요? → 점유 중인 프로그램 종료.
  3. 배선: 어댑터 보드 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 제스처 명령 ​

제스처HEXACKDONE
NOPAA 00 00 00BB 00 00 00—
바위AA 01 00 01BB 01 00 01BB 01 10 11
가위AA 02 00 02BB 02 00 02BB 02 10 12
보AA 03 00 03BB 03 00 03BB 03 10 13
엄지 척AA 04 00 04BB 04 00 04BB 04 10 14
도발1(검지 흔들기)AA 05 00 05BB 05 00 05BB 05 10 15
도발2(약지)AA 06 00 06BB 06 00 06BB 06 10 16
펼치기AA 07 00 07BB 07 00 07BB 07 10 17
주먹AA 08 00 08BB 08 00 08BB 08 10 18
OKAA 09 00 09BB 09 00 09BB 09 10 19
핀치AA 0A 00 0ABB 0A 00 0ABB 0A 10 1A
가리키기AA 0C 00 0CBB 0C 00 0CBB 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×角度] CKSUM8바이트 각도

7.3 프레임 형식 ​

帧头(0xAA) + 命令(CMD) + 长度(LEN) + 数据(DATA) + 校验和(CKSUM)
CKSUM = CMD ^ LEN ^ DATA[0] ^ ... ^ DATA[N-1]
响应: 帧头(0xBB) + CMD + STATUS + (CMD^STATUS)

7.4 호스트 PC 도구 ​

도구명령용도
GUItracking_env\Scripts\python hand_gui.py제스처 시각화 + 직접 구동 + 차동 + 추적
패키지 exedist/AmazingHand控制台.exePython 설치 불필요 시각화(추적 없음)
명령줄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