brainwires-hardware

Hardware I/O for the Brainwires Agent Framework.

Provides a unified hardware abstraction layer covering audio, GPIO, Bluetooth, network hardware, and home automation protocols — all behind opt-in feature flags so you only compile what you need.

Modules

Getting started

[dependencies]
# Pick only what you need:
brainwires-hardware = { version = "0.8", features = ["audio"] }
brainwires-hardware = { version = "0.8", features = ["gpio"] }
brainwires-hardware = { version = "0.8", features = ["bluetooth"] }
brainwires-hardware = { version = "0.8", features = ["network"] }

# Or enable everything:
brainwires-hardware = { version = "0.8", features = ["full"] }

Feature flags

Audio

Supports hardware capture and playback via CPAL, plus cloud STT/TTS integrations:

STT: OpenAI, Azure, Deepgram, ElevenLabs, Fish Audio TTS: OpenAI, Azure, Deepgram, ElevenLabs, Fish Audio, Google, Murf, Cartesia

use brainwires_hardware::{TextToSpeech, TtsOptions, OutputFormat};

let tts = OpenAiTts::new(api_key);
let audio = tts.synthesize("Hello, world!", &TtsOptions::default()).await?;

GPIO (Linux)

Safe GPIO access with explicit allow-lists — no pin can be used unless it appears in the configured policy.

use brainwires_hardware::{GpioPinManager, GpioSafetyPolicy};
use brainwires_hardware::gpio::device::GpioDirection;

let mut manager = GpioPinManager::from_config(&config);
let pin = manager.acquire(0, 17, GpioDirection::Output, "my-agent")?;

Bluetooth

Cross-platform BLE scanning using btleplug:

use brainwires_hardware::bluetooth;
use std::time::Duration;

let devices = bluetooth::scan_ble(Duration::from_secs(5)).await;
for d in &devices {
    println!("{} — {:?}", d.address, d.name);
}

Network

use brainwires_hardware::network;
use std::time::Duration;

// List interfaces
for iface in network::list_interfaces() {
    println!("{} ({:?})", iface.name, iface.kind);
}

// IP config with gateways
for cfg in network::get_ip_configs() {
    println!("{}: gateway={:?}", cfg.interface, cfg.gateway);
}

// Port scan
let results = network::scan_common_ports(
    "192.168.1.1".parse().unwrap(),
    Duration::from_millis(500),
).await;

// ARP host discovery (requires CAP_NET_RAW)
let hosts = network::arp_scan("192.168.1.0/24".parse().unwrap()).await;

Voice Activity Detection

EnergyVad is always available (no extra feature needed beyond audio). WebRtcVad requires the vad feature.

use brainwires_hardware::{EnergyVad, VoiceActivityDetector};

let vad = EnergyVad::default(); // -40 dBFS threshold
if vad.is_speech(&audio_buffer) {
    println!("Speech detected!");
}

Wake Word Detection

use brainwires_hardware::{EnergyTriggerDetector, WakeWordDetector};

let mut detector = EnergyTriggerDetector::new(-20.0, 3, 16_000);
// Feed 30 ms i16 frames from the mic:
if let Some(detection) = detector.process_frame(&frame) {
    println!("Wake trigger! score={:.2}", detection.score);
}

Voice Assistant Pipeline

use brainwires_hardware::{VoiceAssistant, VoiceAssistantHandler, VoiceAssistantConfig};
use brainwires_hardware::audio::types::Transcript;
use async_trait::async_trait;

struct MyHandler;

#[async_trait]
impl VoiceAssistantHandler for MyHandler {
    async fn on_speech(&self, transcript: &Transcript) -> Option<String> {
        println!("You said: {}", transcript.text);
        Some("I heard you!".to_string())
    }
}

// Build and run
let mut assistant = VoiceAssistant::builder(capture, stt)
    .with_playback(playback)
    .with_tts(tts)
    .with_wake_word(Box::new(EnergyTriggerDetector::default()))
    .build();

assistant.run(&MyHandler).await?;

Home Automation

All four protocols are behind the homeauto feature (or enable each individually).

brainwires-hardware = { version = "0.8", features = ["homeauto"] }

Zigbee (zigbee)

Two serial backends sharing the ZigbeeCoordinator trait:

use brainwires_hardware::homeauto::{EzspCoordinator, ZigbeeCoordinator};

// Silicon Labs EFR32 stick (EZSP v8 over ASH)
let coord = EzspCoordinator::open("/dev/ttyUSB0", 115_200).await?;
coord.start().await?;
coord.permit_join(60).await?;

for dev in coord.devices().await? {
    println!("{} — {:?}", dev.addr.ieee, dev.kind);
}

Z-Wave (zwave)

use brainwires_hardware::homeauto::{ZWaveSerialController, ZWaveController};
use brainwires_hardware::homeauto::CommandClass;

let ctrl = ZWaveSerialController::open("/dev/ttyUSB0", 115_200).await?;
ctrl.start().await?;

for node in ctrl.nodes().await? {
    println!("Node {}: {:?}", node.node_id, node.kind);
}

// Toggle a binary switch on node 3
ctrl.send_cc(3, CommandClass::SwitchBinary, &CommandClass::switch_binary_set(true)).await?;

Thread (thread)

use brainwires_hardware::homeauto::ThreadBorderRouter;

let otbr = ThreadBorderRouter::new("http://192.168.1.100:8081").await?;
let info = otbr.node_info().await?;
println!("Network: {} ({:?})", info.network_name, info.role);

for neighbor in otbr.neighbors().await? {
    println!("  neighbor {} rssi={}", neighbor.ext_address, neighbor.rssi);
}

Matter (matter)

Controller — commission and control a device:

use brainwires_hardware::homeauto::{MatterController};
use std::path::Path;

let ctrl = MatterController::new("MyFabric", Path::new("/tmp/matter-fabric")).await?;
let device = ctrl.commission_qr("MT:Y.K9042C00KA0648G00", 1).await?;
ctrl.on_off(&device, 1, true).await?;

Device server — expose an agent as a Matter device:

use brainwires_hardware::homeauto::{MatterDeviceConfig, MatterDeviceServer};

let config = MatterDeviceConfig::builder()
    .device_name("Brainwires Light")
    .vendor_id(0xFFF1)
    .product_id(0x8001)
    .discriminator(3840)
    .passcode(20202021)
    .build();

let server = MatterDeviceServer::new(config).await?;
server.set_on_off_handler(|on| println!("On/Off: {on}"));
println!("QR: {}", server.qr_code());
server.start().await?;  // blocks; scan QR code with your Matter controller

Matter Stack — What's Implemented

The matter feature ships a complete Matter 1.3 protocol stack written entirely in pure Rust (no rs-matter or embassy-time dependency):

Run the ready-made examples to get started:

# Expose this machine as a Matter on/off light — scan the printed QR code
cargo run --example matter_server --features matter

# Commission a real Matter device and toggle it
cargo run --example matter_on_off --features matter -- commission "MT:YOUR_QR_CODE"

Migration from brainwires-audio

# Before
brainwires-audio = "0.8"

# After
brainwires-hardware = { version = "0.8", features = ["audio"] }

All public types and traits are re-exported from the crate root — existing code using brainwires_audio::* can switch to brainwires_hardware::* with no further changes.

Examples

cargo run -p brainwires-hardware --example text_to_speech --features audio
cargo run -p brainwires-hardware --example bluetooth_scan --features bluetooth
cargo run -p brainwires-hardware --example network_interfaces --features network
cargo run -p brainwires-hardware --example port_scan --features network -- 192.168.1.1
sudo cargo run -p brainwires-hardware --example host_discovery --features network -- 192.168.1.0/24

# Wake word demo (prints detections from mic)
cargo run -p brainwires-hardware --example wake_word_demo --features wake-word

# Full voice assistant demo (requires OPENAI_API_KEY)
cargo run -p brainwires-hardware --example voice_assistant --features voice-assistant

# Standalone voice assistant binary
cargo run -p voice-assistant -- --list-devices
cargo run -p voice-assistant -- --verbose

# Home automation examples (requires physical hardware for full operation)
cargo run -p brainwires-hardware --example zigbee_scan --features zigbee
cargo run -p brainwires-hardware --example zwave_nodes --features zwave
cargo run -p brainwires-hardware --example thread_info --features thread -- http://192.168.1.100:8081
cargo run -p brainwires-hardware --example matter_on_off --features matter -- serve
cargo run -p brainwires-hardware --example matter_on_off --features matter -- commission "MT:Y.K9042C00KA0648G00"