Skip to content
CrossPad Docs

Install and remove apps

Goal: An app from the catalog running on your board, and the way back out.

You need: Start here done, including the first flash.

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. Prefer menus? CP Tools does the same from a full-screen menu: python3 tools/app_manager.py (Windows python tools\app_manager.py; one-line installer: cptools).

  1. List the catalog

    The list comes from the app catalog on GitHub. It needs no GitHub account, and your computer keeps a copy for an hour.

    Terminal window
    idf.py app-list

    You should see:

    CrossPad Apps (platform: esp-idf):
    ---------------------------------------------------------------------------
    

      Official:
      [ ] pitchplay        One sample or many, played chromatically on the pads and from a MIDI keyboard
      [ ] recorder         Record a sample from the mics, the line-in or the pads, and trim it to a loop
      …
    

      …/… compatible installed  (15 total in registry)

    An installed app is marked [✓]. Apps for other platforms are hidden; add --all to see them.

    If not: idf.py says app-list is not known. If it says No connection, and no app list saved on this computer yet.: app-list says No connection.

  2. Install an app

    The app’s repository becomes a git submodule in components/. On a fresh checkout the catalog apps are already there, so this only records the app (Submodule already exists at components/<repo>, registering in manifest.).

    Terminal window
    idf.py app-install --app recorder

    You should see:

    Installing Recorder...
      Repo: https://github.com/CrossPad/<repo>.git
      Path: components/<repo>
      Ref:  main
    …
    

      Recorder installed successfully.
    

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

    If not: app-install says Failed to add submodule. For an app whose repo’s default branch is master, add --ref master. More: app-update skips an app.

  3. Rebuild from a clean build folder

    The build finds added and removed 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: Generated app_registry_init.cpp with N apps: … while CMake configures, with Recorder in that list, and Project build complete. To flash, run: at the end.

    If not: build stops before Project build complete. If the app is not in the 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 icons

    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. Remove an app

    This saves a backup of any local work in the app, then deletes its submodule. Afterwards rebuild from a clean build folder (step 3), flash again (steps 4 and 5), and commit the changed .gitmodules if the project should keep the change.

    Terminal window
    idf.py app-remove --app recorder

    You should see:

    Removing Recorder...
    …
    

      Recorder removed.
    

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

    If there was local work, two extra lines name it and the backup folder under .crosspad/backups/recorder/.

    If not: App 'recorder' is not installed. means the project has no record of the app: install it first (step 2). If idf.py does not know app-remove: idf.py says app-list is not known.

Check it worked

Section titled “Check it worked”
Terminal window
idf.py app-list

The installed app is marked [✓] with its branch and commit, for example [✓] recorder … [main @ 1a2b3c4d], and the last line counts the installed apps. On the board, the app has a tile with its icon in the launcher.

Section titled “Related”