Skip to content
CrossPad Docs

Start here

CrossPad is a 16-pad MIDI controller. An ESP32-S3 runs the firmware, and an STM32 co-processor sits next to it. CrossPad is also an SDK: the same app code runs on the board and in a simulator on your computer.

What you need

Section titled “What you need”
  • A CrossPad board and a USB data cable (a charge-only cable does not work). These pages use board v2 (PCB r20); boards with PCB r16 / r19 (v1) work too, and step 2 shows the difference. No board? Use the PC simulator.
  • A computer with Linux (Ubuntu or Debian), Windows 10 or 11, or macOS.
  • About 10 GB of free disk space.
  • About an hour the first time. Most of it is downloads.

The steps

Section titled “The steps”

Follow them in order. Each step ends with a check, so you know it worked before you move on.

  1. Set up the toolchain: ESP-IDF, the CrossPad project, CP Tools and the board test tools.
    • Recommended: install each piece by hand, as the page shows. You learn what each piece is and where it lives.
    • Shortcut: the one-line installer does all of step 1 for you. It is at the top of step 1.
    • Optional: keep several ESP-IDF versions side by side, use an ESP-IDF you already have, or let Claude build, flash and test for you.
  2. Build the firmware for your board revision.
  3. Flash the board over USB.
  4. Check it works with CP Tools and a smoke test.

No board needed: PC simulator. It runs the same apps in a window on your computer and skips steps 1–4. The quickstart takes the same route and ends with an example app running.

CP Tools

Section titled “CP Tools”

CP Tools is CrossPad’s command-line helper: it installs and removes apps, checks your setup (doctor) and updates the board. The project starts it as tools/app_manager.py, which fetches the CP Tools code from CrossPad/crosspad-apps; the one-line installer adds the cptools command for the same program.

The SDK repos

Section titled “The SDK repos”

All repos live under github.com/CrossPad.

RepoWhat it is
CrossPad/platform-idfThe ESP-IDF firmware project. You build and flash this one. It pulls in core, GUI and apps as submodules.
CrossPad/crosspad-corePortable C++ core: app logic and platform interfaces, shared by the board and the simulator.
CrossPad/crosspad-guiShared LVGL user interface: widgets, themes and the app lifecycle.
CrossPad/crosspad-appsThe app registry, the CP Tools code and the one-line installer.
CrossPad/crosspad-hilPython tool that finds a connected board, flashes it and runs tests on it.
CrossPad/crosspad-mcpMCP server: lets Claude build, flash and test through tools.
CrossPad/crosspad-pcThe PC simulator: the same apps in a window on your computer.
CrossPad/CrossPad_STM32_r2Firmware for the STM32 co-processor on v2 boards (PCB r20). It also bridges the ESP32 console to USB.

How the layers fit

Section titled “How the layers fit”
CrossPad's layers: your app on crosspad-gui and crosspad-core, which run on the firmware (platform-idf) or the simulator (crosspad-pc). Five rows, top to bottom. Your app, from the crosspad-apps registry or your own repo, uses core interfaces and gui widgets. Under it sit the two shared layers: crosspad-gui, the shared UI (LVGL widgets, AppBase, the launcher, the settings screens, and its own IGuiPlatform and IFileSystem interfaces), and crosspad-core, the portable logic (event bus, pads, MIDI, settings, sequencer, kits, audio graph, and the I*.hpp interfaces). Their interfaces are implemented by one of two platforms: platform-idf, the ESP-IDF firmware for the ESP32-S3 board with the board support package and the Esp* adapters, or crosspad-pc, the SDL2 desktop simulator with the Pc* adapters. Under the firmware is the STM32 co-processor, which scans the pads and runs the power button and the charger, linked to the ESP32-S3 by UART (MIDI and SysEx) and, on v2 boards, I2C. Under the simulator are your keyboard and mouse and the stm32_emu window, which stands in for the STM32. Host tools on your computer drive both platforms from outside: crosspad-hil runs tests on a real board over USB, and crosspad-mcp gives AI assistants build, flash, simulator and trace tools. Your app from the crosspad-apps registry, or your own repo uses core interfaces and gui widgets Shared: one copy, built into both platforms crosspad-gui shared UI LVGL widgets, AppBase, launcher, settings screens its own IGuiPlatform, IFileSystem crosspad-core portable logic event bus, pads, MIDI, settings, sequencer, kits, audio graph; the I*.hpp interfaces each platform implements the core and gui interfaces platform-idf firmware ESP-IDF build for the ESP32-S3 board board support package, Esp* adapters crosspad-pc simulator SDL2 window on your computer Pc* adapters UART (MIDI and SysEx), I2C on v2 boards STM32 co-processor pads, power button, charger Keyboard and mouse a stm32_emu window stands in for the STM32 Host tools on your computer, outside both platforms crosspad-hil: tests on a real board over USB · crosspad-mcp: build, flash, simulator and trace tools for AI assistants
Your app sits on crosspad-gui and crosspad-core. Under them, platform-idf runs it on the board and crosspad-pc runs it in a window on your computer. The details are in Architecture.