The ESP-MDF GitHub repository is updated regularly, especially on the “master branch” where new development happens. There are also stable releases which are recommended for production use.
Documentation for the current stable version can always be found at this URL:
Documentation for the latest version (“master branch”) can always be found at this URL:
The full history of releases can be found on the GitHub repository Releases page. There you can find release notes, links to each version of the documentation, and instructions for obtaining each version.
Documentation for all releases can also be found in the HTML documentation by clicking the “versions” pop up in the bottom-left corner of the page. You can use this popup to switch between versions of the documentation.
Which Version Should I Start With?¶
- For production purposes, use the current stable version. Stable versions have been manually tested, and are updated with “bugfix releases” which fix bugs without changing other functionality (see Versioning Scheme for more details).
- For prototyping, experimentation or for developing new ESP-MDF features, use the latest version (master branch in Git). The latest version in the master branch has all the latest features and has passed automated testing, but has not been completely manually tested (“bleeding edge”).
- If a required feature is not yet available in a stable release, but you don’t want to use the master branch, it is possible to check out a pre-release version or a release branch. It is recommended to start from a stable version and then follow the instructions for Updating to a Pre-Release Version or Updating to a Release Branch.
See Updating ESP-MDF if you already have a local copy of ESP-MDF and wish to update it.
ESP-MDF uses Semantic Versioning. This means:
Major Releases like
v3.0add new functionality and may change functionality. This includes removing deprecated functionality.
When updating to a new major release (for example, from
v3.0), some of your project’s code may need updating and functionality will need to be re-tested. The release notes on the Releases page include lists of Breaking Changes to refer to.
Minor Releases like
v3.1add new functionality and fix bugs but will not change or remove documented functionality, or make incompatible changes to public APIs.
If updating to a new minor release (for example, from
v3.1) then none of your project’s code should need updating, but you should re-test your project. Pay particular attention to items mentioned in the release notes on the Releases page.
Bugfix Releases like
v3.0.1only fix bugs and do not add new functionality.
If updating to a new bugfix release (for example, from
v3.0.1), you should not need to change any code in your project and should only need to re-test functionality relating directly to bugs listed in the release notes on the Releases page.
Checking The Current Version¶
The local ESP-MDF version can be checked using git:
cd $MDF_PATH git describe --tags --dirty
The version is also compiled into the firmware and can be accessed (as a string) via the macro
MDF_VER. The default ESP-MDF bootloader will print the version on boot (these versions in code will not always update, it only changes if that particular source file is recompiled).
Examples of ESP-MDF versions:
||Master branch pre-release, in development for
version 3.2. 306 commits after v3.2 development
started. Commit identifier
The development (Git) workflow of the Espressif ESP-MDF team is:
- New work is always added on the master branch (latest version) first. The ESP-MDF version on
masteris always tagged with
-dev(for “in development”), for example
- Changes are first added to an internal Git repository for code review and testing, but are pushed to GitHub after automated testing passes.
- When a new version (developed on
master) becomes feature complete and “beta” quality, a new branch is made for the release, for example
release/v3.1. A pre-release tag is also created, for example
v3.1-beta1. You can see a full list of branches and a list of tags on GitHub. Beta pre-releases have release notes which may include a significant number of Known Issues.
- As testing of the beta version progresses, bug fixes will be added to both the
masterbranch and the release branch. New features (for the next release) may start being added to
masterat the same time.
- Once testing is nearly complete a new release candidate is tagged on the release branch, for example
v3.1-rc1. This is still a pre-release version.
- If no more significant bugs are found or reported then the final Major or Minor Version is tagged, for example
v3.1. This version appears on the Releases page.
- As bugs are reported in released versions, the fixes will continue to be committed to the same release branch.
- Regular bugfix releases are made from the same release branch. After manual testing is complete, a bugfix release is tagged (i.e.
v3.1.1) and appears on the Releases page.
Updating ESP-MDF depends on which version(s) you wish to follow:
- Updating to Stable Release is recommended for production use.
- Updating to Master Branch is recommended for latest features, development use, and testing.
- Updating to a Release Branch is a compromise between these two.
These guides assume you already have a local copy of ESP-MDF.
Updating to Stable Release¶
To update to new ESP-MDF releases (recommended for production use), this is the process to follow:
Check the Releases page regularly for new releases.
When a bugfix release for a version you are using is released (for example if using
v3.0.2is available), check out the new bugfix version into the existing ESP-MDF directory:
cd $MDF_PATH git fetch git checkout vX.Y.Z git submodule update --init --recursive
When major or minor updates are released, check the Release Notes on the releases page and decide if you would like to update or to stay with your existing release. Updating is via the same Git commands shown above.
If you installed the stable release via zip file rather than using git, it may not be possible to change versions this way. In this case, update by downloading a new zip file and replacing the entire
MDF_PATH directory with its contents.
Updating to a Pre-Release Version¶
It is also possible to
git checkout a tag corresponding to a pre-release version or release candidate, the process is the same as Updating to Stable Release.
Updating to Master Branch¶
Using Master branch means living “on the bleeding edge” with the latest ESP-MDF code.
To use the latest version on the ESP-MDF master branch, this is the process to follow:
Check out the master branch locally:
cd $MDF_PATH git checkout master git pull git submodule update --init --recursive
git pullto pull the latest version of master. Note that you may need to change your project or report bugs after updating master branch.
To switch from
masterto a release branch or stable version, run
git checkoutas shown in the other sections.
It is strongly recommended to regularly run
git pull and then
git submodule update --init --recursive so a local copy of
master does not get too old. Arbitrary old master branch revisions are effectively unsupportable “snapshots” that may have undocumented bugs. For a semi-stable version, try Updating to a Release Branch instead.
Updating to a Release Branch¶
In stability terms, using a release branch is part-way between using
master branch and only using stable releases. A release branch is always beta quality or better, and receives bug fixes before they appear in each stable release.
You can find a list of branches on GitHub.
For example, to follow the branch for ESP-MDF v3.1, including any bugfixes for future releases like
cd $MDF_PATH git fetch git checkout release/v3.1 git pull git submodule --update --init --recursive
Each time you
git pull this branch, ESP-MDF will be updated with fixes for this release.
The is no dedicated documentation for release branches. It is recommended to use the documentation for the closest version to the branch which is currently checked out.