Matrix Portal Gateway

Matrix Portal Gateway

A split-flap display with no split flaps.

This is the Gateway firmware ported to an Adafruit MatrixPortal ESP32-S3 driving a HUB75 RGB LED matrix. The RS-485 transceiver is gone; in its place is a software bus and a wall of virtual split-flap modules, each one emulating a real module's wire protocol byte-for-byte and rendering itself as a flapping character cell on the panel.

Repo: github.com/avandeputte/MatrixPortalGateway

Everything above the bus is the unmodified gateway: the same web UI, REST API, MQTT, Home Assistant discovery, OTA, and module registry. The Companion drives it without any changes and cannot tell the difference from real hardware.

Why use it

• Try the whole stack with no mechanical build — web UI, companion, Home Assistant, the lot, on one ~$25 board plus a panel. No modules, no RS-485, no steppers, no calibration.
• An LED-matrix display in its own right — full colour, real accented characters, lowercase, the colour flaps, and an animated flip effect with a physical-looking seam.
• A faithful test target — because it emulates at the protocol level, it exercises the same code paths a real gateway does.

What you need

Part	Notes
Adafruit MatrixPortal ESP32-S3	The controller (Adafruit #5778).
A HUB75 LED panel	Default layout is a 15 × 3 wall on a 128 × 32 chain (two 64×32 panels in series, or one native 128×32). Bigger panels give roomier cells.
A 5 V power supply	Sized for your panel — check the panel/Adafruit specs.

64-row panels (128×64) need the HUB75 E address line wired; a solder jumper on the MatrixPortal selects which pin that reaches — match it to your panel. See the repo's README for the panel/size table.

Flash & set up

pio run -t upload        # build + flash over USB (double-tap RESET if the port is busy)
pio device monitor       # 115200 baud, native USB CDC

WiFi works like the real gateway: on first boot it raises a SoftAP setup page; once you save a network from the UI, it joins your LAN. From there it's the same web UI as the Gateway — same tabs, same settings.

What's emulated (and what isn't)

• Emulated: everything the gateway actually sends — display and homing commands, flap-set config, version/identity queries, broadcasts, and batch queries. Each virtual module even reports a (fabricated but stable) serial number, so the gateway discovers them exactly as it would real modules.
• The reel is bigger: a virtual module carries the full set of printable characters (over 200 glyphs) plus the seven colour flaps, so it can show lowercase and accents a physical 64-flap reel can't. To stay backward-compatible, m38-r still resolves to the red flap; the lowercase letter r is reachable only by index.
• Not emulated: the mechanism. There's no stepper, Hall sensor or EEPROM, so calibration, diagnostics and provisioning are no-ops (the modules are "born" provisioned). You won't use the Calibration or Provision tabs here.
• The flip is a rendering effect, not a physics simulation — you can cap or disable it.

How it fits the rest of the wiki

The Matrix Portal Gateway is a drop-in replacement for the modules and the gateway. Wherever the rest of this wiki says "the gateway," it applies here too — including registering the Companion and everything in Home Assistant. Skip the Hardware and Module Firmware pages entirely.

---

Next: Companion →