XM10 Extension Module SDK v2.8.0¶

릴리즈 날짜: 2026-09-10 | 대상 보드: Rev 1.1 · Rev 2.0 | 새로 생김: PC 데이터 도구 xm10

한눈에 보기¶

펌웨어보다 PC 쪽이 크게 채워진 릴리즈입니다.

PC 데이터 도구 xm10 이 SDK 에 들어왔습니다. 보드 없이 전체 동작을 볼 수 있는 demo 명령부터 실시간 그래프, 무손실 저장, CSV 내보내기까지 한 스크립트로 됩니다.
Total Data(0x20) 197 채널을 PC 에서 제대로 풀 수 있게 됐습니다. 지금까지는 값이 섞여서 깨져 나왔습니다.
직접 등록한 채널 이름이 PC 화면에 나옵니다. 지금까지는 ch0, ch1… 로만 보였습니다.
예제 35 를 고쳤습니다. 채널 이름만 등록해 두고 값은 한 번도 보내지 않던 자리였습니다.
펌웨어 자체는 거의 바뀌지 않았습니다. 동작에 영향을 주는 변경은 이 문서에 적힌 것이 전부입니다.

이번 릴리즈의 주인공 — PC 데이터 도구 `xm10`¶

위치는 SDK 안 Extension_Module\PythonDecoder\ 폴더입니다. v2.7.0 까지는 여기 없었고, 이번부터 SDK 안에 함께 들어갑니다. 자세한 사용법은 PC 데이터 도구 안내 문서를 보시고, 아래는 감을 잡기 위한 요약입니다.

가장 먼저 해 보실 건 이겁니다 — 보드가 옆에 없어도 됩니다.

cd Extension_Module\PythonDecoder
pip install pyserial pyqt5 pyqtgraph numpy
python xm10.py demo

만들어 둔 데이터를 흘려보내면서 전체 경로를 한 번씩 다 돌려 보고, 마지막에 항목별로 통과했는지 스스로 알려줍니다.

명령	하는 일
`xm10.py demo`	보드 없이 전체 동작을 시연
`xm10.py ports`	연결된 포트 나열, XM10 으로 보이는 포트 표시
`xm10.py recv`	실시간 그래프 창 (`--cli` 옵션으로 콘솔만)
`xm10.py soak --minutes 30`	지정 시간 동안 받으면서 빠진 데이터가 없는지 확인
`xm10.py export FILE --csv DIR`	저장해 둔 `.xmlog` 를 CSV 로 변환
`xm10.py selftest`	보드 없이 도구 자체를 점검

실행파일이 필요하면 build_exe.py 로 만들 수 있습니다. 그래프 창 포함 버전은 약 55.6 MB, --no-gui 옵션(콘솔만, 그래프 없음)은 약 23.0 MB 입니다. 만든 뒤에는 그 실행파일로 selftest 와 demo 를 한 번 돌려서 제대로 됐는지 확인하시길 권합니다.

받은 데이터를 그대로 저장하는 `.xmlog`¶

받은 데이터는 해석하기 전에 있는 그대로 파일에 먼저 저장됩니다. CSV 로 바꾸는 건 나중에 export 명령으로 언제든 할 수 있습니다.
화면에는 안 그리는 채널(시스템 채널 0x20)도 파일에는 전부 들어갑니다.
중간에 빠진 데이터가 있으면 그 자리가 기록으로 남아, 나중에 어디가 비었는지 알 수 있습니다.
받던 도중 프로그램이 꺼지는 등으로 파일이 끊겨도, 그 앞부분까지는 정상적으로 읽힙니다.
그래프 창에는 "Save .xmlog" 체크박스가 있고 기본으로 켜져 있습니다. CSV 와 같은 폴더에 저장됩니다.
파일 이름은 CSV 가 cdc_phai_<시각>.csv, xmlog 가 cdc_<시각>.xmlog 입니다.

Total Data(0x20) 197 채널, 이제 PC 에서 제대로 풀립니다¶

지금까지 XM10 은 이 197 개 채널을 이미 1 kHz 로 보내고 있었지만, PC 쪽은 전체를 모두 float 로 가정하고 읽었습니다. 실제로는 정수와 실수가 섞여 있어서 값이 깨져 나왔습니다.

이번에 xm10 이 각 채널의 실제 형식대로 읽도록 고쳤습니다.

직접 만든 수신 프로그램을 쓰신다면 알아두세요 — 이 데이터는 365 바이트인데, PC 로는 길이를 4 바이트 단위로 맞추느라 뒤에 0 이 3 바이트 붙어 368 바이트로 옵니다.
CSV 로 내보내면 열 제목에 leftHipAngle 처럼 실제 채널 이름이 붙습니다. 더 이상 열 번호로 세어 가며 찾을 필요가 없습니다.

사용자 채널에 이름이 붙습니다¶

펌웨어는 XM_SetUsbCustomMeta() 로 등록한 채널 이름을 원래부터 PC 에 보내고 있었지만, 예전 수신 프로그램은 그 이름을 쓰지 않고 ch0, ch1… 로 표시했습니다. 이번부터 xm10 이 그 이름을 그대로 씁니다.

그래프 제목과 CSV 열 제목에 여러분이 등록한 이름이 나옵니다.
다만 이 경로로는 값의 타입까지는 전해지지 않아서, PC 는 일단 float32 로 가정하고 보여 줍니다. 그 사실을 화면과 CSV 요약에 ⚠ 타입 미상 — float32 가정 으로 표시해 헷갈리지 않게 했습니다.

고친 것 — 예제 35 MultiLayer Transparent Control¶

채널 이름 7 개(Gravity / DOB / Impedance / Total / Angle / Velocity / Mode, 단위는 Nm·deg·deg/s)를 등록만 해 두고 실제로 값을 보내는 호출을 한 번도 하지 않고 있었습니다. PC 쪽에는 이름은 있는데 값은 영원히 안 오는 채널로 보였습니다. Rev 2.0 · Rev 1.1 양쪽 다 고쳤습니다.

USB 로 데이터를 보내는 다른 예제에는 같은 문제가 없는 것을 확인했습니다.

이 도구를 쓰실 때 지켜 주실 것 4 가지¶

이미 예제 09 등에 적혀 있는 내용이지만, 이번에 자동 채널 이름 표시가 생기면서 한 번 더 강조할 가치가 있습니다.

USB 로 보내는 구조체 멤버는 float 만 쓰세요.
JSON 에 등록하는 채널 이름의 개수와 순서는 구조체 멤버 개수·순서와 정확히 같아야 합니다.
Module ID 는 0xF0 ~ 0xFE 범위를 쓰세요.
XM_SetUsbCustomMeta() 는 한 연결에 한 번만 유지됩니다. 여러 번 부르면 나중 호출이 앞의 것을 그냥 덮어씁니다. 채널마다 따로 등록하지 말고 한 번에 모아서 호출하세요.

예제 개수¶

Rev 2.0 46 개 / Rev 1.1 42 개. v2.7.0 과 같습니다.

아직 안 되는 것 — 꼭 읽어 주세요¶

아직 실제 XM10 보드로는 확인하지 못했습니다. 이번 PC 도구는 미리 만들어 둔 데이터와 도구 자체 점검으로만 확인했고, 보드를 연결해 받아 본 적은 없습니다. 써 보시다가 이상한 점이 있으면 알려 주세요.
채널의 값 형식(float 인지 정수인지 등)은 아직 PC 로 전해지지 않습니다. 지금 보드는 채널 이름만 보냅니다 — 그래서 위에서 설명한 대로 PC 는 항상 float32 로 가정합니다.
--no-gui 실행파일은 실시간 수신 경로를 검사하지 못합니다. 그래프 창을 만드는 패키지가 없으면 수신기 자체가 못 뜨기 때문입니다. selftest 를 돌리면 이 사실을 화면에 알려 줍니다.

Rev 1.1 SDK 의 폴더 이름 2 개가 바뀝니다¶

Rev 1.1 SDK 안에서 아래 두 폴더 이름이 바뀝니다. Rev 2.0 은 v2.7.0 에서 이미 바뀌었고, 이번에 Rev 1.1 도 같은 이름으로 맞췄습니다.

예전	지금
`XM_FW/IOIF/`	`XM_FW/phoundation-ioif/`
`XM_FW/AGR_MW/`	`XM_FW/phoundation-mw/`

SDK 를 그대로 쓰시면 하실 일이 없습니다 — 동봉된 CMakeLists.txt 와 .cproject 를 새 경로로 맞춰 두었습니다. 본인 빌드 스크립트나 프로젝트 설정에 옛 경로를 직접 적어 두셨다면 그것만 바꿔 주세요. #include "ioif_agrb_uart.h" 처럼 파일 이름만 쓰는 방식은 영향받지 않습니다.

호환성¶

항목	내용
기존 펌웨어 코드	재빌드만 하면 됩니다. 삭제되거나 이름이 바뀐 공개 API 없음
PC 데이터 도구	이번부터 SDK 동봉. 별도로 Python 패키지 설치 필요 (`pyserial pyqt5 pyqtgraph numpy`)
Rev 1.1	예제 35 수정 반영. 그 외 펌웨어 변경 없음. 단 위 폴더 이름 2 개가 바뀝니다
Total Data / 채널 이름	Rev 1.1 · Rev 2.0 공통

다운로드¶

파일	대상
`Rev2.0.zip`	Rev 2.0 보드용 SDK (예제 46 개, `PythonDecoder/` 포함)
`Rev1.1.zip`	Rev 1.1 보드용 SDK (예제 42 개, `PythonDecoder/` 포함)
`AGR_Bootloader.bin`	XM10 부트로더 — v2.6.0 과 동일본(이번 릴리즈에서 변경 없음)
`SUIT_H10_Binary_20260820.zip`	KIT H10 펌웨어 — v2.6.0 과 동일본
`SUIT_ContentsFiles_20260820.zip`	H10 컨텐츠 파일 — v2.6.0 과 동일본

부트로더·H10 관련 3 개 파일은 v2.6.0 것을 그대로 다시 올린 것입니다. 이번 릴리즈는 XM10 쪽만 바뀌었고 그쪽은 변경이 없습니다.

압축을 풀 때 짧은 경로(예: C:\xm10\)에 푸세요. 경로가 깊으면 윈도우의 경로 길이 제한 때문에 빌드가 실패할 수 있는데, 이건 코드 문제가 아니라 경로 길이 문제입니다.