Crate esp_rtos

This crate provides RTOS functionality for esp-radio, and provides executors to enable running async code.

Setup

This crate requires an esp-hal timer to operate, and needs to be started like so:

use esp_hal::timer::timg::TimerGroup;
let timg0 = TimerGroup::new(peripherals.TIMG0);

use esp_hal::interrupt::software::SoftwareInterruptControl;
let software_interrupt = SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);

esp_rtos::start(timg0.timer0);
// Optionally, start the scheduler on the second core
esp_rtos::start_second_core(
    software_interrupt.software_interrupt0,
    software_interrupt.software_interrupt1,
    || {}, // Second core's main function.
);

// You can now start esp-radio:
// let esp_radio_controller = esp_radio::init().unwrap();

To write async code, enable the embassy feature, and mark the main function with #[esp_rtos::main]. Note that, to create async tasks, you will need the task macro from the embassy-executor crate. Do NOT enable any of the arch-* features on embassy-executor.

Additional configuration

Option	Stability	Default value	Allowed values
ESP_RTOS_CONFIG_TICK_RATE_HZ Tick rate of the task scheduler in Hertz	⚠️ Unstable	100	Positive integer
ESP_RTOS_CONFIG_SW_TASK_OVERFLOW_DETECTION Enable software-based stack overflow detection. The stack guard value and offset is based on esp-hal configuration.	⚠️ Unstable	false
ESP_RTOS_CONFIG_HW_TASK_OVERFLOW_DETECTION Enable hardware-based stack overflow detection. The stack watermark is based on the esp-hal stack-guard-offset configuration.	⚠️ Unstable	true

Feature Flags

• embassy — Enable embassy integration (time driver and executors).

• esp-radio — Enable esp-radio support.

• esp-alloc — Enable the use of the esp-alloc crate for dynamic memory allocation.

  Memory allocation is required by esp-radio. If you choose to not enable this feature, you need to provide implementations for the following functions:

  • pub extern "C" fn malloc_internal(size: usize) -> *mut u8
  • pub extern "C" fn free_internal(ptr: *mut u8)

  Note that the untyped nature of the allocator functions means that esp-alloc is likely the more memory efficient option.

• rtos-trace — Enable rtos-trace support.

Chip selection

One of the following features must be enabled to select the target chip:

• esp32
• esp32c2
• esp32c3
• esp32c6
• esp32h2
• esp32s2
• esp32s3

Logging Feature Flags

• log-04 — Enable logging output using version 0.4 of the log crate.
• defmt — Enable logging output using defmt and implement defmt::Format on certain types.

Modules

embassyembassy

OS-aware embassy executors.

semaphore

Semaphores and mutexes.

Structs

CurrentThreadHandle

A handle to the current thread.

Traits

TimerSource

Timers that can be used as time drivers.

Functions

start

Starts the scheduler.

start_second_core

Starts the scheduler on the second CPU core.

start_second_core_with_stack_guard_offset

Starts the scheduler on the second CPU core.

start_with_idle_hook

Starts the scheduler, with a custom idle hook.

Attribute Macros

mainembassy

Creates a new instance of esp_rtos::embassy::Executor and declares an application entry point spawning the corresponding function body as an async task.