Skip to main content

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.

TypeInputJavaScriptArduino
0 EMPTYNo payload argumentsSend/receive; handler receives only tagSend/receive; length zero
1 TEXTOne stringSend/receiveSend/receive
2 BINARYOne binary valueSend/receiveSend/receive
3 OBJECTOne object or arrayAutomatic selection/restorationNo default high-level send/restoration
4 MJSONMultiple arguments without binaryRestores separate argumentsProvides a two-string send overload
5 MBAMultiple arguments including binaryRestores separate argumentsNo 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 tag only. A declared second parameter is therefore undefined; 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 current Arduino implementation escapes quotes, backslashes, and control characters and sizes the buffer after escaping. C-string NUL still terminates input; embedded NUL is unsupported. A single JSON-looking string remains TEXT and needs application parsing.

JS 7.2.0 distinguishes EMPTY from explicit null. Older development behavior passed null for EMPTY. See versions and verification before migrating.