Dummy Arcade Interface

Overview

The arcade button interface connects to the Randchip server via WebSocket. It receives LED state commands and sends button press events. The interface is game-agnostic — it doesn't know what game is running. It just relays button presses and displays LED states.

This dummy page is a browser-based reference implementation. The production interface runs on a Raspberry Pi controlling physical LEDs and reading physical button presses, but speaks the exact same WebSocket protocol.

Connection

Connect via WebSocket to:

ws://<server-host>:<port>/ws

Immediately after connecting, send an identify message declaring the role and grid dimensions:

{
  "type": "identify",
  "role": "arcade",
  "rows": 7,
  "cols": 7
}

The rows and cols fields tell the server the grid dimensions. This allows different physical builds to use different grid sizes without changing the server code.

Messages: Server -> Arcade (LED Control)

The server sends LED state changes. Each message controls one LED at a specific grid coordinate:

{
  "type": "led",
  "row": 3,
  "col": 5,
  "state": "on"
}

Coordinates are zero-indexed. Row 0 is the top row, column 0 is the leftmost column.

Valid LED states:

• off — LED is dark/unlit
• on — LED is lit, solid, continuously on
• slow_flash — LED flashes at ~1Hz (on 500ms, off 500ms)
• medium_flash — LED flashes at ~2-3Hz (on 200ms, off 200ms)
• fast_flash — LED flashes at ~5-6Hz (on 100ms, off 100ms)
• single_flash — LED flashes once brightly then returns to off. The arcade interface handles the timing — after a brief flash (~200-300ms), the LED auto-returns to off state. No follow-up "off" message from the server.

The arcade interface owns all flash timing. The server sends a state name; the interface handles the on/off cycling.

Messages: Arcade -> Server (Button Presses)

When a physical button is pressed, send a press event with the grid coordinate:

{
  "type": "press",
  "row": 3,
  "col": 5
}

Press events are momentary (fire-and-forget). One event per press. No release tracking.

Reconnection

If the WebSocket connection drops, reconnect and re-send the identify message. Use exponential backoff (start at 500ms, cap at 5s). The server supports connection eviction — a new connection with the same role will cleanly replace the old one.

On reconnect, all LED states should be treated as unknown. The server will re-send any active LED states as needed.

Example: Full Game Cycle

// 1. Connect and identify
-> { "type": "identify", "role": "arcade", "rows": 7, "cols": 7 }

// 2. Server lights an LED (game started)
<- { "type": "led", "row": 2, "col": 4, "state": "on" }

// 3. Player presses that button
-> { "type": "press", "row": 2, "col": 4 }

// 4. Server turns off old LED, lights new one
<- { "type": "led", "row": 2, "col": 4, "state": "off" }
<- { "type": "led", "row": 5, "col": 1, "state": "on" }

// 5. ... game loop continues ...

// 6. Game ends, server turns off all LEDs
<- { "type": "led", "row": 5, "col": 1, "state": "off" }