107 lines
4.2 KiB
Markdown
107 lines
4.2 KiB
Markdown
# 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
|
|
|
|
```rust
|
|
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
|