Skip to content

Commit db3b104

Browse files
robamurobamu
committed
README update
- Full instructions on how to create a new binary crate based on blinky example
1 parent 69d3fe2 commit db3b104

File tree

1 file changed

+83
-22
lines changed

1 file changed

+83
-22
lines changed

‎examples/README.md

Lines changed: 83 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,70 @@
11
Examples
22
======
33

4-
## Parts with a SMPS
5-
6-
For these parts, the program needs to know more about the power supply
7-
scheme in order to successfully transition from Run* mode to Run mode. For
8-
an explaination of Run* mode, see RM0433 Rev 7 Section 6.6.1 "System/D3
9-
domain modes".
10-
11-
For your own code, see the
12-
[documentation](https://docs.rs/stm32h7xx-hal/latest/stm32h7xx_hal/pwr/index.html#smps)
13-
for the builder methods on `pwr`. However to make things easier for the
14-
examples, there are feature flags that set common power configurations.
15-
16-
Flag | Situation | Applicable Boards (non-exhaustive)
17-
---|---|---
18-
`example-smps` | Board uses Internal SMPS | Any Nucleo with `-Q` suffix
19-
`example-ldo` | Board uses LDO, internal SMPS unconnected |
20-
none | Parts without internal SMPS |
21-
22-
The results of using the wrong power configuration for your hardware are
23-
undefined(!). If you can still access the debug port, load a simple example
24-
with the correct power configuration and power cycle the board.
4+
## Getting started
5+
6+
You can compile the provided examples directly, but it is recommended to create
7+
a new binary crate or one based on existing board specficic example or BSP crates.
8+
This is because most examples will require tweaks to work for your particular board.
9+
You then can copy the examples into your binary crate and make any necessary adjustments.
10+
11+
These board specific crates usually also supply files which make
12+
development on the board easier. They might also contain board specific code or adaptions that
13+
might be required to make the examples work for your particular board.
14+
15+
The hello world of embedded development is usually to blinky a LED. This example
16+
is contained within the [examples folder](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/blinky.rs).
17+
18+
1. Make sure you have the required Rust cross-compiler installed. If you have not
19+
done this yet, you can run the following command to install it
20+
21+
```sh
22+
rustup target add thumbv7em-none-eabihf
23+
```
24+
25+
2. Create a new binary crate with `cargo init`
26+
3. To ensure that `cargo build` cross-compiles, it is recommended to create
27+
a `.cargo/config.toml` file. You can use the `config.toml` provided
28+
in the [`cortex-m-quickstart`](https://github.com/rust-embedded/cortex-m-quickstart/blob/master/.cargo/config.toml)
29+
repository and uncomment `target = "thumbv7em-none-eabihf"`.
30+
4. Copy the `memory.x` file into your project. This file contains information
31+
required by the linker.
32+
5. Copy the `blinky.rs` file to the `src/main.rs` in your binaray crate and copy the `utilities`
33+
folder to your `src` folder as well. The utilities
34+
folder contains common code used by all examples, e.g. for logger initialization.
35+
6. For `blinky.rs`, you also need to add some dependencies to your `Cargo.toml`. If
36+
you are doing this for another example or you'd like to use another logger, you
37+
might need different dependencies. Make sure to replace the configuration
38+
feature `stm32h743v` according to your used board:
39+
40+
```toml
41+
[dependencies]
42+
cortex-m-rt = "0.6.12"
43+
cortex-m = "0.7.1"
44+
log = "0.4.11"
45+
embedded-hal = "0.2.6"
46+
panic-halt = "0.2"
47+
cfg-if = "1.0.0"
48+
49+
[dependencies.stm32h7xx-hal]
50+
version = "0.10"
51+
features = ["stm32h743v"]
52+
```
53+
54+
7. Build the application with
55+
56+
```sh
57+
cargo build
58+
```
59+
60+
8. Flashing the board might work differently for different boards and there is usually
61+
more than one way. You can usually find instructions in the board specific crates or BSPs.
2562

2663
## Logging
2764

28-
Example specific features have been defined to enable different logging outputs for the examples. If no logging feature is selected logging will be disabled and the panic handler will be halt. Supported logging methods are:
65+
Example specific features have been defined to enable different logging outputs for the examples.
66+
If no logging feature is selected logging will be disabled and the panic handler will be halt.
67+
Supported logging methods are:
2968

3069
### RTT (Real Time Trace)
3170

@@ -57,3 +96,25 @@ configure the ITM yourself. See [ITM.md](ITM.md)
5796
If you select this feature flag, then the call to `logger::init()` internally
5897
configures the ITM peripheral. If you also interact with the ITM peripheral
5998
yourself, you should be aware that it has already been configured.
99+
100+
## Parts with a SMPS
101+
102+
For these parts, the program needs to know more about the power supply
103+
scheme in order to successfully transition from Run* mode to Run mode. For
104+
an explaination of Run* mode, see RM0433 Rev 7 Section 6.6.1 "System/D3
105+
domain modes".
106+
107+
For your own code, see the
108+
[documentation](https://docs.rs/stm32h7xx-hal/latest/stm32h7xx_hal/pwr/index.html#smps)
109+
for the builder methods on `pwr`. However to make things easier for the
110+
examples, there are feature flags that set common power configurations.
111+
112+
Flag | Situation | Applicable Boards (non-exhaustive)
113+
---|---|---
114+
`example-smps` | Board uses Internal SMPS | Any Nucleo with `-Q` suffix
115+
`example-ldo` | Board uses LDO, internal SMPS unconnected |
116+
none | Parts without internal SMPS |
117+
118+
The results of using the wrong power configuration for your hardware are
119+
undefined(!). If you can still access the debug port, load a simple example
120+
with the correct power configuration and power cycle the board.

0 commit comments

Comments
 (0)