1# Examples 2 3This directory contains a range of example ESP-IDF projects. These examples are intended to demonstrate parts of the ESP-IDF functionality, and to provide code that you can copy and adapt into your own projects. 4 5# Example Layout 6 7The examples are grouped into subdirectories by category. Each category directory contains one or more example projects: 8 9* `bluetooth/bluedroid` Classic BT, BLE and coex examples using default Bluedroid host stack. 10* `bluetooth/nimble` BLE examples using NimBLE host stack. 11* `bluetooth/esp_ble_mesh` ESP BLE Mesh examples. 12* `bluetooth/hci` HCI transport (VHCI and HCI UART) examples. 13* `build_system` Examples of build system features. 14* `cxx` C++ language utilization examples and experimental components. 15* `ethernet` Ethernet network examples. 16* `get-started` Simple examples with minimal functionality. Good start point for beginners. 17* `mesh` Wi-Fi Mesh examples. 18* `network` Examples related to general network environment, test & analysis. 19* `openthread` OpenThread examples. 20* `peripherals` Examples showing driver functionality for the various onboard ESP32 peripherals. 21* `protocols` Examples showing network protocol interactions. 22* `provisioning` Wi-Fi provisioning examples. 23* `security` Examples about security features. 24* `storage` Examples showing data storage methods using SPI flash, external storage like the SD/MMC interface and flash partitioning. 25* `system` Demonstrates some internal chip features, or debugging & development tools. 26* `wifi` Advanced Wi-Fi features (For network protocol examples, see `protocols` instead.) 27 28In addition to these examples, `commmon_components` directory contains code shared by several examples. 29 30# Using Examples 31 32Before building an example, be sure to follow the [ESP-IDF Getting Started Guide](https://idf.espressif.com/) to ensure you have the required development environment. 33 34Building an example is the same as building any other project: 35 36* Change into the directory of the new example you'd like to build. 37* Run `idf.py set-target TARGET` to select the correct chip target to build before opening the project configuration menu. By default the target is `esp32`. For all options see `idf.py set-target --help` 38* Run `idf.py menuconfig` to open the project configuration menu. Most examples have a project-specific "Example Configuration" section here (for example, to set the WiFi SSID & password to use). 39* `idf.py build` to build the example. 40* Follow the printed instructions to flash, or run `idf.py -p PORT flash`. 41 42## Running Test Python Script 43 44Some of the examples have `..._test.py` scripts that are used to test that the example works as expected. These scripts run automatically in the internal test queue. They are not intended to be run by ESP-IDF users but sometimes you may want to run them locally. The following requirements must be met in the IDF python virtual environment. 45 46* ttfw needs to be in the `PYTHONPATH`. Add it like this: `export PYTHONPATH=$PYTHONPATH:$IDF_PATH/tools/ci/python_packages` 47* Install all requirements from `tools/ci/python_packages/ttfw_idf/requirements.txt`: `python -m pip install -r $IDF_PATH/tools/ci/python_packages/ttfw_idf/requirements.txt` 48 49These commands help solve the issue with `ModuleNotFoundError: No module named 'ttfw_idf'` and `ModuleNotFoundError: No module named 'tiny_test_fw'`. 50 51Some examples might fail due to other missing packages. You might need to install them manually: `pip install websocket`. 52 53# Copying Examples 54 55Each example is a standalone project. The examples *do not have to be inside the esp-idf directory*. You can copy an example directory to anywhere on your computer in order to make a copy that you can modify and work with. 56 57The `IDF_PATH` environment variable is the only thing that connects the example to the rest of ESP-IDF. 58 59If you're looking for a more bare-bones project to start from, try [esp-idf-template](https://github.com/espressif/esp-idf-template). 60 61# Contributing Examples 62 63If you have a new example you think we'd like, please consider sending it to us as a Pull Request. 64 65In the ESP-IDF documentation, you can find a "Creating Examples" page which lays out the steps to creating a top quality example. 66
