Protocol

바이트 맵

버튼 이벤트

• 눌림(1)·뗌(2)이 각각 정확히 한 번 실립니다. 눌린 동안 반복되지 않습니다.
• 버튼 이벤트 시 레코드가 추가로 즉시 나갈 수 있어, 도착 간격이 항상 일정하지는 않습니다.
• 2초 길게 누르면 전원이 꺼지고 연결이 끊깁니다(별도 이벤트 없음).

파싱 예제 (Python)

import struct

def parse_record(r: bytes):
    gx, gy, gz = struct.unpack_from('<hhh', r, 0)
    cube_no    = r[6] - 0x77                 # 0=미지정, 1~3
    ext,       = struct.unpack_from('<H', r, 7)
    ax, ay, az = struct.unpack_from('<hhh', r, 11)
    return {
        'gyro_dps': (gx/16.384, gy/16.384, gz/16.384),
        'accel_g':  (ax/8192, ay/8192, az/8192),   # ±4g 기준
        'cube': cube_no, 'ext': ext, 'ext1': r[9], 'ext2': r[10],
        'prox': r[17],
        'button': r[18] >> 6,
        'battery': round((r[18] & 0x3F) * 100 / 63),
    }

def on_notify(data: bytes):
    if len(data) % 20 == 0:                      # 센서 레코드
        for i in range(0, len(data), 20):
            print(parse_record(data[i:i+20]))
    else:                                        # 통보 프레임
        print('frame', hex(data[0]), data.hex(' '))

명령 (호스트 → 큐브)

통보 프레임 (큐브 → 호스트)

진단 응답 0xED · 0xF1~0xF5 · 0xF8 · 0xFB는 「진단·성능」 탭을 참조하세요.

FRAME확장 센서 종류 0xFF — 5바이트

연결 직후, 감지 상태가 바뀔 때, [0x24]·[0x25] 응답으로 옵니다. 이 프레임을 받기 전의 ext 값은 해석하지 마세요. 방수온도(14)는 주소 칸이 연결 여부(1=연결, 0=미연결)입니다.

종류 코드와 레코드 적재 규칙

1·4·6은 예약 번호입니다. 1바이트 칸은 정밀도를 줄인 값이므로 정밀값은 0xEE를 사용하세요. 심박·산소포화도는 교육용 추정값이며 의료용이 아닙니다.

CMD상세값 요청 0xEE → FRAME0xEE

요청할 때만 응답합니다. 응답은 [EE][종류][값1 u16 LE][값2 u16 LE]…이며, 값 개수는 종류가 정합니다. 상세값이 없는 센서는 [EE][종류] 2바이트만 옵니다.

CMDLED 매트릭스 그리기 0x26 — 9~10바이트

[26][행0]…[행7]([밝기 0~15]) · 행0 = 맨 위, 각 행의 bit0 = 왼쪽 칸. 매트릭스(종류 9)가 감지된 경우에만 동작합니다.

26 00 66 FF FF 7E 3C 18 00 08     // 하트, 밝기 8

한 번 그리는 데 약 2ms가 걸리므로 연속 갱신은 100ms 정도 간격을 권장합니다.

CMD인터랙션 모듈 LED 0x2C — 2바이트

[2C][마스크] · bit0 = 빨강, bit1 = 초록, bit2 = 파랑 (1 = 켜짐, 8가지 색)

2C 00   // 끄기      2C 01   // 빨강
2C 06   // 청록      2C 07   // 흰색

응답 대신 현재 켜진 색이 레코드 [8]에 실립니다. 보낸 값과 다르면 다시 보내세요(재시도 횟수 제한 권장).

스텝모터 (본체)

CMD각도 이동 0x27 — 4바이트

[27][각도 i16][속도 1~10] · 현재 위치 기준 상대 각도(부호 = 방향) · 0.18°/스텝 · 속도 1~10 ≈ 3~30 RPM. 이동 중 새 명령을 보내면 새 명령으로 바뀝니다.

27 5A 00 05      // +90°, 속도 5
27 A6 FF 0A      // −90°, 속도 10

CMD연속 회전 / 정지 0x28

[28][속도 i8] = 회전(부호 = 방향, 0 = 정지) · [28] = 정지. 정지하면 코일 전류가 꺼집니다(유지 토크 없음). 연결이 끊기면 자동 정지합니다.

FRAME스텝모터 상태 0xEF — 4바이트

[EF][상태][남은 각도 i16] · 상태 0 = 멈춤, 1 = 각도 이동 중, 2 = 연속 회전 중. 상태가 바뀔 때만 옵니다.

CMD연결 순번 0x10 — 2바이트

[10][n] · n = 1(빨강), 2(초록), 3(파랑). 연결 LED 색과 레코드 [6](= 0x77 + n)에 반영됩니다. 연결이 끊기면 초기화됩니다.

FRAME주기 통보 0xF7 — 3바이트

[F7][주기 ms][사유] · 사유 0 = 구독 시작, 1 = 명령 적용, 2 = 자동 감속, 3 = 자동 회복. 주기가 바뀌면 반드시 통보됩니다.

CMD그룹번호 0x23 → FRAME0xFE

[23][XX] = 지정 · [23] = 조회. 기기 이름 SCUBE.XX.AIR의 XX이며, 저장 후 다음 부팅부터 적용됩니다.

• XX는 16진 2자리이며 자리마다 0~9입니다. 그룹 “23” → 23 23 전송.
• 0x0A처럼 A~F가 들어간 값은 거부됩니다.

응답 [FE][저장값][광고 중 값][상태] · 상태 0 = 조회, 1 = 저장 완료, 2 = 같은 값, 3 = 범위 밖, 4 = 쓰기 실패. 두 값이 다르면 재부팅이 필요합니다.

→ 23 23
← FE 23 00 01      // 23 저장, 현재 00으로 광고 중 → 재부팅 후 SCUBE.23.AIR

FRAME펌웨어 정보 0xEC — 18바이트

CMD단발 녹음 0x20

[20][AIN 채널 0~3]([flags]) · 1.28초(10240샘플) 녹음 후 요약 0xFA 1개와 데이터 0xF9가 이어집니다. 소리센서는 채널 3입니다.

CMD음성 모드 0x21 · 연속 스트리밍 0x22

1. 21 01 → 음성 모드 진입 (센서 레코드 전송 정지) · 0xFC [FC][1][사유]
2. 22 03 → 채널 3 연속 스트리밍 시작 · 0xFD 시작 통보 후 0xF9 연속
3. 22 → 정지 (남은 데이터 모두 전송 후 0xFD 종료 통보)
4. 21 00 → 센서 모드 복귀

스트리밍 중 큐브 버튼을 짧게 누르면 정지합니다. 연결이 끊기면 센서 모드로 돌아갑니다.

진단 명령 (개발·점검용)

진단 명령 중 일부는 실행 중 센서 레코드를 잠시 멈춥니다.

전송 성능 (Windows PC 실측)

• 먼저 연결한 큐브가 대역을 적게 받는 경향이 있습니다. 동시에 여러 대를 쓰면 주기를 낮추세요.
• 전송 큐가 차면 오래된 센서 레코드를 버립니다(최신 우선). 통보·소리 프레임은 버리지 않습니다.
• 유실은 [0x13] 통계로 확인합니다. 레코드에는 순번 필드가 없습니다.