10-minute quickstart

Goal: an example app running in the CrossPad simulator on your computer, with “Pressed 1 time” on its screen.

You need:

• A computer with Linux (Ubuntu or Debian) or Windows 10 or 11, and an internet connection.
• No CrossPad board and no ESP-IDF. The simulator runs the same core, GUI and apps as the board, in a window.
• About 10 minutes on Linux, most of it downloads. On Windows the Visual Studio build tools alone take about 20 minutes.

You build the simulator and start it once, so you know it works. Then you copy the Hello screen example into it, build again and open the app.

Some repositories open soon

crosspad-core, crosspad-gui and the built-in apps, which the simulator’s clone downloads as submodules, open soon, and so does crosspad-examples, where the example app comes from. Until they open, these steps need access to the CrossPad organisation on GitHub: ask the CrossPad team for it in the CrossPad Discord.

Linux

These commands are for Ubuntu and Debian.

1. 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

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

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

2. Download the simulator with its submodules.

   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

3. Build it.

   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

4. Start it.

   ./bin/CrossPad

   You should see: the CrossPad window with the launcher, and [Remote] Listening on 127.0.0.1:19840 in the terminal. Close the window before the next step.

   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

5. Download the examples next to the simulator, and copy Hello screen into it.

   cd ~
   git clone https://github.com/CrossPad/crosspad-examples.git
   cd crosspad-examples
   python3 tools/install.py --target pc ~/crosspad-pc hello-screen

   You should see: installed example-hello-screen -> …/src/apps/crosspad-example-hello-screen.

   If not: a request for a GitHub login, or Repository not found, means the repository is not open yet (see the note at the top). has no src/apps/ means the path after --target pc is not your simulator folder.

6. Build the simulator again. It looks for apps while CMake configures, so configure again before you build. cmake -B build reuses the settings of step 3.

   cd ~/crosspad-pc
   cmake -B build
   cmake --build build

   You should see: a line starting -- App submodule: crosspad-example-hello-screen while CMake configures, and a build that ends without error.

   If not: a new app does not show up

7. Start the simulator and click the HelloScreen tile in the launcher.

   ./bin/CrossPad

   You should see: “Hello, CrossPad”, a Press me button, the line “Pressed 0 times”, and the Details and ✕ Close buttons.

   If not: no HelloScreen tile: a new app does not show up

8. Click Press me.

   You should see: “Pressed 1 time”.

Windows

Folder paths must not contain spaces.

1. In PowerShell, install Git, Python 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 Python.Python.3.12 --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 and python.

   You should see: git --version prints git version 2. and a number, and python --version prints Python 3. and a number.

   If not: git or Python not found after install

2. Install vcpkg into C:\vcpkg and use it to install SDL2.

   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

3. Download the simulator with its submodules.

   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

4. Build it. Open x64 Native Tools Command Prompt for VS 2022 from the Start menu (it is a cmd window, not PowerShell) and run:

   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

5. Start it, in the same window.

   bin\CrossPad.exe

   You should see: the CrossPad window with the launcher, and [Remote] Listening on 127.0.0.1:19840 in the console. Close the window before the next step.

   If not: simulator window does not open

6. Download the examples next to the simulator, and copy Hello screen into it. Stay in the same Native Tools window.

   cd /d C:\
   git clone https://github.com/CrossPad/crosspad-examples.git
   cd crosspad-examples
   python tools\install.py --target pc C:\crosspad-pc hello-screen

   You should see: installed example-hello-screen -> …\src\apps\crosspad-example-hello-screen.

   If not: a request for a GitHub login, or Repository not found, means the repository is not open yet (see the note at the top). has no src/apps/ means the path after --target pc is not your simulator folder.

7. Build the simulator again. It looks for apps while CMake configures, so configure again before you build. cmake -B build reuses the settings of step 4.

   cd /d C:\crosspad-pc
   cmake -B build
   cmake --build build

   You should see: a line starting -- App submodule: crosspad-example-hello-screen while CMake configures, and a build that ends without error.

   If not: a new app does not show up

8. Start the simulator and click the HelloScreen tile in the launcher.

   bin\CrossPad.exe

   You should see: “Hello, CrossPad”, a Press me button, the line “Pressed 0 times”, and the Details and ✕ Close buttons.

   If not: no HelloScreen tile: a new app does not show up

9. Click Press me.

   You should see: “Pressed 1 time”.

What you did

• You built the simulator, the PC version of the CrossPad: the same core, GUI and apps as the board, in a window. The mouse plays it: a left click on the screen is a tap, the wheel turns the encoder and the middle button presses it. The power button is the round button under the encoder, or the Space key.
• You added an app the way every app is added: its folder goes where the build looks for apps (src/apps/ in the simulator), and the next configure finds it.

Next

• Hello screen: the app you ran, line by line, and how to run it on a CrossPad.
• Build an app: six more recipes, from pads and LEDs to MIDI out.
• Start here: the toolchain, the firmware build and the flash, for when you have a board.