Skip to content

Hardware and Firmware

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

Hardware and firmware

Hardware Setup mode

Studio can configure:

  • controller;
  • display driver;
  • hardware or software SPI;
  • logical width and height;
  • rotation and RGB/BGR color order;
  • SPI frequency;
  • CS, DC, reset, MOSI, SCLK, MISO, and backlight pins;
  • Wi-Fi SSID and password.

Profiles are validated before being saved. Required display pins must be present and unique, dimensions must be 16–320 pixels, and SPI frequency must be between 1 and 80 MHz.

Available profiles

Controllers exposed by Studio:

  • ESP32-C3 Super Mini
  • ESP32-S3 DevKitC-1
  • ESP32 DevKit V1

Display profiles:

  • ST7735/ST7735S, default 160×128
  • ST7789, default 240×240
  • ILI9341, default 320×240

Bus profiles:

  • Hardware SPI — recommended
  • Software SPI — useful for flexibility but slower and CPU-bound

The fully validated reference combination is ESP32-C3 Super Mini with a 160×128 ST7735S display.

Generated files

Hardware Setup writes:

firmware/display-client/hardware.json
firmware/display-client/hardware_config.h
firmware/display-client/secrets.h

hardware_config.h contains generated compile-time macros. secrets.h contains Wi-Fi credentials and is excluded from Git. The Studio API never returns the saved password.

Reference ESP32-C3 wiring

ESP32-C3 Super Mini Display
5V VCC
GND GND
GPIO0 CS
GPIO4 RESET
GPIO3 DC/A0
GPIO2 MOSI/SDA
GPIO1 SCLK
3V3 LED/backlight

Always verify the labels and voltage requirements of the exact display board.

Firmware build and flash

Studio invokes PlatformIO using the environment associated with the selected controller. Successful builds are versioned from version.json, and firmware binaries are archived in the gitignored firmware build directory.

From the command line:

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

If upload reports that a serial port is missing or busy, reconnect the board, verify its current /dev/cu.* path, close Serial Monitor, and retry.

Firmware lifecycle

On boot the client connects to Wi-Fi, then opens a TCP connection to the host. Connection loss triggers throttled retries. Commands may be fragmented across TCP packets, so firmware accumulates and dispatches only complete protocol messages. It resets parser state after reconnect.

The client draws commands, processes FRAME_END, and returns an ACK. This ACK is what advances the server frame loop.

TinyPanel Studio

Clone this wiki locally