Flash TouchDeck to your Guition 3.5" deck straight from your browser.

A touch control deck for Home Assistant, live PC stats from the TouchDeck Companion and Bambu Lab printers, set up from a web portal on the device. No cloud, no accounts.

On the device

Recorded frame by frame from the display. Pick an animation set under Display > Animations.

TouchDeck Calm animations with touch ripples and expanding cards — Calm: a ripple on touch, a glow when a tile turns on, pages crossfade, cards grow out of their tile.

TouchDeck Water animations with drop rings and flooding tile colours — Water: drop rings, the on colour floods out of your finger, a water edge between pages.

TouchDeck Glass animations with glossy highlights and rising cards — Glass: a highlight under your finger, a glossy sheen, pages slide in depth, cards rise like a glass sheet.

TouchDeck Heavy animations with bending tiles and aurora colours — Heavy: the tile bends like water, aurora colours, pages change column by column.

TouchDeck idle photo frame with full screen pictures and a clock — Photo frame: when idle, the tiles step aside for full screen pictures and a clock.

TouchDeck Bambu Lab printer animations with a spool and filament change — Bambu Lab printer: heating glow, a turning spool and a filament change.

TouchDeck PC stats page with CPU and GPU charts, RAM, temperatures, power and fans — PC stats from the TouchDeck Companion: charts, temperatures, power and fans.

TouchDeck home lab page with Proxmox and pfSense readings from Home Assistant — Home lab: Proxmox and pfSense readings from Home Assistant.

Before you start

Desktop Chrome or Edge. Web Serial does not run on Firefox, Safari or mobile.
A real data USB-C cable. A power-only cable will not expose a serial port.
Guition JC3248W535 only. This firmware is for the ESP32-S3 N16R8 board. Find the printed case on MakerWorld.
Stuck in a connect / disconnect loop? Hold BOOT, plug in USB while holding, then release. Or hold BOOT, tap RESET, then release both.
Close anything that holds the serial port. The TouchDeck Companion talks to the deck over the USB cable when plugged in. Close it, Arduino IDE, PlatformIO Monitor and the serial monitor below before flashing.
Updating a deck that already runs TouchDeck? Use the OTA file instead to keep your pages: download TouchDeck-<version>-ota.bin from Releases and upload it in the deck's portal under Maintenance > Firmware update. Back up the configuration first under Maintenance > Backup.

Flash your deck

One board, ready to go: 16 MB flash, 8 MB PSRAM and a 3.5" IPS QSPI panel with capacitive touch.

chip: ESP32-S3
board: Guition JC3248W535
display: AXS15231B 320x480 touch
firmware: ...
flash: 0x0 - full image (bootloader + partitions + app)

Loading firmware version...

SHA-256 checksums

A dialog will ask which serial port to use. Pick the one that appears when you plug in the deck. Choosing Erase device on a fresh install wipes everything stored on the deck. The full image is flashed at 0x0 and takes about a minute (around 2.7 MB).

Connect to WiFi

Right after flashing, send your WiFi credentials over USB in this tab. If you miss that window, join the deck's setup hotspot from your phone or laptop.

recommended

Configure WiFi in this tab

The installer offers Configure WiFi using Improv Serial on a freshly flashed deck with no WiFi stored, for about 3 minutes.

Wait for Installation complete and keep the install dialog open.
Pick your WiFi network, enter its password and click Connect.
The deck reboots onto your WiFi and shows its IP address. Note it down for the next steps.

fallback

Or join the setup hotspot

Scan the QR code shown on the screen or join the hotspot by hand.

setup-mode access point

networkTouchDeck-XXXX

passwordtouchdeck1234

portalhttp://192.168.4.1

The XXXX suffix is unique to your deck. The hotspot closes once the deck joins your WiFi.

Join TouchDeck-XXXX using the password touchdeck1234.
The setup page opens at http://192.168.4.1. Open it by hand if it does not appear.
Choose your WiFi network, enter its password and save.
The deck reboots onto your WiFi and shows its IP address.

Afterwards the portal is at the device IP or http://touchdeck.local.

Connect Home Assistant

In the portal, open Pages & tiles. Enter your Home Assistant address (for example http://192.168.0.7:8123) and a long-lived access token from your HA profile's Security tab. The token stays on the device.
Install the icon font from the portal: Material Design Icons, the set Home Assistant uses.
Click Update from HA to cache the entity list. Add tiles from the entity picker, then place them in the grid editor. Arrange landscape and portrait separately.
Optionally, open Advanced for Bambu Lab printers (LAN or through the Home Assistant Bambu Lab integration) and MQTT discovery.

See the Home Assistant setup guide for more details.

Connect your PC TouchDeck Companion

The companion sends live PC metrics to your deck and lets you pair it for media keys, volume, lock and sleep.

Install LibreHardwareMonitor, run it as Administrator, then enable Options > Remote Web Server > Run (port 8085).
Download TouchDeckCompanion-<version>.exe from Releases and run it. Its control panel opens at http://127.0.0.1:8750.
Point it at the deck's IP, pick sensors and click Start. In the deck portal add tiles with + Add PC metric.
For PC control, on the companion's Device page click Pair for control, then tap Allow on the deck.

from source

Run these commands from TouchDeck-CompanionApp/:

powershell

> pip install -r win-companion/requirements.txt
> python win-companion/touchdeck_companion.py

Run these commands from TouchDeck-CompanionApp/:

bash

$ pip install -r linux-companion/requirements.txt
$ python linux-companion/touchdeck_companion_linux.py

Open http://127.0.0.1:8750. Enter the deck's IP, pick sensors and click Start.
In the deck portal, use + Add PC metric to add your sensors.
For PC control, click Pair for control on the companion's Device page, then tap Allow on the deck.

Metrics travel over UDP 4210, signed PC commands over UDP 4211, and cover art over TCP 8751. Allow the companion through the firewall. PC and deck must share a subnet. See PC stats and control.

View serial logs

Capture a boot loop, a WiFi error or a crash for a bug report. Plug the deck in over USB, click Connect and pick the same serial port you would use for flashing.

Only one program can hold the serial port at a time. The companion holds it while the USB cable is connected, so close it and any PlatformIO / Arduino monitors first. Disconnect this monitor before installing. Baud rate: 115200.