# Set up the desk display

The desk display is a small ESP32 screen that sits on your desk and shows one
TractionScout figure at a time, large enough to read from across the room: who
is on your sites now, the day so far, each project's objective with the change
the server measured, what is waiting for you, and what Scout has noticed. When
something happens that Scout judges worth looking up for — a first payment, a
first customer — the display shows it at once and chimes.

It is a companion to the dashboard and the Mac app, and it only reads. Approving
work still happens on the board or in the Mac app, where you can see the whole
item.

[Download the firmware](/downloads/TractionScout-Desk-Display-firmware.zip)
(about 150 kB). It carries the firmware, the simulator that draws its screens on
your own machine, the host tests and these instructions. It is a prototype: it
has not yet been run on hardware, and the panel port needs its pins filled in
from the board vendor's own example before it will build.

## What you need

- An **ESP32-S3 board with a 4-inch 480×480 screen**. The firmware is written
  for the Waveshare ESP32-S3-Touch-LCD-4; its PSRAM holds the frame buffer and
  the network buffers comfortably, and an IPS panel does not burn in the way an
  always-on OLED would.
- A **USB-C data cable** (a charge-only cable will not do).
- **[PlatformIO](https://platformio.org/install/cli)** on your computer
  (`brew install platformio`, or `pip install platformio`).
- A 2.4 GHz **Wi-Fi network**. The ESP32-S3 does not join 5 GHz networks.
- A phone or computer already signed in to TractionScout, to approve the
  display once.

A buzzer is optional. Without one, alerts are seen and not heard.

## 1. Build and flash

Unzip the download, then check it is the archive we published before you build
it. The checksum beside it on this server is the one to compare against:

```bash
shasum -a 256 TractionScout-Desk-Display-firmware.zip
curl -s https://tractionscout.com/downloads/TractionScout-Desk-Display-firmware.zip.sha256
```

Then flash the board over USB:

```bash
cd TractionScout-Desk-Display-firmware
pio run -d firmware -e waveshare_lcd4 -t upload
```

Before that env builds, open
`firmware/src/board/waveshare_lcd4_pins.h` and fill in the pins, panel timings
and ST7701 initialisation from the vendor's example for your board revision.
They are deliberately left blank rather than guessed, because a wrong backlight
or power pin can damage a panel.

To try the firmware on any ESP32-S3 board before the panel is wired, flash the
console build instead. It prints the same cards over USB serial, so you can
check Wi-Fi, sign-in and the live connection without a screen:

```bash
pio run -d firmware -e esp32s3_serial -t upload
pio device monitor -b 115200
```

## 2. Join Wi-Fi

Connect the board over USB and open its console at 115200 baud
(`pio device monitor -b 115200`), then send:

```text
wifi <network name> <password>
```

The display restarts and joins. If your deployment is not `tractionscout.com`,
set it as well — `https://` is required, except for a local address while you
develop:

```text
server https://tractionscout.example
```

Other commands: `tz <IANA zone>` overrides the account's time zone for the day's
counts, `range <7d|30d|90d|365d>` sets the window each change compares, `status`
shows what the display is signed in as, and `signout` forgets the session.

## 3. Approve the display

The display cannot open a browser, so it shows a QR code instead. Scan it with a
phone or computer that is signed in to TractionScout, and approve
**TractionScout desk display**.

This is the same one-time device authorization that the Mac app uses. The
display never asks for your password, and nothing is typed on the device. The
session it receives is listed under
[Security settings → Active sessions](/settings/security) as *TractionScout desk
display*, and you can revoke it there at any time.

The code expires after five minutes. Press the board's BOOT button for a fresh
one.

## 4. Use it

The display moves to the next card every nine seconds; BOOT moves it on at once.
Along the top it says whether it is live and, when the connection has been quiet,
how old the figures are — in which case everything dims rather than pretending to
be current. A figure the server could not measure shows as a dash with the
reason, never as a zero.

**Alerts.** When Scout accepts a moment worth interrupting for, the display shows
it immediately, holds it for thirty seconds, draws a coloured edge and chimes
once. Each moment alerts once, even if the display restarts.

## Privacy and security

The display holds one TractionScout session, kept on the device. It makes only
read requests, plus the realtime connection that tells it when to re-read; it
never writes to your projects. The connection is HTTPS with the standard
certificate bundle.

Until a read-only device session lands, that session carries the same rights as
your account, so treat the device as you would a signed-in laptop: revoke it
under Active sessions if it leaves your desk, and turn on flash encryption for a
display that sits anywhere public.

## If something is wrong

| What you see | What it means |
| --- | --- |
| "Set up Wi-Fi" | No network stored yet — send `wifi <name> <password>` over the console. |
| "Connecting to Wi-Fi" for a long time | Wrong password, or a 5 GHz-only network. |
| "Can't reach TractionScout" | The deployment URL is wrong or unreachable; check it with `status`. |
| A QR code you have already approved | The code expired before it was approved; press BOOT for a new one. |
| "Signed out" | The session was revoked or expired; press BOOT to sign in again. |
| Everything dimmed | The connection has been quiet; the figures are as old as the top line says. |
| Alerts are silent | No buzzer is wired, or the board has none. |


Maintained by TractionScout · Reviewed 2026-11-13 · Updated 2026-11-13
