Skip to content
OpenArcade Logo OpenArcade

Config App Overview

Config App Overview

The OpenArcade Config App is a browser-based 3D configurator for designing controller layouts and mapping buttons.

Features

3D Layout Designer

Visualize and arrange your controller modules in 3D space.

Button Mapping

Assign keyboard keys or gamepad buttons to each physical input.

Live Preview

See real-time button presses reflected in the 3D view.

WebSerial

Direct connection to the Pi via USB serial.

Technology Stack

LayerTechnology
3D RenderingThree.js
FrameworkReact
StylingTailwind CSS
CommunicationWebSerial API

How It Works

┌──────────────┐         WebSerial         ┌──────────────┐
│  Config App  │◄─────────────────────────►│  RPi Serial  │
│  (Browser)   │    /dev/ttyGS0            │  Service     │
└──────┬───────┘                           └──────────────┘
       │
       │  JSON-lines protocol
       │
       ▼
┌──────────────────────────────────────────────────────────┐
│  Commands:                                                │
│  - list_devices     Get all connected modules            │
│  - get_device       Get device config                    │
│  - set_mapping      Update button mapping                │
│  - set_ui_binding   Bind UI element to physical control  │
│  - get_live_state   Stream real-time button states       │
└──────────────────────────────────────────────────────────┘

Connecting to the Pi

  1. Connect via USB – Plug your Pi into your computer
  2. Open Config App – Navigate to the app in Chrome/Edge
  3. Select Serial Port – Click “Connect” and choose the OpenArcade serial port
  4. Start Configuring – Devices appear automatically

Interface Overview

┌─────────────────────────────────────────────────────────────────────┐
│  OpenArcade Configurator                          [Connect] [Save]  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────────────────────────┐  ┌──────────────────────┐  │
│  │                                     │  │  Device List         │  │
│  │                                     │  │                      │  │
│  │        3D Controller View           │  │  ○ Left Module       │  │
│  │                                     │  │  ● Right Module      │  │
│  │        [Interactive Three.js]       │  │  ○ D-Pad Module      │  │
│  │                                     │  │                      │  │
│  │                                     │  ├──────────────────────┤  │
│  └─────────────────────────────────────┘  │  Button Mapping      │  │
│                                           │                      │  │
│                                           │  Button 1: [Z    ▼]  │  │
│                                           │  Button 2: [X    ▼]  │  │
│                                           │  Button 3: [C    ▼]  │  │
│                                           │                      │  │
│                                           └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

3D Model Integration

The config app loads 3D models representing each module type:

  • Button panels – Individual plate with button cutouts
  • Joystick modules – Balltop or battop style
  • D-pad modules – Classic directional pad

Models are loaded from /public/plates/ in the config app.

Running the Config App

Development

Terminal window
cd config_app
npm install
npm run dev

Then open http://localhost:5173 in a Chromium browser.

Production Build

Terminal window
npm run build
# Output in dist/

Live State Streaming

The app can stream real-time button states for visual feedback:

{ "cmd": "get_live_state", "device_id": "AA:BB:CC:DD:EE:FF" }

Response (repeating):

{ "device_id": "AA:BB:CC:DD:EE:FF", "state": { "1": true, "2": false, ... } }

Pressed buttons light up in the 3D view.

Next Steps