Protocol Overview

Protocol overview

A server returns a JSON document containing an ordered list of commands. The device fetches it over HTTP or HTTPS, builds drawing commands, renders a framebuffer, and refreshes the display. The desktop emulator fetches the same format.

Commands run in order. Later drawing can overwrite earlier pixels. There are no retained objects, layers, or animation commands. Rotation and mirroring alter subsequent drawing state.

The normal display is 792 pixels wide and 272 pixels high. Coordinates are integers measured from the top-left, with X increasing right and Y increasing down. See Renderer Notes for command-specific offsets and bounds behavior.

The drawing colors are black, white, yellow, and red. Transparency is supported for text backgrounds and packed image pixels, not as a general primitive color.

{
  "version": "2.0",
  "commands": [
    {
      "cmd": "clear",
      "args": {
        "color": "white"
      }
    },
    {
      "cmd": "draw_text",
      "args": {
        "x": 20,
        "y": 20,
        "width": 740,
        "height": 70,
        "spans": [
          {
            "text": "Hello, JSON Paper!",
            "family": "helvetica",
            "weight": "regular",
            "size": 32,
            "color": "black"
          }
        ]
      }
    }
  ]
}

Serve the JSON body directly with Content-Type: application/json. Use a reachable endpoint returning HTTP 200; an HTML page linking to JSON is not a drawing document.

See Protocol Structure, Command Reference, Examples, and Versioning.

Implementation references

• Arduino/src/network/request.cpp
• Emulator/src/network/request.cpp