From 4caafe10aeb0b884a820f1e317f131b61e701e3c Mon Sep 17 00:00:00 2001 From: Barnaby Walters <barnaby@waterpigs.co.uk> Date: Thu, 11 Jan 2024 19:49:05 +0100 Subject: [PATCH 1/4] Expanded readme for crates release --- embassy-stm32/README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 embassy-stm32/README.md diff --git a/embassy-stm32/README.md b/embassy-stm32/README.md new file mode 100644 index 000000000..b9b1f7820 --- /dev/null +++ b/embassy-stm32/README.md @@ -0,0 +1,28 @@ +# Embassy STM32 HAL + +The embassy-stm32 HAL aims to provide a safe, idiomatic hardware abstraction layer for all STM32 families. The HAL implements both blocking and async APIs for many peripherals. Where appropriate, traits from both blocking and asynchronous versions of [embedded-hal](https://docs.rs/embedded-hal/latest/embedded_hal/) v0.2 and v1.0 are implemented, as well as serial traits from embedded-io\[-async]. + +* [embassy-stm32 on crates.io](https://crates.io/crates/embassy-stm32) +* [Documentation](https://docs.embassy.dev/embassy-stm32/) (**Important:** use docs.embassy.dev rather than docs.rs to see the specific docs for the chip you’re using!) +* [Source](https://github.com/embassy-rs/embassy/tree/main/embassy-stm32) +* [Examples](https://github.com/embassy-rs/embassy/tree/main/examples) + +## embassy-stm32 supports all STM32 chip families + +STM32 microcontrollers come in many families and flavors, and supporting all of them is a big undertaking. Embassy takes advantage of the fact that the STM32 peripheral versions are shared across chip families. For example, instead of re-implementing the SPI peripheral for every STM32 chip family, embassy has a single SPI implementation that depends on code-generated register types that are identical for STM32 families with the same version of a given peripheral. + +In practice, this works as follows: + +1. You tell the compiler which chip you’re using with a feature flag +1. The stm32-metapac module generates register types for that chip at compile time, based on data from the stm32-data module +1. The embassy-stm32 HAL picks the correct implementation each peripheral based on automatically-generated feature flags, and applies any other tweaks which are required for the HAL to work on that chip + +Be aware that, while embassy-stm32 strives to consistently support all peripherals across all chips, this approach can lead to slightly different APIs and capabilities being available on different families. Check the [documentation](https://docs.embassy.dev/embassy-stm32/) for the specific chip you’re using to confirm exactly what’s available. + +## Minimum supported Rust version (MSRV) +Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release. + +## embassy-time Timer Driver +If the `time` feature is enabled, embassy-stm32 provides a timer driver for use with [embassy-time](https://docs.embassy.dev/embassy-time/). You can pick which hardware timer is used for this internally via the `time-driver-*` features, or let embassy pick with `time-driver-any`. + +embassy-time has a default tick rate of 1MHz, which is fast enough to cause problems with the 16-bit timers currently supported by the embassy-stm32 time driver (specifically, if a critical section delays an IRQ by more than 32ms). To avoid this, it’s recommended to pick a lower tick rate. 32.768kHz is a reasonable default for many purposes. \ No newline at end of file From ccf61f50feba45c496de1c3dc49b58cad5b8f7a1 Mon Sep 17 00:00:00 2001 From: Barnaby Walters <barnaby@waterpigs.co.uk> Date: Thu, 11 Jan 2024 19:55:15 +0100 Subject: [PATCH 2/4] Corrections from review --- embassy-stm32/README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/embassy-stm32/README.md b/embassy-stm32/README.md index b9b1f7820..7cce97d5e 100644 --- a/embassy-stm32/README.md +++ b/embassy-stm32/README.md @@ -19,10 +19,7 @@ In practice, this works as follows: Be aware that, while embassy-stm32 strives to consistently support all peripherals across all chips, this approach can lead to slightly different APIs and capabilities being available on different families. Check the [documentation](https://docs.embassy.dev/embassy-stm32/) for the specific chip you’re using to confirm exactly what’s available. -## Minimum supported Rust version (MSRV) -Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release. - -## embassy-time Timer Driver +## embassy-time Time Driver If the `time` feature is enabled, embassy-stm32 provides a timer driver for use with [embassy-time](https://docs.embassy.dev/embassy-time/). You can pick which hardware timer is used for this internally via the `time-driver-*` features, or let embassy pick with `time-driver-any`. embassy-time has a default tick rate of 1MHz, which is fast enough to cause problems with the 16-bit timers currently supported by the embassy-stm32 time driver (specifically, if a critical section delays an IRQ by more than 32ms). To avoid this, it’s recommended to pick a lower tick rate. 32.768kHz is a reasonable default for many purposes. \ No newline at end of file From 1697386820993f7fc8ab39708a1b7349d9ed621e Mon Sep 17 00:00:00 2001 From: Barnaby Walters <barnaby@waterpigs.co.uk> Date: Thu, 11 Jan 2024 19:57:24 +0100 Subject: [PATCH 3/4] Correction from review --- embassy-stm32/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/embassy-stm32/README.md b/embassy-stm32/README.md index 7cce97d5e..23c1bf967 100644 --- a/embassy-stm32/README.md +++ b/embassy-stm32/README.md @@ -20,6 +20,6 @@ In practice, this works as follows: Be aware that, while embassy-stm32 strives to consistently support all peripherals across all chips, this approach can lead to slightly different APIs and capabilities being available on different families. Check the [documentation](https://docs.embassy.dev/embassy-stm32/) for the specific chip you’re using to confirm exactly what’s available. ## embassy-time Time Driver -If the `time` feature is enabled, embassy-stm32 provides a timer driver for use with [embassy-time](https://docs.embassy.dev/embassy-time/). You can pick which hardware timer is used for this internally via the `time-driver-*` features, or let embassy pick with `time-driver-any`. +If the `time` feature is enabled, embassy-stm32 provides a time driver for use with [embassy-time](https://docs.embassy.dev/embassy-time/). You can pick which hardware timer is used for this internally via the `time-driver-*` features, or let embassy pick with `time-driver-any`. embassy-time has a default tick rate of 1MHz, which is fast enough to cause problems with the 16-bit timers currently supported by the embassy-stm32 time driver (specifically, if a critical section delays an IRQ by more than 32ms). To avoid this, it’s recommended to pick a lower tick rate. 32.768kHz is a reasonable default for many purposes. \ No newline at end of file From 557399e2d6537ee64691e44f7a1f4a3e61e20490 Mon Sep 17 00:00:00 2001 From: Barnaby Walters <barnaby@waterpigs.co.uk> Date: Thu, 11 Jan 2024 20:00:33 +0100 Subject: [PATCH 4/4] Included README.md in docs --- embassy-stm32/src/lib.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/embassy-stm32/src/lib.rs b/embassy-stm32/src/lib.rs index 45a2ab63e..18871e83b 100644 --- a/embassy-stm32/src/lib.rs +++ b/embassy-stm32/src/lib.rs @@ -1,5 +1,6 @@ #![cfg_attr(not(test), no_std)] #![allow(async_fn_in_trait)] +#![doc = include_str!("../README.md")] #![warn(missing_docs)] //! ## Feature flags