Metadata-Version: 2.4
Name: esp-idf-diag
Version: 0.2.0
Summary: Diagnostic tool for ESP-IDF
Author: Espressif Systems
Project-URL: Homepage, https://github.com/espressif/esp-idf-diag
Keywords: espressif,embedded,diagnostic,bug,report
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML
Requires-Dist: rich
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: commitizen; extra == "dev"
Requires-Dist: czespressif>=1.3.1; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# 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](esp_idf_diag/data/recipes/README.md).


## 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](esp_idf_diag/data/purge/README.md). 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.
