Crate esp_rtos 

An RTOS (Real-Time Operating System) implementation for esp-hal.

This crate provides the runtime necessary to run async code on top of esp-hal, and implements the necessary capabilities (threads, queues, etc.) required by esp-radio.

Setup

This crate requires an esp-hal timer, as well as the FROM_CPU0 software interrupt to operate, and needs to be started like so:

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

esp_rtos::start(timg0.timer0, peripherals.FROM_CPU_INTR0);
// Optionally, start the scheduler on the second core
use static_cell::ConstStaticCell;
use esp_hal::system::Stack;

static STACK: ConstStaticCell<Stack<8192>> = ConstStaticCell::new(Stack::new());
esp_rtos::start_second_core(
    peripherals.CPU_CTRL,
    peripherals.FROM_CPU_INTR1,
    STACK.take(),
    || {}, // 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 make the main function async. This will create a thread-mode executor on the main thread. 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. The scheduler can also run on the second core alone, which keeps the first core free for bare-metal code. See start_on_second_core_only for that configuration and its restrictions.

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_LIGHT_SLEEP_MIN_US Minimum predicted sleep duration, in microseconds, required for the auto light-sleep idle hook to enter light sleep instead of WFI.	⚠️ Unstable	1000	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_STACK_POINTER_RANGE_CHECK Enable range-check based stack overflow detection.	⚠️ Unstable	true
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
ESP_RTOS_CONFIG_RADIO_TIMER_THREAD_PRIORITY Priority of the timer thread serving esp-radio.	⚠️ Unstable	2	Integer in range 2..28

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
• esp32c5
• esp32c6
• esp32c61
• esp32h2
• esp32p4
• esp32s2
• esp32s3
• esp32s31

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.

Structs

CurrentThreadHandle

A handle to the current thread.

Traits

TimerSource

Timers that can be used as time drivers.

Functions

rearm_alarm

Rearms the alarm timer.

start

Starts the scheduler.

start_on_second_core_onlymulti_core

Starts the scheduler on the second CPU core only.

start_second_coremulti_core

Starts the scheduler on the second CPU core.

start_second_core_with_stack_guard_offsetmulti_core

Starts the scheduler on the second CPU core.

start_with_idle_hook

Starts the scheduler, with a custom idle hook.

Attribute Macros

mainembassy

Attribute to declare the entry point of the program.