ESP-IDF - Revision history

Whitebow: Updated the requirements path to reflect ESP-IDF v5.0 removal of the root requirements.txt file. This still needs updating, as it doesn't currently result in a working ESP-IDF environment.

2026-04-17T10:59:37Z

Updated the requirements path to reflect ESP-IDF v5.0 removal of the root requirements.txt file. This still needs updating, as it doesn't currently result in a working ESP-IDF environment.

← Older revision		Revision as of 10:59, 17 April 2026
Line 22:		Line 22:

	== The manual way ==		== The manual way ==
	If you want to set up the environment yourself, here is one way to do it.		If you want to set up the environment yourself, here is one way to do it.

			{{Warning\|As of ESP-IDF v5.0, the following guide does not work properly and results in errors. Any contributions toward a fix would be appreciated.}}

	=== Setting up the toolchain ===		=== Setting up the toolchain ===
Line 121:		Line 123:
	python -m venv $IDF_PYTHON_ENV_PATH		python -m venv $IDF_PYTHON_ENV_PATH
	. $IDF_PYTHON_ENV_PATH/bin/activate		. $IDF_PYTHON_ENV_PATH/bin/activate
	pip install -r $IDF_PATH/requirements.txt		pip install -r $IDF_PATH/tools/requirements/requirements.core.txt
	else		else
	. $IDF_PYTHON_ENV_PATH/bin/activate		. $IDF_PYTHON_ENV_PATH/bin/activate

Whitebow: Changed esp32-idf to esp-idf-full : device-specific shells are deprecated and will be removed with ESP-IDF v6.0.

2026-04-17T10:54:56Z

Changed esp32-idf to esp-idf-full : device-specific shells are deprecated and will be removed with ESP-IDF v6.0.

← Older revision		Revision as of 10:54, 17 April 2026
Line 6:		Line 6:

	<syntaxhighlight lang="sh">		<syntaxhighlight lang="sh">
	nix --experimental-features 'nix-command flakes' develop github:mirrexagon/nixpkgs-esp-dev#~~esp32~~-idf		nix --experimental-features 'nix-command flakes' develop github:mirrexagon/nixpkgs-esp-dev#esp-idf-full
	</syntaxhighlight>		</syntaxhighlight>

Jthoward: Link to archive.org for broken link to vscode tutorial

2025-08-18T20:14:52Z

Link to archive.org for broken link to vscode tutorial

← Older revision		Revision as of 20:14, 18 August 2025
Line 146:		Line 146:
	* [https://github.com/bgamari/esp32.nix esp32.nix] provides nix expression for building the esp32 sdk as well as micropython.		* [https://github.com/bgamari/esp32.nix esp32.nix] provides nix expression for building the esp32 sdk as well as micropython.
	* [https://github.com/taktoa/esp32-baremetal esp32-baremetal] has an example how to build esp32 firmware without relying on an sdk.		* [https://github.com/taktoa/esp32-baremetal esp32-baremetal] has an example how to build esp32 firmware without relying on an sdk.
	* [https://specific.solutions.limited/projects/hanging-plotter/electronics tutorial] for setting up the prebuilt toolchain with vscode		* [https://web.archive.org/web/20240621182952/https://specific.solutions.limited/projects/hanging-plotter/electronics tutorial] for setting up the prebuilt toolchain with vscode

	[[Category:Guide]]		[[Category:Guide]]

imported>Mse63: pkgconfig has been replaced by pkg-config

2024-01-14T18:34:05Z

pkgconfig has been replaced by pkg-config

← Older revision		Revision as of 18:34, 14 January 2024
Line 99:		Line 99:
	bison		bison
	gperf		gperf
	~~pkgconfig~~		pkg-config

	cmake		cmake

imported>Olafklingt: update version for manual toolchain

2022-06-11T18:20:28Z

update version for manual toolchain

← Older revision		Revision as of 18:20, 11 June 2022
Line 25:		Line 25:

	=== Setting up the toolchain ===		=== Setting up the toolchain ===
	ESP-IDF uses the Xtensa ESP32 GCC toolchain. Espressif hosts the official [https://github.com/espressif/crosstool-NG/releases prebuilt binaries] on GitHub. Sadly, these are not statically compiled, and do not work on NixOS without the use of a FHS environment. I will use <code>buildFHSUserEnv</code> to make the binaries work. Let's make a derivation out of this:		ESP-IDF uses the Xtensa or risc-v32 ESP32 GCC toolchain. Espressif hosts the official [https://github.com/espressif/crosstool-NG/releases prebuilt binaries] on GitHub. Sadly, these are not statically compiled, and do not work on NixOS without the use of a FHS environment. I will use <code>buildFHSUserEnv</code> to make the binaries work. Let's make a derivation out of this:

	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">
Line 40:		Line 40:
	stdenv.mkDerivation rec {		stdenv.mkDerivation rec {
	pname = "esp32-toolchain";		pname = "esp32-toolchain";
	version = "2021r2";		version = "2021r2-patch3";

	src = fetchurl {		src = fetchurl {
			# url = "https://github.com/espressif/crosstool-NG/releases/download/esp-${version}/riscv32-esp-elf-gcc8_4_0-esp-${version}-linux-amd64.tar.gz";
			# hash = "sha256-F5y61Xl5CtNeD0FKGNkAF8DxWMOXAiQRqOmGfbIXTxU=";
	url = "https://github.com/espressif/crosstool-NG/releases/download/esp-${version}/xtensa-esp32-elf-gcc8_4_0-esp-${version}-linux-amd64.tar.gz";		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~~=";		hash = "sha256-nt0ed2J2iPQ1Vhki0UKZ9qACG6H2/2fkcuEQhpWmnlM=";
	};		};

Line 87:		Line 89:
	pkgs.mkShell {		pkgs.mkShell {
	name = "esp-idf-env";		name = "esp-idf-env";

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

imported>Mirrexagon: Add easy setup with nixpkgs-esp-dev

2021-11-14T05:22:37Z

Add easy setup with nixpkgs-esp-dev

@@ Line 1: / Line 1: @@
 [https://github.com/espressif/esp-idf ESP-IDF] is the official framework to develop programs for the Espressif Systems [https://en.wikipedia.org/wiki/ESP32 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).
+This guide explains how to install and use ESP-IDF on NixOS.
-== Setting up the toolchain ==
+== The easy way ==
-ESP-IDF uses the Xtensa ESP32 GCC toolchain. Espressif hosts [https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz 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 <code>buildFHSUserEnv</code> to make the binaries work. Let's make a derivation out of this:
+The ESP32 toolchain and ESP-IDF have been packaged in https://github.com/mirrexagon/nixpkgs-esp-dev. If you have Nix 2.4 or later, you can get a shell with everything you need to build ESP-IDF projects for ESP32 with this command (no need to download anything yourself):
 <syntaxhighlight lang="nix">
@@ Line 51: / Line 73: @@
 {{note| You can choose any other location instead of <code>~/esp</code>. This guide assumes that the location is <code>~/esp</code>.}}
-== Setting up ESP-IDF and the development shell ==
+=== Setting up ESP-IDF and the development shell ===
 Clone the [https://github.com/espressif/esp-idf espressif/esp-idf] repository:
 <syntaxhighlight lang="sh">

imported>Mirrexagon: Move Python venv note below shell.nix and put in Note: box

2021-11-03T05:27:47Z

Move Python venv note below shell.nix and put in Note: box

← Older revision		Revision as of 05:27, 3 November 2021
Line 59:		Line 59:

	Now that we have ESP-IDF in place, it's time to set up the <code>nix-shell</code> environment with all the dependencies we need.		Now that we have ESP-IDF in place, it's time to set up the <code>nix-shell</code> 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 <code>.python_env</code> directory and re-run <code>nix-shell</code>.

	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">
Line 115:		Line 113:
	nix-shell		nix-shell
	</syntaxhighlight>		</syntaxhighlight>

			{{note\|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 <code>.python_env</code> directory and re-run <code>nix-shell</code>.}}

	That's all you need to start developing with ESP-IDF on NixOS!		That's all you need to start developing with ESP-IDF on NixOS!

imported>Mirrexagon: Updated toolchain derivation to latest as of 2021-11-03, overhauled shell.nix to create a Python venv

2021-11-03T05:25:24Z

Updated toolchain derivation to latest as of 2021-11-03, overhauled shell.nix to create a Python venv

← Older revision		Revision as of 05:25, 3 November 2021
Line 17:		Line 17:

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

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

Line 52:		Line 52:

	== Setting up ESP-IDF and the development shell ==		== Setting up ESP-IDF and the development shell ==
	Clone the [https://github.com/espressif/esp-idf ~~Espressif~~/esp-idf] repository:		Clone the [https://github.com/espressif/esp-idf espressif/esp-idf] repository:
	<syntaxhighlight lang="sh">		<syntaxhighlight lang="sh">
	cd ~/esp		cd ~/esp
Line 58:		Line 58:
	</syntaxhighlight>		</syntaxhighlight>

	Now that we have ESP-IDF in place, it's time to set up the nix-shell environment with all the dependencies we need:		Now that we have ESP-IDF in place, it's time to set up the <code>nix-shell</code> 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 <code>.python_env</code> directory and re-run <code>nix-shell</code>.

	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">
	{ ~~nixpkgs~~ ? import <nixpkgs> {} }:		{ pkgs ? import <nixpkgs> {} }:

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

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

			git
			wget
			gnumake

			flex
			bison
			gperf
			pkgconfig

	~~let~~		cmake
	~~inherit (nixpkgs) pkgs;~~

	~~# esp-idf as of Nov 2019 requires pyparsing < 2.4~~		ncurses5
	~~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 {~~		ninja
	~~name = "esp-idf-env";~~
	~~src = ./esp-idf;~~		(python3.withPackages (p: with p; [
	~~dontBuild = true;~~		pip
	~~dontConfigure = true;~~		virtualenv
	~~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 = ''		shellHook = ''
	export ~~NIX_CFLAGS_LINK~~=-~~lncurses~~		export IDF_PATH=$(pwd)/esp-idf
	export ~~IDF_PATH~~=$~~HOME~~/~~esp/esp-idf~~		export PATH=$IDF_PATH/tools:$PATH
	export ~~IDF_TOOLS_PATH~~=$~~HOME~~/~~esp~~/~~esp~~-~~idf~~/~~tools~~		export IDF_PYTHON_ENV_PATH=$(pwd)/.python_env
	~~export PATH="~~$~~IDF_TOOLS_PATH:$PATH"~~
			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
	'';		'';
	}		}
	</syntaxhighlight>		</syntaxhighlight>

	Save this as <code>~/esp/~~default~~.nix</code>.		Save this as <code>~/esp/shell.nix</code>.

	You can now enter the development shell with the ESP32 toolchain and dependencies of ESP-IDF:		You can now enter the development shell with the ESP32 toolchain and dependencies of ESP-IDF:
	<syntaxhighlight lang="sh">		<syntaxhighlight lang="sh">
	cd ~/esp		cd ~/esp
	nix-shell .		nix-shell
	</syntaxhighlight>		</syntaxhighlight>

Line 113:		Line 121:
	== See also ==		== See also ==

	* [https://github.com/bgamari/esp32.nix esp32.nix] provides nix expression for building the ~~exp32~~ sdk as well as micropython.		* [https://github.com/bgamari/esp32.nix esp32.nix] provides nix expression for building the esp32 sdk as well as micropython.
	* [https://github.com/taktoa/esp32-baremetal esp32-baremetal] has an example how to build esp32 firmware without relying on an sdk.		* [https://github.com/taktoa/esp32-baremetal esp32-baremetal] has an example how to build esp32 firmware without relying on an sdk.
	* [https://specific.solutions.limited/projects/hanging-plotter/electronics tutorial] for setting up the prebuilt toolchain with vscode		* [https://specific.solutions.limited/projects/hanging-plotter/electronics tutorial] for setting up the prebuilt toolchain with vscode

	[[Category:Guide]]		[[Category:Guide]]

imported>Bendlas: mention vscode in comment for tutorial link

2021-05-23T18:59:19Z

mention vscode in comment for tutorial link

← Older revision		Revision as of 18:59, 23 May 2021
Line 115:		Line 115:
	* [https://github.com/bgamari/esp32.nix esp32.nix] provides nix expression for building the exp32 sdk as well as micropython.		* [https://github.com/bgamari/esp32.nix esp32.nix] provides nix expression for building the exp32 sdk as well as micropython.
	* [https://github.com/taktoa/esp32-baremetal esp32-baremetal] has an example how to build esp32 firmware without relying on an sdk.		* [https://github.com/taktoa/esp32-baremetal esp32-baremetal] has an example how to build esp32 firmware without relying on an sdk.
	* [https://specific.solutions.limited/projects/hanging-plotter/electronics tutorial] for setting up the prebuilt toolchain~~, similar to esp32.nix, but~~ with ~~buildFHSUserEnv~~		* [https://specific.solutions.limited/projects/hanging-plotter/electronics tutorial] for setting up the prebuilt toolchain with vscode

	[[Category:Guide]]		[[Category:Guide]]

imported>Bendlas: add blog article to see-also

2021-05-23T18:54:00Z

add blog article to see-also

← Older revision		Revision as of 18:54, 23 May 2021
Line 115:		Line 115:
	* [https://github.com/bgamari/esp32.nix esp32.nix] provides nix expression for building the exp32 sdk as well as micropython.		* [https://github.com/bgamari/esp32.nix esp32.nix] provides nix expression for building the exp32 sdk as well as micropython.
	* [https://github.com/taktoa/esp32-baremetal esp32-baremetal] has an example how to build esp32 firmware without relying on an sdk.		* [https://github.com/taktoa/esp32-baremetal esp32-baremetal] has an example how to build esp32 firmware without relying on an sdk.
			* [https://specific.solutions.limited/projects/hanging-plotter/electronics tutorial] for setting up the prebuilt toolchain, similar to esp32.nix, but with buildFHSUserEnv

	[[Category:Guide]]		[[Category:Guide]]