Embassy: Modern embedded framework, using Rust and async
github.com
github.com
I also want to give a shoutout to reqwless (https://github.com/drogue-iot/reqwless) which is a HTTP client for embassy-net that even supports HTTPS!
Rust embedded was really never actually better then C or C++ but embassy for me is a big reason why I now make my buying decision based on how well I can use Rust on the MCU.
RP is also cheap and has that pretty sweet programmable GPIO and documentation that everyone seems to love. Adafruit has an RP2040 Feather for $12, RP2350 for $15, or with an ESP32-C6 (RISC-V) for $15. NXP has chips with similarly programmable GPIO but they're not well supported by Rust. The RP's PIO stuff is bonkers and potentially very interesting if you wanted to make random protocol dongles. VGA out? Why not?
Nordic stuff looks pretty sweet (and their Bluetooth support seems well loved) but is generally a bit expensive. Dev boards are available from micro:bit and Adafruit, among others.
I've been working on a HAL for an older Atmel SoC and absolutely loved the documentation. But Atmel stuff is expensive. Quality of the Chinese clones is iffy. I set myself back a bit by bricking my one board but am hoping to have a beta release in a month or so.
More recent Atmel/Microchip stuff (D21, D51, E51) has a HAL that the Embassy folks seem to have overlooked. You can get them on Adafruit boards at varying price points.
Or just pick something unsupported and start writing a HAL. It's a great way to get up close and personal with how everything fits together.
The one thing I wouldn't do is get some high end thing to start with. Teensy's (NXP i.MXRT) pack a lot of punch but even their native Arduino libs don't really let you exploit the power. STM's H7 series as well, they're way too complex to use as a learning tool even if they are fairly cheap.
Just like security bugs, lengthy errata doesn't mean anything. A popular MCU will have bigger errata sheet because it gets more eyes on it.
>documentation from STM is poorly organized and spread out over a zillion different documents
The spreading out over multiple documents is good organization. You don't want to combine your datasheet, reference manual and appnotes into one.
In STM32G0 for example, there is "SPIv1" peripheral which has very critical implementation bugs which can get SPI to completely stuck until reset by RCC.
There is very brief mention in STM errata about this, I had to dig up forums and dance up with SWD around this.
Just like security bugs, lengthy errata doesn't mean anything. A popular
MCU will have bigger errata sheet because it gets more eyes on it.
> The spreading out over multiple documents is good organization.
No, it's really not. It's things like reading up on a peripheral in the reference manual and then trying to figure out which pins you can use with it. Some vendors will put that in the section with each peripheral, most will include a table within the RM, and STM splits it up into multiple documents — per variant within a family because the families are often loosely related.
None of this stuff is offered up in printed form, they could at least hyperlink it (whether intra- or inter- document).
It's not that surprising really. You've gotta cut costs somewhere.
I've yet to see a MCU vendor ship without bugs. At least with ST, the MCU is very cheap.
>USB controllers straight up doesn't enumerate with ARM Macs
I've seen USB devices struggling to enumerate on Mac/IOS devices before. This feels more like an Apple bug to me considering how they work very well on Linux, Windows and Android.
I've yet to see a MCU vendor ship without bugs. At least with ST,
the MCU is very cheap.
This feels more like an Apple bug to me considering how they work very
well on Linux, Windows and Android.
Meanwhile I've been using Macs on and off since before USB came around and this is the first USB device I've found that glitches out like that. Given that Apple uses off the shelf USB silicon (TI) and the complaints about STM's older USB FS peripherals I came across I'd fully believe it's an STM problem.
What is entirely STM's fault is that they still market the F7 based devices (ST Link, Nucleo, etc) as being Mac compatible. They've also skipped out on putting that fun little wart into the F7 errata.
Apple's products being shit in some ways isn't even a weird outlier, the company knows its loyal fans have nowhere else to go.
If you don't need any of the wireless radio stuff, I think the raspberry pi microcontroller family is also ridiculously well supported in rust and it's possible to get one of the newer raspberry pi microcontroller is complete with ethernet and several megs of flash for not even 10 bucks.
I cant tell you how awesome it is with minimal setup to get
- Full print logging
- Option to attach a debugger
- cargo r will just flash your code and reset the RP2040
Because of the Xtensa, you need to use a special fork of Rust maintained by Espressif, but worth a try.
Some Nordic MCUs are easy too, specifically nrf52840.
Have fun!
never understood what a watchdog is tho...
Watchdogs exist on MCUs but also on some "proper" computers. The Raspberry Pi has one for example.
All modern computers have watchdog. You can check your logs
`journalctl -b | grep watchdog`
So these days you can find a variation on the TCO timer watchdog in most PCs, even if the exact implementation varies so we now have a bunch of drivers for the different variants.
In both cases they do have software watchdogs (NMI based) which relies on a hardware timer triggering an NMI in the kernel. But that relies on the NMI handler still working, which is not as good as a real HW watchdog.
For whatever reason, it's enabled on my laptop despite it obviously not having IPMI support :)
Coming from a lot of bare metal C and FreeRTOS it finally feels like embedded is getting a toolchain that is actually modern and better.
Some of that isn't just Embassy but the surrounding ecosystem, some highlights:
* probe-rs w/cargo run integration
* defmt logging (combined with probe-rs and rtt it's very nice)
* embedded_hal (and in my case stm32-rs)
I have also tried RTIC but I decided to keep going with Embassy because I like the async ergonomics more and the few times it's been a downside/missing functionality (no existing async driver for specific peripherals basically) it wasn't to hard to implement what I needed.
I was surprised it just works out of the box on OS X also, generally speaking I would always end up having to use Linux to develop for embedded. Being able to compile on fast Apple M hardware and then run immediately with zero friction is awesome.
It took a little bit to get my head around how to share access to peripherals etc but once I did it's been great and it's nice to know that locking semantics are essentially enforced at compile time so it's actually not possible to have 2 things stomping over the same bus etc which can sometimes be a very hard bug to track down when working with big and fast SOCs.
Other really big aspect Embassy has been good for is really high quality USB and networking stacks. I am using both the USB stack (for PLDM over USB) and Ethernet w/the TCP stack in embassy_net and both have been flawless.
Only real downsides I can think of are it can sometimes be hard to onboard folk that are used to copy/paste from vendor examples and sometimes communicating and debugging with vendors themselves when they aren't familar and won't engage unless you can reproduce on the vendor HAL.
So overall really happy with it and I highly recommend trying it out especially if you are in the STM ecosphere.
UPDATE: it seems so, using a second executor. There is "embassy_sync" to communicate.
In my case, one CPU is doing the CAN-based communication and the device control loop, and the other core is providing the IP-based interface with SNMP-based monitoring.
Last time i tried embassy, it pulled over 100 dependencies just to build a blinky. Its great for hobbyist programming but i doubt its going to be used in any industrial application any time soon.
Supply chain attacks. There are also regulatory requirements to keep track of your tools.
I know that sonair [0] is actually using Rust in the safety critical path. Toyota Woven [1] is for now just using it in infotainment and non-safety applications.
I am closely monitoring the space, as I am currently evaluating to use Rust and potentially embassy for a safety-critical embedded product myself. I hope to this way also contribute to safety-critical Rust usage. If anyone has further information or just wants to exchange ideas, I'd be super happy to! [0] https://www.sonair.com/journal/leading-the-way-for-safety-ce... [1] https://filtra.io/rust/interviews/woven-by-toyota-nov-25
(Also, I am currently using it for an industrial application)
loop { let btn = ir.wait_for_press().await; // use btn }
Meanwhile the compiler builds the state machine for you.
I think this style is an emergent property of async + no-std that hasn’t really been collected or named yet. A lot of discussion focuses on HALs, bring-up, or executors, but less on how people structure applications once those pieces are in place.
Brad Gibson and I talked about some of these ideas in this (free) article on how Embassy shines on embedded devices: https://medium.com/@carlmkadie/how-rust-embassy-shine-on-emb...
I’ve also started an open repo to experiment with and document these patterns: https://github.com/carlkcarlk/device-kit
Would love links to other repos that use Embassy at this higher, application-oriented level.
I used to write extremely low-lebel NIC firmware that was basically a big bundle of state machines. Rust wasn't ready back then but I was desperate for something like coroutines/async. I think it would have been incredibly valuable.
(There are tricks to do coroutines in C but I think they're too hacky. Also, back then we believed that RTOS threads with their own stack were too expensive, in retrospect I'm not sure we ever entirely proved that).
I may be naïve in this case but I think it would also have been super useful for the high level protocol stuff. Like: 802.11 association flows. If we could have just spun up a Tokio task for each peer, I feel the code would have been an order of magnitude smaller and simpler.
C RTOSes are conceptually nice, but such as pain to use in the real world, a lean framework like embassy is the natural evolution.
The best thing is that embassy can actually be considered as a real-time "OS" (you can read more here: https://kerkour.com/introduction-to-embedded-development-wit...).
Also worth noting that the discrete STLink V3 dongles also use the F7 for USB stuff.
Also also worth noting that not all of the Embassy examples are set up to work with Nucleo boards. It's an odd choice but it is what it is.
https://www.waveshare.com/esp32-c6-touch-lcd-1.47.htm
I've been really impressed. It's basically a hackable Fitbit with no strap or battery. Full wifi, BLE, 6-axis motion. It's was really easy to get the C demos running. LVGL is awesome. Can't speak to Rust. I get enough of that complexity in my day job.
Other brands that look good for beginners are Elecrow and Makerfabs.
I specifically wanted to get into RISC-V, but they all have boards for other architectures as well.
This one is nice too, it has an enclosure. You could use this for a smart home dashboard. Be careful with the boards with two USB ports, they will backfeed power.
If we're talking Rust, rp-hal is great for starting, and of course Embassy is great too, though maybe Embassy is better for later when you start running into the types of problems that it aims to solve.
rp-hal: https://github.com/rp-rs/rp-hal
If you want to take things a bit closer to bare metal, check out ESP32 boards. Super cheap from China and you can find them with all sorts of cool form factors with lipo battery chargers, screens, etc.
If you want to understand how interacting with peripherals and hardware works, an RP2040 is a good option - it has great documentation and sensible peripherals. Or STM32s have huge numbers of examples in the wild.
Ultimately the biggest difference - the thing you need to learn the most - is peripheral setup. Things like setting up the clock, setting up an I2C or SPI bus, reading and writing bytes from a UART etc. This stuff happens on every computer all the way up to a Raspberry Pi, but the bigger and more powerful the MCU the more it tends to be abstracted away by libraries and middleware.
If you want to truly learn this stuff you have to get low down, strip away all the abstractions and get very familiar with the 1000+ page user manual. Doing that on the simplest microcontroller possible is a benefit, because you're not overwhelmed by complex peripherals and too-many-settings.
I'd also recommend starting with C, rather than trying to mess around with Rust. Rust (and embassy) are great for building apps with very few runtime bugs, but debugging stuff in the Rust async world is a headache, and you've got an abstraction layer sitting between you and the chip.
It's actually really powerful to realise that a peripheral is just 10 memory addresses, and to make it work you just need to define a C struct and point it to the start address. Suddenly you're talking to the peripheral and can configure it. None of that is obvious with layers of middleware and abstractions.
https://docs.embassy.dev/embassy-rp/git/rp2040/index.html https://www.raspberrypi.com/documentation/microcontrollers/
There’s different kinds of embedded. What traditionally was referred to as embedded is microcontrollers (e.g., 32-bit ARM Cortex M devices like the STM32 or an NXP IMX106x chip ). A configuration for a Cortex-M7 chip (that some may consider on the high end of traditional embedded) is a 600MHz clock, 1MB of RAM, and 4MB of flash memory. These run either bare metal or a real time operating system but don’t have an MMU.
These days the definition is sometimes expanded to include devices that run full fledged OSes like Linux (embedded Linux) on devices like the RPI with much more memory than an MCU.
To answer the original posters question a bit: get used to C and C++ and not using malloc() / new(), which includes a lot of the standard library.
Also libc is bloat :P
You'll want a dev board, which has the chip plus some supporting components on it. The Raspberry Pi Pico is a good choice because it's so widely used and well documented.
If you care about Rust, you'll also want to get the Debug Probe. Worth the money.
If you don't care about Rust, any Adafruit dev board should run CircuitPython, have good documentation, and likely some projects you can start with. The reason I don't recommend these for Rust is because many of their dev boards do not "break out"/make available the connections for a debug probe.
Edit: Having a project you want to do is good, but just making an LED blink can be magical, too, especially if you haven't done anything with hardware.
I was in the same situation. I've been programming high-level languages for decades now and wanted to get my hands on embedded. I've got friends in my local hackerspace and while you can teach yourself programming those chips, it's good to know whom to ask when you get stuck. You can find a hackerspace near you here: https://wiki.hackerspaces.org/Hackerspaces
I've been programming C and Rust on Wokwi. I even simulates electronic components and stuff like switch-bounce-effects. It's very easy and can be used free. You can even use a local IDE like VSCode(ium) and. I've used it with one project and it speed up my project a lot. https://wokwi.com/
If you enjoy Async PC rust programming, I think this will be a good starting point. I like how it has unified hardware access to different MCUs, and its hardware support for STM32, for example, is a step up from the initial generation of Trait-based HALs. I seem to be the odd one out as an embedded rust programmer (Personally and professionally) for whom Async is not my cup of tea.
I don't quite understand the opposition to async in this context though. Embassy's executor is quite nice. You get to write much more straightforward linear code, and it's more battery efficient because the CPU core goes to sleep at await points. The various hardware interrupts then wake up the core and notify the executor to continue making progress.
The compiler transformation from async/await to a state machine is a godsend for this. Doing the equivalent by hand would be a major pain to get the same power efficiency and code ergonomics.
In C or "regular" embedded Rust, if I want to compose several tasks together, while sleeping the CPU core while waiting on interrupts, I need to scatter global variables over the code, and write custom state machines for all the "yield" points in my code. Oh and then requirements come in later and I need to add some timeouts to various operations. That gets messy quickly. Yes it's "not that hard" but Embassy is right there and it works. I get the state machines for free, I get CPU sleeps for free, the code is easier for others to jump in and work with, and with async combinators it's significantly easier to rearrange logic when new requirements get added.
Just for a concrete example from a (somewhat esoteric) project I'm working on:
https://gist.github.com/bschwind/3905ecf8acd3046d35bf750283f...
This code is receiving uncompressed video frames over USB High Speed and forwarding them to an OLED display. In this case I have the luxury of having enough SRAM to hold two framebuffers in memory, so it's a classic double-buffering strategy of displaying one buffer while the other is being filled. Using a simple combinator, `join()`, I can kick off two DMA transfers with one filling the back buffer, and the other transmitting the front buffer to the display. I can have timeouts on these operations, the code flows pretty linearly, and no external globals or custom interrupt handlers are needed (obviously these exist, but they're in the Embassy code layer). And while these transfers are happening the core is automatically sleeping, assuming I don't have other async tasks running.
To me, this is beautiful for embedded code, and brings a major ergonomic gain over the equivalent in C or even regular old embedded Rust. Obviously you don't have to use it, but I see a bright future for embedded Rust if Embassy and others (like RTIC) can keep up the momentum.
Interrupts map one to one to async execution so I honestly don't even understand what you are arguing for or against.
The notion that Async is the only right or acceptable way to do embedded programming, or embedded programming on rust. The Overton window has shifted so much that I have to state this explicitly.
I’ve been doing async non-blocking code for decades, but this is the first time I e seen that word used? I’m assume you’re meaning something like one big ass select!() or is this something else?
> IMO one of the big reasons Arduino stayed firmly hobbyist tier is because it was almost entirely stuck in a single-threaded blocking mindset and everything kind of fell apart as soon as you had to do two things at once.
This. Having to do something like this recently, in C, was not fun and end up writing your own event management layer (and if you’re me, poorly).
The wildly popular ESPHome is also driven by a superloop. On every iteration the main loop will call an update handler for each component which then is supposed to check if the timers have elapsed, if there is some data coming from a sensor, etc before doing actual work.
This pattern brings with it loads of pitfalls. No component ought to do more than a "tick" worth of work or they can start interfering with other components who expect to be updated at some baseline frequency. Taking too long in any one component can result in serial buffers overrunning in another component, for example.
Googling I see people attempting to use -fstack-usage and -fcallgraph-info for FreeRTOS, but in an ad hoc manner. It seems there's nothing available that handles things end-to-end, such as generating C source type info to reflect back the computed size of a call graph based on the entry function.
In principle Rust might have a much tighter bound for maximum stack usage, but in an embedded context, especially embedded C, you don't normally stack-allocate large buffers or objects, so the variance between minimum and maximum stack usage of functions should be small. And given Rust's preference for stack allocation, I wouldn't be surprised if a C-based threading framework has similar or even better stack usage.
“… better stack usage, if you can keep it”
— Benjamin Franklin
IMO one of the big reasons Arduino stayed firmly hobbyist tier is because
it was almost entirely stuck in a single-threaded blocking mindset and'
everything kind of fell apart as soon as you had to do two things at once.
Conversely Embassy suffers from being immature with some traits that haven't really been fleshed out sufficiently.
Even data structure libraries, like embassy-sync, all have `try_` methods, which would allow for polling usage outside of async.
There's no mandate to use async - and helping folks that DO see value in it (which is a LOT of folks), isn't "splitting the ecosystem" - it's people doing things the way they like to do it. Embassy still works very hard to support folks who DON'T want to use async, to avoid duplicated work. There's nothing stopping you from preferring to write and maintain your own HALs, I know you have been for a while! But it's not something that people necessarily have to do, even if they aren't interested or don't prefer async!
If you look at espressif and how they support rust they have to offer both blocking and non blocking options, they also offer using rust on their freertos and C library setup. It’s quite an undertaking to do all of this.
On the other hand, the rust embedded core tooling including the cargo/rustc/it's target system, probe-rs, defmt, and the PAC project are phenomenal, and make the most important parts one of the lowest-friction embedded workflows around!
Edit: Replace blocking with synchronous
(Case in point: An example of the the "It's Async or blocking" meme I mentioned.)
(which leads to one of my embedded hot takes which is that I think striving for a generic HAL is kind of misguided. If you're striving for any form of mechanical sympathy, your HAL is almost certainly specific to at least your framework and probably actually your application)
(I wanted to test a radio library I wrote with two of the modules connected to one MCU, one sending and one receiving. The normally blocking api meant I would need two devices, so I decided to go with async.)
That should never happen unless you are using a high end 1GHz+ MPUs.Check your GPIOs to make sure there are no shorts.
There’s good and bad things about this. It’s clever for sure but there can be variable latency between when the hardware event occurs and when the next step in the task starts. This is a lot like zephyr/linux work queues but with linear reading code sprinkled with async/await.
https://tweedegolf.nl/en/blog/65/async-rust-vs-rtos-showdown
Obviously if you're working on something truly hard real-time you probably wouldn't be reaching for these tools to begin with, but for the average embedded project it seems you will enjoy quite good latency and jitter characteristics by default.
If I had to complain, I'd say that usually an RTOS isn't really meant for something like button handling. You can use it and it will work, but the bread and butter workload of an RTOS is multiple simultaneous CPU/time intensive tasks that need to complete within a deadline.
The embassy scheduler here could run into a problem because long running tasks would block short lived interrupts.
I know their implementations and behaviors can be quite different, but I'd like to hear more about what makes this an apples to oranges comparison.
There's a large number of things that the cooperative scheduler can't do. Maybe you don't need those things, that's fine! Embassy really is quite nice for cooperative task scheduling. But to benchmark a context swapping RTOS which can and pays the cost for doing so, against a cooperative task queue scheduler... these are not at all the same things, and won't have the same performance characteristics in simple scenarios like the one in the blog post.
Not that I mind correctness, but I want to play with this and maybe do some minor hobby projects with limited cognitive load.
Otherwise I'd just do FreeRTOS, which is also a good option.
Once you get the basics, though, it's very productive and I've found it surprisingly easy to write building blocks I can reuse across a wide range of hardware projects and MCUs!
My learning project -- using mqtt for HomeAssistant integration: <https://github.com/n8henrie/esp32c3-rust-mqtt>
Sadly, I bought an nRF54L15 board to start my embedded journey, which isn't 100% supported yet :/
Now I have to wait. I'm not gonna go back to C :D
But what's the overhead price with Embassy?
"The hardware accelerated Rust RTOS" -- it can use your interrupt controller as a scheduler.
It also has software tasks, which is presumably the Embassy tie-in you mention.
The data-sharing maybe could be nicer, but I do think it's an improvement over C -- you get the ability to do things that you might otherwise need something much bigger like Zephyr for.
Isnt' that how schedulers always work?
Uh, what does async have to do with hard real-time guarantees?
You can get preemptive scheduling of async tasks with InterruptExecutor. You create one executor for each priority level, then spawn the tasks in the right one. The latency of the executor and the compiler-generated async state machines is predictable, so you can use Embassy for hard real-time work. See example: https://github.com/embassy-rs/embassy/blob/main/examples/nrf...
Additionally the executor has support for scheduling tasks by priority or deadline within a single priority level. (in latest git, will be in next crates.io release)
I prefer C for embedded but must admit that's pretty compelling.
I don't think the authors understand what an RTOS is, because it has very little to do with concurrency. It is about providing hard guarantees about execution timing of interrupt events. E.g. you need to poll an input port every 20ms, or something like that, because that's when the signal will be on the wire. Not "Please wait at least 20ms before resuming" but rather "I must resume execution in +0.020 sec from now with timing error constrained to no more than +/- 100 nanoseconds"
This is traditionally done by having an operating system with deterministic timing in its interrupt handling, so that it can schedule preemptive wake-up calls exactly when needed. As well as some important edge case handling like fast queueing of interrupts for later processing, or even dropping them entirely if a hard scheduled interrupt is being processed. Preemptive execution and OS threading is an absolute requirement.
Async rust doesn't even provide hard interrupts. It's cooperative multithreading so if some other event handler happens to be running when you need to resume, you're boned.
So AFAICT Embassy doesn't do this at all? In which case it doesn't "obsolete the need for a traditional RTOS with kernel context switching."
I haven't used Embassy, but the README mentions "Tasks on the same async executor run cooperatively, but you can create multiple executors with different priorities so that higher priority tasks preempt lower priority ones" and links to an example that shows how a higher priority task runs even though a lower priority one runs a long time job (does not yield), thus understanding and infrastructure seems to be there.
So, Embassy may in its entirety replace an RTOS / be one, but it's not the async mechanism that can provide the RT part (and I guess you're right to point out the dangerous sentence as it could mislead people to use only async and believe it's RT).
OTOH the sentence would be right if it were something like "async multitasking is an alternative to preemptive multitasking, and can replace the use of a preemptive OS if real-time guarantees are not needed (note that Embassy separately allows running multiple executors to allow to pre-empt tasks running in lower-priority executors)". They should probably also describe what the reason for not needing per-task stack size tuning is.
(interrupt queuing and prioritization can be handled by the hardware nowadays. RTIC, a similar project, uses this to drop the need for a scheduler altogether and just runs all code in interrupt handlers, something which 'traditional' realtime wisdom would forbid because it's from an era where you didn't have something like an NVIC.)