본문으로 건너뛰기

데이터 형식과 JS·Arduino 호환성

JS와 Arduino의 지원 범위​

데이터 없음(EMPTY), 문자열(TEXT), 바이너리(BINARY)는 JS와 Arduino가 함께 사용하는 기본 유형입니다. JS(Node.js와 browser)는 객체 하나나 여러 인자를 보내는 기능도 제공합니다.

JS의 signal(tag, ...args)는 인자 개수와 자료형으로 payload 유형을 자동 선택하고, 수신 측은 (tag, ...args)로 복원해 전달합니다. 유형 번호를 지정하거나 바이트를 직접 파싱할 필요가 없습니다.

유형보내는 데이터JS 지원Arduino 지원
0 EMPTY (데이터 없음)인자 없음송신·수신 (payload 인자 생략)송신·수신 (길이 0)
1 TEXT문자열 하나송신·수신송신·수신
2 BINARY바이너리 하나송신·수신송신·수신
3 OBJECT객체 또는 배열 하나자동 선택·복원기본 송신·자동 복원 없음
4 MJSON바이너리 없는 여러 인자자동 선택·각 인자로 복원문자열 2개 송신만 제공
5 MBA바이너리를 포함한 여러 인자자동 선택·각 인자로 복원기본 송신·자동 복원 없음

Arduino도 OBJECT/MJSON/MBA 메시지를 받을 수 있지만, 콜백에는 유형값·원시 바이트·길이가 전달됩니다. 자동 복원하지 않으므로 앱에서 JSON/MBP 파싱을 구현해야 합니다.

JS 송신 인자별 유형과 수신 인자입니다.

io.signal('room'); // EMPTY → (tag)
io.signal('room', 'hello'); // TEXT → (tag, 'hello')
io.signal('room', new Uint8Array([0, 255])); // BINARY → (tag, 바이너리)
io.signal('room', { value: 42 }); // OBJECT → (tag, { value: 42 })
io.signal('room', [1, 2]); // OBJECT → (tag, [1, 2])
io.signal('room', 'value', 42); // MJSON → (tag, 'value', 42)
io.signal('room', 'data', new Uint8Array([7])); // MBA → (tag, 'data', 바이너리)

예외와 지원 범위:

  • 숫자 하나는 TEXT로 변환됩니다. signal('room', 42)의 수신값은 숫자 42가 아니라 문자열 '42'입니다.
  • EMPTY(signal(tag))는 핸들러가 (tag)로 호출되므로 args.length === 0(또는 payload === undefined)으로 확인합니다. signal(tag, null)은 OBJECT (tag, null)이라 구별됩니다. Arduino는 payloadType = EMPTY, payloadSize = 0이며 payload를 읽지 않습니다.
  • 바이너리는 원시 바이트로 전달됩니다. 원래 TypedArray 생성자나 요소의 바이트 순서까지 자동 복원하는 것은 아닙니다.
  • 단순 객체·배열과 평평한 인자 목록을 쓰고 바이너리는 독립 인자로 보내세요. 바이너리 여부는 최상위 인자만 검사하므로 { data: buffer }는 OBJECT이며 내부 버퍼가 원형대로 복원되지 않습니다. OBJECT/MJSON에는 JSON으로 표현 가능한 데이터만 씁니다.

Arduino에는 다음과 같이 문자열 두 개를 MJSON으로 보내는 오버로드가 있습니다.

io.signal("room", "left", "right"); // MJSON → JS 수신: (tag, "left", "right")

라이브러리는 두 문자열을 그대로 ["…","…"] 안에 넣고 이스케이프하지 않습니다. 따옴표("), 역슬래시, 제어문자가 들어 있으면 JSON이 깨지므로 넣지 마세요. 문자열 안의 NUL도 지원하지 않습니다. JSON 모양 문자열 하나를 보내는 signal(tag, jsonText)는 TEXT이므로 수신 측에서 따로 파싱해야 합니다.

바이너리 보내기 예​

Uint8Array를 그대로 넘기면 BINARY로 전송됩니다. 아래는 ESP32-S3 RGB 예제에 녹색을 보내는 코드입니다. 앞의 세 바이트가 R, G, B이고 마지막 바이트는 쓰지 않습니다.

import { IO } from 'iosignal';

const io = new IO('wss://io.remocon.kr/ws');
io.on('ready', () => {
io.signal('#robot', Uint8Array.of(0x00, 0xff, 0x00, 0x00));
setTimeout(() => io.destroy(), 500);
});

Arduino는 태그와 함께 payloadSize를 확인하고 바이트를 그대로 읽습니다. CLI의 sig_bin은 0으로 채운 데이터만 보냅니다.

버전 차이​

이전 버전에서 올릴 때의 동작 변화는 버전과 검증 기준에 모았습니다. Arduino는 별도 버전의 라이브러리를 사용합니다.