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 {
  name = "esp32-toolchain";
  version = "1.22.0";

  src = fetchurl {
    url = "https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz";
    sha256 = "0mji8jq1dg198z8bl50i0hs3drdqa446kvf6xpjx9ha63lanrs9z";
  };

  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:

{ nixpkgs ? import <nixpkgs> {} }:

let
  inherit (nixpkgs) pkgs;

  # esp-idf as of Nov 2019 requires pyparsing < 2.4
  python2 = let
    packageOverrides = self: super: {
            pyparsing = super.pyparsing.overridePythonAttrs( old: rec {
                version = "2.3.1";
                src = super.fetchPypi {
                    pname="pyparsing";
                    inherit version;
                    sha256="66c9268862641abcac4a96ba74506e594c884e3f57690a696d21ad8210ed667a";
                };
        });
    };
    in pkgs.python2.override{inherit packageOverrides; self= python2;};
in

pkgs.stdenv.mkDerivation {
  name = "esp-idf-env"; 
  src = ./esp-idf;
  dontBuild = true;
  dontConfigure = true;
  buildInputs = with pkgs; [
    gawk gperf gettext automake bison flex texinfo help2man libtool autoconf ncurses5 cmake glibcLocales
    (python2.withPackages (ppkgs: with ppkgs; [ pyserial future cryptography setuptools pyelftools pyparsing click ]))
    (pkgs.callPackage ~/esp/esp32-toolchain.nix {})
  ];
  shellHook = ''
    export NIX_CFLAGS_LINK=-lncurses
    export IDF_PATH=$HOME/esp/esp-idf
    export IDF_TOOLS_PATH=$HOME/esp/esp-idf/tools
    export PATH="$IDF_TOOLS_PATH:$PATH"
  '';
}

Save this as ~/esp/default.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 exp32 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