feagi_hal/bluetooth/
mod.rs

1// Copyright 2025 Neuraville Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Bluetooth Low Energy (BLE) support for FEAGI embedded systems
5//!
6//! This module provides a platform-agnostic BLE abstraction layer for embedded
7//! FEAGI agents. It includes:
8//! - Protocol layer for FEAGI commands and neuron data
9//! - Nordic UART Service (NUS) definitions
10//! - Platform-specific BLE stack implementations
11//!
12//! ## Architecture
13//!
14//! ```text
15//! ┌─────────────────────────────────────────┐
16//! │  Application (embodiment firmware)      │
17//! └─────────────────┬───────────────────────┘
18//!                   │ uses
19//! ┌─────────────────▼───────────────────────┐
20//! │  Protocol Layer (protocol.rs)           │
21//! │  - Command parsing                      │
22//! │  - Neuron data formatting               │
23//! │  - JSON message handling                │
24//! └─────────────────┬───────────────────────┘
25//!                   │ uses
26//! ┌─────────────────▼───────────────────────┐
27//! │  BLE HAL Trait (../hal/bluetooth.rs)    │
28//! └─────────────────┬───────────────────────┘
29//!                   │ implements
30//! ┌─────────────────▼───────────────────────┐
31//! │  Platform Implementation                │
32//! │  - nRF52 (TrouBLE)                     │
33//! │  - ESP32 (esp-idf)                     │
34//! │  - STM32WB (ST BLE stack)              │
35//! └─────────────────────────────────────────┘
36//! ```
37//!
38//! ## Usage
39//!
40//! ```rust,no_run
41//! use feagi_hal::bluetooth::protocol::BluetoothService;
42//! use feagi_hal::bluetooth::nus::FEAGI_DEVICE_NAME;
43//!
44//! // Initialize BLE stack (platform-specific)
45//! # #[cfg(feature = "bluetooth-esp32")]
46//! # {
47//! use feagi_hal::platforms::Esp32Bluetooth;
48//! let mut ble = Esp32Bluetooth::new("FEAGI-robot").expect("BLE init failed");
49//! # }
50//!
51//! // Protocol layer is platform-agnostic
52//! let mut service = BluetoothService::new("FEAGI-robot");
53//!
54//! loop {
55//!     // Receive commands from FEAGI
56//!     # #[cfg(feature = "bluetooth-esp32")]
57//!     # {
58//!     if let Ok(data) = ble.receive_data() {
59//!         service.process_received_data(&data);
60//!     }
61//!
62//!     // Check for parsed commands
63//!     if let Some(cmd) = service.receive_command() {
64//!         // Handle command (GPIO, LED, etc.)
65//!     }
66//!     # }
67//! }
68//! ```
69//!
70//! ## Feature Flags
71//!
72//! - `bluetooth-nrf52` - nRF52-based devices (micro:bit, nRF52840-DK) using TrouBLE
73//! - `bluetooth-esp32` - ESP32/ESP32-S3/ESP32-C3 using esp-idf BLE stack
74//! - `bluetooth-stm32wb` - STM32WB series with built-in BLE
75//!
76//! ## Current Status
77//!
78//! | Platform | Status | Notes |
79//! |----------|--------|-------|
80//! | nRF52 (TrouBLE) | ⚠️ Experimental | Executor compatibility issues |
81//! | ESP32 (esp-idf) | 🟢 Planned | Should work with embassy |
82//! | STM32WB | 🔵 Planned | Hardware BLE controller |
83
84pub mod nus;
85
86// Re-export the shared transport protocol for backward compatibility
87// The protocol is now in the transports module since it works with both BLE and USB
88pub use crate::transports::protocol::{Command, PacketCommand, Protocol as BluetoothProtocol};
89
90// Platform-specific implementations are in src/platforms/
91// and enabled via feature flags
feagi_hal/bluetooth/mod.rs

feagi_hal/bluetooth/
mod.rs
