Protocol

패킷 구조

모든 명령은 공통 헤더로 시작합니다. 명령 종류에 따라 Generic 헤더(스텝모터·집계 계열, 13바이트 헤더)와 Task 헤더(LED·서보·음악·조회 계열)로 나뉩니다. 두 헤더 모두 [0:8] 구조는 동일합니다.

FF FF 00 00 00 00 CE 00 0E 01 FF 00 00 50   // 14 bytes

OPCODE 전체 목록

G큐브 펌웨어에서 실제 처리되는 명령을 정리한 표입니다. 활성은 현재 펌웨어에서 정상 처리되는 명령입니다.

동작 명령 (Set)

조회 명령 (Get) · 응답은 RX Notify

집계기(Aggregator/멀티롤)

아두이노·확장·플래시·기타

스테퍼 모터 · 서보

G큐브의 핵심 구동부. 속도는 SPS(Steps Per Second) 또는 RPM으로 지정합니다. 속도 부호가 방향입니다.

SET SetSingleSteps 0xC1 — 19바이트

지정한 스텝수만큼 1회 이동 후 정지.

// 예시) 0번 큐브를 속도 50(정회전)으로 100스텝(약 18°) 이동
//        SPS = 50×9 + 100 = 550 = 0x0226,  스텝 100 = 0x0064
FF FF FF 00 10 00 C1 00 13 02 01 00 01 02 26 00 00 00 64

SET SetContinuousSteps 0xCC — 15바이트

속도 기반 연속 회전. 속도 0이면 정지(PauseState=Pause), 그 외에는 Resume.

// 예시) 0번 큐브 속도 50으로 계속 회전  →  SPS = (1100×50 − 10000)/50 = 900 = 0x0384
FF FF FF 00 10 00 CC 00 0F 02 00 00 02 03 84
// 정지 (속도 0, PauseState=Pause)
FF FF FF 00 10 00 CC 00 0F 02 00 00 01 00 00

SET SetScheduledSteps 0xCA — (15 + 값)바이트, CRC16

여러 (속도,스텝) 데이터셋을 미리 전송해두고 재생. Generic 헤더의 Mode=2, Method=3(ScheduledSteps), StepType=0(Full) 또는 4(SetServo).

SET SetScheduledPoints 0xCB — (15 + 값)바이트

이미 전송된 스케줄 데이터셋에서 특정 포인트 구간을 반복 재생. 값: StartPoint[17:18]:StopPoint[19:20]:Repeats[21] 반복.

SET SetAggregateSteps 0xCD

여러 큐브의 SingleSteps/ContinuousSteps/Scheduled 데이터를 하나로 묶어 집계기(Star, ID=AA)에 전송. 헤더 크기 = 13 + Σ(각 큐브 패킷), Assigned ID 상위 = 큐브수<<4, Method는 묶는 명령 종류(0/1/2/3/4).

FF FF FF AA [N<<4] [00] CD [size_hi] [size_lo] 02 [method] 00 00
  { 큐브0 패킷 } { 큐브1 패킷 } ...

20바이트를 넘는 명령 (패킷 조각)

BLE 1패킷은 20바이트(MTU 23 − 3)이므로 0xCA·0xCB·0xCD 처럼 긴 명령은 여러 조각으로 나뉘어 전달됩니다. 예를 들어 35바이트 SetScheduledPoints는 20 + 15 두 조각입니다. 호스트는 조각을 나누어 보내기만 하면 되고, 재조립은 펌웨어가 합니다 — 조각 사이에 지연을 넣거나 응답을 기다릴 필요는 없습니다.

SET SetPauseSteps 0xC0 — 12바이트

[9] PauseState: 1=Pause, 2=Resume, 3=Radio. [10:11] SyncClock(StartTime). Radio 설정 시 집계기 ID 0xFFFFFFAA 사용.

SET SetInstantTorque 0xC6 — 10바이트

[9]: 0=기본(최소) 토크, 1=최대 토크.

서보 (Servo)

SET SetSingleServo 0xE1 — 13바이트

확장 서보 모터의 각도를 설정합니다.

// 예시) 0번 큐브의 서보를 90°로 (타임아웃 0 = 각도만 지정)  →  90 = 0x5A
FF FF FF 00 00 00 E1 00 0D 01 00 5A 00

LED · 디스플레이 · 음악

SET SetColorLED 0xCE — 14바이트

큐브 내장 RGB LED. 색공간 3종 지원.

// 2번 큐브 초록, 밝기 100 (RGB)
FF FF 00 01 00 00 CE 00 0E 01 00 FF 00 64

SET SetDigitalPort 0xCF — 10바이트

확장포트 Dout 핀 HIGH/LOW. [9]: 0=LOW, 1=HIGH.

FF FF FF [cube] 00 00 CF 00 0A [onoff]

SET SetWs2812bLED 0xC7 — 13바이트

외장 네오픽셀(WS2812) 제어. [9]=LED 번호(1,2,3…), [10:12]=R,G,B.

// 예시) 0번 큐브의 1번 네오픽셀을 파랑(R=0,G=0,B=255)으로
FF FF FF 00 00 00 C7 00 0D 01 00 00 FF

SET LED 매트릭스 (I2C, 0xA2 주소 0x70)

HT16K33 기반 8×8 LED 매트릭스. Task ID로 동작을 구분합니다.

공통: [9]=I2C 주소 0x70. 스크래치 클라이언트는 픽셀 명령을 FF FF FF [cube] 00 [task] A2 00 0D 70 [y] [x] [plot] 형태로 전송합니다.

// 예시) 0번 큐브 매트릭스에서 (x=3, y=4) 픽셀 켜기  (Task 00E1)
FF FF FF 00 00 E1 A2 00 0D 70 04 03 01

음악 · 버저 (Music)

SET SetMusicNotes 0xE8 (Task 00A1) — (11 + 음표)바이트

단일 큐브 음표 재생. 음표 하나당 3바이트: PianoKey : Duration : Rest.

// 예시) 0번 큐브에서 도(C5) 재생  →  키 0x34, 길이 0x32(=50→1초), 쉼표 0
FF FF FF 00 00 A1 E8 00 0E 00 00 34 32 00

피아노 키 · 음계표 (발췌)

평균율 배율 1.05946. 스크래치 클라이언트는 PianoKey = 음번호 − 8 보정 후 전송합니다.

SET SetAggregateMusicNotes 0xE8 (Task 00A2)

여러 큐브 화음. 집계기 ID AA, Assigned ID 상위 = 큐브수<<4. 각 큐브의 음표 패킷을 이어붙입니다.

SET GenerateBuzzerTone 0xEF — 13바이트

// 예시) 0번 큐브 버저로 WholeNote C4(index 2)를 세기 5, 길이 10으로
FF FF FF 00 00 00 EF 00 0D 0C 02 05 0A

큐브 연결 · 센서 읽기

멀티롤 · 집계 (여러 큐브 연결)

여러 큐브를 하나의 Star(집계기)에 연결해 로봇을 구성하는 방식입니다. Star의 큐브 ID는 0xAA, 브로드캐스트는 0xFF입니다.

SET SetMultiroleInAction 0xAD — 11바이트

멀티롤 연결/모드를 시작합니다. 스크래치 클라이언트가 다중 큐브 연결 시 사용.

FF FF FF AA [N<<4] 00 AD 00 0B 0A 00        // 기본
FF FF FF AA [N<<4] 00 AD 00 0B 1A [groupId]  // 그룹ID 사용 시

SET SetMultiroleAggregator 0xAA

집계기에 연결할 큐브 수(ConnectionLinkCount, 최대 7 또는 0=전체)와 자동 가상색을 설정. [9]=큐브수, [10]=가상색 자동(0A/1A/00), 이후 각 큐브 ID.

RX 연결 상태 알림

가상색 인덱스

연결 순서를 색으로 표현: 0=RED, 1=GREEN, 2=BLUE, 3=CYAN, 4=MAGENTA, 5=YELLOW, 6=SPRINGGREEN/VIOLET, 7=ORANGERED, E=WHITE(미정), F=BLACK(끊김).

SET RebootMultiroleAggregator 0xA8 — 10바이트

FF FF FF FF 00 00 A8 00 0A 01

연결 해제 시 클라이언트는 이 리부트 명령을 보낸 뒤 소켓을 닫습니다.

그룹번호 (Discovery Group ID)

여러 대의 G큐브가 같은 공간에 있을 때 서로 다른 로봇끼리 섞여 연결되는 것을 막는 식별자입니다. 집계기는 자신과 같은 그룹번호를 가진 큐브만 멤버로 받아들입니다. 값은 플래시에 저장되어 전원을 꺼도 유지됩니다.

범위와 표기

그룹번호는 0x00 ~ 0x99 범위의 16진수 1바이트입니다. 상위 4비트가 앞자리, 하위 4비트가 뒷자리이며, 각 자리는 0~9만 사용하고 A~F는 쓰지 않습니다.

groupId = (앞자리 << 4) | 뒷자리        // 각 자리 0~9

  0x00   0x07   0x12   0x25   0x42   0x99

16진수로 읽은 두 글자가 곧 사용자가 보는 그룹번호입니다 — 0x12는 "일이", 0x25는 "이오"로 읽습니다. 십진수를 그대로 넣으면 안 됩니다. 예를 들어 그룹번호 12를 십진수 12(0x0C)로 보내면 앞자리 0, 뒷자리 0xC가 되어 뒷자리 색이 팔레트의 예약(소등) 영역으로 빠집니다.

0x00은 "미사용"을 뜻해, 이 경우 큐브는 그룹 제한 없이 동작하고 컬러 LED도 무지개(Hue) 표시로 돌아갑니다.

큐브가 그룹번호를 알려주는 방법

그룹번호가 설정되면 큐브는 소리와 색 두 가지로 자기 번호를 표현합니다. 두 방식 모두 자릿수를 앞자리 → 뒷자리 순으로 나타냅니다.

① 음계 — 자리 숫자마다 음 하나

숫자를 도레미에 그대로 대응시켰습니다. 0이 도(C4)이고 숫자가 하나 커질 때마다 음이 하나씩 올라갑니다. 앞자리를 0.2초 짧게, 뒷자리를 0.6초 길게 울려 둘을 구분합니다.

내부 인덱스 = 숫자 + 2 입니다. WholeNote 0·1은 A3(라)·B3(시)라서 도(C4)가 인덱스 2부터 시작합니다.

② 색 — 자리 숫자마다 색 하나

컬러 LED가 0.5초 간격 5단계를 반복하며 두 자리를 보여 줍니다. 뒷자리를 두 틱(1.0초) 켜서 앞자리와 구분합니다.

[앞자리 색] → [소등] → [뒷자리 색] → [뒷자리 색] → [소등]  (총 2.5초 주기)

표시가 나오는 시점

전원을 켤 때, 그룹번호를 새로 설정할 때, 그리고 연결이 끊어져 대기 상태로 돌아갈 때 소리가 납니다. 색 표시는 그룹번호가 설정되어 있는 동안 계속 반복됩니다(SET_DISCOVERYID 모드). 확장포트에 I2C 장치가 꽂혀 있으면 컬러 LED 자동표시가 멈추므로 그룹번호 색도 보이지 않습니다.

BLE 기기 이름

큐브는 광고 이름 뒤에 그룹번호를 16진수 두 자리로 붙입니다 — 0x25 → PINGPONG.25. 펌웨어가 %01X%01X 로 찍기 때문에 저장된 바이트를 16진수로 읽은 값이 그대로 이름이 됩니다. 앱이 스캔 목록에서 그룹을 구분하는 데 쓸 수 있습니다. 0x00이면 PINGPONG.00이 됩니다.

SET SetGroupID 0xFA (FlashDiscoveryFinishGroupId) — 11바이트

FF FF FF FF 00 00 FA 00 0B FE [groupId]

// 예) 그룹번호 0x25 로 설정
FF FF FF FF 00 00 FA 00 0B FE 25

const SERVICE = "6e400001-b5a3-f393-e0a9-e50e24dcca9e";
const TX = "6e400002-b5a3-f393-e0a9-e50e24dcca9e";
const RX = "6e400003-b5a3-f393-e0a9-e50e24dcca9e";
const CUBE_COUNT = 2;               // Star(0) + 멤버(1)
let txChar;

const cmd = {
  // 멀티롤 시작: N개 큐브 연결 (Star 포함).  [4] = N<<4
  multiroleStart: (n) => new Uint8Array([0xFF,0xFF,0xFF,0xAA, n<<4, 0x00, 0xAD, 0x00,0x0B, 0x0A, 0x00]),
  // 컬러 LED (cube=0 Star, 1 멤버)
  colorLED: (cube,r,g,b,br=80) => new Uint8Array([0xFF,0xFF,0x00,cube,0x00,0x00,0xCE,0x00,0x0E,0x01,r,g,b,br]),
  // 전체 큐브 센서 구독 (pos=0xFF)
  getSensors: (pos=0xFF,intv=10) => new Uint8Array([0xFF,0xFF,0xFF,pos,0x00,0xC8,0xB8,0x00,0x0B,intv,0x01]),
};

const send = (b) => txChar.writeValueWithoutResponse(b);

async function connectTwoCubes() {
  // ① Star 한 대에만 BLE 연결
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ namePrefix: "PINGPONG." }], optionalServices: [SERVICE]
  });
  const server = await device.gatt.connect();
  const svc = await server.getPrimaryService(SERVICE);
  txChar = await svc.getCharacteristic(TX);
  const rx = await svc.getCharacteristic(RX);
  await rx.startNotifications();

  // ④ 연결 상태 알림 수신
  rx.addEventListener('characteristicvaluechanged', e => {
    const v = new Uint8Array(e.target.value.buffer);
    if (v[6] === 0xAD) console.log(`연결 진행 중 · 인덱스 ${v[9]}`);
    if (v[6] === 0xAE && v[9] === CUBE_COUNT - 1) {
      console.log("2개 큐브 연결 완료!");
      onAllConnected();
    }
  });

  // ② 500ms 후 멀티롤 시작 → Star가 멤버를 탐색
  setTimeout(() => send(cmd.multiroleStart(CUBE_COUNT)), 500);
  // ③ 이제 멤버 큐브의 전원 버튼을 짧게 눌러 주세요.
}

async function onAllConnected() {
  // ⑤ 개별 제어: 0번(Star) 빨강, 1번(멤버) 초록
  await send(cmd.colorLED(0, 255, 0, 0));
  await send(cmd.colorLED(1, 0, 255, 0));
  // 두 큐브 센서 구독 (연결 3초 뒤 권장)
  setTimeout(() => send(cmd.getSensors(0xFF, 10)), 3000);
}

센서 읽기

SET GetSensors 0xB8 — 11바이트 (구독 시작)

버튼·자이로·가속도(기울기)·근접·확장포트 값을 스트림으로 받습니다.

여러 큐브를 연결했을 때의 실효 출력 주기

집계기는 하위 큐브들의 센서 패킷을 모아 한 프레임으로 올려 보냅니다. 하위 큐브는 각자의 타이머로 보내고 집계기도 자기 타이머로 깨어나므로, 둘의 위상이 어긋나면 그 주기에 아직 도착하지 않은 큐브가 생깁니다. FW 1.0.4.85는 한 주기만 놓쳐도 프레임을 강제로 내보냅니다(2026-08-08, 이전 임계 3주기).

RX 센서 응답 (Method 1, 20바이트)

OpCode [6]=0xB8. 실제 클라이언트가 파싱하는 오프셋:

// 3대 연결 시 60바이트 프레임 파싱
for (let i = 0; i < frame.length / 20; i++) {
  const b = frame.subarray(i * 20, i * 20 + 20);
  const cube = b[0] & 0x0F;        // 0 = 집계기(Star)
  if (cube >= 8) continue;         // 미배정/끊김 블록은 건너뛴다
  sensors[cube] = parse(b);
}

I2C 센서별 바이트 매핑 (Method 1)

확장포트에 I2C 장치가 인식되면 [10]·[12]~[14]·[19] 가 해당 센서 값으로 대체됩니다. 장치는 부팅 시 자동 검출되며, 앱에서 0xA2 Task 0000·[9]=0x80 으로 현재 인식된 주소를 조회할 수 있습니다.

SET GetPeripherals 0xBA — 11바이트

버튼/컬러LED/근접/IMU/배터리를 개별 조회. [9]=InActionId, [10]=Property.

배터리 조회 예(스크래치 checkBattery): FF FF FF [cube] 00 00 BA 00 0B B4 01. 응답 [6]=BA, [9]=B4, [13]=배터리 %.

아두이노 · 큐브이노 · 라인봇

SET Cubino/Arduino/Microbit 0xA3

확장 보드(큐브이노 등) 제어. Task ID로 기능 구분.

응답: Mandatory 10바이트 + A5~A0 아날로그 6바이트(8bit/ch) = 16바이트.

SET 인터랙션 모듈 RGB LED 0xA3 · Task 00E3 — 11바이트

TCA9534 확장보드(I2C 0x20)의 RGB LED를 켭니다. 모듈이 인식된 상태에서만 동작합니다.

// 예시) 0번 큐브의 인터랙션 모듈을 파랑(bit2)으로
FF FF FF 00 00 E3 A3 00 0B 00 04

SET AI 카메라 제어 모드 0xAD · Task 00BC

허스키렌즈·오즈아이(I2C 0x32)가 연결된 큐브를 AI 카메라 제어 모드로 전환합니다. 부팅 시 라인(화살표)이 학습되어 있으면 자동으로 이 모드에 진입하며, 같은 그룹번호의 G큐브 2대만 연결됩니다. 0xBA GetPeripherals 응답의 종류 코드가 0xBC 로 회신되면 AI 카메라 모드입니다.

SET ArduinoI2C 0xA2

I2C 장치 질의/제어. [9]=I2C PortStatus(80=연결주소 질의, 8D=DIO 설정). LED매트릭스(주소 0x70)는 「LED·디스플레이」 탭 참조.

연결 주소 질의는 FF FF FF [cube] 00 00 A2 00 0B 80 로 보내며, 응답 [9] 에 현재 인식된 I2C 주소가 실립니다(미인식 시 0).

SET Control LineBot 0xA4 — 11바이트

라인봇(트레이서보드) 전용. Task ID로 동작, [9][10]에 파라미터.

스크래치 orderLineBot(taskID, p9, p10): FF FF FF 00 00 [taskID] A4 00 0B [p9] [p10]

큐브이노 (Cubeino) — 시리얼 프로토콜

큐브이노는 G큐브의 확장포트에 꽂히는 아두이노 호환 보드입니다. 여기서의 통신은 BLE가 아니라 G큐브 MCU와의 시리얼(UART) 연결이며, 모든 명령이 10바이트 고정 패킷으로 오갑니다.

// 검증바이트 계산 (Cubeino.cpp)
byte get_iv(byte a){ return (a/16) + (a & 0x0F)*16; }   // 니블 스왑
// 예: 0x30 → 0x03,  0xA0 → 0x0A,  0x51 → 0x15

// 전송: send_gcube()는 10바이트를 쓰고 50ms 지연
//       direct_send_gcube()는 10바이트를 쓰고 1ms 지연(라인보드 등 저지연)