Gateway

Gateway

The gateway is the ESP32 controller that sits between your network and the split-flap bus. It owns everything about the hardware — discovering modules, provisioning, calibration, diagnostics, and driving the flaps — and serves a single-page web UI to do all of it. It has no notion of "a weather app" or "a playlist"; that's the Companion's job.

Repo: github.com/avandeputte/SplitFlapGateway · board: Waveshare ESP32-S3-RS485-CAN (RS-485 transceiver on board) · reach it at http://splitflap-gw.local

1. Flash it

Two ways:

• Prebuilt binary (no toolchain): download from the repo's Releases. On a blank board, flash firmware.factory.bin at address 0x0 — either with the browser tool at espressif.github.io/esptool-js or esptool --chip esp32s3 write_flash 0x0 firmware.factory.bin. If it won't program, hold BOOT, tap RESET, release BOOT, and retry. (Use a USB-C data cable.)
• Build from source: VS Code + PlatformIO, open the folder with platformio.ini, Build → Upload. PlatformIO fetches the ESP32 toolchain and libraries automatically.

The first flash must be over USB. Every update after that can be done over WiFi (OTA) from the Settings tab — upload the app-only firmware.bin (never the factory image).

2. Join it to WiFi

On first boot, with no WiFi stored, the gateway raises its own access point:

1. Join the WiFi network Split-Flap-GW (password 12345678).
2. Open http://192.168.4.1.
3. Go to Settings → WiFi, enter your network's SSID and password, Save WiFi.

It joins your LAN and the setup AP shuts off. From then on, reach the UI at http://splitflap-gw.local (or the IP shown on the Status page). The AP only comes back if the gateway loses your WiFi.

3. Set the grid

In Settings → Display Layout, set rows × columns to match your wall (e.g. 3 × 15). This drives the live display and the calibration picker — and the Companion reads it from here, so you set the grid once, on the gateway.

The web UI, tab by tab

• Modules — a grid of every known module: ID, serial, the character it's showing, and firmware version. The list is sticky — it survives reboots and only drops a module after 6 hours unseen. Each card has ⌂ Home, ℹ Info (live query + the module's stored home offset, steps/rev, flap map — editable on newer module firmware), and a 🗑 menu (erase EEPROM / factory reset / de-provision). ↻ Identify All rediscovers the bus.
• Display — a live render of the wall, a Home All button, and boxes to send text across the modules, a single character (to one module or broadcast), or a specific flap by index.
• Provision — discover unprovisioned modules, home one by serial to identify it physically, assign IDs, and de-provision. (This is the UI for provisioning.)
• Calibration — a picker grid matching your layout: edit and save each module's home offset and total steps, nudge live, Count Steps, tune the per-flap map, and run a guided Calibration Wizard.
• Bus Monitor — live decoded RS-485 traffic with timestamps, pause / auto-scroll, a Download Log button, and a Send Frame box (with a Raw option) for hand-crafted commands.
• Settings — WiFi, MQTT, Timezone, Quiet Time schedule, the Companion App registration, Display Layout, Home Assistant, OTA update, and calibration backup/restore.
• Status — network, system health (uptime, heap, per-task stack), the RS-485 bus counters, the clock (RTC + NTP), and whether the companion is checked in.

What else the gateway offers

• REST API — a full JSON API (see the repo's openapi.yaml). The one the companion leans on most is POST /api/rs485/batch: a whole page of flaps in a single request, which is what keeps animations smooth with no broker involved.
• MQTT — optional; publishes bus traffic and a periodic status blob, and subscribes to command topics. Default prefix splitflap, port 1883.
• Home Assistant discovery — opt-in on the Settings tab (needs MQTT). Creates a gateway device with a Display text entity, Maintenance/Quiet switches, and a set of diagnostic sensors. (This is the gateway's own HA device — the companion adds more; see Home Assistant.)
• OTA — update over WiFi after the first USB flash, from Settings or http://<ip>/ota.

The Companion tab

When you run the Companion and point it at the gateway, it registers itself: a Companion tab appears in the gateway's nav, and the companion's own nav gains the gateway's tabs — each side advertises what it has, so the navigation always matches both halves. A container companion can even store its settings on the gateway, so it stays stateless.

---

Next: Companion → — or, no hardware? Matrix Portal Gateway →