alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-08-07 20:00:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add "Creating Examples" docs page, template example README

Browse Source
This commit is contained in:
Angus Gratton
2018-06-08 11:18:14 +10:00
committed by Angus Gratton
parent 34401afe39
commit df4e227855
6 changed files with 137 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
examples/README.md
View File

@@ -1,16 +1,28 @@
# Examples
This directory contains a growing number of simple example projects for esp-idf. These are intended to show basic esp-idf functionality, and to provide you can use for your own projects.
This directory contains a range of example ESP-IDF projects. These are intended to demonstrate parts of ESP-IDF functionality, and to provide code that you can copy and adapt into your own projects.
# Example Layout
The examples are grouped into subdirectories by category. Each category directory contains one or more example projects:
* `bluetooth` contains Bluetooth (BLE & BT Classic) examples.
* `ethernet` contains Ethernet examples.
* `get-started` contains some very simple examples with minimal functionality.
* `mesh` contains Wi-Fi Mesh examples.
* `peripherals` contains examples showing driver functionality for the various onboard ESP32 peripherals.
* `protocols` contains examples showing network protocol interactions.
* `storage` contains examples showing data storage methods using SPI flash or external storage like the SD/MMC interface.
* `system` contains examples which demonstrate some internal chip features, or debugging & development tools.
* `wifi` contains examples of advanced Wi-Fi features. (For network protocol examples, see `protocols` instead.)
# Using Examples
Building examples is the same as building any other project:
Building an example is the same as building any other project:
* Follow the setup instructions in the top-level esp-idf README.
* Set `IDF_PATH` environment variable to point to the path to the esp-idf top-level directory.
* Change into the directory of the example you'd like to build.
* `make menuconfig` to configure the example. Most examples require a simple WiFi SSID & password via this configuration.
* Follow the Getting Started instructions which include building the "Hello World" example.
* Change into the directory of the new example you'd like to build.
* `make menuconfig` to configure the example. Most examples have a project-specific "Example Configuration" section here (for example, to set the WiFi SSID & password to use).
* `make` to build the example.
* Follow the printed instructions to flash, or run `make flash`.
@@ -18,7 +30,7 @@ Building examples is the same as building any other project:
Each 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.
The `IDF_PATH` environment variable is the only thing that connects the example to the rest of the `esp-idf` system.
The `IDF_PATH` environment variable is the only thing that connects the example to the rest of ESP-IDF.
If you're looking for a more bare-bones project to start from, try [esp-idf-template](https://github.com/espressif/esp-idf-template).
@@ -26,13 +38,4 @@ If you're looking for a more bare-bones project to start from, try [esp-idf-temp
If you have a new example you think we'd like, please consider sending it to us as a Pull Request.
Please read the esp-idf CONTRIBUTING.rst file which lays out general contribution rules.
In addition, here are some tips for creating good examples:
* A good example is documented and the basic options can be configured.
* A good example does not contain a lot of code. If there is a lot of generic code in the example, consider refactoring that code into a standalone component and then use the component's API in your example.
* Names (of files, functions, variables, etc.) inside examples should be distinguishable from names of other parts of IDF (ideally, use `example` in names.)
* Functions and variables used inside examples should be declared static where possible.
* Examples should demonstrate one distinct thing each. Avoid multi-purposed "demo" examples, split these into multiple examples instead.
* Examples must be licensed under the Apache License 2.0 or (preferably for examples) if possible you can declare the example to be Public Domain / Creative Commons Zero.
In the ESP-IDF documentation, you can find a "Creating Examples" page which lays out the steps to creating a top quality example.