cli_chat_embedded

A pure #![no_std], zero-heap, single-threaded CLI chat state machine designed for resource-constrained embedded environments (bare-metal).

Features

Zero-Heap Allocation
Strictly #![no_std] with no alloc crate required. Uses const-generics for bounded memory.
Raw Fixed-Record Storage
Direct binary serialization with table-less CRC32 validation.
ANSI Split-Screen Viewport
Built-in terminal UI rendering using DECSTBM and SGR colors.
Host Simulator
Includes runner_std, a host simulator using crossterm and std::fs to test the core logic on your PC.
Mirrored Repositories
Maintained on both GitHub and Codeberg.

Installation

Add to Cargo.toml:

[dependencies]

cli_chat_core = "0.1.0"

Quick Start

use cli_chat_core::{AppState, SerialPort, Storage};
use core::mem::MaybeUninit;

// 1. Allocate state in .bss
static mut STATE: MaybeUninit<AppState> = MaybeUninit::uninit();

// 2. Initialize and run the polling loop
unsafe {
    let state = STATE.write(AppState::uninit());
    
    // Assuming `storage` and `port` are your hardware-specific implementations
    state.init(&mut storage, &mut port).unwrap();
    
    // In your hardware interrupt or polling loop:
    // if let Some(byte) = port.read_byte() {
    //     state.process_byte(byte, &mut port, &mut storage).unwrap();
    // }
}

Available Commands

Once running, use the following commands in the prompt:

/help : Show available commands.
/user <id> or /switch <id> : Switch to a specific user ID.
/name <str> : Set the display name for the current user.
/users : List all active registered users.
/status : Show system uptime and history buffer usage.
/time : Show boot epoch and relative tick information.
/ping : Check system responsiveness.
/about : Show application and license information.
/clear : Clear the screen and redraw the viewport.
/exit : Gracefully exit the application (in host simulator).

Architecture

[ runner_std (bin) ]          [ core (lib) ]              [ target hardware ]
   │                             │                             │
   ├─ impl SerialPort ◄──────────┼── trait SerialPort ─────────┼─ UART / Console
   ├─ impl Storage ◄─────────────┼── trait Storage ────────────┼─ Flash / EEPROM
   ├─ ANSI Split-Screen Init     │                             │
   └─ Non-blocking stdin poll ──►├─ state.process_byte()       │
                                 ├─ minimal line editor        │
                                 ├─ cmd dispatch (guard)       │
                                 ├─ render history & prompt    │
                                 └─ fixed-record load/save     │

Pipeline: Input Byte → Minimal Line Editor → Guard-Checked Parser → State Mutation (Static) → ANSI Stream Output → Trait Write
Memory: Static .bss allocation via MaybeUninit<AppState>.
Storage: Raw fixed-record binary layout with CRC32 validation.

Performance (v0.1.0 Baseline)

Operation	Time
`parse_latency`	~76.5 µs
`storage_serialize`	~76.0 µs
`ansi_render`	~270.2 ns

Tested on Microsoft Windows 11 IoT Enterprise (Build 26200), LENOVO 2347B16 (Intel Core i5-3320M @ 2.60GHz), Rust 1.95.0 (59807616e 2026-04-14) (Rev5, Built by MSYS2 project). Meets strict NFR-01 performance bounds.

Safety & MSRV

MSRV
1.94.0 | Edition: 2024
Public API
100% safe. Fallible operations return Result with static string slices. No panics under normal operation.
Concurrency
Single-threaded deterministic execution. &mut self enforces exclusive access.
Memory
Zero-heap allocation. unsafe confined to MaybeUninit array initialization and pointer math for storage serialization.

License

Distributed under the MIT License. See LICENSE for details.

Coding Standards

Safety
unsafe blocks must include // SAFETY: comments explaining invariants.
Documentation
All pub items follow Summary → Description → Examples → Panics → Errors → Safety → See Also.
Testing
Unit tests for logic, proptest for fuzzing byte parser, criterion for performance regression.

Out of Scope

Dynamic heap allocation (Box, Vec, String, Arc, Mutex).
TOML/JSON/XML parsing in core/.
Multi-session networking or WebSocket.
Async runtimes (tokio, async-std).

cli_chat_core 0.1.0