Crate embassy_rp

Embassy RP HAL

HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed.

The embassy-rp HAL targets the Raspberry Pi RP2040 microcontroller. The HAL implements both blocking and async APIs for many peripherals. The benefit of using the async APIs is that the HAL takes care of waiting for peripherals to complete operations in low power mode and handling interrupts, so that applications can focus on more important matters.

• embassy-rp on crates.io
• Documentation
• Source
• Examples

embassy-time time driver

If the time-driver feature is enabled, the HAL uses the TIMER peripheral as a global time driver for embassy-time, with a tick rate of 1MHz.

Embedded-hal

The embassy-rp HAL implements the traits from embedded-hal (v0.2 and 1.0) and embedded-hal-async, as well as embedded-io and embedded-io-async.

Interoperability

This crate can run on any executor.

Optionally, some features requiring embassy-time can be activated with the time-driver feature. If you enable it, you must link an embassy-time driver in your project.

Feature flags

• rt (enabled by default) — Enable the rt feature of rp-pac. This brings in the cortex-m-rt crate, which adds startup code and minimal runtime initialization.
• defmt — Enable defmt support and enables defmt debug-log messages and formatting in embassy drivers.
• critical-section-impl — Configure the critical-section crate to use an implementation that is safe for multicore use on rp2040.
• unstable-pac — Reexport the PAC for the currently enabled chip at embassy_rp::pac. This is unstable because semver-minor (non-breaking) releases of embassy-rp may major-bump (breaking) the PAC version. If this is an issue for you, you’re encouraged to directly depend on a fixed version of the PAC. There are no plans to make this stable.
• time-driver — Enable the timer for use with embassy-time with a 1MHz tick rate.
• rom-func-cache — Enable ROM function cache. This will store the address of a ROM function when first used, improving performance of subsequent calls.
• intrinsics — Enable implementations of some compiler intrinsics using functions in the rp2040 Mask ROM. These should be as fast or faster than the implementations in compiler-builtins. They also save code space and reduce memory contention. Compiler intrinsics are used automatically, you do not need to change your code to get performance improvements from this feature.
• rom-v2-intrinsics — Enable intrinsics based on extra ROM functions added in the v2 version of the rp2040 Mask ROM. This version added a lot more floating point operations - many f64 functions and a few f32 functions were added in ROM v2.
• qspi-as-gpio — Allow using QSPI pins as GPIO pins. This is mostly not what you want (because your flash is attached via QSPI pins) and adds code and memory overhead when this feature is enabled.
• run-from-ram — Indicate code is running from RAM. Set this if all code is in RAM, and the cores never access memory-mapped flash memory through XIP. This allows the flash driver to not force pausing execution on both cores when doing flash operations.

boot2 flash chip support

RP2040’s internal bootloader is only able to run code from the first 256 bytes of flash. A 2nd stage bootloader (boot2) is required to run larger programs from external flash. Select from existing boot2 implementations via the following features. If none are selected, boot2-w25q080 will be used (w25q080 is the flash chip used on the pico). Each implementation uses flash commands and timings specific to a QSPI flash chip family for better performance.

• boot2-at25sf128a — Use boot2 with support for Renesas/Dialog AT25SF128a SPI flash.

• boot2-gd25q64cs — Use boot2 with support for Gigadevice GD25Q64C SPI flash.

• boot2-generic-03h — Use boot2 that only uses generic flash commands - these are supported by all SPI flash, but are slower.

• boot2-is25lp080 — Use boot2 with support for ISSI IS25LP080 SPI flash.

• boot2-ram-memcpy — Use boot2 that copies the entire program to RAM before booting. This uses generic flash commands to perform the copy.

• boot2-w25q080 — Use boot2 with support for Winbond W25Q080 SPI flash.

• boot2-w25x10cl — Use boot2 with support for Winbond W25X10CL SPI flash.

• boot2-none — Have embassy not provide the boot2 so you can use your own. Place your own in the “.boot2” section like:

  #[link_section = ".boot2"]
  #[used]
  static BOOT2: [u8; 256] = [0; 256]; // Provide your own with e.g. include_bytes!

• rp2040 — Configure the hal for use with the rp2040

• rp235xa — Configure the hal for use with the rp235xA

• rp235xb — Configure the hal for use with the rp235xB

• binary-info — Add a binary-info header block containing picotool-compatible metadata.

  Takes up a little flash space, but picotool can then report the name of your program and other details.

Re-exports

• pub use rp_pac as pac;

Modules

• adc
  ADC driver.
• block
  Support for the RP235x Boot ROM’s “Block” structures
• clocks
  Clock configuration for the RP2040
• config
  HAL configuration for RP.
• dma
  Direct Memory Access (DMA)
• flash
  Flash driver.
• gpio
  GPIO driver.
• i2c
  I2C driver.
• i2c_slave
  I2C slave driver.
• interrupt
  Interrupt definitions.
• multicore
  Multicore support
• otp
  Interface to the RP2350’s One Time Programmable Memory
• peripherals
  Types for the peripheral singletons.
• pio
  PIO driver.
• pio_programs
  Pre-built pio programs for common interfaces
• pwm
  Pulse Width Modulation (PWM)
• rom_data
  //! Functions and data from the RPI Bootrom. //! //! From Section 5.4 of the //! RP2350 datasheet: //! //! > Whilst some ROM space is dedicated to the implementation of the boot //! > sequence and USB/UART boot interfaces, the bootrom also contains public //! > functions that provide useful RP2350 functionality that may be useful for //! > any code or runtime running on the device
• spi
  Serial Peripheral Interface
• time_driver
  Timer driver.
• trng
  True Random Number Generator (TRNG) driver.
• uart
  UART driver.
• usb
  USB driver.
• watchdog
  Watchdog

Macros

• bind_interrupts
  Macro to bind interrupts to handlers.
• into_ref
  Convenience converting into reference.

Structs

• PeripheralRef
  An exclusive reference to a peripheral.
• Peripherals
  Struct containing all the peripheral singletons.

Constants

• NVIC_PRIO_BITS
  Number available in the NVIC for configuring priority

Traits

• Peripheral
  Trait for any type that can be used as a peripheral of type P.

Functions

• init
  Initialize the embassy-rp HAL with the provided configuration.
• install_core0_stack_guard
  Installs a stack guard for the CORE0 stack in MPU region 0. Will fail if the MPU is already configured. This function requires a _stack_end symbol to be defined by the linker script, and expects _stack_end to be located at the lowest address (largest depth) of the stack.

Attribute Macros

• interrupt