Skip to content
CrossPad Docs

Start from the template

Goal: A new app of your own, built into the firmware and open on the board, and in the simulator from its launcher.

You need: Start here done, including the first flash (board revision set in 2. Build the firmware). No GitHub account is needed to create an app; publishing it needs gh auth login.

When to choose it: for an empty app that carries your own id and names from the first command. To start from working code instead, copy the cookbook example closest to your idea: Make an example your own. New to CrossPad apps? Do Hello screen first: it runs in the simulator and explains every line.

Run every command from the project root (~/CrossPad, Windows C:\CrossPad\firmware) with ESP-IDF loaded as in 2. Build the firmware. Used the one-line installer? Use crosspad-idf in place of idf.py.

  1. Generate the app from the template

    The command copies the app template into components/crosspad-my-app, as a folder with its own git repository. Make the id of lowercase letters, digits and dashes, starting with a letter; the C++ class and the app’s name become the id in CamelCase, here MyApp.

    Terminal window
    idf.py app-new --app my-app --name "My App" --category music

    You should see:

      … file(s) generated
      git repository initialised
      placed at components/crosspad-my-app (no remote)
    

      my-app ready at components/crosspad-my-app
    

      Next: idf.py -B build_v2 -DSDKCONFIG=sdkconfig.v2 fullclean && idf.py -B build_v2 -DSDKCONFIG=sdkconfig.v2 build

    If not: idf.py app-new stops with an error. If idf.py does not know app-new: idf.py says app-list is not known.

  2. Write the app

    Edit the sources in components/crosspad-my-app/src/. The template already registers the app at the end of MyAppApp.cpp with REGISTER_APP_PL; keep that line in src/, because the build only looks for registrations there.

    You should see: MyAppApp.cpp and MyAppPadLogic.cpp in components/crosspad-my-app/src/, and a line starting REGISTER_APP_PL(MyApp, near the end of MyAppApp.cpp.

    If not: a new app does not show up

  3. Rebuild from a clean build folder

    The build finds new apps only when it configures from scratch, so clean the build folder first.

    Terminal window
    idf.py -B build_v2 fullclean
    idf.py -B build_v2 -DSDKCONFIG=sdkconfig.v2 build

    You should see: the three app lines shown under Check it worked while CMake configures, and Project build complete. To flash, run: at the end.

    If not: build stops before Project build complete. If the build completes but MyApp is not in the app list: a new app does not show up.

  4. Flash the firmware over USB

    Answer the board’s prompts as in 3. Flash the board: Allow, then Update, then leave the board alone for 10 seconds.

    Terminal window
    python3 tools/ota_flash.py

    You should see:

    OTA complete! (…s, … KB/s)
    Device restarting...
    Running slot: trial

    If not: OTA flash cannot find the board, or OTA times out waiting for confirmation.

  5. Flash the app icon

    App icons live in the assets partition, which you send separately from the firmware.

    Terminal window
    python3 tools/fs_transfer.py assets

    You should see:

    Device ready. Streaming (nothing is erased until the CRC matches)...
    Assets written and verified. The device is restarting.

    If not: OTA flash cannot find the board. If it says Error: no assets.bin for this board, run step 3 again.

  6. Open the app

    Hit pad 1 on the MODE map to open the Sampler. Then, with the board on USB, start the app with the crosspad-hil command-line tool, from the venv you made in 1. Set up the toolchain. Used the one-line installer? Skip the first line: crosspad-hil already works.

    Terminal window
    . ~/CrossPad/.venv/bin/activate
    crosspad-hil app start MyApp

    The command needs the board in MIDI + Serial mode. If the board is in another mode, run crosspad-hil usb-mode set default, press Allow on the board, and start the app again. From another app, open yours with mode_overlay_open_app("MyApp").

    You should see: running=MyApp in the terminal, and on the board the template’s screen: ◀ Back and My App at the top, a tank with fish, + Fish, - Fish and Feed, and a speed slider. ◀ Back or a short press of the power button closes it.

Check it worked

Section titled “Check it worked”

The build output from step 3 lists your app (somewhere inside each list, not at the end):

App component requires: ...;crosspad-my-app;...
Generated app_registry_init.cpp with N apps: ...;MyApp;...
Assets: staged 1 assets from component 'crosspad-my-app'

After the flash, the board knows the app as MyApp (crosspad-hil app list lists it): the class name, not the name in the manifest. In the simulator, the launcher has a tile labelled MyApp with the template’s icon.

Next

Section titled “Next”

Make the app do something. Build an app maps each kind of app (instrument, MIDI controller, sequencer, an app with a UI) to the recipe that shows it, and every recipe in the cookbook is a small complete app you can copy from: start with Hello screen, and read How an app works before your app does more than draw a screen. When it is ready for others, publish it.

Section titled “Related”