Crate lilkaoxide 

lilkaoxide — Rust HAL SDK for the Lilka game console

no_std HAL built on top of [esp-hal] and [embedded-hal]. Supports both blocking and async (embassy) execution models via feature flags.

• Lilka console — https://docs.lilka.dev/
• LilkaOxide docs — https://rust.lilka.dev/
• Source code — https://gitlab.com/imbiruss/lilkaoxide
• crates.io — https://crates.io/crates/lilkaoxide

Hardware (Lilka v2 — ESP32-S3-WROOM-N16R8)

Peripheral	Controller / Interface	GPIOs
IPS TFT display 240×280	ST7789 via SPI2	SCK=18, MOSI=17, MISO=8, DC=15, CS=7, PWR=46
SD card	SPI2 (shared)	CS=16
Buttons (10)	GPIO pull-up, active-low	0, 4, 5, 6, 9, 10, 38, 39, 40, 41
Battery ADC	ADC1 CH2	GPIO3 (100 kΩ / 33 kΩ divider)
Audio DAC (I2S)	I2S0 + DMA	BCLK=42, DOUT=2, LRCK=1
Piezo buzzer	LEDC PWM	GPIO11
Wi-Fi / BT	ESP32-S3 built-in	(feature radio)

Quick start

# Cargo.toml
[dependencies]
lilkaoxide = { version = "0.1", features = ["blocking", "RefCellBus", "display_buffer_8192"] }

Blocking:

#![no_std]
#![no_main]

use lilkaoxide::prelude::*;

#[esp_hal::entry]
fn main() -> ! {
    let mut lilka = Lilka::init(LilkaConfiguration::default())
        .expect("init failed");

    loop {
        if lilka.controller.a.is_low() {
            defmt::info!("Button A pressed");
        }
        let mv = lilka.adc_battery.read_voltage_mv();
        if mv < 3_300 {
            defmt::warn!("Low battery: {} mV", mv);
        }
    }
}

Async (embassy):

#![no_std]
#![no_main]

use lilkaoxide::prelude::*;

#[embassy_executor::main]
async fn main(_spawner: embassy_executor::Spawner) {
    let lilka = Lilka::init(LilkaConfiguration::default())
        .await
        .expect("init failed");

    assert!(lilka.rtos.is_started());
}

Feature flags

Feature	Description
blocking	Blocking drivers. Mutually exclusive with async.
async	Async drivers (embassy). Mutually exclusive with blocking.
RefCellBus	Share SPI via RefCell. Single-core, no ISRs. blocking only.
CriticalSectionBus	Share SPI via critical section. ISR-safe. blocking only.
AtomicBus	Share SPI via atomic cell. blocking only.
AsyncBus	Share SPI via async Mutex. Required with async.
alloc	Global allocator (esp-alloc).
radio	Wi-Fi / BLE (requires alloc).
display_buffer_512	SPI display DMA buffer: 512 B.
display_buffer_1024	SPI display DMA buffer: 1 024 B.
display_buffer_8192	SPI display DMA buffer: 8 192 B (default).

Incompatible feature combinations are caught at compile time via [compile_error!].

Memory and lifetime rules

1. Peripherals are single-owner resources — move each pin/peripheral exactly once into its driver.
2. The shared SPI bus lives in a [static_cell::StaticCell] — all bus references are 'static.
3. DMA descriptors and buffers come from static storage (dma_buffers!) — sizes must be const.
4. Keep long-lived drivers (display, SD, I2S TX) inside Lilka to preserve ownership and lifetimes.
5. In async builds, never hold a borrowed stack reference across .await — keep data owned or 'static.
6. Feature pairs are mutually exclusive: blocking ↔ async, RefCellBus ↔ CriticalSectionBus ↔ AtomicBus ↔ AsyncBus.

Re-exports

pub use defmt;

pub use esp_hal as hal;

pub use mipidsi;

Modules

prelude

Structs

AdcCfg

ADC channel configuration for the battery-monitoring pin (GPIO3 / ADC1).

Adcbattery

Battery voltage monitor using the ESP32-S3 ADC1 peripheral.

Buzzer

PWM buzzer driver backed by the ESP32-S3 LEDC peripheral.

BuzzerConfig

Configuration for the on-board PWM buzzer (LEDC peripheral, GPIO11).

ControllerState

State of all physical input buttons on the Lilka game console.

I2sTxConfig

Configuration for the I2S0 transmitter.

Lilka

The top-level handle to all Lilka console hardware subsystems.

LilkaConfiguration

Top-level configuration passed to crate::Lilka::init.

Enums

BuzzerInitError

Error returned when the LEDC buzzer fails to initialise.

DisplayInitError

Error returned when the ST7789 display fails to initialise.

I2sInitError

Error returned when the I2S0 peripheral fails to initialise.

InitError

Error returned by Lilka::init if any subsystem fails to initialise.

SdInitError

Error returned when the SD card fails to initialise.

SpiInitError

Error returned by SPI bus or device initialisation functions.

Functions

init_bus

Places the raw SPI bus into a 'static shared wrapper and returns a 'static reference to it.

init_spi_master

Initialises the ESP32-S3 SPI2 master bus at the requested frequency.

Type Aliases

I2sTx

Alias for the I2S transmitter handle, parameterised by the blocking/async drive mode.

LilkaDelay

The delay type used by the SPI bus sharing wrappers.

LilkaDisplay

Type alias for the Lilka display handle.

LilkaSpiBus

The raw SPI2 master bus type. Lifetime is 'static because it lives in a [StaticCell] after init_bus is called.

SdVolMgr

Type alias for the SD volume manager (same as [SDC]).

SpiBusWrapper

Shared SPI bus wrapper type, selected by the active bus-sharing feature.

SpiDev

A virtual SPI device (chip-select + delay) created from a shared SpiBusWrapper.