You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Now that we know how to [generate a `no_std` project][generate-no-std], let's inspect what the generated
4
4
project contains, try to understand every part of it, and run it.
@@ -7,48 +7,52 @@ project contains, try to understand every part of it, and run it.
7
7
8
8
## Inspecting the Generated Project
9
9
10
-
When creating a project from [`esp-template`][esp-template] with the following answers:
11
-
- Which MCU to target? · `esp32c3`
12
-
- Configure advanced template options? · `false`
13
-
14
-
For this explanation, we will use the default values, if you want further modifications, see the [additional prompts][prompts] when not using default values.
10
+
When creating a project from [`esp-generate`][esp-generate] with no extra options:
11
+
```
12
+
esp-generate --chip esp32c3 your-project
13
+
```
15
14
16
15
It should generate a file structure like this:
17
16
18
17
```text
18
+
├── build.rs
19
19
├── .cargo
20
-
│ └── config.toml
21
-
├── src
22
-
│ └── main.rs
23
-
├── .gitignore
20
+
│ └── config.toml
24
21
├── Cargo.toml
25
-
├── LICENSE-APACHE
26
-
├── LICENSE-MIT
27
-
└── rust-toolchain.toml
22
+
├── .gitignore
23
+
├── rust-toolchain.toml
24
+
├── src
25
+
│ ├── bin
26
+
│ │ └── main.rs
27
+
│ └── lib.rs
28
+
└── .vscode
29
+
└── settings.json
28
30
```
29
31
30
32
Before going further, let's see what these files are for.
31
-
33
+
-[`build.rs`][build.rs]
34
+
- Sets the linker script arguments based on the template options.
32
35
-[`.cargo/config.toml`][config-toml]
33
36
- The Cargo configuration
34
37
- This defines a few options to correctly build the project
35
-
- Contains `runner = "espflash flash --monitor"` - this means you can just use `cargo run` to flash and monitor your code
36
-
-`src/main.rs`
37
-
- The main source file of the newly created project
38
-
- For details, see the [Understanding `main.rs`][main-rs] section below
39
-
-[`.gitignore`][gitignore]
40
-
- Tells `git` which folders and files to ignore
38
+
- Contains the custom runner command for `espflash` or `probe-rs`. For example, `runner = "espflash flash --monitor"` - this means you can just use `cargo run` to flash and monitor your code
41
39
-[`Cargo.toml`][cargo-toml]
42
40
- The usual Cargo manifest declares some meta-data and dependencies of the project
43
-
-`LICENSE-APACHE`, `LICENSE_MIT`
44
-
- Those are the most common licenses used in the Rust ecosystem
45
-
- If you want to use a different license, you can delete these files and change the license in `Cargo.toml`
41
+
-[`.gitignore`][gitignore]
42
+
- Tells `git` which folders and files to ignore
46
43
-[`rust-toolchain.toml`][rust-toolchain-toml]
47
44
- Defines which Rust toolchain to use
48
45
- The toolchain will be `nightly` or `esp` depending on your target
46
+
-`src/bin/main.rs`
47
+
- The main source file of the newly created project
48
+
- For details, see the [Understanding `main.rs`][main-rs] section below
49
+
-`src/lib.rs`
50
+
- This tells the Rust compiler that this code doesn't use `libstd`
51
+
-`.vscode/settings.json`
52
+
- Defines a set of settings for Visual Studio Code to make Rust Analyzer work.
@@ -68,44 +72,43 @@ Before going further, let's see what these files are for.
68
72
- The `no_main` attribute says that this program won't use the standard main interface, which is usually used when a full operating system is available. Instead of the standard main, we'll use the entry attribute from the `esp-riscv-rt` crate to define a custom entry point. In this program, we have named the entry point `main`, but any other name could have been used. The entry point function must be a [diverging function][diverging-function]. I.e. it has the signature `fn foo() -> !`; this type indicates that the function never returns – which means that the program never terminates.
69
73
70
74
```rust,ignore
71
-
4 use esp_backtrace as _;
72
-
5 use esp_println::println;
73
-
6 use esp_hal::{clock::ClockControl, peripherals::Peripherals, prelude::*, timer::TimerGroup, Rtc};
75
+
4 use esp_backtrace as _;
76
+
5 use esp_hal::delay::Delay;
77
+
6 use esp_hal::prelude::*;
78
+
7 use log::info;
74
79
```
75
80
-`use esp_backtrace as _;`
76
81
- Since we are in a bare-metal environment, we need a panic handler that runs if a panic occurs in code
77
82
- There are a few different crates you can use (e.g `panic-halt`) but `esp-backtrace` provides an implementation that prints the address of a backtrace - together with `espflash` these addresses can get decoded into source code locations
78
-
-`use esp_println::println;`
79
-
- Provides `println!`implementation
80
-
-`use esp_hal::{...}`
81
-
-We need to bring in some types we are going to use
83
+
-`use esp_hal::delay::Delay;`
84
+
- Provides `Delay` driver implementation.
85
+
-`use esp_hal::prelude::*;`
86
+
-Imports the `esp-hal`[prelude][prelude].
82
87
83
88
```rust,ignore
84
89
8 #[entry]
85
90
9 fn main() -> ! {
86
-
10 let peripherals = Peripherals::take();
87
-
11 let system = peripherals.SYSTEM.split();
88
-
12 let clocks = ClockControl::max(system.clock_control).freeze();
89
-
13
90
-
14 println!("Hello world!");
91
-
15
92
-
16 loop {}
91
+
10 esp_println::logger::init_logger_from_env();
92
+
11
93
+
12 let delay = Delay::new();
94
+
13 loop {
95
+
14 info!("Hello world!");
96
+
15 delay.delay(500.millis());
97
+
16 }
93
98
17 }
94
99
```
100
+
95
101
Inside the `main` function we can find:
96
-
-`let peripherals = Peripherals::take()`
97
-
- HAL drivers usually take ownership of peripherals accessed via the PAC
98
-
- Here we take all the peripherals from the PAC to pass them to the HAL drivers later
99
-
-`let mut system = peripherals.SYSTEM.split();`
100
-
- Sometimes a peripheral (here the System peripheral) is coarse-grained and doesn't exactly fit the HAL drivers - so here we split the System peripheral into smaller pieces which get passed to the drivers
Both templates are based on [`cargo-generate`][cargo-generate], a tool that allows you to create a new project based on some existing template. In our case, [`esp-idf-template`][esp-idf-template] or [`esp-template`][esp-template] can be used to generate an application with all the required configurations and dependencies.
7
+
8
+
## `esp-generate`
9
+
10
+
`esp-generate` is project generation tool that can be used to generate an application with all the required configurations and dependencies
11
+
12
+
1. Install `esp-generate`:
13
+
```shell
14
+
cargo install esp-generate
15
+
```
16
+
2. Generate a project based on the template, selecting the chip and the name of the project:
17
+
```shell
18
+
esp-generate --chip=esp32c6 your-project
19
+
```
20
+
See [Understanding `esp-generate`][understanding-esp-generate] for more details on the template project.
21
+
22
+
When the `esp-generate` subcommand is invoked, you will be prompted with a TUI where you can selectthe configuration of your application. Upon completion of this process, you will have a buildable project with all the correct configurations.
23
+
24
+
3. Build/Run the generated project:
25
+
- Use `cargo build` to compile the project using the appropriate toolchain and target.
26
+
- Use `cargo run` to compile the project, flash it, and open a serial monitor with our target device.
`esp-idf-tempalte` is based on [`cargo-generate`][cargo-generate], a tool that allows you to create a new project based on some existing template. In our case, [`esp-idf-template`][esp-idf-template] can be used to generate an application with all the required configurations and dependencies.
8
34
9
35
1. Install `cargo generate`:
10
36
```shell
11
37
cargo install cargo-generate
12
38
```
13
-
2. Generate a project based on one of the templates:
14
-
- `esp-template`:
15
-
```shell
16
-
cargo generate esp-rs/esp-template
17
-
```
18
-
See [Understanding `esp-template`][understanding-esp-template] for more details on the template project.
19
-
- `esp-idf-template`:
20
-
```shell
21
-
cargo generate esp-rs/esp-idf-template cargo
22
-
```
23
-
See [Understanding `esp-idf-template`][understanding-esp-idf-template] for more details on the template project.
39
+
2. Generate a project based on the template:
40
+
```shell
41
+
cargo generate esp-rs/esp-idf-template cargo
42
+
```
43
+
See [Understanding `esp-idf-template`][understanding-esp-idf-template] for more details on the template project.
24
44
25
45
When the `cargo generate` subcommand is invoked, you will be prompted to answer several questions regarding the target of your application. Upon completion of this process, you will have a buildable project with all the correct configurations.
26
46
@@ -30,17 +50,14 @@ Both templates are based on [`cargo-generate`][cargo-generate], a tool that allo
Both template repositories have a prompt forDev Containers support, see detailsin [Dev Containers][dev-container] section of the template README.
57
+
Both template repositories have a prompt for Dev Containers support.
40
58
41
59
Dev Containers use the [`idf-rust`][idf-rust] container image, which was explained in the [Using Container][using-container] section of the [Setting up a Development Environment][setting-env] chapter. This image provides an environment ready to develop Rust applications for Espressif chips with no installation required. Dev Containers also have integration with [Wokwi simulator][wokwi], to simulate the project, and allow flashing from the container using [`web-flash`][web-flash].
0 commit comments