IDF Docker Image

IDF Docker image () is intended for building applications and libraries with specific versions of ESP-IDF, when doing automated builds.espressif/idf

The image contains:

• Common utilities such as git, wget, curl, zip.

• Python 3.7 or newer.

• A copy of a specific version of ESP-IDF (see below for information about versions). environment variable is set, and points to ESP-IDF location in the container.IDF_PATH

• All the build tools required for the specific version of ESP-IDF: CMake, ninja, cross-compiler toolchains, etc.

• All Python packages required by ESP-IDF are installed in a virtual environment.

The image entrypoint sets up environment variable to point to the correct version of tools, and activates the Python virtual environment. As a result, the environment is ready to use the ESP-IDF build system.PATH

The image can also be used as a base for custom images, if additional utilities are required.

Tags

Multiple tags of this image are maintained:

• latest: tracks branch of ESP-IDFmaster

• vX.Y: corresponds to ESP-IDF release vX.Y

• release-vX.Y: tracks branch of ESP-IDFrelease/vX.Y

Usage

Setting up Docker

Before using the Docker image locally, make sure you have Docker installed. Follow the instructions at Get Docker, if it is not installed yet.espressif/idf

If using the image in CI environment, consult the documentation of your CI service on how to specify the image used for the build process.

Building a project with CMake

In the project directory, run:

docker run --rm -v $PWD:/project -w /project espressif/idf idf.py build 

The above command explained:

• docker run: runs a Docker image. It is a shorter form of the command .docker container run

• --rm: removes the container when the build is finished

• -v $PWD:/project: mounts the current directory on the host () as directory in the container$PWD/project

• espressif/idf: uses Docker image with tag (implicitly added by Docker when no tag is specified)espressif/idflatest

• idf.py build: runs this command inside the container

To build with a specific Docker image tag, specify it as , for example:espressif/idf:TAG

docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.4 idf.py build 

You can check the up-to-date list of available tags at Docker.

Using the image interactively

It is also possible to do builds interactively, to debug build issues or test the automated build scripts. Start the container with -i -t flags:

docker run --rm -v $PWD:/project -w /project -it espressif/idf 

Then inside the container, use as usual:idf.py

idf.py menuconfig idf.py build 

Using remote serial port

The RFC2217 (Telnet) protocol can be used to remotely connect to a serial port. For more information please see the remote serial ports documentation in the esptool project. This method can also be used to access the serial port inside a Docker container if it cannot be accessed directly. Following is an example how to use the flash command from within a Docker container.

On host install and start :esp_rfc2217_server

• On Windows, package is available as a one-file bundled executable created by pyinstaller and it can be downloaded from the esptool releases page in a zip archive along with other esptool utilities:

  esp_rfc2217_server -v -p 4000 COM3 

• On Linux/MacOS, package is available as part of esptool which can be found in ESP-IDF environment or by installing using pip:

  pip install esptool 

  And then starting the server by executing:

  esp_rfc2217_server.py -v -p 4000 /dev/ttyUSB0 

Now the device attached to the host can be flashed from inside a Docker container by using:

docker run --rm -v <host_path>:/<container_path> -w /<container_path> espressif/idf idf.py --port rfc2217://host.docker.internal:4000?ign_set_control flash 

Please make sure that is properly set to your project path on the host and is set as a working directory inside the container with the option. The is a special Docker DNS name to access the host. This can be replaced with host IP if necessary.<host_path><container_path>-whost.docker.internal

Building custom images

The Dockerfile in ESP-IDF repository provides several build arguments which can be used to customize the Docker image:

• IDF_CLONE_URL: URL of the repository to clone ESP-IDF from. Can be set to a custom URL when working with a fork of ESP-IDF. Default is .https://github.com/espressif/esp-idf.git

• IDF_CLONE_BRANCH_OR_TAG: Name of a git branch or tag use when cloning ESP-IDF. This value is passed to command using the argument. Default is .git clone--branchmaster

• IDF_CHECKOUT_REF: If this argument is set to a non-empty value, command will be performed after cloning. This argument can be set to the SHA of the specific commit to check out, for example if some specific commit on a release branch is desired.git checkout $IDF_CHECKOUT_REF

• IDF_CLONE_SHALLOW: If this argument is set to a non-empty value, arguments will be used when performing . This significantly reduces the amount of data downloaded and the size of the resulting Docker image. However, if switching to a different branch in such a “shallow” repository is necessary, an additional command must be executed first.--depth=1 --shallow-submodulesgit clonegit fetch origin <branch>

• IDF_INSTALL_TARGETS: Comma-separated list of IDF targets to install toolchains for, or to install toolchains for all targets. Selecting specific targets reduces the amount of data downloaded and the size of the resulting Docker image. Default is .allall

To use these arguments, pass them via the command line option. For example, the following command will build a Docker image with a shallow clone of ESP-IDF v4.4.1 and tools for ESP32-C3, only:--build-arg

docker build -t idf-custom:v4.4.1-esp32c3 \ --build-arg IDF_CLONE_BRANCH_OR_TAG=v4.4.1 \ --build-arg IDF_CLONE_SHALLOW=1 \ --build-arg IDF_INSTALL_TARGETS=esp32c3 \ tools/docker