Built-in project · Raspberry Pi Pico

Mixbox-style controller on a Pico

W A S D directions for the left hand and eight lit buttons for the right, on GP2040-CE’s Pico pins, with SOCD modes, turbo and an OLED input display. The whole build, a Raspberry Pi Pico and 17 more parts, runs here in your browser on the firmware below; open it in the editor to change the wiring or the code and run it again.

Teaching? Assign it to your class in one click.

Advanced About 45 minutes to build and run. Runs in your browser. Free, and no account needed.

The parts retail for about $40. On Mokxi they're free.

The circuit runs here once the page has loaded.

What you'll learn

  • Switches to ground with internal pull-up resistors
  • Debouncing with a short lockout after a change
  • SOCD cleaning when A and D are held together
  • Turbo: arming a button to repeat at TURBO_SHOTS presses a second
  • Lamps that react to presses using PWM
  • Difficulty: Advanced
  • Time: About 45 minutes
  • Board: Raspberry Pi Pico
  • Parts: 18

How it works

This layout puts the four directions on keyboard-style switches for W A S D, wired to GP2 (up), GP3 (down), GP5 (left) and GP4 (right). Eight lit arcade buttons handle attacks. Every switch connects its pin to ground, and the Pico's internal pull-ups make a press read low, so no resistors are needed.

The sketch scans the inputs about every 250 microseconds and uses DEBOUNCE_MS as a lockout after each accepted change. When opposite directions are held together, such as A and D, the SOCD mode decides what is sent. It starts in SOCD_NEUTRAL. Each lamp fades after a press, and the OLED on GP0 and GP1 shows an input history.

Mokxi does not simulate the Pico's USB, so reports appear as lines on the Serial Monitor.

Wiring table

Every connection, pin by pin, read from the circuit itself. Each row joins the pin on the left to the pin on the right, by a jumper wire or a breadboard strip.

Part and pinConnects to
OLED display, 128x64 pin SDARaspberry Pi Pico pin GP0
OLED display, 128x64 pin SCLRaspberry Pi Pico pin GP1
Arcade button (1) pin 2Raspberry Pi Pico pin GND
Arcade button (1) pin 1Raspberry Pi Pico pin GP2
Arcade button (3) pin 1Raspberry Pi Pico pin GP3
Arcade button (4) pin 1Raspberry Pi Pico pin GP4
Arcade button (2) pin 1Raspberry Pi Pico pin GP5
Arcade button (2) pin 2Raspberry Pi Pico pin GND
Arcade button (3) pin 2Raspberry Pi Pico pin GND
Arcade button (4) pin 2Raspberry Pi Pico pin GND
LED arcade button (5) pin 1Raspberry Pi Pico pin GP6
LED arcade button (6) pin 1Raspberry Pi Pico pin GP7
LED arcade button (7) pin 1Raspberry Pi Pico pin GP8
LED arcade button (8) pin 1Raspberry Pi Pico pin GP9
LED arcade button (1) pin 2Raspberry Pi Pico pin GND
LED arcade button (1) pin L-Raspberry Pi Pico pin GND
LED arcade button (2) pin 2Raspberry Pi Pico pin GND
LED arcade button (2) pin L-Raspberry Pi Pico pin GND
LED arcade button (3) pin 2Raspberry Pi Pico pin GND
LED arcade button (3) pin L-Raspberry Pi Pico pin GND
LED arcade button (4) pin 2Raspberry Pi Pico pin GND
LED arcade button (4) pin L-Raspberry Pi Pico pin GND
LED arcade button (5) pin 2Raspberry Pi Pico pin GND
LED arcade button (5) pin L-Raspberry Pi Pico pin GND
LED arcade button (6) pin 2Raspberry Pi Pico pin GND
LED arcade button (6) pin L-Raspberry Pi Pico pin GND
LED arcade button (7) pin 2Raspberry Pi Pico pin GND
LED arcade button (7) pin L-Raspberry Pi Pico pin GND
LED arcade button (8) pin 2Raspberry Pi Pico pin GND
LED arcade button (8) pin L-Raspberry Pi Pico pin GND
Arcade button (5) pin 2Raspberry Pi Pico pin GND
LED arcade button (1) pin 1Raspberry Pi Pico pin GP10
LED arcade button (2) pin 1Raspberry Pi Pico pin GP11
LED arcade button (3) pin 1Raspberry Pi Pico pin GP12
LED arcade button (4) pin 1Raspberry Pi Pico pin GP13
Arcade button (5) pin 1Raspberry Pi Pico pin GP14
LED arcade button (5) pin L+Raspberry Pi Pico pin GP15
OLED display, 128x64 pin GNDRaspberry Pi Pico pin GND
OLED display, 128x64 pin VCCRaspberry Pi Pico pin 3V3
LED arcade button (8) pin L+Raspberry Pi Pico pin GP28
LED arcade button (7) pin L+Raspberry Pi Pico pin GP27
LED arcade button (6) pin L+Raspberry Pi Pico pin GP26
LED arcade button (4) pin L+Raspberry Pi Pico pin GP22
LED arcade button (3) pin L+Raspberry Pi Pico pin GP21
Arcade button (8) pin 1Raspberry Pi Pico pin GP20
LED arcade button (2) pin L+Raspberry Pi Pico pin GP19
LED arcade button (1) pin L+Raspberry Pi Pico pin GP18
Arcade button (6) pin 2Raspberry Pi Pico pin GND
Arcade button (7) pin 2Raspberry Pi Pico pin GND
Arcade button (8) pin 2Raspberry Pi Pico pin GND
Arcade button (7) pin 1Raspberry Pi Pico pin GP17
Arcade button (6) pin 1Raspberry Pi Pico pin GP16

The code

The firmware exactly as the editor opens it. Change a line there and press Run: it compiles in the browser.

sketch.ino · Raspberry Pi Pico
// Mixbox-style controller on a Raspberry Pi Pico: a template for your own build.
//
// The keyboard-hand layout: up, left, down and right on W A S D under the
// left hand's fingers, the way PC players already move, and eight attack
// buttons for the right hand. Builders often use low-profile keyboard
// switches for the four keys and 24 or 30 mm arcade buttons for the rest;
// electrically every one of them is a switch to ground. It has the features
// people expect from a modern controller board:
//
//   - lag-free debounce, explained below where it lives
//   - SOCD cleaning: Neutral, Up priority, Last win and First win, switched
//     with GP2040-CE's own button combos (A and D can be held together on
//     this layout just as on a leverless one)
//   - D-pad, left stick and right stick modes, also on GP2040-CE's combos
//   - turbo per button: hold TURBO and tap a button to arm or disarm it
//   - lit buttons that react to every press, with five themes and brightness
//   - an OLED input display with an input history in numpad notation
//   - an input viewer on the Serial Monitor, one line per change
//
// The pin map is GP2040-CE's default for a bare Pico (configs/Pico in the
// GP2040-CE repository), so a build you prove here can be flashed with
// GP2040-CE on the bench and wired exactly the same.
//
// Try it: press Run, then hold W A S D. U I O P and J K L ; are the attack
// buttons, Q E H are Select, Start and Home, and T is turbo. Hold A and D
// together to see SOCD cleaning at work.
//
// What Mokxi does not simulate: the Pico's USB. A real build sends each
// report to the console or PC; here the same report is a line on the Serial
// Monitor. Everything before that point (wiring, debounce, cleaning, modes,
// lights, screen) runs exactly as written.

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <string.h>

// =============================================================================
//  YOUR BUILD: everything you are likely to change is in this block.
// =============================================================================

// ---- Layout ------------------------------------------------------------------
// Which controller this is. It decides how the OLED draws the buttons and the
// starting SOCD mode; the pins below are the same for all three.
#define LAYOUT_LEVERLESS 0  // four direction buttons (Hit Box style)
#define LAYOUT_LEVER 1      // a joystick lever (Sanwa JLF style)
#define LAYOUT_MIXBOX 2     // W A S D keys for the left hand
#define LAYOUT LAYOUT_MIXBOX

// ---- Pins --------------------------------------------------------------------
// One switch per pin, the other leg on ground. The pin's internal pull-up holds
// it HIGH and a press pulls it LOW, so no resistors are needed anywhere. Set a
// pin to NO_PIN to leave that input out of your build.
//
// Names follow GP2040-CE: B1 to B4 are the face buttons, L1/R1 and L2/R2 the
// shoulders and triggers, S1 Select, S2 Start, A1 Home. B1 to B4 and A1 are
// spelled BTN_B1 to BTN_B4 and BTN_A1 here, because Arduino already uses those
// names: B1 is a binary constant and A1 an analog pin. LABELS is what the
// screen and the Serial Monitor call each one; rename them for your game.
#define NO_PIN 255

enum Input : uint8_t {
  UP, DOWN, LEFT, RIGHT,          // directions
  BTN_B1, BTN_B2, BTN_B3, BTN_B4, // face buttons
  L1, R1, L2, R2,                 // shoulders and triggers
  S1, S2, BTN_A1, TURBO,          // Select, Start, Home, turbo
  INPUT_COUNT
};

//                                 GP2040-CE default for a Pico
const uint8_t PINS[INPUT_COUNT] = {
  2, 3, 5, 4,                   // Up GP2, Down GP3, Left GP5, Right GP4
  6, 7, 10, 11,                 // B1 GP6, B2 GP7, B3 GP10, B4 GP11
  13, 12, 9, 8,                 // L1 GP13, R1 GP12, L2 GP9, R2 GP8
  16, 17, 20, 14,               // S1 GP16, S2 GP17, A1 GP20, turbo GP14
};

// Street Fighter style names: punches on the top row, kicks on the bottom.
// For a four-button game you might use "1" "2" "3" "4" instead.
const char *const LABELS[INPUT_COUNT] = {
  "U", "D", "L", "R",
  "LK", "MK", "LP", "MP",
  "3P", "HP", "3K", "HK",
  "Sel", "Sta", "Hom", "Tur",
};

// The eight attack buttons in the order they sit on the panel, top row then
// bottom row, left to right. The lights and the screen both follow it.
const Input PANEL[8] = {BTN_B3, BTN_B4, R1, L1, BTN_B1, BTN_B2, R2, L2};

// ---- Lit buttons ---------------------------------------------------------------
// One pin per lit button, in PANEL order, driving the lamp inside the button
// through PWM. NO_PIN for a button without a lamp. (GP2040-CE drives a WS2812
// chain from one pin through the RP2040's PIO; Mokxi does not model PIO, so
// this template lights each button from its own pin instead. GP15 is
// GP2040-CE's turbo LED by default; here it lights LK, the first button of
// the bottom row, and the Pico's own LED shows turbo.)
//
// The lamps are the 5 V LED buttons sold for sticks. From a 3.3 V pin they
// glow at about half their rated brightness; for full brightness, switch each
// lamp from 5 V through a small NPN transistor or a driver chip.
const uint8_t LAMP_PINS[8] = {18, 19, 21, 22, 15, 26, 27, 28};
const uint8_t TURBO_LED_PIN = LED_BUILTIN;  // GP25, on the Pico itself

enum Theme : uint8_t { THEME_STATIC, THEME_BREATHE, THEME_WAVE, THEME_REACTIVE, THEME_OFF, THEME_COUNT };
const Theme START_THEME = THEME_REACTIVE;
const uint8_t START_BRIGHTNESS = 3;     // 0 to 4
const uint16_t PRESS_FADE_MS = 280;     // how long a lit press takes to fade

// ---- SOCD cleaning ---------------------------------------------------------------
// What the controller sends when opposite directions are held together. See
// the SOCD section below for what each one does and which events want which.
enum Socd : uint8_t { SOCD_NEUTRAL, SOCD_UP_PRIORITY, SOCD_LAST_WIN, SOCD_FIRST_WIN, SOCD_OFF, SOCD_COUNT };
const Socd START_SOCD = SOCD_NEUTRAL;

// ---- Direction output ------------------------------------------------------------
enum DpadMode : uint8_t { MODE_DPAD, MODE_LEFT_STICK, MODE_RIGHT_STICK, MODE_COUNT };
const DpadMode START_MODE = MODE_DPAD;

// ---- Timing ------------------------------------------------------------------------
const uint8_t DEBOUNCE_MS = 5;          // lockout after an accepted change
const uint16_t SCAN_US = 250;           // read every input this often (4 kHz)
const uint8_t TURBO_SHOTS = 10;         // presses per second while held
const uint16_t TOAST_MS = 1200;         // how long a mode change stays on screen

// ---- Screen and Serial Monitor ------------------------------------------------------
const bool OLED_ENABLED = true;
const uint8_t OLED_SDA = 0;             // GP2040-CE default display pins
const uint8_t OLED_SCL = 1;
const uint8_t OLED_ADDRESS = 0x3C;
const bool INPUT_VIEWER = true;         // one line per change on Serial

The other 733 lines of sketch.ino, the firmware itself, are the same as in Leverless controller on a Pico, apart from 1 line, and that page prints them in full. Open in the simulator has every line of this one.

Troubleshooting

The usual mistakes with this circuit, and the fix for each.

  • Left and right are swapped This project
    Left is GP5 and right is GP4. Check which switch goes to which pin.
  • A button does nothing This project
    Make sure one leg goes to its GP pin and the other leg goes to ground.
  • Holding A and D together gives odd movement This project
    That is SOCD cleaning at work. The starting mode is SOCD_NEUTRAL, which cancels both directions.
  • The OLED stays blank. OLED display
    Check SDA and SCL are not swapped, and power it with 3.3 V or 5 V as its board allows. Most use address 0x3C, some 0x3D. Call display.begin() with the matching address.
  • Text never shows up even though the code runs. OLED display
    Drawing only writes to a buffer. Call display.display() after drawing to push it out. Also set a text color with setTextColor(WHITE) and clear the buffer between frames.
  • The button reads pressed all the time, or never changes, when wired to a pin. Arcade button
    Use the COM and NO terminals of the microswitch. Wire COM to ground, NO to the pin, and use INPUT_PULLUP. NC is the opposite and reads pressed when released.
  • One press counts as several presses in your code. Arcade button
    Microswitch contacts bounce for a few milliseconds. Ignore changes for 10 to 20 ms after the first one, or react only to the edge and wait before checking again.
  • The button lamp never lights or burns out quickly. LED arcade button
    The lamp is an LED with its own pins, separate from the switch. Match it to its rating (5 V or 12 V version) and check polarity. If your supply is different, add a resistor sized for it.

Change it and keep it

Open it in the editor, change the circuit or the code, and keep your version in a free account.