No hardware? PC simulator

No board? The simulator runs the same core, GUI and apps as the board, in a window on your computer; it needs no ESP-IDF, so you can skip steps 1–4. To go from nothing to a running example app, follow the 10-minute quickstart.

You build CrossPad/crosspad-pc with CMake and start it. The pads and the screen appear in the window, and your mouse plays the pads: a click is a hit, the wheel turns the encoder and the middle button presses it. The keyboard plays the pads too once you switch the round keyboard button on the window from OFF to FOCUS.

Linux
Windows

These commands are for Ubuntu and Debian.

Install the build tools and libraries.

sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build git pkg-config libsdl2-dev libasound2-dev libpulse-dev libdbus-1-dev
sudo apt-get install -y libpipewire-0.3-dev   # optional: native PipeWire virtual audio devices

You should see: apt finishes without an E: line.

If not: apt-get install fails or a package is not found

Download the simulator with its submodules.
Terminal window
```
git clone --recursive https://github.com/CrossPad/crosspad-pc.git ~/crosspad-pc
cd ~/crosspad-pc
git submodule update --init --recursive
git submodule status | grep -c '^-' || true
```
You should see: 0 on the last line (no submodule left out).

If not: a request for a GitHub login for a submodule such as crosspad-core or crosspad-gui means it is not open yet (see the note at the top). Anything else: project clone fails
Build it.
Terminal window
```
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug && cmake --build build
```
You should see: MIDI support enabled (RtMidi) and Audio support enabled (RtAudio) while CMake configures, then the build ends without error:.

If not: CMake cannot find SDL2, ALSA or DBus
Start it.
Terminal window
```
./bin/CrossPad
```
You should see: the CrossPad window, and [Remote] Listening on 127.0.0.1:19840 in the terminal.

If not: simulator window does not open. In a VM, WSL, a server or a container without sound or Bluetooth services: running without sound or Bluetooth

Folder paths must not contain spaces.

In PowerShell, install Git and the Visual Studio C++ build tools. The build tools take about 20 minutes, and Windows asks once for permission.

winget install --id Git.Git --exact --silent --scope user --accept-package-agreements --accept-source-agreements
winget install --id Microsoft.VisualStudio.2022.BuildTools --exact --silent --accept-package-agreements --accept-source-agreements --override "--quiet --wait --norestart --nocache --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.CMake.Project --includeRecommended"

Close PowerShell and open a new one, so it finds git.

You should see: git --version prints git version 2. and a number.

If not: git or Python not found after install

Install vcpkg into C:\vcpkg and use it to install SDL2.
Terminal window
```
git clone https://github.com/microsoft/vcpkg.git C:\vcpkg
C:\vcpkg\bootstrap-vcpkg.bat -disableMetrics
C:\vcpkg\vcpkg install sdl2:x64-windows
```
You should see: vcpkg ends with sdl2:x64-windows installed and no error: line.

If not: vcpkg cannot install SDL2
Download the simulator with its submodules.
Terminal window
```
git clone --recursive https://github.com/CrossPad/crosspad-pc.git C:\crosspad-pc
git -C C:\crosspad-pc submodule update --init --recursive
(git -C C:\crosspad-pc submodule status | Select-String '^-').Count
```
You should see: 0 on the last line (no submodule left out).

If not: a request for a GitHub login for a submodule such as crosspad-core or crosspad-gui means it is not open yet (see the note at the top). Anything else: project clone fails
Build it. Open x64 Native Tools Command Prompt for VS 2022 from the Start menu (it is a cmd window, not PowerShell) and run:
Terminal window
```
cd /d C:\crosspad-pc
cmake -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake -DCMAKE_BUILD_TYPE=Debug
cmake --build build
```
You should see: Copying SDL2.dll to output directory, and the build ends without error.

If not: CMake cannot find SDL2, ALSA or DBus
Start it, in the same window.
Terminal window
```
bin\CrossPad.exe
```
You should see: the CrossPad window, and [Remote] Listening on 127.0.0.1:19840 in the console.

If not: simulator window does not open

Simulator vs CrossPad

The simulator runs the same core, GUI and apps as the board. Where the hardware differs, an app sees this:

Part	On the CrossPad	In the simulator
Opening an app	The MODE map; your own apps over USB with `crosspad-hil app start`	A tile for every app in the launcher
Screen	Transport bar on top; app area 320×210	Status bar on top; app area 320×218
Transport bar (PLAY, STOP, BPM key) and `TempoChanged` events	Yes	Not present; an app can still set the tempo
Pads	Velocity, pressure (aftertouch) and left/right position	Mouse and keyboard at velocity 127; the remote-control port on 127.0.0.1:19840 sets any velocity
Pad LEDs	Colours and `PadAnimator` frames	Colours
Kit playback from an app (`postSamplePlayback`)	Pad, velocity, `transpose` and `key`	Pad and velocity
Note-off on a kit pad	Ends a pad in Hold mode	Ends a pad in Loop mode
MIDI out	Notes, control change, pitch bend, aftertouch, program change	Notes and control change
MIDI ports	USB and Bluetooth, as the player’s MIDI settings route them	The ports you choose with the MIDI OUT and MIDI IN jacks; on Linux the simulator picks them
Motion sensor, gestures, haptic motor	Yes	Not present: `isAvailable()` is false
`ISampleTools`, `IOutputLevels`	Yes	Null
HTTP client (`IHttpClient`)	Null	Yes, for tools that run on the computer
SD card	The card, at `/sdcard`	A folder you choose with the SD slot
Virtual serial ports (serial monitor app)	—	On Windows

Hardware for apps maps each part to its API.

Optional Run the simulator's tests (Linux)

From ~/crosspad-pc after a build:

ctest --test-dir build --output-on-failure -LE gui

Next: Build an app: every recipe runs in the simulator first. To begin from an empty app instead: Start from the template.