Skip to content

Architecture

Jump to bottom
Alex Tants edited this page Aug 2, 2026 · 1 revision

Architecture

End-to-end flow

main.canvas.js
      │
      ▼
Node VM + CanvasRenderer
      │ RGBA → RGB565 → dirty rectangles
      ▼
TCP display server :8765
      │ one encoded frame
      ▼
ESP32 firmware → SPI display
      │
      └── ACK → server renders the next frame

The same encoded bytes ──► Device Studio preview :8766

Application runtime

AppLibrary discovers apps/<app-id>/main.canvas.js, parses its TinyPanel JSDoc configuration, validates the source, persists the active app, and tracks source revisions.

LiveCanvasProgram compiles an app into an isolated Node vm context. The context exposes selected globals such as Math, Date, fetch, URL tools, console forwarding, the Canvas context, and immutable frame state. A render timeout prevents one synchronous app frame from blocking indefinitely.

Runtime errors restore the last successful image and appear in Studio instead of replacing the display with a partial frame.

Rendering pipeline

The preferred renderer uses node-canvas:

  1. The app draws through browser-like Canvas 2D methods or TinyPanel helpers.
  2. RGBA pixels are quantized to RGB565.
  3. The current RGB565 framebuffer is compared with the previous frame.
  4. Changed areas are encoded as bounded horizontal dirty rectangles.
  5. Static pixels are not retransmitted.

TinyPanel helpers include clear, drawLine, fillRect, fillCircle, fillTriangle, and compact bitmap drawText. Browser Canvas paths, gradients, transforms, compositing, and image APIs rasterize through the same framebuffer.

Transport and flow control

The data plane is one persistent TCP connection initiated by the ESP32. Commands use fixed binary opcodes and big-endian values. Each logical frame ends with FRAME_END; the server waits for one ACK byte before rendering and sending the next frame.

This lockstep design guarantees at most one frame in flight. If rendering, network transfer, or SPI drawing takes longer than the target frame interval, actual FPS falls naturally instead of accumulating stale frames.

See the full Display Protocol.

Device Studio

The debug/management server exposes local HTTP APIs and SSE streams. Studio contains:

  • device and application lists;
  • App Editor and Hardware Setup modes;
  • transport preview with coordinate rulers;
  • editor diagnostics and application console output;
  • serial and firmware logs;
  • firmware build and flash controls.

The preview subscribes to the actual frame bus. A late viewer receives one bounded current-frame snapshot followed by live diffs; no frame history is retained.

Firmware

Firmware connects to Wi-Fi and the server, incrementally parses commands, dispatches drawing operations to the configured display library, writes bulk RGB565 or decoded JPEG data, and ACKs frame completion. Hardware SPI is the recommended path for display throughput.

Video path

Video mode runs ffmpeg, reads an MJPEG stream, extracts complete JPEG images, and wraps each image in the bounded JPEG_FRAME protocol command. The ESP32 decodes JPEG blocks directly to the panel without allocating a full RGB frame.

TinyPanel Studio

Clone this wiki locally