m5stack-core

Board support crate for M5Stack Fire27 (ESP32) and CoreS3 (ESP32-S3).

Provides chip-agnostic drivers, shared I2C bus, and reusable async IO task loops with fn(...) callbacks.

Features

Exactly one feature must be enabled.

Modules

Drivers (driver::)

M5GO Battery Bottom

The M5GO Battery Bottom plugs into the M-Bus and adds a LiPo cell and ten RGB LEDs (the A014 "Base M5GO Bottom" uses SK6812; the CoreS3-matched A014-D "Bottom3" uses WS2812 — the RMT driver drives both). The LED data line sits on a fixed physical M-Bus pin (pin 23) that maps to a different GPIO per core:

The LEDs are a one-wire NRZ protocol (RMT), not I2C. Battery management differs by board: the Fire (and the PMIC-less classic Core, via the bottom's own IP5306) report through an IP5306 at 0x75; the CoreS3 manages the cell — including the bottom's battery — with its onboard AXP2101 at 0x34, so a bottom's IP5306 does not appear on the CoreS3 I2C bus.

CoreS3 — powering the LEDs. The bottom's LEDs are fed from the CoreS3 M-Bus 5 V rail, which is off by default and gated by the AW9523 expander. Call [Aw9523bDriver::enable_bus_5v] to bring it up — it asserts BOOST_EN (P1_7) and BUS_OUT_EN (P0_1) high (both active-HIGH; P0 must be switched to push-pull first, as it is open-drain by default). Guard it as M5Unified does: only enable when a battery is present or USB is absent (the bus output shares the USB VBUS node, so enabling it with no battery on USB contends the rail). Note the A014 bottom is a classic-Core part — it can't sustain the CoreS3 on battery (the board powers down on unplug), so in practice it runs on USB with the bottom's battery present. The CoreS3-matched bottom is the Bottom3 (A014-D).

Both examples drive a colour-wheel animation on the bars and show the battery reading on the LCD (Fire27: IP5306 %; CoreS3: AXP2101 mV).

Radio: WiFi + BLE (driver::radio)

The on-package radio is shared between BLE and WiFi, modelled as sub-modules of driver::radio and gated by cargo features so a binary only compiles (and pays the RAM for) the radios it uses. All WiFi is async.

The BSP exposes only the BLE controller (BleConnector); the BLE host stack (trouble-host) is an application dependency — see the cores3 coex example. On this esp-hal 1.1 line BleConnector speaks bt-hci 0.8, so pair it with trouble-host 0.6 (the older 0.5 / bt-hci 0.6 line won't bind). coex costs significant heap (~96 KB reclaimed on ESP32); enable it only when both radios run together. esp_rtos::start(..) must run before any radio is created.

STA bring-up. The BSP owns the controller + net runner; the app supplies a seed (from its own TRNG — the BSP leaves RNG/ADC1 free) and a static-lifetime StackResources, then spawns one task:

use m5stack_core::driver::radio::wifi::{self, AuthenticationMethod, IpSetup, StaCredentials};

let wifi = wifi::Wifi::new(peripherals.WIFI)?;
let (stack, control, runner) = wifi.into_sta(
    StaCredentials { ssid, password, auth: AuthenticationMethod::Wpa2Personal },
    IpSetup::Dhcp,                                       // or IpSetup::Static(..)
    seed,
    make_static!(embassy_net::StackResources::<3>::new()),
)?;
spawner.spawn(wifi::wifi_task(runner).unwrap());        // manages assoc + runs the stack
stack.wait_config_up().await;                           // IP acquired
let aps = control.scan().await?;                        // scan while associated

wifi_task is the single owner of the controller: it auto-connects, reconnects on link loss, and serves WifiControl commands (scan/connect/disconnect) so scanning never races association. Scan-only firmware can skip wifi-sta and call Wifi::scan() directly. AP mode is a planned extension point (into_ap + Config::AccessPoint).

Variant note: the esp-radio WiFi API is identical on both chips; only RAM differs. The ControllerConfig RX buffers are trimmed on Fire27 (ESP32). Fire27 cannot DMA from PSRAM — keep StackResources/socket buffers in internal RAM.

IO Tasks (io::)

Async task loops using embassy_time::Ticker with fn(...) callbacks for decoupled integration.

Memory (mem::)

PSRAM heap integration, behind the psram Cargo feature. Both boards have external SPI PSRAM (Fire27 ~4 MB, CoreS3 ~8 MB). mem::init_psram_heap(peripherals.PSRAM) maps it and registers it as an external region of the esp-alloc global heap, returning the free PSRAM bytes. Applications can then allocate from it either implicitly (the global allocator spills into PSRAM after internal DRAM) or explicitly — preferably via the checked helpers:

use m5stack_core::mem;

let psram_free = mem::init_psram_heap(peripherals.PSRAM);
let mut big = mem::psram_vec::<u8>(512 * 1024);  // in PSRAM; atomics rejected at compile time
let scratch = mem::psram_box([0u32; 1024]);      // in PSRAM
let dma = mem::dma_buffer(4 * 1024);             // in internal DRAM; DMA-safe

The raw markers ExternalMemory / InternalMemory are still re-exported for direct allocator_api2 use, but they skip the atomic check — use them only when you know what's going into PSRAM.

The three hardware caveats are now mostly enforced rather than just documented:

PsramSafe requires the esp toolchain's auto_traits + negative_impls (enabled only when psram is on). No esp-hal Cargo feature is required — PSRAM itself is available under the already-enabled unstable feature.

Serial console (io::console)

The complete async logging console for the firmware — both the target-agnostic pipeline AND the per-target hardware. No esp-println/esp-backtrace.

• init() / enable_async() — register the log::Log backend (boots blocking; switches to the async drain once spawned).
• setup(...) -> (ConsoleRx, ConsoleTx) — build + split the peripheral (fire27: UART0 @ 1 Mbaud; cores3: USB-Serial-JTAG) into the RX half (→ serial_cmd) and the TX half (→ the drain task). The binary owns into_async() so the IRQ binds to the calling core.
• drain_task(ConsoleTxAsync) — the single console writer (#[embassy_executor::task]); drains the cross-core queue to the async TX sink.
• send_line(Arguments) — back-pressuring emit for bulk dumps (the :cat read-back); awaits queue space instead of dropping.
• boot_panic_write(&[u8]) (internal) — boot/panic raw-FIFO poke, bounded (drops on a full/host-less FIFO so it never wedges the radio). Bounded-spin on TX-FIFO status — an anti-pattern reserved for the two contexts where the async drain cannot run; do NOT call from steady-state code.
• on_panic(&PanicInfo) -> ! — shared message-only panic print + halt, used by both binaries' #[panic_handler].

alternator-regulator depends on this crate (optional, esp-hal-gated) only so logger::cat_line can call send_line; host builds never pull it.

Key types

// io::rpm
pub struct RpmConfig { pub loop_time_ms: u64, pub pole_pairs: f32, pub pulley_ratio: f32 }
pub fn read_rpm(pcnt: &mut PcntDriver, config: &RpmConfig) -> f32
pub async fn rpm_loop(resources: RpmResources<'static>, config: RpmConfig, on_rpm: fn(f32))

// io::pps
pub struct PpsReadings { pub voltage: f32, pub current: f32, pub temperature: f32, ... }
pub struct PpsSetpoint { pub current_limit: Option<f32>, pub voltage_limit: Option<f32>, pub enabled: Option<bool> }
pub async fn pps_loop(resources: PpsResources, on_read: fn(&PpsReadings), get_setpoint: fn() -> PpsSetpoint)

// io::ow_temp
pub async fn ow_loop(resources: OnewireResources<'static>, on_temperatures: fn(&[(u64, f32)]))

Examples

Each board crate is a set of small, single-topic binaries (one subsystem each) rather than one kitchen-sink demo, so each is copy-pasteable as a starting point. Chip-agnostic helpers (colour wheel, splash/status rendering, I2C scan) live in the shared examples/common crate; per-board chip bring-up lives in each crate's src/lib.rs. Select a binary with --bin <name>.

WIFI_SSID/WIFI_PASSWORD are read at build time; unset → WiFi is skipped and the display still runs. The coex bins need --features coex and must be built --release (the BLE deps trip a dev-profile xtensa codegen bug). The m5go bin needs the M5GO Battery Bottom attached to do anything visible.

Fire27 (ESP32)

cargo +esp run --release -p fire27 --bin <name>

WIFI_SSID=myssid WIFI_PASSWORD=secret cargo +esp run --release -p fire27 --bin wifi_sta
WIFI_SSID=myssid WIFI_PASSWORD=secret cargo +esp run --release -p fire27 --bin coex --features coex

GPIO: I2C SDA=21/SCL=22, SPI CLK=18/MOSI=23/MISO=19, Display CS=14/DC=27/RST=33/BL=32, Buttons=39/38/37, M5GO LEDs=15, IP5306@0x75.

CoreS3 (ESP32-S3)

cargo +esp run --release -p cores3 --bin <name> --target xtensa-esp32s3-none-elf

The m5go bin enables the M-Bus 5V rail (off by default on CoreS3) via the AW9523 expander, guarded against shared-VBUS contention — see the M5GO Battery Bottom section above.

WIFI_SSID=myssid WIFI_PASSWORD=secret \
  cargo +esp run --release -p cores3 --bin wifi_sta --target xtensa-esp32s3-none-elf
WIFI_SSID=myssid WIFI_PASSWORD=secret \
  cargo +esp run --release -p cores3 --bin coex --features coex --target xtensa-esp32s3-none-elf

GPIO: I2C SDA=12/SCL=11, SPI CLK=36/MOSI=37, Display CS=3/DC=35, RST via AW9523B, BL via AXP2101 DLDO1, M5GO LEDs=13, AXP2101@0x34.

LVGL UI (examples/lvgl, Fire27)

A separate example crate that drives the panel with oxivgl (safe LVGL 9 bindings) instead of embedded-graphics — an LVGL render loop with the SPI flush running on a high-priority InterruptExecutor, so the UI animates smoothly while the main task keeps working. The demo shows a title, an animated spinner and a frame counter.

cargo +esp run --release -p lvgl-example --bin lvgl

Notes:

• The flush uses an explicit SpiDmaBus (.with_dma/.with_buffers). On the ESP32 PDMA path a plain Spi::into_async() flush goes "usr-stuck" after the first frame; a descriptor-backed DMA bus avoids it.
• oxivgl-sys downloads and compiles LVGL 9.5 at build time, so this example needs network access, a C compiler (xtensa-esp32-elf-gcc) and libclang for bindgen — all provided by the devcontainer.

Dependencies & the esp-hal fork

The library depends only on stock crates.io crates (esp-hal 1.1.0, esp-radio 0.18.0, esp-sync, esp-alloc) — it uses no fork-specific API (the 1-Wire-over-RMT driver is vendored in-tree; see driver::onewire).

The examples, and all local workspace builds, are redirected to a fork — emobotics-dev/esp-hal — via [patch.crates-io]. The fork is esp-hal 1.1.0 plus a small set of ESP32 fixes not yet upstream, primarily SPI-DMA correctness that the LVGL display example's SpiDmaBus flush depends on:

• feat(spi) — zero-copy DMA in write_async
• fix(spi-dma) — ESP32 PDMA TX unaligned-length wedge (chained-descriptor fix)
• fix(spi/dma) — recover from an RX descriptor fault instead of hanging
• fix(spi) — bound the ESP32 post-DONE busy-re-wake (silent SD-card wedge)

plus assorted ESP32 robustness fixes (linker stack-guard sizing, I2C NACK handling, esp-println UART critical-section bound).

Both the [patch] and the example git dependencies are pinned to a commit rev, not a branch, so builds are reproducible. cargo publish ignores [patch], so a published m5stack-core resolves the plain crates.io versions. The example UI crate's oxivgl/oxivgl-sys deps are likewise rev-pinned.

Roadmap: upstream these patches; once they land in a released esp-hal, the fork and the [patch] are dropped.

Design

• Chip differences handled via #[cfg(feature = "...")] (e.g. RMT channel in ds18b20)
• SharedI2cBus wraps Mutex<RawMutex, I2c> — safe for single-executor async tasks
• Resource pattern: *Resources structs bundle peripherals, consumed by into_driver() or task loops
• IO loops use error counting with threshold (e.g. PPS breaks after 10 consecutive errors)
• GPIO35 (CoreS3): GPIO35 is the display DC line (and is hardware-shared with SPI2 MISO). The cores3 example uses no SD/MISO, so it drives DC as a plain Output — Output::new configures the pad's IO-MUX so the pin actually drives. (A consumer that also needs MISO on the same bus, like alternator-regulator's SD card, must instead claim GPIO35 as MISO and toggle DC via register-level muxing.)

License

Licensed under either of MIT (LICENSE-MIT) or Apache-2.0 (LICENSE-APACHE) at your option.