OVMS3-idf/examples/README.md

# Examples

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/bluedroid` contains Classic BT, BLE and coex examples using default Bluedroid host stack.
* `bluetooth/nimble` contains BLE examples using NimBLE host stack.
* `bluetooth/esp_ble_mesh` contains ESP BLE Mesh examples.
* `bluetooth/hci` contains HCI transport (VHCI and HCI UART) 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.)
* `build_system` contains examples of build system features

# Using Examples

Building an example is the same as building any other project:

* 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.
* 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).
* `idf.py build` to build the example.
* Follow the printed instructions to flash, or run `idf.py -p PORT flash`.

# Copying Examples

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 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).

# Contributing Examples

If you have a new example you think we'd like, please consider sending it to us as a Pull Request.

In the ESP-IDF documentation, you can find a "Creating Examples" page which lays out the steps to creating a top quality example.
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00			`# Examples`

docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			`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.`
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			`# Example Layout`

			`The examples are grouped into subdirectories by category. Each category directory contains one or more example projects:`

Bluetooth examples restructuring The existing Bluetooth examples are split as: 1. examples/bluetooth/bluedroid - Bluedroid Host (BT + BLE) examples a. examples/bluetooth/bluedroid/classic_bt - Classic BT examples b. examples/bluetooth/bluedroid/ble - BLE examples c. examples/bluetooth/bluedroid/coex - Classic BT and BLE coex examples d. examples/bluetooth/bluedroid/hci - VHCI and HCI UART examples i. Rename ble_adv to controller_vhci_ble_adv and move it in hci folder 2. examples/bluetooth/nimble - NimBLE BLE Host + NimBLE Mesh examples 3. examples/bluetooth/esp_ble_mesh - ESP BLE Mesh examples 4. Update documentation references 2019-07-01 11:21:57 +00:00			* `bluetooth/bluedroid` contains Classic BT, BLE and coex examples using default Bluedroid host stack.
			* `bluetooth/nimble` contains BLE examples using NimBLE host stack.
			* `bluetooth/esp_ble_mesh` contains ESP BLE Mesh examples.
README fixes 2019-11-13 09:48:14 +00:00			* `bluetooth/hci` contains HCI transport (VHCI and HCI UART) examples
docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			* `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.)
examples: generic cmake support examples 2018-11-11 07:36:24 +00:00			* `build_system` contains examples of build system features
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			`# Using Examples`
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			`Building an example is the same as building any other project:`
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			`* 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.`
build system: Use CMake-based build system as default when describing commands 2019-06-23 01:54:31 +00:00			* 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).
examples: change default build instructions in docs to CMake 2019-08-02 03:31:20 +00:00			* `idf.py build` to build the example.
			* Follow the printed instructions to flash, or run `idf.py -p PORT flash`.
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
			`# Copying Examples`

			`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.`

docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			The `IDF_PATH` environment variable is the only thing that connects the example to the rest of ESP-IDF.
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
			`If you're looking for a more bare-bones project to start from, try [esp-idf-template](https://github.com/espressif/esp-idf-template).`

			`# Contributing Examples`

			`If you have a new example you think we'd like, please consider sending it to us as a Pull Request.`

docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			`In the ESP-IDF documentation, you can find a "Creating Examples" page which lays out the steps to creating a top quality example.`