Guide

Flashing a board

Install Pitrig on a new board from the browser, or from a downloaded archive with esptool.

A Pitrig build carries one board identity. Flash the image that matches the hardware in front of you: an image built for another board is rejected on boards with a different chip, and boots with the wrong display on the two that share one.

What you need

  • A supported board: LilyGO T-Display-S3, Guition ESP32-4848S040, Guition JC1060P470C or an ESP32-S3-DevKitC-1.
  • A USB data cable. A charge-only cable powers the board but shows no serial port.
  • A Chromium browser for the web flasher: Chrome, Edge, Brave or Opera on a desktop computer.

From the browser

  1. 1Close anything else that holds the serial port — the configurator, SimHub, a serial monitor.
  2. 2Connect the board over USB. On a board with two USB sockets, use the one wired to the serial bridge.
  3. 3Open the web flasher and select your board.
  4. 4Press install, choose the port in the browser dialog, and confirm the erase when asked.
  5. 5Wait for the progress bar to finish and the board to restart into an empty dashboard.

If the port never appears, hold the BOOT button while plugging the board in. That starts the ROM download mode, and the installer can talk to a board whose firmware is not running.

From the command line

The download page publishes a full flash archive for every board. It holds the bootloader, the partition table, the OTA data and the application, plus the flasher arguments that name their offsets.

Unpack the archive and write it with esptool
tar xzf firmware-t-display-s3.tar.gz
cd firmware-t-display-s3

esptool --chip esp32s3 --port /dev/tty.usbmodem1101 --baud 921600 \
  write-flash --flash-mode dio --flash-size 16MB --flash-freq 80m \
  0x0 bootloader.bin \
  0x8000 partition-table.bin \
  0xd000 ota_data_initial.bin \
  0x10000 pitrig-t-display-s3.bin

Updating a board that already runs Pitrig

Do not reflash over a cable to update. The configurator uploads the update image over the same serial link, the new image takes over at the next restart, and the configuration, fonts and images stay on the board. A cable flash is for a first install or a rescue.