PisteCast Guide

How it works

The scoring machine is the only source of score, clock, cards, and priority. This system never writes to it — the referee's machine is always right, and the stream just mirrors it. Control adds the human context: which fencers are on the strip, the event, the round.

Three pages, three jobs:

• Bridge — reads the machine over USB. Lives on the OBS laptop. Set-and-forget.
• Control — roster and bout management. Works on any phone or tablet on the same network.
• Overlay — the graphics OBS shows. Nobody interacts with it directly.

Stream-day checklist

1. Start the server on the OBS laptop (or confirm it's running): score chip in the header of this page updates once everything is alive.
2. Open Bridge in Chrome on the OBS laptop. If the hardware was used before, it connects by itself — look for machine live in the header. First time on a new laptop: click Connect to FA-07 once and pick the USB device.
3. Open OBS — the overlay browser source should already be in the scene (see OBS setup).
4. On a phone, open Control → pick the two fencers → Start bout.
5. Glance at the Live tab in Control: does the bar match reality? Names on the correct sides? If mirrored, hit Swap sides — see below.

Bridge page

Minimal by design: it shows connection status, a live score readout, and a frame counter. Healthy looks like this:

• Serial port: connected
• Server: connected
• Frames: counting up at roughly 24/s, green dot pulsing
• CRC errors: zero or nearly so

If the USB cable is knocked out, the page watches for the device returning and reconnects on its own. If the server connection drops (network blip), the bridge buffers everything and replays it when the server returns — a 30-second outage doesn't lose the bout.

Simulate machine runs a fake bout with no hardware — useful for testing the overlay, training a volunteer, or checking OBS before the machine is set up.

Control page

Bout tab

Pick the camera-left and camera-right fencer, set the target (5 for pools, 15 for direct elimination — this drives auto-logging), optionally event and round, then Start bout. When the clock hits 0:00 or a fencer reaches the target, the result is logged automatically — no typing. End bout now logs it early with the current score.

Live tab

Shows the actual overlay exactly as OBS renders it. The checkerboard is what's transparent on stream. When in doubt, trust this view.

Roster & Import tabs

Add fencers one at a time, or paste/upload a CSV — columns name, display_name, club, nation, weapon (only name is required; nation is a 2-letter code like us). The preview shows exactly what will be imported and flags problem rows; nothing saves until you commit. Display name is what appears on stream — the roster name is never mangled to fit.

Clubs tab

Upload each club's logo once (under 2 MB). The preview shows it against dark and light backgrounds — a logo that looks like a white box there will look like a white box on stream. Clubs with no logo get a colored circle with their initials, which always looks fine.

Settings tab

Identity display chooses flags vs club marks on the bar, with a live preview. auto is the right default: club always, flags only when the two fencers' nations differ. The overlay URL for OBS lives here too — regenerating the token breaks the old URL, so only do that on purpose.

OBS setup

1. Copy the overlay URL from Control → Settings.
2. In OBS: Sources → + → Browser.
3. URL: paste it. Width 1920, height 1080. Leave the custom CSS box alone.
4. Done — the background is transparent and the bar sits in the lower third.

The overlay animates in only when it has data, so an empty scene before the first bout is normal. A small STALE badge on the bar means the feed stopped — the score shown is the last known good one, frozen rather than zeroed. Check the Bridge laptop.

Swap sides — read this one

The machine's idea of "left" is relative to itself, not the camera. Worse, the machine has its own change-position button that flips its display without telling anyone. So at some point the overlay will show the fencers on the wrong sides. This is normal and takes one tap to fix:

Rule of thumb: fix mirroring with Swap sides. Use Swap fencer assignment only when the wrong people were entered on each side to begin with.

Accounts

Control and Bridge require a login; the first visit to a fresh install asks you to create the admin account. Two roles:

• operator — bouts, roster, clubs, imports: everything a volunteer does on stream day.
• admin — all of that plus user accounts, settings, and the overlay URL.

Volunteers can request their own account at /signup — it sits as pending approval until an admin approves it in Control → Settings → User accounts (approve as operator or admin, or deny). Admins can also create accounts directly there.

Forgot password? There's no email here — the reset goes through an admin. Request a reset from the login page; the admin sees the request in User accounts and generates a one-time reset link (valid 1 hour) to hand over in person or by text.

The OBS overlay needs no login (its secret URL is its key), and this guide and the landing page stay open to everyone on the network.

Fencer stats come free with results: click any fencer's name in the Roster or Results tabs for their record, touches for/against, indicator, recent form, and bout history — all built from auto-logged bouts.

Troubleshooting

Hardware assembly and wiring live in a separate sheet: docs/ASSEMBLY.md in the repo.