mirror of
https://github.com/esp-rs/esp-hal.git
synced 2025-09-27 04:10:28 +00:00
8c86bf727a
* Move all `embassy` examples to `async` and convert to individual projects * Move all peripheral examples to `peripheral` and convert to individual projects * Move all interrupt examples to `interrupt` and convert to individual projects * Move all `ble` examples to `ble` and convert to individual projects * Move all `esp-now` examples to `esp-now` and convert to individual projects * Move all Wi-Fi examples to `wifi` and convert to individual projects * Move all `ieee802154` examples to `ieee802154` and convert to individual projects * Move all OTA examples to `ota` and convert to individual projects * Remove files which are no longer required * Update `xtask` to handle new examples project layout * Update `examples/README.md` * Don't hide TOML parsing error in `is_published` * Update `fmt-packages` subcommand to handle new examples project layout
52 lines
2.4 KiB
Markdown
52 lines
2.4 KiB
Markdown
# Examples
|
|
|
|
This directory contains a number of binary applications demonstrating the use of various hardware peripherals found within the ESP32 family of devices from Espressif.
|
|
|
|
Each device has its own unique set of peripherals, and as such not every example will run on every device. We recommend building and flashing the examples using the `xtask` method documented below, which will greatly simplify the process.
|
|
|
|
To check if a device is compatible with a given example, check the features in the `Cargo.toml` file for the example application, which will include a feature for each supported device.
|
|
|
|
As previously stated, we use the [cargo-xtask] pattern for automation. Commands invoking this tool must be run from the root of the repository.
|
|
|
|
For more information regarding the examples, refer to the `README.md` file in any of the subdirectories within the `examples/` directory.
|
|
|
|
[cargo-xtask]: https://github.com/matklad/cargo-xtask
|
|
|
|
## Building Examples
|
|
|
|
You can build all examples for a given device using the `build examples` subcommand:
|
|
|
|
```shell
|
|
cargo xtask build examples esp-hal esp32
|
|
```
|
|
|
|
Note that we must specify which package to build the examples for, since this repository contains multiple packages. Specifying `esp-hal` will build the examples in the `examples/` directory instead.
|
|
|
|
## Running Examples
|
|
|
|
You can also build and then subsequently flash and run an example using the `run example` subcommand. With a target device connected to your host system, run:
|
|
|
|
```shell
|
|
cargo xtask run example esp-hal esp32c6 --example embassy_hello_world
|
|
```
|
|
|
|
Again, note that we must specify which package to build the example from, plus which example to build and flash to the target device.
|
|
|
|
## Adding Examples
|
|
|
|
If you are contributing to `esp-hal` and would like to add an example, the process is generally the same as any other project. The `Cargo.toml` file should include a feature for each supported chip, which itself should enable any dependency's features required for the given chip.
|
|
|
|
Another thing to be aware of is the GPIO pins being used. We have tried to use pins available the DevKit-C boards from Espressif, however this is being done on a best-effort basis.
|
|
|
|
In general, the following GPIO are recommended for use, though be conscious of whether certain pins are used for UART, strapping pins, etc. on some devices:
|
|
|
|
- GPIO0
|
|
- GPIO1
|
|
- GPIO2
|
|
- GPIO3
|
|
- GPIO4
|
|
- GPIO5
|
|
- GPIO8
|
|
- GPIO9
|
|
- GPIO10
|