Payload formats and JS–Arduino compatibility
EMPTY, TEXT, and BINARY are shared basic types. JavaScript also supports a single object/array and multiple arguments. signal(tag, ...args) automatically selects a wire type, and JS restores the received arguments.
| Type | Input | JavaScript | Arduino |
|---|---|---|---|
| 0 EMPTY | No payload arguments | Send/receive; handler receives only tag | Send/receive; length zero |
| 1 TEXT | One string | Send/receive | Send/receive |
| 2 BINARY | One binary value | Send/receive | Send/receive |
| 3 OBJECT | One object or array | Automatic selection/restoration | No default high-level send/restoration |
| 4 MJSON | Multiple arguments without binary | Restores separate arguments | Provides a two-string send overload |
| 5 MBA | Multiple arguments including binary | Restores separate arguments | No default high-level send/restoration |
Arduino can receive OBJECT/MJSON/MBA packets, but its callback gets a type, raw bytes, and length. The app must implement JSON/MBP parsing; an enum does not imply automatic object restoration.
io.signal('room'); // EMPTY: (tag)
io.signal('room', 'hello'); // TEXT: (tag, 'hello')
io.signal('room', new Uint8Array([0, 255])); // BINARY
io.signal('room', { value: 42 }); // OBJECT
io.signal('room', [1, 2]); // OBJECT
io.signal('room', 'value', 42); // MJSON: (tag, 'value', 42)
io.signal('room', 'data', new Uint8Array([7])); // MBA
Important distinctions
- One number becomes TEXT:
signal('room', 42)receives the string'42'. - EMPTY calls a JS handler with
tagonly. A declared second parameter is thereforeundefined; a rest array is empty.signal(tag, null)is OBJECT and receives(tag, null). - Binary transport preserves bytes, not the original TypedArray constructor or automatic byte-order interpretation.
- Binary detection examines top-level arguments.
{data: buffer}is OBJECT, not an automatically separated MBA payload. Use JSON-compatible values for OBJECT/MJSON and separate binary arguments. - Do not assume complex nested structures or custom types will round-trip unchanged.
Arduino two-string messages
io.signal("room", "left", "right"); // JS receives (tag, "left", "right")
The library puts the two strings into ["…","…"] as they are, without escaping. A double quote, backslash or control character breaks the JSON, so leave them out. C-string NUL still terminates input; embedded NUL is unsupported. A single JSON-looking string remains TEXT and needs application parsing.
Sending binary
Passing a Uint8Array sends BINARY. This code sends green to the ESP32-S3 RGB example. The first three bytes are R, G, and B; the last byte is unused.
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 checks payloadSize along with the tag and reads the bytes as they are. The CLI's sig_bin sends only zero-filled data.
Behavior changes from earlier releases are collected in versions and verification.