csi-webserver-core

Embeddable Rust library for bridging ESP32 CSI firmware (esp-csi-cli-rs) to HTTP and WebSocket clients. Use this crate when you want to run the CSI server inside your own process, register devices programmatically, or build a custom host application.

For the ready-to-run executable, see csi-webserver.

Documentation

Rust API reference: https://docs.rs/csi-webserver-core
HTTP route handlers and request types: src/routes/, src/models.rs
This guide: embedding, supervisor, and registration

Features

Axum HTTP API under /api/devices/{id}/...
Per-device WebSocket CSI frame stream (/ws)
Parquet session dumps (decoded from serialized COBS+postcard frames)
USB hotplug supervisor (supervisor)
Explicit device registration (DeviceRegistry::attach)

Quick embed

[dependencies]
csi-webserver-core = "0.1.0"
tokio = { version = "1", features = ["full"] }
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

use std::time::Duration;
use csi_webserver_core::{AppState, ServerConfig, SupervisorConfig, run_supervisor, serve};

#[tokio::main]
async fn main() -> std::io::Result<()> {
    tracing_subscriber::fmt::init();

    let state = AppState::new();
    tokio::spawn(run_supervisor(SupervisorConfig {
        registry: state.devices.clone(),
        baud_rate: 115_200,
        scan_interval: Duration::from_secs(2),
        aliases: vec![],
    }));

    serve(ServerConfig { bind: "0.0.0.0:3000".into() }, state).await
}

Register a device without hotplug

use csi_webserver_core::{AppState, DeviceAttachSpec};

let state = AppState::new();
state.devices.attach(DeviceAttachSpec {
    id: "lab1".into(),
    port_path: "/dev/ttyUSB0".into(),
    baud_rate: 115_200,
    native_usb: false,
    mac: None,
    ..Default::default()
});

Use supervisor::probe_port to read native_usb and MAC from USB enumeration before attaching.

Public API surface

Export	Purpose
`AppState`, `DeviceRegistry`, `DeviceHandle`, `DeviceAttachSpec`	Shared runtime state
`ServerConfig`, `build_router`, `serve`	HTTP server
`SupervisorConfig`, `run_supervisor`, `detect_esp_ports`, `probe_port`	Hotplug discovery
`models`	JSON request/response types and CLI command mappers
`csi`	COBS/postcard frame decoder
`routes`	Axum handler functions (for custom router extension)
`serial`, `parquet_sink`	Lower-level pipelines

Custom router

Mount the default routes or compose your own:

use axum::Router;
use csi_webserver_core::{build_router, AppState};

let state = AppState::new();
let app: Router = build_router(state);
// or nest `build_router(state)` under your own paths

Migration from pre-0.1.5 single crate

Before	After
`csi_webserver::run_supervisor`	`csi_webserver_core::run_supervisor`
`spawn_device` + `registry.insert`	`registry.attach(DeviceAttachSpec { ... })`
Binary in same crate	Use `csi-webserver` or embed this library

Related crates

Crate	Role
`csi-webserver-core`	This library
`csi-webserver`	Default executable + HTTP API

License

Apache-2.0. See LICENSE.

csi-webserver-core 0.1.1