Note: You can also just clone this repository instead of using cargo-generate, but this involves additional manual adjustments. This flip-link CI patch can serve as a reference on what to do.

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}} --defmt"
+runner = "probe-run --chip nRF52840_xxAA --defmt"

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)

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

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-run supports

$ probe-run --version
probe-run 0.1.4 (3521a42 2020-11-12)
supported defmt version: 3db6b41f08a5c866e6d6ed7103d01b0b0fe5a1f4

In the example output, the supported version is 3db6b41f08a5c866e6d6ed7103d01b0b0fe5a1f4

Switch defmt dependencies to git: uncomment the last part of the root Cargo.toml and enter the hash reported by probe-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 = "3db6b41f08a5c866e6d6ed7103d01b0b0fe5a1f4" }
+defmt-rtt = { git = "https://github.com/knurling-rs/defmt", rev = "3db6b41f08a5c866e6d6ed7103d01b0b0fe5a1f4" }
+defmt-test = { git = "https://github.com/knurling-rs/defmt", rev = "3db6b41f08a5c866e6d6ed7103d01b0b0fe5a1f4" }
+panic-probe = { git = "https://github.com/knurling-rs/defmt", rev = "3db6b41f08a5c866e6d6ed7103d01b0b0fe5a1f4" }

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.

README.md

app-template

Dependencies

1. flip-link:

2. probe-run:

3. cargo-generate: