BLE·USB 디바이스 프로토콜 설계 노트

핵심 요약: 디바이스 프로토콜은 어느 쪽이든 구현을 시작하기 전에 문서로 정리합니다. 전송 매핑, 프레임 형식, 메시지 유형, 버전 관리, 오류 코드, 타임아웃입니다. 애플리케이션 프로토콜은 BLE나 USB와 무관하게 만들어 시리얼 케이블로도 테스트할 수 있게 합니다. 공유 명세와 호스트 측 테스트 하네스가 있으면 펌웨어 팀과 앱 팀이 병행해서 작업하고 서로 어긋나는 부분을 일찍 찾을 수 있습니다.

디바이스 프로토콜 계층도: 스마트폰이나 PC 애플리케이션이 프로토콜 라이브러리를 거쳐 BLE GATT 또는 USB CDC/HID 전송 어댑터와 통신하고, 이는 디바이스의 전송 드라이버, 프레임 파서, 명령 디스패처, 디바이스 애플리케이션으로 이어진다. 호스트 테스트 하네스는 프레임 계층에 연결된다.
그림 1. 프로토콜 계층. 전송은 바뀌어도 프레임과 메시지 계층은 바뀌지 않는다.

1.0 디바이스 프로토콜이 꼬이는 지점

프로토콜 문제 대부분은 BLE나 USB 자체 때문이 아닙니다. 인터페이스를 한 번도 문서로 남기지 않았기 때문입니다. 펌웨어 엔지니어가 바이트 배치를 정하고, 앱 개발자가 로그를 보고 그것을 읽어 내고, 두 쪽은 조금씩 어긋납니다. 두 번째 펌웨어 릴리스쯤이면 어느 쪽이 맞는지 아무도 모르고, 업데이트가 이미 스토어에 올라간 앱 버전을 깨뜨리며, 수정하려면 양쪽 릴리스를 맞춰서 내야 합니다.

명세에는 전송 방식, 프레임, 메시지 표, 오류 표, 타임아웃이 들어갑니다. 첫 스니퍼 캡처 전에 작성하세요. 그 뒤가 아닙니다.

2.0 계층 구조

각 계층을 따로 테스트할 수 있도록 프로토콜을 계층으로 나눕니다.

계층역할바뀌는 시점
전송바이트 이동: BLE GATT 캐릭터리스틱, USB CDC-ACM, USB HID 리포트, UART하드웨어나 OS가 바뀔 때
프레이밍메시지 경계, 길이, 무결성 검사, 시퀀스 번호드물게
메시지명령과 응답 유형, 페이로드 인코딩, 오류 코드새 기능 추가 시
애플리케이션디바이스가 명령을 받고 하는 일제품 동작이 바뀔 때

프레이밍과 메시지 계층은 아래에 어떤 전송이 있는지 몰라야 합니다. 그래야 같은 프로토콜을 벤치에서는 UART로, 양산 테스트에서는 USB-시리얼 어댑터로, 제품에서는 BLE로 돌릴 수 있습니다.

3.0 전송 방식 선택

요구 사항BLEUSB CDC-ACM(가상 시리얼)USB HID
스마트폰과 무선 연결본래 용도해당 없음해당 없음
데스크톱 OS에서 드라이버 불필요OS 블루투스 스택 필요Windows 10 이상, macOS, Linux에 기본 드라이버 내장드라이버 불필요
브라우저 접근지원 환경에서 Web Bluetooth지원 환경에서 Web Serial지원 환경에서 WebHID
처리량연결 간격과 MTU로 제한더 높음리포트 크기와 폴링으로 제한
전력저전력용으로 설계됨연결 중에는 버스 전원을 쓸 수 있음CDC와 동일

Web Bluetooth, Web Serial, WebHID 지원 여부는 브라우저와 플랫폼마다 다르므로, 의존하기 전에 사용자가 쓰는 브라우저의 현재 지원 상황을 확인하세요. 둘 다 쓰는 제품도 많습니다. 스마트폰 앱에는 BLE, 설정·공장 테스트·복구에는 USB를 씁니다.

3.1 BLE GATT 매핑

흔히 쓰는 방식은 두 가지입니다.

  • 값마다 속성 하나. 설정값이나 측정값마다 별도 캐릭터리스틱을 둡니다. 범용 BLE 도구로 확인하기 쉽지만, 기능을 추가할 때마다 GATT 테이블이 바뀌고 여러 필드를 한 번에 갱신하는 것이 원자적이지 않습니다.
  • 메시지 파이프. 호스트→디바이스 쓰기용 캐릭터리스틱 하나와 디바이스→호스트 알림용 하나로 프레임 단위 메시지를 주고받습니다. 모든 기능을 하나의 프로토콜로 다루고 GATT 테이블은 고정됩니다.

디바이스가 노출하는 값이 몇 개를 넘으면 메시지 파이프를 쓰고, 표준 서비스(Device Information, Battery)는 범용 도구가 계속 동작하도록 속성으로 둡니다. 커스텀 서비스에는 128비트 UUID가 필요하며, 표준 UUID는 Bluetooth SIG의 Assigned Numbers 목록에 있습니다.

처리량과 지연 시간은 연결 파라미터와 협상된 ATT MTU에 따라 달라지는데, 이를 주로 정하는 쪽은 디바이스가 아니라 스마트폰입니다. 메시지 하나가 여러 알림에 나뉘어도 재조립할 수 있게 프로토콜을 설계하고, 특정 MTU를 가정하지 마세요.

3.2 USB 매핑

CDC-ACM은 호스트에 시리얼 포트로 보이며, 프레이밍을 갖춘 바이트 스트림 프로토콜에 맞습니다. HID는 고정 크기 리포트를 쓰고 드라이버 없이 동작해 보안이 엄격한 사내 PC에서 유리합니다. 이때는 프레이밍 계층이 메시지를 여러 리포트로 나눕니다. 두 클래스 명세 모두 USB-IF가 공개합니다.

4.0 프레임

출발점으로 삼는 프레임 형식입니다.

필드크기비고
시작 마커 또는 길이 접두사1–2바이트BLE/HID에서는 길이 접두사, 바이트 스트림에서는 COBS나 SLIP 방식 구분
프로토콜 버전1바이트프레임 형식의 메이저 버전
시퀀스 번호1–2바이트응답을 요청과 짝짓고 누락을 감지
메시지 유형1–2바이트명령, 응답, 이벤트, 오류
페이로드 길이2바이트전송 계층에 길이가 있어도 명시
페이로드가변인코딩은 프로젝트별 선택(고정 구조체, TLV, CBOR, protobuf)
무결성 검사2–4바이트바이트 스트림에서는 CRC, 전송 계층이 이미 검사하면 생략 가능

페이로드 인코딩은 디바이스 코드 크기와 유연성 사이의 절충입니다. 리틀 엔디언 고정 구조체가 가장 작지만 확장하기는 가장 어렵습니다. TLV나 CBOR를 쓰면 이전 읽기 측을 깨뜨리지 않고 선택 필드를 추가할 수 있습니다.

5.0 버전 관리와 호환성

호환성 규칙을 문서로 남기세요. 저희 규칙은 다음과 같습니다.

  1. 디바이스는 형태가 절대 바뀌지 않는 “hello” 또는 “get info” 명령에 대한 응답으로 프로토콜 버전과 기능 플래그를 보고한다.
  2. 새 필드는 선택 항목으로 추가한다. 읽는 쪽은 모르는 필드를 무시한다.
  3. 필드를 없애거나 의미를 바꾸려면 메이저 버전을 올려야 하며, 앱은 문서화된 기간 동안 이전 메이저 버전도 지원한다.
  4. 펌웨어와 앱 릴리스 노트에 지원하는 프로토콜 버전을 적는다.

6.0 오류, 타임아웃, 상태

모든 명령에는 정확히 하나의 응답이 돌아옵니다. 데이터를 담은 성공이거나, 문서화된 표에 있는 오류 코드입니다. 대표적인 오류 분류는 잘못된 프레임, 알 수 없는 명령, 잘못된 파라미터, 사용 중, 현재 상태에서 허용되지 않음, 내부 오류입니다. 오류 표는 코드 안에만 두지 말고 명세에 넣으세요.

타임아웃도 프로토콜의 일부입니다. 명령 분류별 최대 응답 시간, 타임아웃 시 호스트의 동작(같은 시퀀스 번호로 재시도할지, 포기할지), 여러 부분으로 된 메시지의 나머지를 디바이스가 버리기 전까지 기다리는 시간을 정합니다.

펌웨어 업데이트나 캘리브레이션처럼 오래 걸리는 작업은 응답을 붙잡고 있지 말고 즉시 “수락됨”을 돌려준 뒤 진행 상황을 이벤트로 알립니다.

7.0 보안 고려 사항

BLE 페어링과 본딩은 링크를 보호하지만, 인증된 상대가 무엇을 할 수 있는지까지 정하지는 않습니다. 상태를 바꾸는 명령, 인가된 세션이 필요한 명령, 연결된 어떤 호스트에 노출해도 안전한 명령을 목록으로 정리하세요. 공장용·디버그용 명령은 양산 펌웨어에서 비활성화하거나 잠가야 하며, 그 방법을 명세에 적어야 합니다.

8.0 테스트 하네스

시리얼 포트로 프로토콜을 주고받는 작은 호스트 측 도구를 프로젝트에 별도 지정이 없으면 Python으로 작성합니다. 이 도구가 하는 일은 세 가지입니다. 앱이 생기기 전에 펌웨어 엔지니어가 명령을 시험해 볼 수 있게 하고, 벤치의 보드를 대상으로 CI에서 스크립트 기반 회귀 테스트를 돌리고, 앱 팀이 비교할 수 있는 참조 구현이 됩니다. 같은 도구로 잘못된 입력을 프레임 파서에 넣는 퍼징을 하면 평소 사용에서는 드러나지 않는 유형의 크래시를 잡을 수 있습니다.

9.0 인계 항목

  • 프로토콜 명세: 전송 방식, 프레임, 메시지 표, 오류 표, 타임아웃, 버전 규칙.
  • GATT 테이블 또는 USB 디스크립터.
  • 호스트 테스트 도구와 스크립트.
  • 명령별로 캡처한 예시 세션.

이 작업의 디바이스 쪽은 임베디드 펌웨어 페이지에서, 디바이스와 통신하는 앱과 백엔드는 웹·클라우드·디바이스 관리에서 다룹니다. 기존 프로토콜 검토가 필요하면 프로젝트 상담 양식에서 시작하세요.

참고 자료

자주 묻는 질문

BLE 표준 프로파일과 커스텀 서비스 중 무엇을 써야 하나요?

Battery나 Device Information처럼 데이터에 맞는 표준 서비스가 있으면 그것을 씁니다. 범용 도구와 운영체제가 이해하기 때문입니다. 제품 고유 기능에는 커스텀 서비스가 필요합니다. 메시지 파이프 서비스 하나로 묶어 두면 기능이 늘어나도 커스텀 부분은 그대로 유지됩니다.

페이로드 인코딩은 무엇을 골라야 하나요?

디바이스의 플래시·RAM 여유와 프로토콜이 얼마나 자주 바뀔지를 기준으로 고릅니다. 고정 구조체는 작고 안정적인 명령 세트에 맞습니다. TLV나 CBOR는 코드가 더 들지만 이전 앱을 깨뜨리지 않고 필드를 추가할 수 있습니다.

펌웨어 업데이트 후에도 이전 앱이 동작하게 하려면?

버전 조회 명령은 영구히 고정하고, 필드는 선택 항목으로 추가하며, 읽는 쪽은 모르는 필드를 무시하게 합니다. 호환성을 깨는 변경은 새 메이저 버전에 넣고, 이전 버전 지원 기간을 양쪽 릴리스 노트에 적어 둡니다.

같은 프로토콜을 BLE와 USB에서 모두 쓸 수 있나요?

프레이밍과 메시지를 전송 계층과 분리해 두는 이유가 바로 그것입니다. 바뀌는 것은 전송 어댑터뿐입니다. 덕분에 제품 앱은 BLE를 쓰고, 공장 테스트와 복구 도구는 케이블을 쓸 수 있습니다.

프로토콜 명세는 언제 작성해야 하나요?

펌웨어와 앱 작업이 본격적으로 시작되기 전입니다. 첫 초안은 짧아도 됩니다. 전송 방식, 프레임, 명령 대여섯 개, 오류 표 정도면 됩니다. 이후에는 디버깅이 아니라 리뷰를 거쳐 바뀌게 됩니다.