ESP-IDF

ESP-IDF is the official framework to develop programs for the Espressif Systems ESP32 series microcontrollers. This guide explains how to install and use ESP-IDF on NixOS (I have not tested this on non-NixOS systems, but it might also work).

Setting up the toolchain

ESP-IDF uses the Xtensa ESP32 GCC toolchain. Espressif hosts prebuilt binaries on their website. Sadly, these are not statically compiled, and do not work on NixOS without the use of a FHS environment. I will use buildFHSUserEnv to make the binaries work. Let's make a derivation out of this:

{ stdenv, lib, fetchurl, makeWrapper, buildFHSUserEnv }:

let
  fhsEnv = buildFHSUserEnv {
    name = "esp32-toolchain-env";
    targetPkgs = pkgs: with pkgs; [ zlib ];
    runScript = "";
  };
in

stdenv.mkDerivation rec {
  pname = "esp32-toolchain";
  version = "2021r2";

  src = fetchurl {
    url = "https://github.com/espressif/crosstool-NG/releases/download/esp-${version}/xtensa-esp32-elf-gcc8_4_0-esp-${version}-linux-amd64.tar.gz";
    hash = "sha256-PrPWiyf6a6Wvb4jaIcuPrOm+AJTaqolgeTz+Vwq3hf8=";
  };

  buildInputs = [ makeWrapper ];

  phases = [ "unpackPhase" "installPhase" ];

  installPhase = ''
    cp -r . $out
    for FILE in $(ls $out/bin); do
      FILE_PATH="$out/bin/$FILE"
      if [[ -x $FILE_PATH ]]; then
        mv $FILE_PATH $FILE_PATH-unwrapped
        makeWrapper ${fhsEnv}/bin/esp32-toolchain-env $FILE_PATH --add-flags "$FILE_PATH-unwrapped"
      fi
    done
  '';

  meta = with lib; {
    description = "ESP32 toolchain";
    homepage = https://docs.espressif.com/projects/esp-idf/en/stable/get-started/linux-setup.html;
    license = licenses.gpl3;
  };
}

Create a new directory ~/esp and save this derivation as ~/esp/esp-toolchain.nix.

Note: You can choose any other location instead of ~/esp. This guide assumes that the location is ~/esp.

Setting up ESP-IDF and the development shell

Clone the espressif/esp-idf repository:

cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git

Now that we have ESP-IDF in place, it's time to set up the nix-shell environment with all the dependencies we need.

Note that this environment uses a Python virtual environment and pip to get all the necessary Python dependencies, which is easier to keep up to date than using Python packages from Nix (at the cost of some reproducibility). The virtual environment is created if it doesn't already exist. When updating ESP-IDF, delete the .python_env directory and re-run nix-shell.

{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  name = "esp-idf-env";

  buildInputs = with pkgs; [
    (pkgs.callPackage ./esp32-toolchain.nix {})

    git
    wget
    gnumake

    flex
    bison
    gperf
    pkgconfig

    cmake

    ncurses5

    ninja

    (python3.withPackages (p: with p; [
      pip
      virtualenv
    ]))
  ];

  shellHook = ''
    export IDF_PATH=$(pwd)/esp-idf
    export PATH=$IDF_PATH/tools:$PATH
    export IDF_PYTHON_ENV_PATH=$(pwd)/.python_env

    if [ ! -e $IDF_PYTHON_ENV_PATH ]; then
      python -m venv $IDF_PYTHON_ENV_PATH
      . $IDF_PYTHON_ENV_PATH/bin/activate
      pip install -r $IDF_PATH/requirements.txt
    else
      . $IDF_PYTHON_ENV_PATH/bin/activate
    fi
  '';
}

Save this as ~/esp/shell.nix.

You can now enter the development shell with the ESP32 toolchain and dependencies of ESP-IDF:

cd ~/esp
nix-shell

That's all you need to start developing with ESP-IDF on NixOS! The next step is to follow the ESP-IDF Get Started guide from section "Start a project" onward.

See also

• esp32.nix provides nix expression for building the esp32 sdk as well as micropython.
• esp32-baremetal has an example how to build esp32 firmware without relying on an sdk.
• tutorial for setting up the prebuilt toolchain with vscode