Skip to content

Getting Started

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

Getting started

Requirements

  • Node.js 20 or newer
  • npm
  • PlatformIO for firmware build and flash
  • A supported ESP32 and SPI display
  • ffmpeg only when using video mode

Install and run

git clone git@github.com:Sany18/TinyPanel-Studio.git
cd TinyPanel-Studio
npm ci
npm start

npm start builds the local CodeMirror browser bundle, starts the display server on TCP 8765, and starts Device Studio on HTTP 8766.

Open:

http://localhost:8766

If startup reports EADDRINUSE, another TinyPanel process already owns the port. Stop that process before starting a second server.

Configure hardware

  1. Open Hardware Setup in Studio.
  2. Select the controller, display, and SPI bus.
  3. Set display dimensions, rotation, color order, SPI frequency, and pins.
  4. Enter Wi-Fi credentials.
  5. Save the profile.

Studio stores the validated profile in firmware/display-client/hardware.json and generates firmware/display-client/hardware_config.h. Wi-Fi credentials are written to the gitignored secrets.h.

Build and flash

Use the Firmware tab in Studio and select Build or Flash ESP32. Serial Monitor is stopped automatically before flashing so both operations do not compete for the USB port.

The equivalent command-line workflow is:

cd firmware/display-client
pio run -e esp32-c3-super-mini -t upload

The exact PlatformIO environment follows the selected hardware profile.

Connect the display

The ESP32 connects outward to the host display server. The firmware must know the host LAN address and TCP port, and both devices must be reachable on the same network. When connected, Studio lists the device by address and begins showing the exact transported frame.

Select an application

Choose an app in the left-side App Library. The active app is persisted in the gitignored apps/.active-app file and switches without restarting the server or reconnecting the ESP32.

Other runtime modes

npm run start:canvas
npm run start:synthwave
npm run start:html
npm run start:video

Canvas is the normal Studio mode. Synthwave and HTML are compatibility/legacy paths. Video mode accepts DISPLAY_VIDEO_SOURCE; without it, ffmpeg generates a test pattern.

TinyPanel Studio

Clone this wiki locally