TractionScout

Maintained by TractionScout · Reviewed · Updated

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 (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 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:

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:

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:

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:

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:

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 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.