app-template
Quickly set up a
probe-run+defmt+flip-linkembedded project
Dependencies
1. flip-link:
$ cargo install flip-link
2. probe-run:
$ # make sure to install v0.2.0 or later
$ cargo install probe-run
3. cargo-generate:
$ cargo install cargo-generate
Note: You can also just clone this repository instead of using
cargo-generate, but this involves additional manual adjustments.
Setup
1. Initialize the project template
$ cargo generate \
--git https://github.com/knurling-rs/app-template \
--branch main \
--name my-app
If you look into your new my-app folder, you'll find that there are a few TODOs in the files marking the properties you need to set.
Let's walk through them together now.
2. Set probe-run chip
Pick a chip from probe-run --list-chips and enter it into .cargo/config.toml.
If, for example, you have a nRF52840 Development Kit from one of our workshops, replace {{chip}} with nRF52840_xxAA.
# .cargo/config.toml
[target.'cfg(all(target_arch = "arm", target_os = "none"))']
-runner = "probe-run --chip {{chip}}"
+runner = "probe-run --chip nRF52840_xxAA"
3. Adjust the compilation target
In .cargo/config.toml, pick the right compilation target for your board.
# .cargo/config.toml
[build]
-target = "thumbv6m-none-eabi" # Cortex-M0 and Cortex-M0+
-# target = "thumbv7m-none-eabi" # Cortex-M3
-# target = "thumbv7em-none-eabi" # Cortex-M4 and Cortex-M7 (no FPU)
-# target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)
+target = "thumbv7em-none-eabihf" # Cortex-M4F (with FPU)
Add the target with rustup.
$ rustup target add thumbv7em-none-eabihf
4. Add a HAL as a dependency
In Cargo.toml, list the Hardware Abstraction Layer (HAL) for your board as a dependency.
For the nRF52840 you'll want to use the nrf52840-hal.
# Cargo.toml
[dependencies]
-# some-hal = "1.2.3"
+nrf52840-hal = "0.14.0"
5. Import your HAL
Now that you have selected a HAL, fix the HAL import in src/lib.rs
// my-app/src/lib.rs
-// use some_hal as _; // memory layout
+use nrf52840_hal as _; // memory layout
(6. Get a linker script)
Some HAL crates require that you manually copy over a file called memory.x from the HAL to the root of your project. For nrf52840-hal, this is done automatically so no action is needed. For other HAL crates, you can get it from your local Cargo folder, the default location is under:
~/.cargo/registry/src/
Not all HALs provide a memory.x file, you may need to write it yourself. Check the documentation for the HAL you are using.
7. Run!
You are now all set to cargo-run your first defmt-powered application! There are some examples in the src/bin directory.
Start by cargo run-ning my-app/src/bin/hello.rs:
$ # `rb` is an alias for `run --bin`
$ cargo rb hello
Finished dev [optimized + debuginfo] target(s) in 0.03s
flashing program ..
DONE
resetting device
0.000000 INFO Hello, world!
(..)
$ echo $?
0
If you're running out of memory (flip-link bails with an overflow error), you can decrease the size of the device memory buffer by setting the DEFMT_RTT_BUFFER_SIZE environment variable. The default value is 1024 bytes, and powers of two should be used for optimal performance:
$ DEFMT_RTT_BUFFER_SIZE=64 cargo rb hello
(8. Set rust-analyzer.linkedProjects)
If you are using rust-analyzer with VS Code for IDE-like features you can add following configuration to your .vscode/settings.json to make it work transparently across workspaces. Find the details of this option in the RA docs.
{
"rust-analyzer.linkedProjects": [
"Cargo.toml",
"firmware/Cargo.toml",
]
}
Running tests
The template comes configured for running unit tests and integration tests on the target.
Unit tests reside in the library crate and can test private API; the initial set of unit tests are in src/lib.rs. cargo test --lib will run those unit tests.
$ cargo test --lib
(1/1) running `it_works`...
└─ app::unit_tests::__defmt_test_entry @ src/lib.rs:33
all tests passed!
└─ app::unit_tests::__defmt_test_entry @ src/lib.rs:28
Integration tests reside in the tests directory; the initial set of integration tests are in tests/integration.rs. cargo test --test integration will run those integration tests. Note that the argument of the --test flag must match the name of the test file in the tests directory.
$ cargo test --test integration
(1/1) running `it_works`...
└─ integration::tests::__defmt_test_entry @ tests/integration.rs:13
all tests passed!
└─ integration::tests::__defmt_test_entry @ tests/integration.rs:8
Note that to add a new test file to the tests directory you also need to add a new [[test]] section to Cargo.toml.
Trying out the git version of defmt
This template is configured to use the latest crates.io release (the "stable" release) of the defmt framework. To use the git version (the "development" version) of defmt follow these steps:
- Install the git version of
probe-run
$ cargo install --git https://github.com/knurling-rs/probe-run --branch main
- Check which defmt version
probe-runsupports
$ probe-run --version
0.2.0 (aa585f2 2021-02-22)
supported defmt version: 60c6447f8ecbc4ff023378ba6905bcd0de1e679f
In the example output, the supported version is 60c6447f8ecbc4ff023378ba6905bcd0de1e679f
- Switch defmt dependencies to git: uncomment the last part of the root
Cargo.tomland enter the hash reported byprobe-run --version:
-# [patch.crates-io]
-# defmt = { git = "https://github.com/knurling-rs/defmt", rev = "use defmt version reported by `probe-run --version`" }
-# defmt-rtt = { git = "https://github.com/knurling-rs/defmt", rev = "use defmt version reported by `probe-run --version`" }
-# defmt-test = { git = "https://github.com/knurling-rs/defmt", rev = "use defmt version reported by `probe-run --version`" }
-# panic-probe = { git = "https://github.com/knurling-rs/defmt", rev = "use defmt version reported by `probe-run --version`" }
+[patch.crates-io]
+defmt = { git = "https://github.com/knurling-rs/defmt", rev = "60c6447f8ecbc4ff023378ba6905bcd0de1e679f" }
+defmt-rtt = { git = "https://github.com/knurling-rs/defmt", rev = "60c6447f8ecbc4ff023378ba6905bcd0de1e679f" }
+defmt-test = { git = "https://github.com/knurling-rs/defmt", rev = "60c6447f8ecbc4ff023378ba6905bcd0de1e679f" }
+panic-probe = { git = "https://github.com/knurling-rs/defmt", rev = "60c6447f8ecbc4ff023378ba6905bcd0de1e679f" }
You are now using the git version of defmt!
NOTE there may have been breaking changes between the crates.io version and the git version; you'll need to fix those in the source code.
Support
app-template is part of the Knurling project, Ferrous Systems' effort at improving tooling used to develop for embedded systems.
If you think that our work is useful, consider sponsoring it via GitHub Sponsors.
License
Licensed under either of
-
Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
-
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.
![error[E0463]: can't find crate for `test`](https://avatars.githubusercontent.com/u/8765278?v=4)
Other than readme instructions for device specific bits, no modifications have been made
22 Mar 7, 2023
37 Jan 7, 2023
5.2k Jan 3, 2023
2 Dec 27, 2021
8 Aug 23, 2022
44 Dec 27, 2022
39 Nov 28, 2022
1 Dec 5, 2021
0 Feb 17, 2022
16 Nov 22, 2022
88 Nov 6, 2022
28 Dec 12, 2022
73 Jun 15, 2023
13 Oct 27, 2022
19 Oct 3, 2022
9 Apr 10, 2022
1 May 24, 2022
6 Dec 15, 2022
4 Feb 7, 2023