XM10 Extension Module SDK v2.2.2¶
릴리즈 날짜: 2026-05-20 | 대상 HW: Rev 1.1 / Rev 2.0 | KIT H10 FW: v2.3.0+
한눈에 보기¶
SDK 안의 예제 코드를 다듬은 패치 릴리즈 입니다. 사용자들이 따라 하다가 헷갈릴 만한 부분이나 버퍼/부호 처리가 어설픈 부분을 정리했습니다. 또 Ex.36 (OnDevice Kinesthetic Learning) 이 Rev 1.1 에서는 빌드가 안 된다는 점을 모든 안내에 명시했습니다.
- 9 개 예제의 코드 정리
- Ex.36 이 Rev 2.0 전용 임을 소스 헤더 / README / tutorials 로드맵 / troubleshooting 4 곳에 일관 표기
- 예제 빌드 확인 — Rev 2.0 은 전체 통과, Rev 1.1 은 Ex.36 을 뺀 나머지 전체 통과
- 빌드 환경, API, KIT H10 펌웨어는 v2.2.1 과 동일 — 다시 받기만 하면 됩니다
기존 사용자 코드는 그대로 동작합니다. API / 동작 변경 없음. v2.2.1 로 학습 진행 중이라면 굳이 받지 않으셔도 되고, 새로 시작하시는 분만 본 ZIP 으로 받아주세요.
다운로드¶
| 파일 | 대상 보드 |
|---|---|
| Rev1.1.zip | XM10 Rev 1.1 (초기 개발용 보드) |
| Rev2.0.zip | XM10 Rev 2.0 (Ethernet / PSRAM / RTC 포함 최신 보드) |
압축을 풀면 한 폴더가 나옵니다. 그 폴더가 곧 STM32CubeIDE Import root + Claude Code 진입 폴더입니다.
본인 보드 리비전과 같은 ZIP 을 받아주세요. 라벨이 모호하면 외관상 RJ45 Ethernet 포트가 있으면 Rev 2.0, 없으면 Rev 1.1 입니다. 자세한 비교는 docs/hardware/README.md - 보드 리비전 비교.
Release 첨부 파일¶
부트로더 / KIT H10 펌웨어 / 컨텐츠 파일은 v2.2.0 / v2.2.1 과 동일합니다. 이전 릴리즈에서 이미 설치하셨다면 v2.2.2 에서 다시 받지 않으셔도 됩니다. 처음 v2.2.2 부터 시작하시는 분만 함께 다운로드.
| 파일 | 설명 |
|---|---|
AGR_Bootloader.bin |
XM10 부트로더 (v1.1.0). 0x08000000 에 한 번만 설치하면 됩니다. |
SUIT_FW_ContentsFiles_20260518.zip/SUIT_CM_APP_X_X_X.bin |
KIT H10 CM 펌웨어. USB-C 메모리로 직접 업데이트. |
SUIT_FW_ContentsFiles_20260518.zip/SUIT_SAM10_APP_X_X_X.bin |
KIT H10 MD(SAM10) 펌웨어. |
SUIT_FW_ContentsFiles_20260518.zip/SUIT_ESP32_FW_X_X_X.bin |
KIT H10 ESP32 펌웨어. |
SUIT_FW_ContentsFiles_20260518.zip/SUIT_ContentsFiles.zip |
KIT H10 컨텐츠파일. SD card 폴더 전체 교체. |
업데이트 절차: docs/kit-h10-firmware/.
도구¶
| 도구 | 링크 |
|---|---|
| PhAI Studio (실시간 데이터 모니터링, 데이터 수집) | studio.onephai.com |
| STM32CubeProgrammer (부트로더 최초 설치) | st.com |
| STM32CubeIDE (펌웨어 개발 IDE) | st.com |
예제 코드 정리 — 9 건¶
사용자가 예제를 따라 만들 때 가장 자주 발을 거는 패턴들이라, 짧은 패치라도 모아 릴리즈합니다.
그대로 따라 쓰면 안 되는 패턴¶
- Ex.31 (Friction_Comp_DOB) —
MAX_TORQUE_NM이 같은 파일에서 두 번#define되어 있어 (8.0f뒤에5.0f) 컴파일러가redefined경고를 출력하고 있었습니다. 두 정의 중5.0f가 실제 동작 값이라 토크 클램프는 5 Nm 로 정상이지만, 위쪽 주석은 8 Nm 를 가리키고 있어 사용자가 "왜 8 까지 안 가지?" 로 혼선이 가능. 5.0 Nm 단일 정의로 통합. - Ex.08 (CDC_Sensor_Print) · Ex.13 (Resistive_Mode) — 64 byte 스택 버퍼에 bare
sprintf(...)를 쓰고 있었습니다. 포맷 문자열이 늘어나면 버퍼를 조용히 넘쳐 쓸 위험이 있어snprintf(buf, sizeof(buf), ...)로 교체. Ex.08 은 "CDC 디버그 print 모범 예시" 의 위치라 사용자가 그대로 복사해 갈 가능성이 높아 먼저 고쳤습니다.
동작은 하지만 헷갈리던 부분¶
- Ex.15 (Inverted_Pendulum) — 디버그 라인의 고정소수점 출력에서 음수 부호가 사라지던 버그. 예를 들어
theta = -0.35가 시리얼 로그에0.35로 찍혀, 골반이 한쪽으로 기울어졌는데도 부호 없이 표시돼서 PD 게인 튜닝 디버그가 어려웠습니다. 부호를%s로 prefix 분리 해-0.35가 그대로 표시되도록 수정. - Ex.33 (Kinesthetic_Teaching) — 재생 인덱스 전진 타이머가 "loop-count 매크로" 를 "ms 임계값" 으로 재활용하고 있었습니다. 우연히 둘 다
10이라 동작은 했지만, 둘 중 하나라도 바뀌면 깨지는 구조.REPLAY_STEP_MS = 10U매크로 신설 로 의미를 분리. - Ex.36 (OnDevice_Kinesthetic_Learning) —
Active상태로 다시 들어올 때 첫 주기에 곧바로STANDBY로 빠져버릴 수 있었습니다.Active_Entry에서 값을 명시적으로 초기화하도록 고쳤습니다. 더불어 학습 task 와 제어 루프가 값을 주고받을 때의 주의점을 헤더 주석에 남겨, "왜 Ex.38 에서는 mutex 를 쓰는데 여기서는 안 쓰지?" 의 답이 코드에서 보이도록 보강.
오해하기 쉬운 부분¶
- Ex.22 (CPG_Oscillator) — AFO 의 frequency 적응 식이 phase advance 이후 의
sin(φ)를 쓰고 있어, 문서화된 Ronsse 2011 식 (φ[k]사용) 과 한 스텝 어긋나 있었습니다.sin(φ[k]) / cos(φ[k])를 미리 계산 해 두 업데이트 식이 같은 시점의 위상을 보도록 정렬. - Ex.24 (Virtual_Constraint) — 5 차 Bézier basis 가 1 kHz 루프에서
powf를 12 회 호출하고 있었습니다. 거듭곱 체인 (s2 = s*s,s3 = s2*s, ...) 으로 교체 — powf 가 사라져서 호출 비용이 곱셈 ~14 회로 떨어졌습니다. - Ex.26 (ILC) — 보행 주기 1 회당 1 번만 호출되는데 함수 헤더에 그게 명시되지 않아 "1 kHz 루프에서 매번 USB send 하는 거 아닌가?" 오해를 줄 수 있었습니다. 호출 빈도 (≈ 1 Hz) 와 다른 빈도로 옮길 때의 가이드를 헤더 주석에 명시.
- Ex.16 (TinyAI Sensor_Fusion) — NN raw logit 을
× 100.0f해서Conf:%라벨로 출력 — 사용자가 보면 확률처럼 보이지만 실제는 softmax 가 아닌 raw 값. 라벨을Score:로,× 100제거 해 단위 그대로 노출. 헤더 주석에도 "raw logit" 임을 명시.
Ex.36 (OnDevice Kinesthetic Learning) 은 Rev 2.0 전용 — 4 곳에 일관 표기¶
Ex.36 은 학습된 NN 가중치를 전원 OFF/ON 사이에 보존하기 위해 내장 Flash 저장 API (XM_UserNV_Read/Write/Erase) 를 사용합니다. 이 API 는 Rev 2.0 의 libXM_Lib.a 에만 포함되어 있어 Rev 1.1 에서는 link 단계에서 undefined reference to XM_UserNV_* 가 발생합니다.
지금까지는 코드도 문서도 이 사실을 알려주지 않아서 Rev 1.1 보드를 받은 사용자가 Ex.36 에서 막힐 때 원인을 짐작하기 어려웠습니다. 본 릴리즈에서 4 곳에 일관 표기를 넣었습니다.
| 위치 | 내용 |
|---|---|
examples/36_OnDevice_Kinesthetic_Learning/ondevice_kinesthetic_learning.c 헤더 |
@warning Rev 2.0 전용 + 원인 + Rev 1.1 사용자 대안 (Ex.35 까지) |
examples/36_OnDevice_Kinesthetic_Learning/README.md 상단 |
🛑 Rev 2.0 전용 안내 배너 |
docs/troubleshooting.md 신규 섹션 |
undefined reference to XM_UserNV_* 증상 — 원인 — 해결 절차 |
docs/tutorials/README.md 예제 로드맵 |
Ex.36 행에 "Rev 2.0 전용" 표기 |
본인 보드가 Rev 1.1 이면 Ex.35 (Multi-Layer Transparent Control) 까지 진행하시면 됩니다. Ex.36 의 NN 학습 + LQR 부분만 보고 싶다면 BTN1 long-press (Flash 저장) 만 제거하고 RAM 만 쓰도록 임시 수정해 학습용으로 활용 가능.
호환성 안내¶
| 항목 | 영향 |
|---|---|
사용자 코드 (Control_Setup / Control_Loop) |
변경 없음 — v2.2.1 코드 그대로 빌드 가능 |
| API 시그니처 | 변경 없음 — 헤더 변경 없음 |
| KIT H10 펌웨어 | v2.3.0 그대로 — 동반 펌웨어 업데이트 불필요 |
| 부트로더 | v1.1.0 그대로 |
| 사용자 데이터 (USB 메모리 로그 등) | 변경 없음 — 데이터 포맷 호환 |
v2.2.1 로 학습 진행 중이라면 본 v2.2.2 로 굳이 갈 필요 없습니다 (예제 코드 정리 + Ex.36 표기 명확화 위주). 새로 시작하시는 분 또는 Ex.36 에서 막혔던 Rev 1.1 사용자는 본 ZIP 으로 받아주세요.