lilkaoxide/

lib.rs

#![no_std]
//! # lilkaoxide — Rust HAL SDK for the [Lilka](https://docs.lilka.dev/) game console
//!
//! `no_std` HAL built on top of [`esp-hal`](esp_hal) and [`embedded-hal`](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
//!
//! ```toml
//! # Cargo.toml
//! [dependencies]
//! lilkaoxide = { version = "0.1", features = ["blocking", "RefCellBus", "display_buffer_8192"] }
//! ```
//!
//! **Blocking:**
//!
//! ```rust,no_run
//! #![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):**
//!
//! ```rust,no_run
//! #![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`.

use crate::cfg::Configuration;
use esp_hal::Config;
#[cfg(feature = "async")]
use esp_hal::interrupt::software::SoftwareInterruptControl;
use esp_hal::peripherals::Peripherals;
#[cfg(feature = "async")]
use esp_hal::timer::timg::TimerGroup;
use esp_println as _;
mod adcbattery;
mod buzzer;
mod cfg;
mod controller;
mod display;
mod i2s;
/// Optional wall-clock inheritance after a KeiraOS MultiBoot software reset.
#[cfg(feature = "keira-rtc")]
pub mod keira_rtc;
mod sd;
mod sd_wire;
mod spi;

pub use adcbattery::{AdcCfg, Adcbattery};
pub use buzzer::{Buzzer, BuzzerInitError};
pub use cfg::{BuzzerConfig, Configuration as LilkaConfiguration};
pub use controller::ControllerState;
pub use display::DisplayInitError;
pub use display::LilkaDisplay;
pub use i2s::{I2sInitError, I2sTx, I2sTxConfig};
pub use sd::{SdInitError, SdVolMgr};
pub use spi::{
    InnerDelay as LilkaDelay, SpiBusInner as LilkaSpiBus, SpiBusWrapper, SpiDev, SpiInitError,
    init_bus, init_spi_master,
};

use crate::sd::SDC;
pub use defmt;
#[cfg(feature = "async")]
pub use embassy_time;
pub use esp_hal as hal;
#[cfg(feature = "async")]
pub use esp_rtos;
#[cfg(feature = "async")]
pub use lcd_async;
pub use mipidsi;

pub mod prelude {
    #[cfg(feature = "async")]
    pub use crate::RtosRuntime;
    pub use crate::cfg::{BuzzerConfig, Configuration};
    pub use crate::{Lilka, LilkaConfiguration};
    #[cfg(feature = "async")]
    pub use embassy_executor;
    #[cfg(feature = "async")]
    pub use embassy_time;
    pub use esp_hal;
    #[cfg(feature = "async")]
    pub use esp_rtos;
    pub use mipidsi;
}
/// The top-level handle to all Lilka console hardware subsystems.
///
/// Created by calling [`Lilka::init`] with a [`LilkaConfiguration`].  All fields are
/// `pub` so you can borrow them independently in your game loop.
///
/// # Field overview
///
/// | Field | Type | Purpose |
/// |---|---|---|
/// | `peripherals` | [`esp_hal::peripherals::Peripherals`] | Raw peripheral singleton (already consumed during init; kept for future use). |
/// | `delay` | [`LilkaDelay`] | `embedded-hal` delay implementation — `Delay` for blocking, `embassy_time::Delay` for async. |
/// | `controller` | [`ControllerState`] | D-pad + action buttons (A/B/C/D), Select, Start. |
/// | `adc_battery` | [`Adcbattery`] | Battery voltage ADC on GPIO3 via ADC1. |
/// | `display` | [`LilkaDisplay`] | 240×280 ST7789 TFT display via SPI2. |
/// | `sd` | `Option<`[`SdVolMgr`]`>` | SD card volume manager; `None` if no card was detected. |
/// | `i2s_tx` | [`I2sTx`] | I2S transmitter for audio output (default 44 100 Hz stereo). |
/// | `buzzer` | [`Buzzer`] | PWM buzzer driven by the LEDC peripheral (GPIO11). |
///
/// # Example — reading a button
///
/// ```rust,no_run
/// use lilkaoxide::prelude::*;
///
/// # fn example(mut lilka: Lilka) {
/// // Buttons use pull-up resistors: low = pressed
/// if lilka.controller.a.is_low() {
///     defmt::info!("A pressed!");
/// }
/// # }
/// ```
///
/// # Example — reading battery voltage
///
/// ```rust,no_run
/// use lilkaoxide::prelude::*;
///
/// # fn example(mut lilka: Lilka) {
/// let mv = lilka.adc_battery.read_voltage_mv();
/// defmt::info!("Battery: {} mV", mv);
/// # }
/// ```
pub struct Lilka {
    pub peripherals: Peripherals,
    /// Available only with the `async` feature; holds the embassy/esp-rtos runtime handle.
    #[cfg(feature = "async")]
    pub rtos: RtosRuntime,
    pub delay: LilkaDelay,
    pub controller: ControllerState,
    pub adc_battery: Adcbattery<'static>,
    pub display: LilkaDisplay,
    pub sd: Option<SDC<'static>>,
    pub i2s_tx: I2sTx<'static>,
    pub buzzer: Buzzer,
}

#[cfg(feature = "async")]
/// Handle to the embedded async runtime (embassy + esp-rtos).
///
/// Automatically created by [`Lilka::init`] when the `async` feature is enabled.
/// The runtime is started exactly once via [`esp_rtos::start`] and drives the embassy
/// executor.  You normally do not need to interact with this type directly — use
/// `embassy_executor` tasks and `embassy_time` futures instead.
pub struct RtosRuntime {
    started: bool,
}

#[cfg(feature = "async")]
impl RtosRuntime {
    fn start(
        timg0: esp_hal::peripherals::TIMG0<'static>,
        sw_interrupt: esp_hal::peripherals::SW_INTERRUPT<'static>,
    ) -> Self {
        let timg0 = TimerGroup::new(timg0);
        let sw_interrupt = SoftwareInterruptControl::new(sw_interrupt);
        esp_rtos::start(timg0.timer0, sw_interrupt.software_interrupt0);

        Self { started: true }
    }

    /// Returns `true` if the async runtime has been successfully started.
    ///
    /// This will always be `true` after a successful [`Lilka::init`] call.
    /// The flag is provided as a cheap sanity check before spawning embassy tasks.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # #[cfg(feature = "async")]
    /// # fn example(lilka: lilkaoxide::Lilka) {
    /// assert!(lilka.rtos.is_started(), "runtime must be running");
    /// # }
    /// ```
    pub const fn is_started(&self) -> bool {
        self.started
    }
}

#[derive(Debug, Clone, Copy, PartialEq)]
/// Error returned by [`Lilka::init`] if any subsystem fails to initialise.
///
/// Initialisation is sequential; the first fatal failure stops the process
/// and is returned as this error.  The SD card is **non-fatal**: a missing or
/// unreadable card results in `Lilka::sd == None`, not an error.
///
/// # Variants
///
/// * [`InitError::Spi`] — SPI2 bus could not be created (clock/pin config issue).
/// * [`InitError::Display`] — ST7789 display did not respond or tearing config failed.
/// * [`InitError::Sd`] — SD card SPI bus device init failed (card absent is silent).
/// * [`InitError::I2s`] — I2S0 peripheral init failed (DMA or pin conflict).
/// * [`InitError::Buzzer`] — LEDC timer or channel configuration failed.
///
/// # Example
///
/// ```rust,no_run
/// use lilkaoxide::{Lilka, InitError, prelude::*};
///
/// # fn example() {
/// match Lilka::init(LilkaConfiguration::default()) {
///     Ok(lilka) => { /* use lilka */ }
///     Err(InitError::Spi(e))     => defmt::error!("SPI failed: {}", e.as_str()),
///     Err(InitError::Display(e)) => defmt::error!("Display failed: {}", e.as_str()),
///     Err(InitError::I2s(e))     => defmt::error!("I2S failed: {}", e.as_str()),
///     Err(InitError::Buzzer(e))  => defmt::error!("Buzzer failed: {}", e.as_str()),
///     Err(InitError::Sd(e))      => defmt::error!("SD bus failed: {}", e.as_str()),
/// }
/// # }
/// ```
pub enum InitError {
    /// SPI2 master bus initialisation failed.
    Spi(SpiInitError),
    /// ST7789 display initialisation or tearing-effect configuration failed.
    Display(DisplayInitError),
    /// SD card SPI device (bus sharing layer) could not be created.
    Sd(SdInitError),
    /// I2S0 transmitter initialisation failed.
    I2s(I2sInitError),
    /// LEDC buzzer timer or channel configuration failed.
    Buzzer(BuzzerInitError),
}

#[derive(Clone, Copy)]
enum StepStatus {
    Ok,
    Error(&'static str),
    Skipped,
}

impl StepStatus {
    fn log(self, step: &'static str) {
        match self {
            Self::Ok => defmt::info!("[OK] {=str}", step),
            Self::Error(reason) => defmt::error!("[ERR] {=str}: {=str}", step, reason),
            Self::Skipped => defmt::warn!("[SKIP] {=str}", step),
        }
    }
}

#[derive(Clone, Copy)]
struct InitStatusLog {
    spi: StepStatus,
    display: StepStatus,
    sd: StepStatus,
    controller: StepStatus,
    adc_battery: StepStatus,
    i2s_tx: StepStatus,
    buzzer: StepStatus,
}

impl Default for InitStatusLog {
    fn default() -> Self {
        Self {
            spi: StepStatus::Skipped,
            display: StepStatus::Skipped,
            sd: StepStatus::Skipped,
            controller: StepStatus::Skipped,
            adc_battery: StepStatus::Skipped,
            i2s_tx: StepStatus::Skipped,
            buzzer: StepStatus::Skipped,
        }
    }
}

fn log_init_status(status: &InitStatusLog) {
    defmt::info!("Init status summary:");
    status.spi.log("SPI");
    status.display.log("Display");
    status.sd.log("SD");
    status.controller.log("Controller");
    status.adc_battery.log("ADC battery");
    status.i2s_tx.log("I2S TX");
    status.buzzer.log("Buzzer");
}

#[cfg(feature = "blocking")]
fn init_delay() -> LilkaDelay {
    spi::InnerDelay::new()
}

#[cfg(feature = "async")]
fn init_delay() -> LilkaDelay {
    embassy_time::Delay
}

impl Lilka {
    /// Initialises all Lilka console hardware subsystems in a fixed order.
    ///
    /// This is the **only** correct entry-point to the SDK.  Call it once at the
    /// beginning of `main` (or your embassy task) with a [`Configuration`] and
    /// receive a fully-initialised [`Lilka`] handle.
    ///
    /// # Initialisation order
    ///
    /// 1. `esp_hal::init` — set CPU clock from `config.cpu_clock`.
    /// 2. `RtosRuntime::start` — start embassy executor (**`async` only**).
    /// 3. `init_spi_master` — SPI2 at `config.spi_frequency` (GPIO18 SCK, GPIO17 MOSI, GPIO8 MISO).
    /// 4. `init_bus` — wrap the raw SPI bus in the selected sharing wrapper (`RefCell` / `CriticalSection` / …).
    /// 5. `display::init_display` — ST7789 240×280 on GPIO46 (power), GPIO15 (DC), GPIO7 (CS).
    /// 6. `sd::init_sd` — SD card on GPIO16 (CS), shared SPI bus.
    /// 7. `ControllerState::init_controller` — GPIO5/6/10/9/38/41/39/40/0/4 pulled-up inputs.
    /// 8. `adcbattery::init_adcbattery` — ADC1, GPIO3, configured attenuation.
    /// 9. `i2s::init_i2s_tx` — I2S0 DMA TX on GPIO42 (BCLK), GPIO2 (DOUT), GPIO1 (LRCK).
    /// 10. `buzzer::init_buzzer` — LEDC on GPIO11.
    ///
    /// Steps 3–5, 9, and 10 are **fatal**: failure returns immediately via [`InitError`].
    /// Step 6 (SD) is **non-fatal**: an absent or unreadable card sets `Lilka::sd` to `None`.
    ///
    /// # Parameters
    ///
    /// * `config` — a [`Configuration`] (use [`Configuration::default`] for sensible defaults).
    ///
    /// # Returns
    ///
    /// `Ok(Lilka)` with all subsystems initialised, or `Err(`[`InitError`]`)` on the first
    /// fatal failure.  Regardless of the outcome the init status is printed via `defmt`.
    ///
    /// # Note on `async` vs `blocking`
    ///
    /// The function signature is `async fn` but the `deasync` proc-macro generates a
    /// synchronous wrapper when the `blocking` feature is active.  You call `Lilka::init`
    /// the same way in both modes — just omit `.await` in blocking code.
    ///
    /// # Examples
    ///
    /// **Blocking** (`features = ["blocking", "RefCellBus", "display_buffer_8192"]`):
    ///
    /// ```rust,no_run
    /// #![no_std]
    /// #![no_main]
    ///
    /// use lilkaoxide::prelude::*;
    ///
    /// #[esp_hal::entry]
    /// fn main() -> ! {
    ///     let lilka = Lilka::init(LilkaConfiguration::default())
    ///         .expect("hardware init failed");
    ///
    ///     defmt::info!("Display ready, battery: {} mV",
    ///         // Note: need mut borrow for ADC reads
    ///         // lilka.adc_battery.read_voltage_mv()
    ///     );
    ///     loop {}
    /// }
    /// ```
    ///
    /// **Async** (`features = ["async", "AsyncBus", "display_buffer_8192"]`):
    ///
    /// ```rust,no_run
    /// #![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("hardware init failed");
    ///
    ///     assert!(lilka.rtos.is_started());
    /// }
    /// ```
    #[cfg_attr(not(feature = "async"), deasync::deasync)]
    pub async fn init(config: Configuration) -> Result<Self, InitError> {
        let mut status = InitStatusLog::default();
        let Configuration {
            cpu_clock,
            spi_frequency,
            display_refresh_order,
            display_rotation,
            display_tearing,
            adc_cfg,
            i2s_tx_config,
            buzzer_config,
        } = config;
        let peripherals = esp_hal::init(Config::default().with_cpu_clock(cpu_clock));
        #[cfg(feature = "async")]
        let rtos = RtosRuntime::start(peripherals.TIMG0, peripherals.SW_INTERRUPT);

        // Deselect SD before the display sends anything on their shared bus.
        let sd_cs = sd::SdChipSelect::new(peripherals.GPIO16);
        let spi = match init_spi_master(
            peripherals.SPI2,
            peripherals.GPIO18,
            peripherals.GPIO17,
            peripherals.GPIO8,
            spi_frequency,
        ) {
            Ok(spi) => {
                status.spi = StepStatus::Ok;
                spi
            }
            Err(err) => {
                status.spi = StepStatus::Error(err.as_str());
                log_init_status(&status);
                return Err(InitError::Spi(err));
            }
        };
        let delay = init_delay();
        let spi_bus = init_bus(spi);
        let display = match display::init_display(
            peripherals.GPIO46,
            peripherals.GPIO15,
            peripherals.GPIO7,
            spi_bus,
            delay.clone(),
            display_refresh_order,
            display_rotation,
            display_tearing,
        )
        .await
        {
            Ok(display) => {
                status.display = StepStatus::Ok;
                display
            }
            Err(err) => {
                status.display = StepStatus::Error(err.as_str());
                log_init_status(&status);
                return Err(InitError::Display(err));
            }
        };
        let sd = match sd::init_sd(spi_bus, sd_cs, sd::SdDelay(delay.clone()), spi_frequency).await
        {
            Ok(sd) => {
                status.sd = StepStatus::Ok;
                Some(sd)
            }
            Err(err) => {
                status.sd = StepStatus::Error(err.as_str());
                None
            }
        };
        let controller = ControllerState::init_controller(
            peripherals.GPIO5,
            peripherals.GPIO6,
            peripherals.GPIO10,
            peripherals.GPIO9,
            peripherals.GPIO38,
            peripherals.GPIO41,
            peripherals.GPIO39,
            peripherals.GPIO40,
            peripherals.GPIO0,
            peripherals.GPIO4,
        );
        status.controller = StepStatus::Ok;
        let adc_battery = adcbattery::init_adcbattery(peripherals.GPIO3, adc_cfg, peripherals.ADC1);
        status.adc_battery = StepStatus::Ok;
        let i2s_tx = match i2s::init_i2s_tx(
            i2s_tx_config,
            peripherals.GPIO42,
            peripherals.GPIO2,
            peripherals.GPIO1,
            peripherals.I2S0,
            peripherals.DMA_CH0,
        ) {
            Ok(i2s_tx) => {
                status.i2s_tx = StepStatus::Ok;
                i2s_tx
            }
            Err(err) => {
                status.i2s_tx = StepStatus::Error(err.as_str());
                log_init_status(&status);
                return Err(InitError::I2s(err));
            }
        };
        let buzzer = match buzzer::init_buzzer(buzzer_config, peripherals.LEDC, peripherals.GPIO11)
        {
            Ok(buzzer) => {
                status.buzzer = StepStatus::Ok;
                buzzer
            }
            Err(err) => {
                status.buzzer = StepStatus::Error(err.as_str());
                log_init_status(&status);
                return Err(InitError::Buzzer(err));
            }
        };

        log_init_status(&status);

        Ok(Self {
            peripherals: unsafe { Peripherals::steal() },
            #[cfg(feature = "async")]
            rtos,
            delay,
            controller,
            adc_battery,
            display,
            sd,
            i2s_tx,
            buzzer,
        })
    }
}