Protocol Structure

Protocol structure

Root object

Field	Type	Required	Meaning
version	string	Yes	Exactly "2.0"
commands	array	Yes	Ordered command objects

{
  "version": "2.0",
  "commands": []
}

An empty array is a valid document shape. On the physical device, an empty command list causes the refresh to be skipped and the existing display to be kept. To blank the screen, send clear explicitly.

Command object

Field	Type	Required	Meaning
cmd	string	Yes	Registered command identifier
args	object	Yes	Arguments described on the command page

{
  "cmd": "clear",
  "args": {
    "color": "white"
  }
}

Command examples on individual reference pages are objects to insert into commands; they are not complete endpoint responses. Send integers as JSON numbers, flags as booleans, and names/text as strings. Rich text uses a nested spans array.

Limits and failures

• The firmware request reader limits the response body to 128 KiB. PHP and Java JSON serialization helpers also enforce a 128 KiB document limit.
• Return valid UTF-8 JSON with the exact string version "2.0".
• Unsupported versions are rejected. Unknown commands are skipped or logged.
• Invalid arguments can skip a command; a parse/type error in the emulator can reject the whole document. Validation is not identical between targets.
• Use well-formed, bounded arguments; the parser is not a substitute for server-side validation.

See Command Reference, Draw Text, and Renderer Notes.

Implementation references

• Arduino/src/network/request.cpp
• Emulator/src/network/request.cpp
• Server/PHP/lib/Display.php
• Server/Java/src/main/java/solutions/trp/jsonpaper/Display.java