From 028ca55f9ca3bfa2e4aa99b16bc0e0e29241fe70 Mon Sep 17 00:00:00 2001 From: kalkyl Date: Mon, 8 Jul 2024 17:16:35 +0200 Subject: Add more docs and cross-links --- docs/pages/faq.adoc | 3 ++- docs/pages/sharing_peripherals.adoc | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/pages/faq.adoc b/docs/pages/faq.adoc index a2f56a539..fc1316062 100644 --- a/docs/pages/faq.adoc +++ b/docs/pages/faq.adoc @@ -352,7 +352,8 @@ There are two main ways to handle concurrency in Embassy: In general, either of these approaches will work. The main differences of these approaches are: -When using **separate tasks**, each task needs its own RAM allocation, so there's a little overhead for each task, so one task that does three things will likely be a little bit smaller than three tasks that do one thing (not a lot, probably a couple dozen bytes). In contrast, with **multiple futures in one task**, you don't need multiple task allocations, and it will generally be easier to share data, or use borrowed resources, inside of a single task. +When using **separate tasks**, each task needs its own RAM allocation, so there's a little overhead for each task, so one task that does three things will likely be a little bit smaller than three tasks that do one thing (not a lot, probably a couple dozen bytes). In contrast, with **multiple futures in one task**, you don't need multiple task allocations, and it will generally be easier to share data, or use borrowed resources, inside of a single task. +An example showcasing some methods for sharing things between tasks link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/sharing.rs[can be found here]. But when it comes to "waking" tasks, for example when a data transfer is complete or a button is pressed, it's faster to wake a dedicated task, because that task does not need to check which future is actually ready. `join` and `select` must check ALL of the futures they are managing to see which one (or which ones) are ready to do more work. This is because all Rust executors (like Embassy or Tokio) only have the ability to wake tasks, not specific futures. This means you will use slightly less CPU time juggling futures when using dedicated tasks. diff --git a/docs/pages/sharing_peripherals.adoc b/docs/pages/sharing_peripherals.adoc index 6bcd56b01..ebd899c4e 100644 --- a/docs/pages/sharing_peripherals.adoc +++ b/docs/pages/sharing_peripherals.adoc @@ -126,3 +126,5 @@ async fn toggle_led(control: Sender<'static, ThreadModeRawMutex, LedState, 64>, This example replaces the Mutex with a Channel, and uses another task (the main loop) to drive the LED. The advantage of this approach is that only a single task references the peripheral, separating concerns. However, using a Mutex has a lower overhead and might be necessary if you need to ensure that the operation is completed before continuing to do other work in your task. + +An example showcasing more methods for sharing link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/sharing.rs[can be found here]. \ No newline at end of file -- cgit From af9c7379f99b309a99b0b573ebfb8ea1bebecaf9 Mon Sep 17 00:00:00 2001 From: kalkyl Date: Mon, 8 Jul 2024 22:53:50 +0200 Subject: Add link to example in book --- docs/pages/sharing_peripherals.adoc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/pages/sharing_peripherals.adoc b/docs/pages/sharing_peripherals.adoc index ebd899c4e..6ba13f93b 100644 --- a/docs/pages/sharing_peripherals.adoc +++ b/docs/pages/sharing_peripherals.adoc @@ -127,4 +127,8 @@ async fn toggle_led(control: Sender<'static, ThreadModeRawMutex, LedState, 64>, This example replaces the Mutex with a Channel, and uses another task (the main loop) to drive the LED. The advantage of this approach is that only a single task references the peripheral, separating concerns. However, using a Mutex has a lower overhead and might be necessary if you need to ensure that the operation is completed before continuing to do other work in your task. -An example showcasing more methods for sharing link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/sharing.rs[can be found here]. \ No newline at end of file +An example showcasing more methods for sharing link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/sharing.rs[can be found here]. + +== Sharing an I2C or SPI bus between multiple devices + +An example of how to deal with multiple devices sharing a common I2C or SPI bus link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/shared_bus.rs[can be found here]. -- cgit From 2f62376a15b931dcf24708717695107f2c99fb1b Mon Sep 17 00:00:00 2001 From: rafael Date: Mon, 8 Jul 2024 23:27:42 +0200 Subject: add faq --- docs/pages/faq.adoc | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/pages/faq.adoc b/docs/pages/faq.adoc index fc1316062..4ab04e2a1 100644 --- a/docs/pages/faq.adoc +++ b/docs/pages/faq.adoc @@ -358,3 +358,7 @@ An example showcasing some methods for sharing things between tasks link:https:/ But when it comes to "waking" tasks, for example when a data transfer is complete or a button is pressed, it's faster to wake a dedicated task, because that task does not need to check which future is actually ready. `join` and `select` must check ALL of the futures they are managing to see which one (or which ones) are ready to do more work. This is because all Rust executors (like Embassy or Tokio) only have the ability to wake tasks, not specific futures. This means you will use slightly less CPU time juggling futures when using dedicated tasks. Practically, there's not a LOT of difference either way - so go with what makes it easier for you and your code first, but there will be some details that are slightly different in each case. + +== splitting peripherals resources between tasks + +There are two ways to split resources between tasks, either manually assigned or by a convenient macro. See link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/assign_resources.rs[this example] \ No newline at end of file -- cgit From dc6639fa4d53ec7ad6a6aa0bd810952e4123e51d Mon Sep 17 00:00:00 2001 From: Mark Tomlin Date: Mon, 22 Jul 2024 06:59:13 -0400 Subject: Updated github branch from `master` to `main`. --- docs/pages/basic_application.adoc | 2 +- docs/pages/nrf.adoc | 2 +- docs/pages/overview.adoc | 2 +- docs/pages/stm32.adoc | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/pages/basic_application.adoc b/docs/pages/basic_application.adoc index 7b4ebda4f..5c4e3e8b3 100644 --- a/docs/pages/basic_application.adoc +++ b/docs/pages/basic_application.adoc @@ -4,7 +4,7 @@ So you've got one of the examples running, but what now? Let's go through a simp == Main -The full example can be found link:https://github.com/embassy-rs/embassy/tree/master/docs/examples/basic[here]. +The full example can be found link:https://github.com/embassy-rs/embassy/tree/main/docs/examples/basic[here]. NOTE: If you’re using VS Code and rust-analyzer to view and edit the examples, you may need to make some changes to `.vscode/settings.json` to tell it which project we’re working on. Follow the instructions commented in that file to get rust-analyzer working correctly. diff --git a/docs/pages/nrf.adoc b/docs/pages/nrf.adoc index 1706087ae..de052b63f 100644 --- a/docs/pages/nrf.adoc +++ b/docs/pages/nrf.adoc @@ -1,6 +1,6 @@ = Embassy nRF HAL -The link:https://github.com/embassy-rs/embassy/tree/master/embassy-nrf[Embassy nRF HAL] is based on the PACs (Peripheral Access Crate) from link:https://github.com/nrf-rs/[nrf-rs]. +The link:https://github.com/embassy-rs/embassy/tree/main/embassy-nrf[Embassy nRF HAL] is based on the PACs (Peripheral Access Crate) from link:https://github.com/nrf-rs/[nrf-rs]. == Timer driver diff --git a/docs/pages/overview.adoc b/docs/pages/overview.adoc index 1b9381bfe..7d59d5521 100644 --- a/docs/pages/overview.adoc +++ b/docs/pages/overview.adoc @@ -48,7 +48,7 @@ link:https://github.com/lora-rs/lora-rs[lora-rs] supports LoRa networking on a w link:https://docs.embassy.dev/embassy-usb/[embassy-usb] implements a device-side USB stack. Implementations for common classes such as USB serial (CDC ACM) and USB HID are available, and a rich builder API allows building your own. === Bootloader and DFU -link:https://github.com/embassy-rs/embassy/tree/master/embassy-boot[embassy-boot] is a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks. +link:https://github.com/embassy-rs/embassy/tree/main/embassy-boot[embassy-boot] is a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks. == What is DMA? diff --git a/docs/pages/stm32.adoc b/docs/pages/stm32.adoc index 7bfc0592b..df139a420 100644 --- a/docs/pages/stm32.adoc +++ b/docs/pages/stm32.adoc @@ -1,6 +1,6 @@ = Embassy STM32 HAL -The link:https://github.com/embassy-rs/embassy/tree/master/embassy-stm32[Embassy STM32 HAL] is based on the `stm32-metapac` project. +The link:https://github.com/embassy-rs/embassy/tree/main/embassy-stm32[Embassy STM32 HAL] is based on the `stm32-metapac` project. == The infinite variant problem -- cgit From 4811c14cc8ad57251e50e3aaa6d221f80603f577 Mon Sep 17 00:00:00 2001 From: Mark Tomlin Date: Mon, 22 Jul 2024 07:26:55 -0400 Subject: Updated cargo toml section links. --- docs/pages/new_project.adoc | 2 +- docs/pages/sharing_peripherals.adoc | 4 ++-- docs/pages/time_keeping.adoc | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/pages/new_project.adoc b/docs/pages/new_project.adoc index 346d9f0f8..821bcbd27 100644 --- a/docs/pages/new_project.adoc +++ b/docs/pages/new_project.adoc @@ -1,6 +1,6 @@ = Starting a new project -Once you’ve successfully xref:getting_started.adoc[run some example projects], the next step is to make a standalone Embassy project. +Once you’ve successfully xref:#_getting_started[run some example projects], the next step is to make a standalone Embassy project. == Tools for generating Embassy projects diff --git a/docs/pages/sharing_peripherals.adoc b/docs/pages/sharing_peripherals.adoc index 6ba13f93b..dfb8c1ffe 100644 --- a/docs/pages/sharing_peripherals.adoc +++ b/docs/pages/sharing_peripherals.adoc @@ -8,7 +8,7 @@ The following examples shows different ways to use the on-board LED on a Raspber Using mutual exclusion is the simplest way to share a peripheral. -TIP: Dependencies needed to run this example link:/book/dev/basic_application.html#_the_cargo_toml[can be found here]. +TIP: Dependencies needed to run this example link:#_the_cargo_toml[can be found here]. [,rust] ---- use defmt::*; @@ -78,7 +78,7 @@ To indicate that the pin will be set to an Output. The `AnyPin` could have been A channel is another way to ensure exclusive access to a resource. Using a channel is great in the cases where the access can happen at a later point in time, allowing you to enqueue operations and do other things. -TIP: Dependencies needed to run this example link:/book/dev/basic_application.html#_the_cargo_toml[can be found here]. +TIP: Dependencies needed to run this example link:#_the_cargo_toml[can be found here]. [,rust] ---- use defmt::*; diff --git a/docs/pages/time_keeping.adoc b/docs/pages/time_keeping.adoc index 17492a884..11ddb2b2b 100644 --- a/docs/pages/time_keeping.adoc +++ b/docs/pages/time_keeping.adoc @@ -16,7 +16,7 @@ The `embassy::time::Timer` type provides two timing methods. An example of a delay is provided as follows: -TIP: Dependencies needed to run this example link:/book/dev/basic_application.html#_the_cargo_toml[can be found here]. +TIP: Dependencies needed to run this example link:#_the_cargo_toml[can be found here]. [,rust] ---- use embassy::executor::{task, Executor}; @@ -41,7 +41,7 @@ that expect a generic delay implementation to be provided. An example of how this can be used: -TIP: Dependencies needed to run this example link:/book/dev/basic_application.html#_the_cargo_toml[can be found here]. +TIP: Dependencies needed to run this example link:#_the_cargo_toml[can be found here]. [,rust] ---- use embassy::executor::{task, Executor}; -- cgit From 44282b18faf77b7ff2fa521eb7995fa46ca16e01 Mon Sep 17 00:00:00 2001 From: Ulf Lilleengen Date: Fri, 2 Aug 2024 19:20:26 +0200 Subject: Prepare embassy-time release --- docs/examples/basic/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/examples/basic/Cargo.toml b/docs/examples/basic/Cargo.toml index e82165032..40d23ffa1 100644 --- a/docs/examples/basic/Cargo.toml +++ b/docs/examples/basic/Cargo.toml @@ -7,7 +7,7 @@ license = "MIT OR Apache-2.0" [dependencies] embassy-executor = { version = "0.5.0", path = "../../../embassy-executor", features = ["defmt", "integrated-timers", "arch-cortex-m", "executor-thread"] } -embassy-time = { version = "0.3.1", path = "../../../embassy-time", features = ["defmt"] } +embassy-time = { version = "0.3.2", path = "../../../embassy-time", features = ["defmt"] } embassy-nrf = { version = "0.1.0", path = "../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] } defmt = "0.3" -- cgit From 2f3b3335e12f4c3aa988078d46cb6a3597277bd7 Mon Sep 17 00:00:00 2001 From: Ulf Lilleengen Date: Fri, 2 Aug 2024 19:25:35 +0200 Subject: Prepare for embassy-nrf release --- docs/examples/basic/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/examples/basic/Cargo.toml b/docs/examples/basic/Cargo.toml index 40d23ffa1..6d5689d07 100644 --- a/docs/examples/basic/Cargo.toml +++ b/docs/examples/basic/Cargo.toml @@ -8,7 +8,7 @@ license = "MIT OR Apache-2.0" [dependencies] embassy-executor = { version = "0.5.0", path = "../../../embassy-executor", features = ["defmt", "integrated-timers", "arch-cortex-m", "executor-thread"] } embassy-time = { version = "0.3.2", path = "../../../embassy-time", features = ["defmt"] } -embassy-nrf = { version = "0.1.0", path = "../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] } +embassy-nrf = { version = "0.2.0", path = "../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] } defmt = "0.3" defmt-rtt = "0.3" -- cgit From 37d7b0cd06b7a5d952d2e7de173b10ab32d96c5a Mon Sep 17 00:00:00 2001 From: Ulf Lilleengen Date: Fri, 2 Aug 2024 21:50:18 +0200 Subject: prepare release embassy-executor --- docs/examples/basic/Cargo.toml | 2 +- docs/examples/layer-by-layer/blinky-async/Cargo.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/examples/basic/Cargo.toml b/docs/examples/basic/Cargo.toml index 6d5689d07..5d391adf3 100644 --- a/docs/examples/basic/Cargo.toml +++ b/docs/examples/basic/Cargo.toml @@ -6,7 +6,7 @@ version = "0.1.0" license = "MIT OR Apache-2.0" [dependencies] -embassy-executor = { version = "0.5.0", path = "../../../embassy-executor", features = ["defmt", "integrated-timers", "arch-cortex-m", "executor-thread"] } +embassy-executor = { version = "0.6.0", path = "../../../embassy-executor", features = ["defmt", "integrated-timers", "arch-cortex-m", "executor-thread"] } embassy-time = { version = "0.3.2", path = "../../../embassy-time", features = ["defmt"] } embassy-nrf = { version = "0.2.0", path = "../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] } diff --git a/docs/examples/layer-by-layer/blinky-async/Cargo.toml b/docs/examples/layer-by-layer/blinky-async/Cargo.toml index 64f7e8403..7f8d8af3e 100644 --- a/docs/examples/layer-by-layer/blinky-async/Cargo.toml +++ b/docs/examples/layer-by-layer/blinky-async/Cargo.toml @@ -8,7 +8,7 @@ license = "MIT OR Apache-2.0" cortex-m = "0.7" cortex-m-rt = "0.7" embassy-stm32 = { version = "0.1.0", features = ["stm32l475vg", "memory-x", "exti"] } -embassy-executor = { version = "0.5.0", features = ["arch-cortex-m", "executor-thread"] } +embassy-executor = { version = "0.6.0", features = ["arch-cortex-m", "executor-thread"] } defmt = "0.3.0" defmt-rtt = "0.3.0" -- cgit