Skip to content

Debugging and Troubleshooting

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

Debugging and troubleshooting

Studio diagnostics

The bottom dock separates four concerns:

  • Debug — validation and runtime problems
  • App logs — application console output
  • Serial monitor — opt-in USB serial output
  • Firmware — PlatformIO build and flash output

Transport statistics show receive bandwidth, bit rate, and observed FPS. They are diagnostics, not app settings; target FPS belongs in the app JSDoc config.

Exact preview

Studio preview replays the same bytes sent to the connected ESP32. If both the preview and panel pause, the ACK-controlled frame loop paused upstream. If the preview is correct but the physical panel is corrupted, investigate firmware, SPI frequency, wiring, display driver/profile, and power.

The preview-only IDE view is available at:

http://localhost:8766/preview

Enable server performance logs

DISPLAY_SERVER_PERF_LOG=1 npm start

Periodic output includes server FPS, frame bytes, build time, ACK latency, heap use, and event-loop delay. Increasing ACK latency points toward network, firmware, or SPI display time. Increasing build/event-loop time points toward application or server rendering work.

Common startup errors

EADDRINUSE on 8765 or 8766

Another Studio instance owns the port. Stop it, or select another port with DISPLAY_SERVER_PORT / DISPLAY_SERVER_DEBUG_PORT.

ESP32 does not appear

  • Confirm the server LAN address in firmware.
  • Confirm the ESP32 and host can reach each other.
  • Check Wi-Fi credentials and serial boot logs.
  • Verify TCP port 8765 is not blocked.

Flash port missing or busy

  • Reconnect the controller and verify its current serial device name.
  • Stop Serial Monitor before upload.
  • Ensure no other PlatformIO/Arduino process owns the port.

Studio stops its own Serial Monitor automatically before flashing.

Rendering problems

Runtime error in an app

Studio shows the source location and stack trace. The renderer restores the last valid framebuffer. Correct the code and save again.

Lower FPS than configured

@fps is a maximum target. Actual FPS is limited by render time, changed frame size, TCP throughput, ACK latency, SPI speed, and display write time. Reduce full-screen updates or lower target FPS to a sustainable value.

Layer mixing, tearing, or shifted pixels

  • Confirm the server and firmware use the same protocol revision.
  • Verify display dimensions, rotation, color order, and driver.
  • Prefer hardware SPI and test a lower SPI frequency if wiring is marginal.
  • Check power integrity and wire length.
  • Reflash after changing Hardware Setup.

Canvas animation uses raster dirty rectangles after the initial frame so intermediate vector layers are not exposed one command at a time.

Performance worsens over time

  • Avoid creating gradients or large reusable Canvas resources every frame.
  • Keep arrays, logs, and application globals bounded.
  • Enable performance logs and compare heap, RSS, build time, and ACK latency.
  • Test Blank Canvas to separate renderer/transport cost from app behavior.

Video troubleshooting

Video mode requires ffmpeg. Set DISPLAY_VIDEO_SOURCE to a file, camera, or network input that ffmpeg understands. JPEG payloads are limited by the protocol and must fit within the firmware receive buffer.

TinyPanel Studio

Clone this wiki locally