From 80a740bc72430a9be6f7da9d94916984530838e0 Mon Sep 17 00:00:00 2001 From: Ulf Lilleengen Date: Tue, 3 Oct 2023 21:35:31 +0200 Subject: [PATCH] docs: minor doc improvements and cleanup --- docs/modules/ROOT/nav.adoc | 4 ++-- docs/modules/ROOT/pages/getting_started.adoc | 7 +++++-- docs/modules/ROOT/pages/hal.adoc | 4 +++- docs/modules/ROOT/pages/index.adoc | 17 +++++++++++++++-- docs/modules/ROOT/pages/layer_by_layer.adoc | 5 ++--- docs/modules/ROOT/pages/nrf.adoc | 6 +++++- docs/modules/ROOT/pages/runtime.adoc | 2 +- 7 files changed, 33 insertions(+), 12 deletions(-) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 261a3c19..ee559a82 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,6 +1,6 @@ * xref:getting_started.adoc[Getting started] ** xref:basic_application.adoc[Basic application] -** xref:layer_by_layer.adoc[Layer by Layer] +* xref:layer_by_layer.adoc[Bare metal to async] * xref:runtime.adoc[Executor] * xref:hal.adoc[HAL] ** xref:nrf.adoc[nRF] @@ -9,4 +9,4 @@ * xref:examples.adoc[Examples] * xref:developer.adoc[Developer] -** xref:developer_stm32.adoc[Developer: STM32] \ No newline at end of file +** xref:developer_stm32.adoc[Developer: STM32] diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/modules/ROOT/pages/getting_started.adoc index 881e449b..2c6f4b1e 100644 --- a/docs/modules/ROOT/pages/getting_started.adoc +++ b/docs/modules/ROOT/pages/getting_started.adoc @@ -3,7 +3,7 @@ So you want to try Embassy, great! To get started, there are a few tools you need to install: * link:https://rustup.rs/[rustup] - the Rust toolchain is needed to compile Rust code. -* link:https://crates.io/crates/probe-run[probe-run] - to flash the firmware on your device. If you already have other tools like `OpenOCD` setup, you can use that as well. +* link:https://crates.io/crates/probe-rs[probe-rs] - to flash the firmware on your device. If you already have other tools like `OpenOCD` setup, you can use that as well. If you don't have any supported board, don't worry: you can also run embassy on your PC using the `std` examples. @@ -30,6 +30,10 @@ Embassy supports many microcontroller families, but the easiest ways to get star * link:https://www.raspberrypi.com/products/raspberry-pi-pico/[Raspberry Pi Pico] +=== ESP32 + +* link:https://github.com/esp-rs/esp-rust-board[ESP32C3] + == Running an example First you need to clone the [github repository]; @@ -38,7 +42,6 @@ First you need to clone the [github repository]; ---- git clone https://github.com/embassy-rs/embassy.git cd embassy -git submodule update --init ---- You can run an example by opening a terminal and entering the following commands: diff --git a/docs/modules/ROOT/pages/hal.adoc b/docs/modules/ROOT/pages/hal.adoc index de4ab33b..b1382e8e 100644 --- a/docs/modules/ROOT/pages/hal.adoc +++ b/docs/modules/ROOT/pages/hal.adoc @@ -7,4 +7,6 @@ Embassy provides HALs for several microcontroller families: * `embassy-rp` for the Raspberry Pi RP2040 microcontrollers These HALs implement async/await functionality for most peripherals while also implementing the -async traits in `embedded-hal-async`. You can also use these HALs with another executor. +async traits in `embedded-hal` and `embedded-hal-async`. You can also use these HALs with another executor. + +For the ESP32 series, there is an link:https://github.com/esp-rs/esp-hal[esp-hal] which you can use. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 805a1e70..c6dead46 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -17,13 +17,26 @@ The Embassy project consists of several crates that you can use together or inde * **Hardware Abstraction Layers** - HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed. The Embassy project maintains HALs for select hardware, but you can still use HALs from other projects with Embassy. ** link:https://docs.embassy.dev/embassy-stm32/[embassy-stm32], for all STM32 microcontroller families. ** link:https://docs.embassy.dev/embassy-nrf/[embassy-nrf], for the Nordic Semiconductor nRF52, nRF53, nRF91 series. +** link:https://docs.embassy.dev/embassy-rp/[embassy-rp], for the Raspberry Pi RP2040 microcontroller. +** link:https://github.com/esp-rs[esp-rs], for the Espressif Systems ESP32 series of chips. ++ +NOTE: A common question is if one can use the Embassy HALs standalone. Yes, it is possible! There are no dependency on the executor within the HALs. You can even use them without async, +as they implement both the link:https://github.com/rust-embedded/embedded-hal[Embedded HAL] blocking and async traits. -* **Networking** - The link:https://docs.embassy.dev/embassy-net/[embassy-net] network stack implements extensive networking functionality, including Ethernet, IP, TCP, UDP, ICMP and DHCP. Async drastically simplifies managing timeouts and serving multiple connections concurrently. +* **Networking** - The link:https://docs.embassy.dev/embassy-net/[embassy-net] network stack implements extensive networking functionality, including Ethernet, IP, TCP, UDP, ICMP and DHCP. Async drastically simplifies managing timeouts and serving multiple connections concurrently. Several drivers for WiFi and Ethernet chips can be found. * **Bluetooth** - The link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] crate provides Bluetooth Low Energy 4.x and 5.x support for nRF52 microcontrollers. -* **LoRa** - link:https://docs.embassy.dev/embassy-lora/[embassy-lora] supports LoRa networking on STM32WL wireless microcontrollers and Semtech SX127x transceivers. +* **LoRa** - link:https://github.com/embassy-rs/lora-phy[lora-phy] and link:https://docs.embassy.dev/embassy-lora/[embassy-lora] supports LoRa networking on a wide range of LoRa radios, fully integrated with a Rust link:https://github.com/ivajloip/rust-lorawan[LoRaWAN] implementation. * **USB** - 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. + +== Resources + +For more reading material on async Rust and Embassy: + +* link:https://tweedegolf.nl/en/blog/65/async-rust-vs-rtos-showdown[Comparsion of FreeRTOS and Embassy] +* link:https://dev.to/apollolabsbin/series/20707[Tutorials] +* link:https://blog.drogue.io/firmware-updates-part-1/[Firmware Updates with Embassy] diff --git a/docs/modules/ROOT/pages/layer_by_layer.adoc b/docs/modules/ROOT/pages/layer_by_layer.adoc index a78a64a9..1d7bdc89 100644 --- a/docs/modules/ROOT/pages/layer_by_layer.adoc +++ b/docs/modules/ROOT/pages/layer_by_layer.adoc @@ -1,4 +1,4 @@ -= Embassy layer by layer += From bare metal to async Rust If you're new to Embassy, it can be overwhelming to grasp all the terminology and concepts. This guide aims to clarify the different layers in Embassy, which problem each layer solves for the application writer. @@ -8,8 +8,7 @@ The application we'll write is a simple 'push button, blink led' application, wh == PAC version -The PAC is the lowest API for accessing peripherals and registers, if you don't count reading/writing directly to memory addresses. It provides distinct types -to make accessing peripheral registers easier, but it does not prevent you from writing unsafe code. +The PAC is the lowest API for accessing peripherals and registers, if you don't count reading/writing directly to memory addresses. It provides distinct types to make accessing peripheral registers easier, but it does not prevent you from writing unsafe code. Writing an application using the PAC directly is therefore not recommended, but if the functionality you want to use is not exposed in the upper layers, that's what you need to use. diff --git a/docs/modules/ROOT/pages/nrf.adoc b/docs/modules/ROOT/pages/nrf.adoc index 10fe54b4..1706087a 100644 --- a/docs/modules/ROOT/pages/nrf.adoc +++ b/docs/modules/ROOT/pages/nrf.adoc @@ -8,7 +8,7 @@ The nRF timer driver operates at 32768 Hz by default. == Peripherals -The following peripherals have a HAL implementation at present: +The following peripherals have a HAL implementation at present * PWM * SPIM @@ -23,3 +23,7 @@ The following peripherals have a HAL implementation at present: * UARTE * TWIM * SAADC + +== Bluetooth + +For bluetooth, you can use the link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] crate. diff --git a/docs/modules/ROOT/pages/runtime.adoc b/docs/modules/ROOT/pages/runtime.adoc index 5096f5a4..cb8afef2 100644 --- a/docs/modules/ROOT/pages/runtime.adoc +++ b/docs/modules/ROOT/pages/runtime.adoc @@ -10,7 +10,7 @@ The Embassy executor is an async/await executor designed for embedded usage alon * No busy-loop polling: CPU sleeps when there's no work to do, using interrupts or `WFE/SEV`. * Efficient polling: a wake will only poll the woken task, not all of them. * Fair: a task can't monopolize CPU time even if it's constantly being woken. All other tasks get a chance to run before a given task gets polled for the second time. -* Creating multiple executor instances is supported, to run tasks with multiple priority levels. This allows higher-priority tasks to preempt lower-priority tasks. +* Creating multiple executor instances is supported, to run tasks at different priority levels. This allows higher-priority tasks to preempt lower-priority tasks. == Executor