XM10 Extension Module SDK v2.6.0¶
릴리즈 날짜: 2026-08-20 | 대상 보드: Rev 1.1 · Rev 2.0 | 함께 제공하는 KIT H10 펌웨어: v2.4.0
한눈에 보기¶
안전 동작을 중심으로 손본 릴리즈입니다.
- 제어를 끄면 확실히 꺼집니다.
MONITOR로 돌아갈 때 토크를 0 까지 내리고 0 을 확실히 보낸 뒤 출력을 끕니다. - 펌웨어가 멈추면 보드가 스스로 재시작합니다. 하드웨어 워치독(약 8 초)이 들어갔습니다.
forwardVelocity값이 바로잡혔습니다. 실제보다 60 배 크게 나오던 문제입니다.- 예제 15 개의 안전 장치를 보강했습니다. 예제 번호와 배우는 내용은 그대로입니다.
- KIT H10 펌웨어가 v2.4.0 으로 올라갔습니다.
Rev 1.1 은 v2.5.0 이후 첫 업데이트입니다 (v2.5.1 은 Rev 2.0 전용이었습니다).
꼭 확인할 변경 3 가지¶
1. MONITOR 로 돌아가는 데 0.3 ~ 0.6 초가 걸립니다¶
예전에는 XM_SetControlMode(XM_CTRL_MONITOR) 를 부르면 XM10 이 그 자리에서 전송을 멈췄습니다. H10 은 새 명령이 오지 않으면 마지막에 받은 명령을 계속 유지하므로, 끈 줄 알았는데 토크가 남아 있을 수 있었습니다.
이제는 토크를 0 까지 부드럽게 내리고 → 0 을 여러 번 확실히 보내고 → 벡터를 해제한 뒤 출력을 끕니다. 이 동안(보통 0.3 ~ 0.6 초) 여러분이 넣는 토크 명령은 반영되지 않습니다.
- 즉시 멈춰야 하면
XM_EmergencyDisengage()를 부르세요. 감쇠 없이 바로 0 을 보냅니다. - 지금 실제로 어느 상태인지는
XM_GetAppliedControlMode()로 확인합니다 (CONTROL/MONITOR/TRANSITION). MONITOR에서는 토크든 벡터든 어떤 제어 명령도 나가지 않습니다.
2. forwardVelocity 가 60 배 작아집니다 (정상값)¶
XM.status.h10.forwardVelocity 가 실제보다 60 배 크게 나오고 있었습니다. 이제 1 m/s 로 걸으면 약 1.0 이 들어옵니다.
- 이 값을 화면에 보기만 했다면 — 별도 조치 없습니다.
- 이 값을 제어에 썼다면 — 60 배를 상쇄하려고 게인을 작게 잡아두셨을 수 있습니다. 다시 잡아주세요.
- 예전에 모은 데이터의
forwardVelocity는 60 배 값입니다. 새 데이터와 섞지 마세요. - Ex.22 · 23 · 24 · 26 의 정지 판정이 이제 동작합니다.
forwardVelocity < 0.1조건이 예전에는 사실상 성립하지 않아 늘 "보행 중"으로 처리됐습니다.
3. 8 초 넘게 붙잡고 있으면 보드가 리셋됩니다¶
워치독은 Control_Loop 가 도는 1 kHz 주기에서 갱신됩니다. 따라서 Control_Setup 이나 Control_Loop 안에서 8 초 넘게 머물면 워치독이 보드를 재시작시킵니다. 오래 걸리는 작업은 나눠서 하세요.
XM_Task_CreateOneShot() / XM_Task_CreatePeriodic() 으로 만든 task 는 Control_Loop 보다 낮은 우선순위로 돌기 때문에 해당하지 않습니다. 무거운 계산은 이쪽으로 옮기면 됩니다 (Ex.36 참고).
⚠️ 워치독은 비상 정지 장치가 아닙니다. 코드가 멈추지 않은 채 잘못된 토크를 계속 내보내는 상황에서는 워치독이 동작하지 않습니다. 착용 실험에서는 착용 안전 수칙대로 사람이 직접 정지시키는 것이 1 차 안전망입니다.
새로 생긴 API¶
| API | 용도 |
|---|---|
XM_EmergencyDisengage() |
감쇠 없이 즉시 토크 0 |
XM_GetAppliedControlMode() |
실제 적용 중인 제어 모드 조회 |
xm_api_safety.h |
안전 토크 헬퍼 — XM_SafeTorque_*, XM_SafeAssistLevel(), XM_SafeIsFresh() |
xm_api_safety.h 는 xm_api.h 가 이미 포함하므로 따로 #include 하지 않아도 됩니다.
이름이 하나 바뀌었습니다¶
토크뿐 아니라 P/I 벡터까지 포함하는 모드라 XM_CTRL_TORQUE → XM_CTRL_CONTROL 로 바꿨습니다. 옛 이름도 같은 값의 별칭으로 남아 있어 기존 코드는 고치지 않아도 그대로 빌드됩니다. 예제와 문서는 새 이름으로 통일했으니, 새로 쓰는 코드는 XM_CTRL_CONTROL 을 쓰세요.
static XmSafeTorque_t s_safe;
void Control_Setup(void) {
/* 한계 2.5 Nm | 0 → 한계까지 최소 500 ms | 시작할 때 500 ms 소프트스타트 */
XM_SafeTorque_Init(&s_safe, 2.5f, 500U, XM_SAFETY_DEFAULT_RAMP_MS);
}
void Control_Loop(void) {
/* 이상값 차단 → 한계 클램프 → 소프트스타트 → 기울기 제한 */
float t = XM_SafeTorque_Step(&s_safe, my_desired_torque);
XM_SetAssistTorqueRH(t);
}
제어를 껐다 다시 켤 때는 XM_SafeTorque_Reset(&s_safe) 로 소프트스타트를 다시 시작시키세요. XM_SafeTorque_Step() 은 Control_Loop 에서 매 tick 한 번만 부릅니다.
예제¶
| 무엇 | 어느 예제 |
|---|---|
| 켜는 순간 튀지 않도록 소프트스타트 · 기울기 제한 | Ex.14 · 21 · 27 · 30 · 33 |
| 목표값이 계단처럼 바뀔 때 생기던 충격 제거 | Ex.14 |
| 정지 스위치 단선 대응 · 출력 클램프 · 정지 램프 · 센서 끊김 타임아웃 | Ex.06 · 13 · 17 · 26 · 32 |
| 호밍이 끝나기 전에 제어로 들어가는 경로 차단 | Ex.11 · 12 · 15 · 35 · 36 |
착용하지 않고 돌릴 때¶
Ex.15 · 21 · 30 · 33 은 사람이 착용한 상태를 기준으로 게인이 잡혀 있습니다. 착용하지 않고 다리만 매달린 상태로 돌리면 관성이 훨씬 작아 진동하거나 발산합니다. 예제가 고장 난 게 아닙니다.
각 예제 파일 맨 위에 벤치용 파라미터 안내를 넣어 두었습니다. 링크 하나만의 질량·무게중심 값(0.184 kg / 0.1264 m)으로 바꾸면 안정적으로 관찰할 수 있습니다.
다운로드¶
| 파일 | 대상 보드 |
|---|---|
| Rev2.0.zip | XM10 Rev 2.0 (RJ45 Ethernet 포트 있음) |
| Rev1.1.zip | XM10 Rev 1.1 (포트 없음) |
함께 첨부한 파일¶
| 파일 | 용도 | 이번에 바뀌었나 |
|---|---|---|
AGR_Bootloader.bin |
XM10 부트로더 (SWD 로 설치) | 갱신 — 설정 영역이 손상돼도 스스로 복구 |
SUIT_H10_Binary_20260820.zip |
KIT H10 (CM · MD · ESP32) 펌웨어 | 갱신 — CM · MD v2.4.0 (ESP32 는 그대로) |
SUIT_ContentsFiles_20260820.zip |
KIT H10 컨텐츠 파일 (모션 · 사운드) | 내용 동일 (파일명만 날짜 변경) |
- 부트로더: v2.6.0 펌웨어는 예전 부트로더에서도 그대로 동작합니다. 부팅이 아예 안 되는 상황에 대한 대비이므로 권장이지 필수는 아닙니다. → 부트로더 업로드
- KIT H10 펌웨어: USB 스틱에 넣어 업데이트합니다. → KIT H10 펌웨어
빌드 마지막 단계에서 Python 을 사용합니다. 아직 설치하지 않았다면 개발 환경 구축 을 따라 Python 3.10+ 를 설치해 주세요 (PATH 등록 필수).
호환성¶
| 항목 | 영향 |
|---|---|
여러분의 Control_Setup / Control_Loop |
재빌드만 하면 됩니다. 없어진 함수 없음, 옛 이름 XM_CTRL_TORQUE 도 그대로 |
XM_SetControlMode(XM_CTRL_MONITOR) |
즉시 차단이 아니라 0.3 ~ 0.6 초 후 차단 |
MONITOR 모드 |
토크 · 벡터 모두 완전 차단 |
XM.status.h10.forwardVelocity |
값이 60 배 작아짐 (정상값) |
Control_Setup / Control_Loop |
8 초 넘게 머물면 워치독 리셋 |
| Total Data 패킷 | 크기 · 채널 위치 그대로 (365 B) — 기존 수신 프로그램 무수정 동작 |
| PhAI Studio | 그대로 동작 |
| 예제 개수 | 변동 없음 (Rev 2.0 45 개 / Rev 1.1 42 개) |