Skip to content
CrossPad Docs

Use several ESP-IDF versions

Goal: Keep your other ESP-IDF versions while CrossPad uses 5.5.x (minimum 5.5.4, tested 5.5.5; 6.x releases are not supported).

You need: Start here done, or about to run the one-line installer. Switching versions by sourcing an export script is in Several ESP-IDF versions side by side; this page is about how the installer picks one.

The installer never changes an ESP-IDF it did not install. It uses a 5.5.x it finds, or adds its own next to yours, and only CrossPad’s commands use that choice.

  1. Make this terminal forget other ESP-IDFs

    Another ESP-IDF loaded in this terminal gets in the way of the install, so clear it here, as in the ESP-IDF tools step of 1. Set up the toolchain (step 4 on Linux, step 5 on macOS and Windows). Run the next steps in this same terminal.

    Terminal window
    unset IDF_PATH IDF_PYTHON_ENV_PATH
    PATH=$(printf %s "$PATH" | tr : '\n' | grep -v -e /.espressif/ -e /esp-idf | paste -sd: -)

    You should see: no output. Your other terminals and your shell profile are unchanged.

    If not: Python environment is set to … which was generated for another ESP-IDF

  2. Run the installer next to your other versions

    If ~/esp/esp-idf holds another version, the installer puts 5.5 in ~/esp/esp-idf-v5.5 (Windows: C:\CrossPad\esp-idf-v5.5) and leaves yours untouched.

    Terminal window
    curl -fsSL https://raw.githubusercontent.com/CrossPad/crosspad-apps/main/install/install.sh | bash

    You should see: in the ESP-IDF step, a note about the versions it found, then the line for CrossPad’s copy:

      found ESP-IDF <version> at <dir> — CrossPad needs 5.5; it goes next to them, yours stay as they are
      ✓ ESP-IDF v5.5.5 at <home>/esp/…

    The folder in the last line is ~/esp/esp-idf-v5.5 with your home folder spelled out. Windows prints [OK] ESP-IDF v5.5.5 at C:\CrossPad\esp-idf-v5.5, and a - in place of the —.

    If not: The installer picked a different ESP-IDF. If it stops at a red line: The one-line installer stops with an error.

  3. Reuse an ESP-IDF from EIM or the VS Code extension

    Installed ESP-IDF 5.5.x with EIM (Espressif Installation Manager) or the VS Code ESP-IDF extension? Run the installer from step 2 without a pin; it finds that install through esp_idf.json and uses it as it is.

    You should see:

      found your ESP-IDF <version> at <dir> — using it as it is
      ✓ ESP-IDF … at <dir>

    On Windows the second line starts with [OK].

    If not: The installer picked a different ESP-IDF

  4. Pin a specific 5.5.x install

    The installer does not check the version of a pinned tree, so point CROSSPAD_IDF_DIR only at a 5.5.x checkout of https://github.com/espressif/esp-idf.git. The pin lasts for this terminal (on Windows the ESP-IDF tools stay in C:\CrossPad\.espressif); pass it again on every re-run, or the installer re-detects and the highest 5.5.x patch wins.

    Terminal window
    export CROSSPAD_IDF_DIR=/path/to/your/esp-idf IDF_TOOLS_PATH=~/.espressif
    curl -fsSL https://raw.githubusercontent.com/CrossPad/crosspad-apps/main/install/install.sh | bash

    You should see: no found … note this time, because a pin skips the search. The ESP-IDF step ends with ✓ ESP-IDF v<version> at /path/to/your/esp-idf (Windows: [OK] ESP-IDF v<version> at C:\path\to\your\esp-idf).

    If not: a line your ESP-IDF at … does not start means the pinned tree or its tools need a fresh install: The one-line installer stops with an error. A different folder in the line: The installer picked a different ESP-IDF.

Check it worked

Section titled “Check it worked”

The installer prints ✓ ESP-IDF v<version> at <dir> (Windows: [OK] ESP-IDF v<version> at <dir>) with your chosen directory. Then run the CP Tools doctor from the project root (~/CrossPad, Windows C:\CrossPad\firmware) with CrossPad’s ESP-IDF loaded; after the one-line installer, cptools doctor does the same.

Terminal window
python3 tools/app_manager.py doctor

You should see: ESP-IDF ok in the Tools row:

  [OK ] Tools                ESP-IDF ok, git ok, Python …

With no board plugged in, the doctor also notes that it found no board.

If not: CP Tools uses the wrong ESP-IDF. For other [BAD] rows: Doctor reports things to fix.

Section titled “Related”