콘텐츠로 이동

XM10 Extension Module SDK v2.2.0

릴리즈 날짜: 2026-05-18 | 대상 HW: Rev 1.1 / Rev 2.0 | KIT H10 FW: v2.3.0+

한눈에 보기

이번 버전은 사용자 함수 이름을 정리하고, 여러 작업을 동시에 돌리는 방법 을 양 리비전에서 똑같이 쓸 수 있도록 평준화한 업데이트입니다.

  • 사용자 함수 이름: User_Setup / User_Loop → Control_Setup / Control_Loop (예전 이름은 더 이상 지원되지 않으니 함수명을 바꿔 주세요)
  • 폴더 이름: XM_Apps/User_Algorithm/ → XM_Apps/Control_Task/
  • Rev 1.1 에도 보조 작업(task) API + 데이터 공유 보호 API 추가 — 이제 Rev 1.1 / Rev 2.0 어느 보드든 똑같은 방식으로 멀티 작업을 짤 수 있습니다
  • 학습 예제 2 개 추가 (Ex.38, Ex.39)
  • 작업 구조 가이드 문서 1 편 추가 (docs/api-reference/09-task-creation.md)

기존 자산을 그대로 사용해도 됩니다. 새 이름이 더 직관적이라 새로 짤 때 권장.

다운로드

SDK ZIP — GitHub Release 페이지에서 직접 다운로드

파일 대상 보드
Rev1.1.zip XM10 Rev 1.1 (초기 개발용 보드)
Rev2.0.zip XM10 Rev 2.0 (Ethernet / PSRAM / RTC 포함 최신 보드)

압축을 풀면 한 폴더가 나옵니다. 그 폴더가 곧 STM32CubeIDE Import root + Claude Code 진입 폴더입니다.

Release 첨부 파일

파일 설명
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 컨텐츠파일 SDcard에 직접 폴더 전체 교체 필요.

자세한 업데이트 절차는 docs/kit-h10-firmware/ 참고.

도구

도구 링크
PhAI Studio (실시간 데이터 모니터링, 데이터 수집) studio.onephai.com
STM32CubeProgrammer (부트로더 최초 설치) st.com
STM32CubeIDE (펌웨어 개발 IDE) st.com

새로 추가된 것

1. 사용자 함수 이름 정리

이전까지 사용자가 작성하는 두 함수의 이름이 User_Setup / User_Loop 였는데, 이번 버전부터 Control_Setup / Control_Loop 으로 통일했습니다. "제어 코드를 여기에 쓴다" 라는 의도가 더 명확하기 때문입니다.

// 이전
void User_Setup(void) { /* 초기화 */ }
void User_Loop(void)  { /* 1 ms 주기 반복 */ }

// 이번 버전 (권장)
void Control_Setup(void) { /* 초기화 */ }
void Control_Loop(void)  { /* 1 ms 주기 반복 */ }

기존 코드는 그대로 둬도 됩니다. SDK 내부에서 옛 이름과 새 이름을 둘 다 받아들이도록 처리해 두었습니다. 새로 시작하는 코드는 새 이름으로 쓰시면 됩니다.

폴더 이름도 같은 맥락에서 XM_Apps/User_Algorithm/ → XM_Apps/Control_Task/ 로 바뀌었습니다.

2. Rev 1.1 에도 보조 작업(task) API 추가

Rev 2.0 에만 있던 다음 API 가 이제 Rev 1.1 에도 같이 들어갑니다. 어떤 보드를 쓰든 동일한 방식으로 멀티 작업 코드를 짤 수 있습니다.

// 1회만 실행되는 무거운 계산 (예: 학습, FFT)
XmTaskHandle_t XM_Task_CreateOneShot(...);

// 주기적으로 도는 보조 작업 (예: 10ms 마다 평균 계산)
XmTaskHandle_t XM_Task_CreatePeriodic(...);

// 작업 끝났는지 확인 / 정리
bool XM_Task_IsComplete(XmTaskHandle_t h);
void XM_Task_Delete(XmTaskHandle_t h);

// 두 작업이 같은 데이터를 안전하게 주고받기 위한 잠금
XmMutexHandle_t XM_Mutex_Create(void);
bool            XM_Mutex_Lock(XmMutexHandle_t m, uint32_t timeout_ms);
void            XM_Mutex_Unlock(XmMutexHandle_t m);

기존 XM_BgTask_Create 도 그대로 동작합니다 (deprecated 표시만 추가). 새 코드는 새 API 권장.

3. 학습 예제 2 개 추가

예제 학습 포인트
Examples/38_Periodic_Background_Task/ Control_Loop(1 kHz, 빠른 제어) 과 보조 task(100 Hz, 평균 계산) 가 같은 데이터를 안전하게 주고받는 패턴
Examples/39_Task_Lifecycle/ 버튼 누르면 200 ms 짜리 무거운 계산을 별도 task 로 돌리고 끝나면 깔끔하게 정리하는 패턴

처음 보조 task 를 만들어 보는 사용자에게 추천합니다. README 에 회로 셋업과 흔한 실수까지 정리되어 있습니다.

4. 작업 구조 가이드 문서

docs/api-reference/09-task-creation.md — 보드 안에서 어떤 task 들이 어떤 우선순위로 돌고 있는지, 사용자가 만든 보조 task 가 어디에 들어가는지 한 그림으로 정리한 문서입니다. 1 kHz 주기를 깨지 않으면서 안전하게 코드 추가하는 데 도움이 됩니다.

Rev 1.1 ↔ Rev 2.0 평준화

이전까지는 Rev 2.0 에만 있던 기능이 몇 개 있었지만, 이번 버전부터 사용자 코드 영역의 API 는 두 보드가 동일합니다.

항목 Rev 1.1 Rev 2.0
사용자 함수 이름 (Control_Setup/Loop) ✅ ✅
보조 task API (XM_Task_*) ✅ (v2.2.0 부터) ✅
데이터 보호 API (XM_Mutex_*) ✅ (v2.2.0 부터) ✅
Ex.38 / Ex.39 학습 예제 ✅ (v2.2.0 부터) ✅
작업 구조 가이드 ✅ (v2.2.0 부터) ✅
ETH / PSRAM / RTC ❌ (HW 부재) ✅

사용자 학습 코스는 Rev 1.1 / Rev 2.0 어느 쪽이든 동일하게 진행할 수 있습니다.

호환성 안내

기존 v2.1.1 코드를 v2.2.0 SDK 로 올릴 때

함수 이름만 새 규칙으로 바꾸면 됩니다 (예전 이름은 더 이상 지원되지 않습니다).

  • 옛 함수 이름 (User_Setup / User_Loop) → Control_Setup / Control_Loop 로 변경 필요
  • 옛 API (XM_BgTask_Create) 그대로 두어도 동작
  • 사용자 코드 폴더는 옛 위치에 그대로 두면 자동으로 새 위치 (Control_Task/) 로 찾아갑니다 (단, ZIP 새로 풀면 Control_Task/ 만 들어 있습니다 — 그 안에 본인 코드를 옮기세요)

새로 시작하는 코드

  • XM_Apps/Control_Task/control_task.c 안에 Control_Setup() / Control_Loop() 작성
  • 보조 task 가 필요하면 Ex.38 / Ex.39 패턴 참고

변경 파일

SDK 안의 펌웨어 라이브러리(libXM_Lib.a)도 위 변경을 반영해 새로 빌드되었습니다. 사용자가 따로 할 일은 없습니다.

도움 받기

이번 v2.2.0 은 이름 정리 + 평준화 가 핵심입니다. 다음 학기 / 다음 프로젝트 시작 전에 한 번 새 SDK 로 올려두시는 걸 권장합니다.