1. 전송, SMP, 그룹 핸들러는 다른 일을 한다
v3.7.0 MCUmgr 문서는 원격 이미지·파일·OS·설정·Shell·통계 관리 등을 소개한다. 이것은 펌웨어 내부에서 DEVICE_DT_GET()으로 드라이버 장치를 얻는 로컬 device model과 별개다. 또한 Shell 명령 트리 자체가 모든 MCUmgr 요청의 처리기가 되는 것도 아니다. Shell 관리 그룹을 별도로 넣었을 때에만 원격 Shell 명령 실행이 관리 기능 중 하나가 된다.
↔ 오른쪽으로 이동하며 클라이언트·전송·SMP·그룹·응답의 소유자를 따라가세요.
| 기능 | 누가 호출하나 | 주소·실행 경계 |
|---|---|---|
| MCUmgr | 외부 관리 클라이언트 | 전송 → SMP 그룹/명령 ID → 등록된 핸들러 |
| Device model | 장치 안의 애플리케이션·드라이버 | Devicetree 노드와 struct device, 로컬 드라이버 API |
| Shell | Shell 인스턴스의 입력 | 텍스트 명령 트리와 핸들러; MCUmgr Shell 그룹은 별도 선택 |
| Network management | 네트워크 상태를 다루는 로컬 코드 | 인터페이스·이벤트·연결 상태; SMP 관리 명령의 전송과 다름 |
근거: 3.7.0 MCUmgr 개요, 그룹 핸들러 설명, SMP 프레임.
2. SMP 헤더의 8바이트는 명령의 위치와 짝을 지정한다
SMP는 응용 계층 프로토콜이다. v3.7.0 사양의 헤더는 8바이트이며 그 뒤에 길이가 0일 수도 있는 데이터가 온다. 다바이트 숫자는 네트워크 바이트 순서다. Group ID와 Command ID가 핸들러를 가리키고, 응답의 Sequence Num은 요청과 같아야 한다. 전송별 UART 마커나 BLE GATT 조각은 이 SMP 헤더 바깥의 문제다.
↔ 왼쪽부터 8바이트 헤더와 가변 데이터의 역할을 읽으세요.
| 필드 | 읽을 질문 | 오해하기 쉬운 점 |
|---|---|---|
OP | 읽기/쓰기 요청인가, 그에 대한 응답인가? | 같은 명령 ID라도 OP에 따라 처리 함수가 달라질 수 있다. |
Group ID + Command ID | 어느 관리 기능과 명령인가? | 번호가 정의돼 있어도 해당 빌드에 핸들러가 있다는 뜻은 아니다. |
Sequence Num | 어느 요청의 응답인가? | 응답은 요청과 같은 번호를 사용해야 한다. |
Data Length + Data | 헤더 뒤 내용은 얼마나 되는가? | 전송 프레임 길이나 BLE 조각 크기와 동일한 개념이 아니다. |
오류도 응답으로 읽는다. v3.7.0 사양에서 성공 응답의 CBOR 맵은 비어 있을 수 있고, SMP v2의 그룹 오류는 err.group/err.rc, 이전 방식이나 SMP 자체 오류는 rc에 나타날 수 있다. 응답이 없다는 것과 오류 응답은 다른 장애다.
근거: 3.7.0 프레임·응답·오류 형식.
3. 그룹 번호는 약속이고, 사용 가능한 명령은 빌드가 결정한다
사양은 흔히 쓰는 그룹 번호를 정의한다. 예를 들어 OS는 0, 이미지 관리는 1, 파일 관리는 8, Shell 관리는 9다. 그러나 번호를 안다고 원격 장치에서 그 명령을 쓸 수 있는 것은 아니다. v3.7.0 공식 smp_svr 샘플의 prj.conf도 OS·IMG·STAT 그룹을 명시적으로 켜며, 파일·Shell 관리는 별도의 overlay 선택을 보여 준다.
| Group ID | 사양의 영역 | 해석할 때 확인 |
|---|---|---|
| 0 | OS 관리 | OS 그룹 핸들러와 해당 명령 옵션 |
| 1 | 이미지 관리 | 이미지 그룹·플래시 맵·MCUboot 통합 조건 |
| 2 / 3 | 통계 / 설정 관리 | 해당 그룹과 백엔드·데이터 존재 여부 |
| 8 / 9 | 파일 / Shell 관리 | 그룹별 선택·파일 시스템 또는 Shell 구성 |
| 63 / 64+ | Zephyr 전용 / 사용자 정의 | 등록된 고유 그룹 ID와 별도 핸들러 |
그룹은 16비트 ID 하나당 하나만 등록할 수 있고, 명령 ID는 그 그룹 안에서 8비트다. 애플리케이션이나 외부 모듈도 자체 그룹 핸들러를 등록할 수 있다. 이때 클라이언트와 서버가 같은 그룹·명령 계약을 공유해야 한다.
근거: 3.7.0 그룹 번호, 핸들러 등록 경계, 태그된 샘플 Kconfig.
4. 같은 SMP 요청도 BLE·UART·UDP에서 다르게 실린다
v3.7.0 MCUmgr 개요는 BLE, UART, UDP 전송을 안내한다. 한 전송이 연결됐다고 해서 다른 전송이나 관리 그룹이 자동으로 켜진 것은 아니다. BLE는 GATT characteristic에 Write Without Response로 요청하고 Notification으로 응답한다. UART의 콘솔 공존 방식은 시작 마커·Base64·종료 개행으로 프레임을 나누며, UDP는 IP 경로에 의존한다. 각 전송의 MTU·분할·접근 통제는 따로 확인한다.
| 경로 | SMP가 실리는 방식 | 첫 진단 지점 |
|---|---|---|
| BLE | GATT Write Without Response 요청 / Notification 응답 | 연결·서비스/characteristic·MTU/조각 |
| UART/serial | 콘솔 공존 프레이밍과 Base64 | 포트 선택·마커/개행·버퍼 크기 |
| UDP over IP | IP 네트워크를 통한 SMP | 인터페이스 주소·도달 경로·선택된 서버 설정 |
| 샘플 Shell 전송 | 별도 Shell overlay에서 선택하는 SMP 운반 경로 | Shell 관리 그룹과 혼동하지 않고 구성 파일 확인 |
Shell 전송 ≠ Shell 관리 그룹. 전자는 SMP를 어떤 입력 경로로 옮길지의 선택이고, 후자는 들어온 요청이 Shell 명령을 실행하도록 하는 기능의 선택이다. 둘을 각각 켤 수 있는지와 동작 조건은 해당 빌드의 overlay·Kconfig를 봐야 한다.
5. 공식 smp_svr에서 전송과 그룹을 따로 확인한다
v3.7.0 공식 샘플은 SMP 서버를 제공하며 BLE·serial·Shell·UDP 등 실행 선택지를 별도 overlay로 보여 준다. 아래는 샘플의 prj.conf 중 관리 기능 선택만 발췌한 것이다. 그 자체로 빌드 가능한 전체 설정이 아니다. 같은 샘플은 CONFIG_BOOTLOADER_MCUBOOT=y를 쓰며, 이미지 관리가 제대로 동작하려면 MCUboot와 이미지 배치가 필요하다고 별도 경고한다.
# v3.7.0 smp_svr/prj.conf의 관리 관련 선택 발췌
CONFIG_MCUMGR=y
CONFIG_MCUMGR_GRP_OS=y
CONFIG_MCUMGR_GRP_IMG=y
CONFIG_MCUMGR_GRP_STAT=y
# 실제 전송은 overlay 및 보드 구성이 별도로 결정한다.| 샘플에서 읽을 파일 | 결정하는 것 | 잘못 내리기 쉬운 결론 |
|---|---|---|
prj.conf | MCUmgr와 OS·IMG·STAT 그룹 등 공통 선택 | 그룹 옵션만으로 BLE/UART가 열렸다는 결론 |
overlay-bt.conf 등 | BLE/serial/Shell/UDP 중 샘플 실행 경로 | 한 overlay 결과를 모든 보드의 기본값으로 일반화 |
| FS·Shell 관리 overlay | 추가 관리 명령의 노출 | 전송 이름의 Shell과 Shell 관리 그룹을 동일시 |
| MCUboot·flash layout | 이미지 업로드·전환의 전제 | IMG 그룹을 켜기만 하면 안전한 DFU가 완성된다는 결론 |
샘플 설명은 실행 후 관리 도구의 echo 기능으로 문자열을 보내 되돌려 받는 검증을 권한다. 그 결과는 선택한 전송과 OS 명령 경로가 왕복했다는 증거다. 이미지 업로드, 파일 접근, Shell 실행까지 모두 성공한다는 증거는 아니다.
6. 접근 가능성은 전송·그룹·명령별 전제에서 결정된다
외부에서 어떤 명령이 가능한지는 단계마다 달라진다. 사용 가능한 전송과 등록된 그룹을 먼저 확인하고, 그 그룹의 특정 명령이 요구하는 저장소·부트로더·후크 정책을 본다. v3.7.0의 MCUmgr callback 기능은 설정된 경우 파일 경로 접근 등을 허용·거부할 수 있지만, CONFIG_MCUMGR_MGMT_NOTIFICATION_HOOKS만 켠다고 모든 보호 콜백이 자동 설치되지는 않는다.
↔ 한 단계에서 실패하면 다음 단계의 문제로 단정하지 마세요.
| 확인된 사실 | 아직 확인되지 않은 것 |
|---|---|
| BLE 또는 UART에 연결됨 | SMP 서버와 원하는 명령 그룹의 존재 |
| OS echo 응답을 받음 | IMG·FS·Shell 그룹과 각 명령의 사용 가능성 |
| IMG 그룹이 빌드됨 | MCUboot 이미지 배치·서명·업로드/전환의 성공 |
| callback 기반 정책을 설계함 | 필요한 notification/이벤트 Kconfig와 등록 코드의 실제 적용 |
네트워크에 노출되는 전송을 고를 때는 링크의 접근 통제와 보드 배포 환경을 별도로 설계한다. SMP 헤더에 Group ID가 있다고 해서 인증·권한이 자동으로 생기는 것은 아니다. Shell 명령 실행이나 파일 쓰기처럼 영향이 큰 그룹은 활성화 여부와 요청 거부 지점을 함께 검토한다.
근거: 3.7.0 notification hooks와 FS 접근 거부 예시, SMP 봉투 필드, IMG·MCUboot 전제.
7. 실패를 “전송 없음”과 “명령 거부”로 나눠 읽는다
| 관측 | 먼저 볼 경계 | 다음 확인 |
|---|---|---|
| 관리 도구가 아예 응답을 못 받음 | 전송·서버 | overlay, BLE characteristic/UART 포트/IP 주소, 프레이밍과 버퍼 |
| 응답이 왔지만 순서 번호가 다름 | SMP 요청·응답 짝 | 클라이언트의 동시 요청과 프레임 파싱 |
| OS echo는 되는데 다른 명령이 없음 | 그룹·명령 활성화 | 해당 그룹/명령의 Kconfig와 등록 코드 |
| 명령 오류 응답이 돌아옴 | 그룹 핸들러·전제 | err.group/err.rc 또는 rc, 기능별 백엔드·정책 |
| 이미지 전환이 기대대로 안 됨 | DFU 통합 | MCUboot, 슬롯/서명, 샘플의 빌드·플래시 절차 |
응답이 있는 경우에는 전송만 계속 의심하지 말고 SMP 오류와 선택된 그룹의 상태로 범위를 좁힌다. 반대로 응답 자체가 없다면 서버 부재·장치 무응답·전송 프레이밍 문제를 먼저 분리한다. 이 표는 진단 순서이며 모든 오류를 한 가지 원인으로 단정하지 않는다.
근거: 3.7.0 최소 응답·오류 표현, 전송별 경계.
8. 고정 버전 근거와 재현 범위
Zephyr v3.7.0 공식 MCUmgr·SMP 문서와 같은 태그의 smp_svr 샘플 설정·설명을 기준으로 썼다. 그림의 단계는 이 계약을 설명하기 위해 새로 구성한 것이며, 현장 보드의 연결·인증·DFU 결과를 시험한 그림이 아니다.
| 고정 근거 | 확인 대상 |
|---|---|
| MCUmgr 3.7.0 | 원격 관리 영역과 BLE/UART/UDP 개요 |
| SMP 프로토콜 3.7.0 | 8바이트 헤더·그룹/명령·응답 순서·오류 |
| SMP 전송 3.7.0 | BLE GATT, serial 프레임과 MTU |
| 핸들러 3.7.0 | 그룹 등록과 사용자 그룹 |
태그된 서버 샘플, prj.conf | 전송 overlay·그룹 옵션·echo·MCUboot 조건 |