Frequently Asked Questions

These are a list of unsorted, commonly asked questions and answers.

Please feel free to add items to this page, especially if someone in the chat answered a question for you!

How to deploy to RP2040 without a debugging probe.

Install elf2uf2-rs for converting the generated elf binary into a uf2 file.

Configure the runner to use this tool, add this to .cargo/config.toml:

[target.'cfg(all(target_arch = "arm", target_os = "none"))']
runner = "elf2uf2-rs --deploy --serial --verbose"

The command-line parameters --deploy will detect your device and upload the binary, --serial starts a serial connection. See the documentation for more info.

Missing main macro

If you see an error like this:

#[embassy_executor::main]
|                   ^^^^ could not find `main` in `embassy_executor`

You are likely missing some features of the embassy-executor crate.

For Cortex-M targets, check whether ALL of the following features are enabled in your Cargo.toml for the embassy-executor crate:

  • arch-cortex-m

  • executor-thread

For ESP32, consider using the executors and #[main] macro provided by your appropriate HAL crate.

Why is my binary so big?

The first step to managing your binary size is to set up your profiles.

[profile.release]
lto = true
opt-level = "s"
incremental = false
codegen-units = 1
# note: debug = true is okay - debuginfo isn't flashed to the device!
debug = true

All of these flags are elaborated on in the Rust Book page linked above.

My binary is still big…​ filled with std::fmt stuff!

This means your code is sufficiently complex that panic! invocation’s formatting requirements could not be optimized out, despite your usage of panic-halt or panic-reset.

You can remedy this by adding the following to your .cargo/config.toml:

[unstable]
build-std = ["core"]
build-std-features = ["panic_immediate_abort"]

This replaces all panics with a UDF (undefined) instruction.

Depending on your chipset, this will exhibit different behavior.

Refer to the spec for your chipset, but for thumbv6m, it results in a hardfault. Which can be configured like so:

#[exception]
unsafe fn HardFault(_frame: &ExceptionFrame) -> ! {
    SCB::sys_reset() // <- you could do something other than reset
}

Refer to cortex-m’s exception handling for more info.

embassy-time throws linker errors

If you see linker error like this:

  = note: rust-lld: error: undefined symbol: _embassy_time_now
          >>> referenced by driver.rs:127 (src/driver.rs:127)
          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::now::hefb1f99d6e069842) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib

          rust-lld: error: undefined symbol: _embassy_time_allocate_alarm
          >>> referenced by driver.rs:134 (src/driver.rs:134)
          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::allocate_alarm::hf5145b6bd46706b2) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib

          rust-lld: error: undefined symbol: _embassy_time_set_alarm_callback
          >>> referenced by driver.rs:139 (src/driver.rs:139)
          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::set_alarm_callback::h24f92388d96eafd2) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib

          rust-lld: error: undefined symbol: _embassy_time_set_alarm
          >>> referenced by driver.rs:144 (src/driver.rs:144)
          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::set_alarm::h530a5b1f444a6d5b) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib

You probably need to enable a time driver for your HAL (not in embassy-time!). For example with embassy-stm32, you might need to enable time-driver-any:

[dependencies.embassy-stm32]
version = "0.1.0"
features = [
    # ...
    "time-driver-any", # Add this line!
    # ...
]

If you are in the early project setup phase and not using anything from the HAL, make sure the HAL is explicitly used to prevent the linker removing it as dead code by adding this line to your source:

use embassy_stm32 as _;

Error: Only one package in the dependency graph may specify the same links value.

You have multiple versions of the same crate in your dependency tree. This means that some of your embassy crates are coming from crates.io, and some from git, each of them pulling in a different set of dependencies.

To resolve this issue, make sure to only use a single source for all your embassy crates! To do this, you should patch your dependencies to use git sources using [patch.crates.io] and maybe [patch.'https://github.com/embassy-rs/embassy.git'].

Example:

[patch.crates-io]
embassy-time-queue-driver = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
embassy-time-driver = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
# embassy-time = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }

Note that the git revision should match any other embassy patches or git dependencies that you are using!

How can I optimize the speed of my embassy-stm32 program?

  • Make sure RCC is set up to go as fast as possible

  • Make sure flash cache is enabled

  • build with --release

  • Set the following keys for the release profile in your Cargo.toml:

    • opt-level = "s"

    • lto = "fat"

  • Set the following keys in the [unstable] section of your .cargo/config.toml

    • build-std = ["core"]

    • build-std-features = ["panic_immediate_abort"]

  • Enable feature embassy-time/generic-queue, disable feature embassy-executor/integrated-timers

  • When using InterruptExecutor:

    • disable executor-thread

    • make main` spawn everything, then enable SCB.SLEEPONEXIT and loop { cortex_m::asm::wfi() }

    • Note: If you need 2 priority levels, using 2 interrupt executors is better than 1 thread executor + 1 interrupt executor.

How do I set up the task arenas on stable?

When you aren’t using the nightly feature of embassy-executor, the executor uses a bump allocator, which may require configuration.

Something like this error will occur at compile time if the task arena is too large for the target’s RAM:

rust-lld: error: section '.bss' will not fit in region 'RAM': overflowed by _ bytes
rust-lld: error: section '.uninit' will not fit in region 'RAM': overflowed by _ bytes

And this message will appear at runtime if the task arena is too small for the tasks running:

ERROR panicked at 'embassy-executor: task arena is full. You must increase the arena size, see the documentation for details: https://docs.embassy.dev/embassy-executor/'
If all tasks are spawned at startup, this panic will occur immediately.

Check out Task Arena Documentation for more details.

Can I use manual ISRs alongside Embassy?

Yes! This can be useful if you need to respond to an event as fast as possible, and the latency caused by the usual “ISR, wake, return from ISR, context switch to woken task” flow is too much for your application. Simply define a #[interrupt] fn INTERRUPT_NAME() {} handler as you would in any other embedded rust project.

How can I measure resource usage (CPU, RAM, etc.)?

For CPU Usage:

There are a couple techniques that have been documented, generally you want to measure how long you are spending in the idle or low priority loop.

We need to document specifically how to do this in embassy, but this older post describes the general process.

If you end up doing this, please update this section with more specific examples!

For Static Memory Usage

Tools like cargo size and cargo nm can tell you the size of any globals or other static usage. Specifically you will want to see the size of the .data and .bss sections, which together make up the total global/static memory usage.

For Max Stack Usage

Check out cargo-call-stack for statically calculating worst-case stack usage. There are some caveats and inaccuracies possible with this, but this is a good way to get the general idea. See the README for more details.