Sungah/omx_box_act

OMX 상자 → 핑키 · ACT 실행 번들

ROBOTIS OMX 로봇팔로 상자를 집어 핑키(흰색 원형 로봇) 위에 올리는 작업을 학습한 ACT 모델과, 학원 PC에서 바로 실행하기 위한 스크립트를 한 폴더에 담았습니다.

들어 있는 모델

폴더	학습 데이터	입력 state	로봇 타입 (ROBOT_TYPE)
models/act_merged	Sungah/omx_box_merged	관절 6	omx_follower
models/act_merged_grip	Sungah/omx_box_merged_grip	관절 6 + 그리퍼 전류 1	omx_follower_grip

• lerobot 0.6.1 · ACT · 처음부터 학습(이미지 인코더만 ImageNet ResNet18) · batch 8 · 100k step
• 카메라: top(위쪽), wrist(손목) · 640×480 · 30fps
• 학습에서 뺀 시연 8개(데이터셋 에피소드 5, 15, 25, 35, 45, 55, 61, 67)로 평가

평가 결과 (녹화 영상 기반, 처음 보는 시연, 50스텝 실행, lerobot 단위 · 관절 1단위 ≈ 1.8°)

모델	1022 환경 관절 / 그리퍼 오차	v1 환경 관절 / 그리퍼 오차
act_merged	2.08 / 0.70	2.40 / 1.14
act_merged_grip	2.08 / 0.60	2.43 / 1.13

실물 로봇 성공률은 아직 측정하지 않았습니다.

빠른 시작

hf download Sungah/omx_box_act --local-dir omx_box_act
cd omx_box_act && chmod +x run.sh run_native.sh

A. 설치된 lerobot으로 실행 (Docker 없이)

lerobot이 설치된 환경을 켠 뒤:

./run_native.sh check          # 버전 확인, 모델 로딩 확인, 캘리브레이션 목록
./run_native.sh find-port      # → config.env 의 ROBOT_PORT
./run_native.sh find-cameras   # → config.env 의 FRONT_CAM(위쪽), WRIST_CAM(손목)
./run_native.sh rollout

• lerobot 0.6 이상 권장. 0.4~0.5에서는 act_merged만 실행됩니다(그리퍼 전류 모델과 ENSEMBLE_K는 0.6 이상 필요).
• 캘리브레이션이 없으면 ./run_native.sh calibrate

B. Docker로 실행

./run.sh build      # 최초 1회 (CPU용 이미지)
./run.sh find-port
./run.sh find-cameras
./run.sh calibrate  # 최초 1회
./run.sh rollout

설정 (config.env)

항목	기본값	설명
MODEL	models/act_merged	그리퍼 전류 모델은 models/act_merged_grip
ROBOT_TYPE	omx_follower	그리퍼 전류 모델은 omx_follower_grip (스크립트가 맞지 않으면 알려줌)
FRONT_CAM_NAME / WRIST_CAM_NAME	top / wrist	모델 입력 이름. 바꾸지 마세요
FPS	30	학습 데이터와 같아야 함
N_ACTION_STEPS	50	한 번 예측 후 실행할 스텝 수 (아래 참고)
ENSEMBLE_K / ENSEMBLE_M	비움 / 0.01	k스텝마다 예측해 겹치는 예측을 평균 (부드럽지만 반응이 느림, GPU 권장)
MAX_RELATIVE_TARGET	10	한 스텝 최대 이동량 (안전장치). 너무 느리면 키우거나 비움

실행 길이와 속도

• CPU 8코어에서 예측 1회에 약 0.6~1.0초. 예측하는 동안 로봇이 잠깐 멈출 수 있습니다.
• CPU: N_ACTION_STEPS=50 (기본) 권장. GPU: DEVICE=cuda, N_ACTION_STEPS=10 정도까지 줄이면 더 정확(녹화 영상 평가 기준).

그리퍼 전류 모델

• omx_grip_robot.py가 OMX를 상속해 그리퍼 모터의 Present_Current(부호 있는 원시값, 1 = 1 mA)를 7번째 state로 추가합니다. 녹화 때 aux.gripper_current와 같은 값입니다.
• 캘리브레이션 파일은 일반 omx_follower와 공유합니다.
• 실물 로봇 없이 가상 모터·카메라로 lerobot-rollout 전체 흐름을 돌려, 정책에 7개 값 state가 들어가고 동작 명령이 나가는 것까지 확인했습니다. 실물 로봇에서는 아직 확인하지 않았습니다.
• lerobot-rollout은 이름이 .pos/.vel로 끝나는 값만 정책에 넘기므로, 코드 안에서는 전류를 gripper_current.pos라는 이름으로 다룹니다 (값은 전류 그대로).

파일

파일	역할
run.sh / run_native.sh	Docker / 설치된 lerobot 실행 스크립트
config.env	실행 설정
omx_rollout.py	lerobot-rollout + 그리퍼 전류 로봇 + (선택) k스텝 앙상블
omx_grip_robot.py	omx_follower_grip 로봇 타입
act_ensemble.py	k스텝 temporal ensembling
fix_model_config.py	lerobot 0.4~0.5에서 모델 설정 호환 처리
weights/	ResNet18 가중치 (인터넷 없이 실행)
Dockerfile	실행용 이미지 (lerobot 0.6.1, CPU torch)

안전

• 처음에는 MAX_RELATIVE_TARGET=10으로 시작하고, 로봇 옆에서 전원을 바로 끌 수 있게 준비하세요.
• 카메라 위치·조명·물체가 학습 데이터와 다르면 성능이 크게 떨어집니다.