Ruview/v2/crates/ruv-neural/ruv-neural-esp32

ruv-neural-esp32

ESP32 edge integration for neural sensor data acquisition and preprocessing.

Overview

ruv-neural-esp32 provides lightweight processing modules designed to run on ESP32 microcontrollers for real-time neural sensor data acquisition and preprocessing at the edge. It handles ADC sampling, time-division multiplexing for multi-sensor coordination, IIR filtering and downsampling on-device, power management for battery operation, a binary communication protocol for streaming data to the rUv Neural backend, and multi-node data aggregation.

Features

• ADC interface (adc): AdcReader with configurable AdcConfig including sample rate, resolution, attenuation levels, and multi-channel support via AdcChannel
• TDM scheduling (tdm): TdmScheduler and TdmNode for time-division multiplexed multi-sensor coordination with configurable SyncMethod (GPIO trigger, I2S clock, software timer)
• Edge preprocessing (preprocessing): EdgePreprocessor with fixed-point IIR filters (IirCoeffs), downsampling, and DC offset removal optimized for constrained embedded environments
• Communication protocol (protocol): NeuralDataPacket with PacketHeader and ChannelData for efficient binary data streaming to the backend over UART, SPI, or WiFi
• Power management (power): PowerManager with PowerConfig and PowerMode (active, light sleep, deep sleep, hibernate) for battery-powered deployments
• Multi-node aggregation (aggregator): NodeAggregator for combining data from multiple ESP32 nodes into synchronized multi-channel streams

Usage

use ruv_neural_esp32::{
    AdcReader, AdcConfig, Attenuation,
    TdmScheduler, TdmNode, SyncMethod,
    EdgePreprocessor, IirCoeffs,
    NeuralDataPacket, PacketHeader, ChannelData,
    PowerManager, PowerConfig, PowerMode,
    NodeAggregator,
};

// Configure ADC for 4-channel acquisition
let config = AdcConfig {
    sample_rate_hz: 1000,
    resolution_bits: 12,
    attenuation: Attenuation::Db11,
    channels: vec![
        AdcChannel { pin: 32, gain: 1.0 },
        AdcChannel { pin: 33, gain: 1.0 },
        AdcChannel { pin: 34, gain: 1.0 },
        AdcChannel { pin: 35, gain: 1.0 },
    ],
};
let mut adc = AdcReader::new(config);

// Set up TDM scheduling for multi-sensor sync
let scheduler = TdmScheduler::new(SyncMethod::GpioTrigger);
let node = TdmNode::new(0, scheduler);

// Preprocess on-device with IIR filter
let mut preprocessor = EdgePreprocessor::new(1000.0);
let filtered = preprocessor.process(&raw_samples);

// Build a data packet for transmission
let packet = NeuralDataPacket {
    header: PacketHeader::new(4, 250),
    channels: vec![ChannelData { samples: filtered }],
};

// Power management
let mut power = PowerManager::new(PowerConfig::default());
power.set_mode(PowerMode::LightSleep);

API Reference

Module	Key Types
adc	AdcReader, AdcConfig, AdcChannel, Attenuation
tdm	TdmScheduler, TdmNode, SyncMethod
preprocessing	EdgePreprocessor, IirCoeffs
protocol	NeuralDataPacket, PacketHeader, ChannelData
power	PowerManager, PowerConfig, PowerMode
aggregator	NodeAggregator

Feature Flags

Feature	Default	Description
std	Yes	Standard library (desktop simulation)
no_std	No	Bare-metal ESP32 target
simulator	No	Simulated ADC for testing (requires std)

Integration

Depends on ruv-neural-core for shared types. Preprocessed data packets are sent to the host system where ruv-neural-sensor or ruv-neural-signal can consume them for further processing. Designed to run independently on ESP32 hardware or in simulation mode on desktop for testing.

License

MIT OR Apache-2.0