Getting Started

Everything from unboxing to live departures — step by step.

Before You Start

Make sure you have everything on the Build Guide parts list. The key decision is which hardware variant you're using:

	MatrixPortal S3	Generic ESP32-S3
Wiring	Plug & play	Manual GPIO wiring
Level shifters	Built-in	Optional but recommended
Difficulty	Easy	Medium
Cost	~$65–90	~$51–85

Level shifters (generic ESP32-S3 only): The ESP32-S3 outputs 3.3V logic, but HUB75 panels expect 5V. Most panels work anyway, but it's out of spec — some batches won't. The MatrixPortal S3 has 74AHCT245 level shifters built in. For generic ESP32-S3, adding two 74AHCT245 chips (~$2–6) guarantees reliable operation with any panel.

Step 1: Assemble the Hardware

MatrixPortal S3

Plug the MatrixPortal S3 into the first panel's HUB75 input connector
Connect a HUB75 ribbon cable from Panel 1 OUT → Panel 2 IN to daisy-chain the second panel
Connect 5V power via USB-C (2A minimum, 3A recommended) to the MatrixPortal — it passes power to both panels via the screw terminals

Generic ESP32-S3

Wire the ESP32-S3 GPIO pins to the first panel's HUB75 input — full pin mapping in the Wiring Guide
Connect a HUB75 ribbon cable from Panel 1 OUT → Panel 2 IN
Connect a 5V power supply (2A+) directly to the panels via screw terminals
Power the ESP32-S3 via USB or from the same 5V supply — ensure common GND between ESP32 and panels

⚠️ Panel chain order: Looking at the back of the panels, the controller board goes on the left. Chain runs left → right (OUT → IN). Getting this backwards causes a split or mirrored image.

Step 2: Flash the Firmware

Option A: Pre-built binary (recommended)

Go to GitHub Releases and download the .bin for your board:
- spojboard-matrixportal_s3-r*.bin — MatrixPortal S3
- spojboard-esp32_s3_n8r2-r*.bin — Generic ESP32-S3
Install esptool if you don't have it:
```
pip install esptool
```

Connect your board via USB and flash:

esptool.py --chip esp32s3 --baud 921600 write_flash 0x0 spojboard-matrixportal_s3-r*.bin

GUI alternative: If you prefer a graphical tool, use ESP Flasher — select your port, pick the .bin file, and click Flash.

Option B: Build from source

If you want to modify the firmware or use a different board configuration:

git clone https://github.com/xbach/spojboard-firmware.git
cd spojboard-firmware
pio run -t upload

Requires PlatformIO CLI. The default environment matches the MatrixPortal S3 — check platformio.ini for other board targets.

Step 3: First Boot & WiFi Setup

After flashing, the display shows WiFi credentials:

WiFi Setup Mode
SSID: SpojBoard-XXXX
Pass: xxxxxxxx
Go to: 192.168.4.1

Connect your phone or laptop to the SpojBoard-XXXX network
A captive portal opens automatically (or go to 192.168.4.1)
Enter your home WiFi credentials and save
The device reboots and connects to your WiFi

If the device can't connect (wrong password, network issue), it automatically falls back to AP mode with a new random password shown on the display. Just reconnect and try again.

Step 4: Configure via Web Interface

Find the device IP on your router's DHCP list (or check the serial monitor), then open http://<device-ip>/ in a browser.

Connection tab

Select your city: Prague, Berlin, or MQTT (Custom)

Transit Data tab

Prague: Enter your Golemio API key and stop ID(s)
Berlin: No API key needed — just enter stop ID(s)
MQTT: Configure broker address, request/response topics — see MQTT Guide

Need your stop ID? Use the Station Search tool to find it by name.

Display tab

Brightness (default 90, range 0–255)
Display mode: Vanilla / Platform / Dual ETA / Dual ETA + Platform
Custom line colors

Optional tab

Weather display (Open-Meteo, no API key required)
Rest mode (scheduled off periods)

Hit Save on each tab. The device applies settings and starts pulling live departures.

Step 5: Test & Tune

Demo mode — available in the web interface before API setup; lets you preview the display with sample departure data
Brightness — lower is easier on the eyes indoors; default 90 is a good starting point
Dual ETA — enable to see the next two departures per line, useful for high-frequency routes
Trip filtering — default 3 min minimum hides departures you can't catch; adjust to taste
Scrolling — enable for very long destination names (off by default)