ESP-IDF Diag Tool (esp-idf-diag)

The esp-idf-diag tool gathers information about the ESP-IDF environment, the system information, and the ESP-IDF project into a report directory to help with troubleshooting problems.

Installation

You can install the esp-idf-diag tool from the Python Package Index (PyPI) using:

$ pip install esp-idf-diag

Creating report directory

In an activated ESP-IDF environment, execute the following in your ESP-IDF project:

$ esp-idf-diag create

By default, this will create a report directory named diag-UUID, where UUID is a randomly generated Universally Unique Identifier. For example diag-5aaa949b-40dc-4d53-96f1-1280c801585a. You can change the output directory using the --output option. This directory will contain files that were collected and generated by esp-idf-diag. You can review the contents and add or remove files as necessary.

Creating a zipped archive of the report directory

Once the report directory is prepared, it can be compressed into a zip archive with:

$ esp-idf-diag zip diag-5aaa949b-40dc-4d53-96f1-1280c801585a

Please be aware that the report directory name is taken from the create example mentioned earlier. This name will vary with each create run unless the --output option is specified.

The zip archive can be attached to a GitHub issue to provide more context for a problem you are experiencing.

Recipes

The data collected by esp-idf-diag is managed through recipes, which are straightforward YAML files containing commands whose outputs are saved in the report directory. For further details, please refer to the Recipe format description.

Redacting sensitive data

When a report directory is created, its contents are scanned for sensitive information, such as passwords or tokens in URLs. This process is guided by a purge file, in YAML format, that specifies which matching regular expressions should be replaced. For further details, refer to the Purge format description. A default purge file is available, but you can provide a custom one using the --purge option. It is recommended to review the generated report directory for sensitive data before sharing it.