# MIT License # # Copyright (c) 2025 Reticulum BLE Interface Contributors # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to deal # in the Software without restriction, including without limitation the rights # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell # copies of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included in # all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. """ BLEInterface - Bluetooth Low Energy interface for Reticulum This interface enables Reticulum mesh networking over BLE on Linux devices without additional hardware. Key features: - Auto-discovery of BLE peers - Multi-peer mesh support (up to 7 simultaneous connections) - Packet fragmentation for BLE MTU limits - Power management modes for battery efficiency - Linux-only (requires BlueZ 5.x for GATT server) """ import RNS import sys import os import threading import time import asyncio import logging from collections import deque from typing import Optional # Add interface directory to path for importing other BLE modules # This is needed when loaded as external interface try: # __file__ exists when imported normally _interface_dir = os.path.dirname(os.path.abspath(__file__)) except NameError: # __file__ doesn't exist when loaded via exec() by Reticulum # Try to get the config directory from RNS _interface_dir = None try: import RNS if hasattr(RNS.Reticulum, 'configdir') and RNS.Reticulum.configdir: _interface_dir = os.path.join(RNS.Reticulum.configdir, "interfaces") except (ImportError, AttributeError): pass # Fall back to default if we couldn't get it from RNS if _interface_dir is None: _interface_dir = os.path.expanduser("~/.reticulum/interfaces") if _interface_dir not in sys.path: sys.path.insert(0, _interface_dir) # Import base Interface class # When integrated into Reticulum, this will be: # from RNS.Interfaces.Interface import Interface # For now, we'll need to handle the import path try: from RNS.Interfaces.Interface import Interface except ImportError: # Fallback for development import os sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../../')) from RNS.Interfaces.Interface import Interface # Import fragmentation module # Note: When loaded as external interface, use absolute imports try: from BLEFragmentation import BLEFragmenter, BLEReassembler except ImportError: # Fallback for when loaded as part of RNS package from RNS.Interfaces.BLEFragmentation import BLEFragmenter, BLEReassembler # Import GATT server for peripheral mode try: from BLEGATTServer import BLEGATTServer HAS_GATT_SERVER = True except ImportError: try: from RNS.Interfaces.BLEGATTServer import BLEGATTServer HAS_GATT_SERVER = True except ImportError: HAS_GATT_SERVER = False # Import driver abstraction try: from bluetooth_driver import BLEDriverInterface, BLEDevice except ImportError: from RNS.Interfaces.bluetooth_driver import BLEDriverInterface, BLEDevice # Import platform-specific driver (optional - can be overridden by subclasses) try: from linux_bluetooth_driver import LinuxBluetoothDriver HAS_LINUX_DRIVER = True except ImportError: try: from RNS.Interfaces.linux_bluetooth_driver import LinuxBluetoothDriver HAS_LINUX_DRIVER = True except ImportError: HAS_LINUX_DRIVER = False LinuxBluetoothDriver = None HAS_DRIVER = True class DiscoveredPeer: """ Tracks information about a discovered BLE peer for connection prioritization. This class stores signal strength (RSSI), connection history, and timing information to enable smart peer selection in mesh networks. Algorithm Design Decisions: --------------------------- 1. RSSI Tracking: Signal strength is the primary indicator of connection quality in BLE networks. We track and update RSSI on every discovery to adapt to changing environmental conditions (movement, obstacles). 2. Connection History: Past behavior is a strong predictor of future reliability. We track attempts vs successes to identify consistently reachable peers vs flaky ones. 3. Temporal Data: Both first_seen and last_seen timestamps enable: - Recency-based prioritization (prefer active peers) - Stale peer cleanup (remove disappeared peers) - Connection attempt rate limiting 4. Separation of Concerns: We track successful_connections separately from failed_connections to enable nuanced scoring (e.g., a peer with 80% success from 100 attempts is more reliable than one with 100% from 2 attempts). """ def __init__(self, address, name, rssi): """ Initialize a discovered peer. Args: address: BLE MAC address of the peer name: Advertised device name rssi: Signal strength in dBm (typically -30 to -100) """ self.address = address self.name = name self.rssi = rssi self.first_seen = time.time() self.last_seen = time.time() # Connection tracking self.connection_attempts = 0 self.successful_connections = 0 self.failed_connections = 0 self.last_connection_attempt = 0 def update_rssi(self, rssi): """Update RSSI and last seen timestamp.""" self.rssi = rssi self.last_seen = time.time() def record_connection_attempt(self): """Record that a connection attempt is being made.""" self.connection_attempts += 1 self.last_connection_attempt = time.time() def record_connection_success(self): """Record a successful connection.""" self.successful_connections += 1 def record_connection_failure(self): """Record a failed connection.""" self.failed_connections += 1 def get_success_rate(self): """ Get the connection success rate. Returns: float: Success rate from 0.0 to 1.0, or 0.0 if no attempts """ if self.connection_attempts == 0: return 0.0 return self.successful_connections / self.connection_attempts def __repr__(self): return (f"DiscoveredPeer({self.address}, {self.name}, " f"RSSI={self.rssi}, attempts={self.connection_attempts}, " f"success_rate={self.get_success_rate():.2f})") class BLEInterface(Interface): """ BLE interface for Reticulum networking. Implements the Reticulum Interface API for Bluetooth Low Energy transport, enabling mesh networking over BLE connections. ARCHITECTURE: - Dual-mode: Acts as both central (client) and peripheral (server) - Spawns BLEPeerInterface for each connected peer - Fragments packets larger than BLE MTU (~185 bytes) - Auto-reconnects on connection loss THREADING MODEL: - Driver owns async event loop in separate thread - LOCK ORDERING CONVENTION (to prevent deadlocks): 1. peer_lock - ALWAYS acquire first for peer state access 2. frag_lock - THEN acquire for fragmentation state NEVER acquire locks in reverse order! (HIGH #2: deadlock prevention) - Driver callbacks invoked from driver thread MEMORY USAGE (per-peer overhead): - Fragmenter + Reassembler: ~400 bytes per peer - Max peers: configurable (default 7) - Reassembly buffers: Auto-cleanup after 30s timeout (CRITICAL #2) - Discovery cache: ~100 bytes per discovered device (limited to 100) ERROR RECOVERY: - Connection failure: Exponential backoff + blacklist - Transmission timeout: Packet dropped (Reticulum retransmits) - Fragmentation failure: Buffer cleanup after timeout - Adapter error: Interface marked offline, Transport handles """ # Interface constants HW_MTU = 500 # Reticulum standard MTU BITRATE_GUESS = 700_000 # ~700 Kbps average BLE throughput DEFAULT_IFAC_SIZE = 16 # BLE-specific constants SERVICE_UUID = "37145b00-442d-4a94-917f-8f42c5da28e3" # Custom Reticulum BLE service CHARACTERISTIC_RX_UUID = "37145b00-442d-4a94-917f-8f42c5da28e5" # RX characteristic CHARACTERISTIC_TX_UUID = "37145b00-442d-4a94-917f-8f42c5da28e4" # TX characteristic CHARACTERISTIC_IDENTITY_UUID = "37145b00-442d-4a94-917f-8f42c5da28e6" # Identity characteristic (Protocol v2) # Discovery and connection settings DISCOVERY_INTERVAL = 5.0 # seconds between discovery scans CONNECTION_TIMEOUT = 30.0 # seconds before connection times out MAX_PEERS = 7 # Maximum simultaneous BLE connections (conservative default) MIN_RSSI = -85 # Minimum signal strength (dBm) - more permissive for better peer discovery # Power management modes POWER_MODE_AGGRESSIVE = "aggressive" # Continuous scanning POWER_MODE_BALANCED = "balanced" # Intermittent scanning (default) POWER_MODE_SAVER = "saver" # Minimal scanning # Fragmentation constants FRAG_TYPE_START = 0x01 FRAG_TYPE_CONTINUE = 0x02 FRAG_TYPE_END = 0x03 FRAG_HEADER_SIZE = 5 # bytes: type(1) + sequence(2) + total(2) # Platform-specific driver class (override in subclasses for different platforms) driver_class = LinuxBluetoothDriver def __init__(self, owner, configuration): """ Initialize BLE interface. Args: owner: The Reticulum.Transport instance that owns this interface configuration: Dictionary or ConfigObj with interface settings """ # Check dependencies if not HAS_DRIVER: raise ImportError( "BLEInterface requires the driver abstraction. " "Ensure bluetooth_driver.py and linux_bluetooth_driver.py are available." ) super().__init__() # Parse configuration c = Interface.get_config_obj(configuration) # Basic interface setup self.IN = True self.OUT = True # Enable bidirectional communication self.name = c.get("name", "BLEInterface") self.owner = owner self.online = False self.bitrate = BLEInterface.BITRATE_GUESS self.mode = Interface.MODE_FULL # Full mode: enable announce propagation, meshing, transport # BLE configuration self.service_uuid = c.get("service_uuid", BLEInterface.SERVICE_UUID) # Device name for BLE advertising (optional, configurable via config file) # Default is None (no device name) to save advertisement packet space (31-byte limit). # Discovery is based on service UUID only. Identity is obtained from the Identity # characteristic after connection. If set, keep it short (max 8 chars recommended). self.device_name = c.get("device_name", None) self.discovery_interval = float(c.get("discovery_interval", BLEInterface.DISCOVERY_INTERVAL)) self.max_peers = int(c.get("max_connections", BLEInterface.MAX_PEERS)) self.min_rssi = int(c.get("min_rssi", BLEInterface.MIN_RSSI)) self.connection_timeout = float(c.get("connection_timeout", BLEInterface.CONNECTION_TIMEOUT)) # Service discovery delay (for bluezero D-Bus registration timing) # bluezero registers characteristics asynchronously with BlueZ D-Bus # A small delay after connection allows registration to complete before discovery self.service_discovery_delay = float(c.get("service_discovery_delay", 1.5)) # Default 1.5s # Power management self.power_mode = c.get("power_mode", BLEInterface.POWER_MODE_BALANCED) if self.power_mode not in [BLEInterface.POWER_MODE_AGGRESSIVE, BLEInterface.POWER_MODE_BALANCED, BLEInterface.POWER_MODE_SAVER]: RNS.log(f"{self} Invalid power mode '{self.power_mode}', using balanced", RNS.LOG_WARNING) self.power_mode = BLEInterface.POWER_MODE_BALANCED # Central mode (scanning and connecting) configuration enable_central_val = c.get("enable_central", True) # Convert string "yes"/"no" to boolean if isinstance(enable_central_val, str): self.enable_central = enable_central_val.lower() in ["yes", "true", "1"] else: self.enable_central = bool(enable_central_val) # Peripheral mode (GATT server) configuration enable_peripheral_val = c.get("enable_peripheral", True) # Convert string "yes"/"no" to boolean if isinstance(enable_peripheral_val, str): self.enable_peripheral = enable_peripheral_val.lower() in ["yes", "true", "1"] else: self.enable_peripheral = bool(enable_peripheral_val) if self.enable_peripheral and not HAS_GATT_SERVER: RNS.log(f"{self} Peripheral mode requested but BLEGATTServer not available", RNS.LOG_WARNING) self.enable_peripheral = False # Local announce forwarding workaround # WORKAROUND: Reticulum Transport.py doesn't forward locally-originated announces (hops=0) # to physical interfaces. This option enables manual forwarding of local announces to BLE peers. # See: Transport.py lines 987-1069 (locally originated announces skip forwarding block) # Default: False (disabled, assume Transport behavior is intentional) enable_local_announce_val = c.get("enable_local_announce_forwarding", False) if isinstance(enable_local_announce_val, str): self.enable_local_announce_forwarding = enable_local_announce_val.lower() in ["yes", "true", "1"] else: self.enable_local_announce_forwarding = bool(enable_local_announce_val) # State tracking self.peers = {} # address -> (client, last_seen, mtu) self.peer_lock = threading.Lock() # Identity-based interface tracking self.spawned_interfaces = {} # identity_hash (16 hex chars) -> BLEPeerInterface self.address_to_identity = {} # address -> peer_identity (16-byte identity) self.identity_to_address = {} # identity_hash -> address (for reverse lookup) # Fragmentation self.fragmenters = {} # address -> BLEFragmenter (per MTU) self.reassemblers = {} # address -> BLEReassembler self.frag_lock = threading.Lock() # Discovery state with prioritization # Initialize BLE driver (uses class attribute, can be overridden by subclasses) if self.driver_class is None: raise ImportError( "No BLE driver available. LinuxBluetoothDriver not found and no " "driver_class override provided by subclass." ) self.driver = self.driver_class( discovery_interval=self.discovery_interval, connection_timeout=self.connection_timeout, min_rssi=self.min_rssi, service_discovery_delay=self.service_discovery_delay, max_peers=self.max_peers, adapter_index=0 # TODO: Make configurable ) RNS.log(f"{self} Using driver: {type(self.driver).__name__}", RNS.LOG_DEBUG) # Set driver callbacks self.driver.on_device_discovered = self._device_discovered_callback self.driver.on_device_connected = self._device_connected_callback self.driver.on_mtu_negotiated = self._mtu_negotiated_callback self.driver.on_data_received = self._data_received_callback self.driver.on_device_disconnected = self._device_disconnected_callback self.driver.on_error = self._error_callback self.driver.on_duplicate_identity_detected = self._check_duplicate_identity # Redirect Python logging to RNS logging for proper formatting self._setup_logging_redirect() # Set driver power mode self.driver.set_power_mode(self.power_mode) self.discovered_peers = {} # address -> DiscoveredPeer self.connection_blacklist = {} # address -> (blacklist_until_timestamp, failure_count) self.scanning = False # HIGH #4: Limit discovered peers to prevent unbounded memory growth self.max_discovered_peers = int(c.get("max_discovered_peers", 100)) # Reasonable limit for discovery cache # Connection prioritization configuration self.connection_rotation_interval = float(c.get("connection_rotation_interval", 600)) # 10 minutes self.connection_retry_backoff = float(c.get("connection_retry_backoff", 60)) # 1 minute self.max_connection_failures = int(c.get("max_connection_failures", 3)) # blacklist threshold # Local adapter address (will be populated on first scan) self.local_address = None RNS.log(f"{self} initializing with service UUID {self.service_uuid}", RNS.LOG_INFO) RNS.log(f"{self} power mode: {self.power_mode}, max peers: {self.max_peers}", RNS.LOG_DEBUG) RNS.log(f"{self} central mode: {'ENABLED' if self.enable_central else 'DISABLED'}", RNS.LOG_INFO) RNS.log(f"{self} peripheral mode: {'ENABLED' if self.enable_peripheral else 'DISABLED'}", RNS.LOG_INFO) # Local announce forwarding status log if self.enable_local_announce_forwarding: RNS.log(f"{self} local packet forwarding ENABLED (workaround for Transport hops=0 bug)", RNS.LOG_INFO) else: RNS.log(f"{self} local packet forwarding DISABLED (relies on Transport for propagation)", RNS.LOG_DEBUG) # CRITICAL #2: Periodic cleanup task for stale reassembly buffers # This prevents memory leaks from incomplete packet transmissions (disconnects, corrupted data) # Runs every 30 seconds to clean up timed-out buffers self.cleanup_timer = None self._start_cleanup_timer() # Start the interface self.start() def start(self): """Start the BLE interface operations.""" RNS.log(f"{self} starting BLE operations", RNS.LOG_INFO) # Start the BLE driver try: self.driver.start( service_uuid=self.service_uuid, rx_char_uuid=BLEInterface.CHARACTERISTIC_RX_UUID, tx_char_uuid=BLEInterface.CHARACTERISTIC_TX_UUID, identity_char_uuid=BLEInterface.CHARACTERISTIC_IDENTITY_UUID ) RNS.log(f"{self} driver started successfully", RNS.LOG_INFO) except Exception as e: RNS.log(f"{self} failed to start driver: {e}", RNS.LOG_ERROR) return # If central mode is enabled, start scanning for peers if self.enable_central: try: self.driver.start_scanning() RNS.log(f"{self} started scanning for peers", RNS.LOG_INFO) except Exception as e: RNS.log(f"{self} failed to start scanning: {e}", RNS.LOG_ERROR) # Bug #13 workaround: Clear stale BLE paths from Transport.path_table # Reticulum core bug: Paths loaded from storage may have timestamp=0, # causing immediate expiration and message delivery failures. # This workaround removes stale BLE paths on interface startup. # TODO: Remove when upstream Transport.py is fixed (see session notes) self._clear_stale_ble_paths() # Set interface online self.online = True RNS.log(f"{self} interface online", RNS.LOG_INFO) def final_init(self): """ Interface lifecycle hook called AFTER interface is added to Transport.interfaces but BEFORE Transport.start() loads Transport.identity. Use this to start a background thread that waits for Transport.identity to be loaded, then sets it on the driver and starts advertising. """ if self.enable_peripheral: RNS.log(f"{self} Launching driver advertising startup thread (will wait for Transport.identity)", RNS.LOG_DEBUG) startup_thread = threading.Thread(target=self._start_advertising_when_identity_ready, daemon=True, name="BLE-Advertising-Startup") startup_thread.start() def _setup_logging_redirect(self): """ Redirect Python logging from the BLE driver to RNS logging for consistent formatting. Only redirects logs from 'root' logger (used by linux_bluetooth_driver), not from underlying libraries like bleak, dbus_fast, etc. """ class RNSLoggingHandler(logging.Handler): def __init__(self, interface_name): super().__init__() self.interface_name = interface_name def emit(self, record): try: # Only process logs from root logger (linux_bluetooth_driver) # Ignore verbose logs from underlying libraries (bleak, dbus_fast, etc.) if record.name != 'root': return # Map Python logging levels to RNS log levels level_map = { logging.DEBUG: RNS.LOG_DEBUG, logging.INFO: RNS.LOG_INFO, logging.WARNING: RNS.LOG_WARNING, logging.ERROR: RNS.LOG_ERROR, logging.CRITICAL: RNS.LOG_CRITICAL } rns_level = level_map.get(record.levelno, RNS.LOG_INFO) # Format message message = self.format(record) # Log to RNS RNS.log(f"{self.interface_name} {message}", rns_level) except Exception: # Silently fail if RNS logging fails (don't want to break the driver) pass # Get root logger (used by linux_bluetooth_driver) root_logger = logging.getLogger() # Remove any existing stream handlers from root logger to prevent duplicate console output for handler in root_logger.handlers[:]: if isinstance(handler, logging.StreamHandler): root_logger.removeHandler(handler) # Only add handler if not already added (avoid duplicates) handler_exists = any(isinstance(h, RNSLoggingHandler) for h in root_logger.handlers) if not handler_exists: handler = RNSLoggingHandler(str(self)) handler.setLevel(logging.INFO) # Only INFO and above from driver handler.setFormatter(logging.Formatter('%(message)s')) root_logger.addHandler(handler) root_logger.setLevel(logging.INFO) # Don't capture DEBUG from libraries def _start_advertising_when_identity_ready(self): """ Background thread that waits for Transport.identity, sets it on driver, then starts advertising. Times out after 60 seconds if identity doesn't load. """ import RNS.Transport as Transport attempt = 0 start_time = time.time() timeout = 60.0 # 60 second timeout RNS.log(f"{self} Waiting for Transport.identity to be loaded...", RNS.LOG_DEBUG) # Poll until Transport.identity is available (with 60s timeout) while time.time() - start_time < timeout: attempt += 1 try: if hasattr(Transport, 'identity') and Transport.identity: identity_hash = Transport.identity.hash if identity_hash and len(identity_hash) == 16: elapsed = time.time() - start_time RNS.log(f"{self} Transport.identity available after {elapsed:.1f}s", RNS.LOG_INFO) # Set identity on driver self.driver.set_identity(identity_hash) # Start advertising try: self.driver.start_advertising(self.device_name, identity_hash) if self.device_name: RNS.log(f"{self} Started advertising as {self.device_name}", RNS.LOG_INFO) else: RNS.log(f"{self} Started advertising (no device name)", RNS.LOG_INFO) except Exception as e: RNS.log(f"{self} Failed to start advertising: {e}", RNS.LOG_ERROR) return except Exception as e: RNS.log(f"{self} Error waiting for identity: {e}", RNS.LOG_DEBUG) time.sleep(0.5) RNS.log(f"{self} Timeout waiting for Transport.identity after {timeout}s", RNS.LOG_ERROR) def _clear_stale_ble_paths(self): """ Clear stale BLE paths from Transport.path_table on interface startup. Bug #13 workaround: Reticulum core loads path table entries from storage with timestamp=0 (or very old timestamps), causing paths to immediately expire. This prevents LXMF message delivery as messages wait for paths that are constantly expiring and being recreated. This workaround clears any BLE paths with invalid timestamps on startup, forcing fresh path discovery via announces. TODO: Remove this workaround when Reticulum core is fixed to refresh timestamps when loading paths from storage (Transport.py:252). """ try: import RNS.Transport as Transport if not hasattr(Transport, 'path_table') or not Transport.path_table: return current_time = time.time() stale_threshold = 60 # Paths older than 60 seconds are considered stale stale_paths = [] # Scan for stale BLE paths for dest_hash, entry in list(Transport.path_table.items()): try: timestamp = entry[0] # IDX_PT_TIMESTAMP receiving_interface = entry[5] # IDX_PT_RVCD_IF # Check if this is a BLE path if receiving_interface and "BLE" in str(type(receiving_interface).__name__): # Check for timestamp=0 bug or very old timestamps if timestamp == 0: stale_paths.append((dest_hash, timestamp, "timestamp=0 (Unix epoch bug)")) elif (current_time - timestamp) > stale_threshold: stale_paths.append((dest_hash, timestamp, f"age={(current_time - timestamp):.0f}s (stale from previous session)")) except (IndexError, TypeError) as e: # Malformed path entry RNS.log(f"{self} Skipping malformed path table entry: {e}", RNS.LOG_DEBUG) continue # Remove stale paths if stale_paths: RNS.log(f"{self} Bug #13 workaround: Found {len(stale_paths)} stale BLE path(s) to clear", RNS.LOG_INFO) for dest_hash, old_timestamp, reason in stale_paths: Transport.path_table.pop(dest_hash) RNS.log(f"{self} Cleared stale BLE path for {RNS.prettyhexrep(dest_hash)} - {reason}", RNS.LOG_DEBUG) RNS.log(f"{self} Stale path cleanup complete. Fresh paths will be discovered via announces.", RNS.LOG_INFO) else: RNS.log(f"{self} No stale BLE paths found in path table", RNS.LOG_DEBUG) except Exception as e: RNS.log(f"{self} Error during stale path cleanup (non-fatal): {e}", RNS.LOG_WARNING) def _start_cleanup_timer(self): """ Start the periodic cleanup timer. CRITICAL #2: This timer prevents memory leaks from incomplete reassembly buffers caused by peer disconnections or corrupted partial transmissions. """ if self.cleanup_timer: self.cleanup_timer.cancel() self.cleanup_timer = threading.Timer(30.0, self._periodic_cleanup_task) self.cleanup_timer.daemon = True self.cleanup_timer.start() def _periodic_cleanup_task(self): """ Periodically clean up stale reassembly buffers (CRITICAL #2: prevent memory leak) This task runs every 30 seconds to remove incomplete packet reassembly buffers that have timed out. Without this, failed transmissions would leave buffers in memory indefinitely, leading to memory exhaustion on long-running instances (especially critical on Pi Zero with only 512MB RAM). """ if not self.online: return # Don't reschedule if interface is offline with self.frag_lock: total_cleaned = 0 for peer_address, reassembler in list(self.reassemblers.items()): cleaned = reassembler.cleanup_stale_buffers() if cleaned > 0: total_cleaned += cleaned RNS.log(f"{self} cleaned {cleaned} stale reassembly buffer(s) for {peer_address}", RNS.LOG_DEBUG) if total_cleaned > 0: RNS.log(f"{self} periodic cleanup: removed {total_cleaned} stale reassembly buffer(s) total", RNS.LOG_INFO) # Reschedule for next cleanup cycle self._start_cleanup_timer() def _device_discovered_callback(self, device: BLEDevice): """ Driver callback: Handle discovered BLE device. This callback is invoked by the driver when a device is discovered during scanning. We use peer scoring and connection logic to decide whether to connect. """ # Primary: Match by service UUID (standard BLE discovery) if self.service_uuid not in device.service_uuids: RNS.log(f"{self} device {device.name if device.name else device.address} does not advertise Reticulum service UUID, skipping", RNS.LOG_EXTREME) return # Validate RSSI - skip devices with invalid/sentinel values if device.rssi in (-127, -128, 0): RNS.log(f"{self} skipping {device.name or device.address} ({device.address}): invalid sentinel RSSI {device.rssi} dBm", RNS.LOG_DEBUG) return # Update or create discovered peer entry if device.address not in self.discovered_peers: self.discovered_peers[device.address] = DiscoveredPeer( address=device.address, name=device.name, rssi=device.rssi ) else: self.discovered_peers[device.address].update_rssi(device.rssi) # Prune discovery cache if needed (HIGH #4) if len(self.discovered_peers) > self.max_discovered_peers: # Remove oldest entries by last_seen timestamp sorted_peers = sorted( self.discovered_peers.items(), key=lambda x: x[1].last_seen ) to_remove = sorted_peers[:-self.max_discovered_peers] for addr, _ in to_remove: del self.discovered_peers[addr] # Decide whether to connect based on peer scoring peers_to_connect = self._select_peers_to_connect() if device.address in [p.address for p in peers_to_connect]: # Record connection attempt BEFORE calling driver.connect() # This prevents rapid-fire retries if discovery callback fires again if device.address in self.discovered_peers: self.discovered_peers[device.address].record_connection_attempt() # Initiate connection via driver try: self.driver.connect(device.address) except Exception as e: RNS.log(f"{self} failed to initiate connection to {device.name}: {e}", RNS.LOG_ERROR) def _device_connected_callback(self, address: str, peer_identity: Optional[bytes]): """ Driver callback: Handle successful device connection. Called when driver has established a connection. For central connections, the peer_identity is provided. For peripheral connections, identity will arrive later via handshake. Args: address: MAC address of connected peer peer_identity: 16-byte identity hash (None for peripheral connections) """ role = self.driver.get_peer_role(address) if peer_identity is not None: # Central mode: identity provided by driver if len(peer_identity) == 16: identity_hash = self._compute_identity_hash(peer_identity) # Store identity mappings self.address_to_identity[address] = peer_identity self.identity_to_address[identity_hash] = address RNS.log(f"{self} connected to {address} as CENTRAL, received identity: {identity_hash}", RNS.LOG_INFO) self._record_connection_success(address) else: RNS.log(f"{self} invalid identity from {address} (wrong length), disconnecting", RNS.LOG_WARNING) self.driver.disconnect(address) self._record_connection_failure(address) elif role == "peripheral": # Peripheral mode: identity will arrive via handshake RNS.log(f"{self} connected to {address} as PERIPHERAL, waiting for identity handshake...", RNS.LOG_INFO) # The identity will be received in `_data_received_callback` else: RNS.log(f"{self} connected to {address}, but identity not provided and role is {role}. Disconnecting.", RNS.LOG_WARNING) self.driver.disconnect(address) def _check_duplicate_identity(self, address: str, peer_identity: bytes) -> bool: """ Driver callback: Check if peer identity already exists under a different MAC. This handles Android MAC randomization where the same device advertises with one MAC but connects with a different MAC. Args: address: MAC address attempting to connect peer_identity: 16-byte identity hash of the peer Returns: True if this identity is already connected via a different MAC (abort connection) False if this is a new identity or same MAC (allow connection) """ if not peer_identity or len(peer_identity) != 16: return False identity_hash = self._compute_identity_hash(peer_identity) existing_address = self.identity_to_address.get(identity_hash) if existing_address and existing_address != address: # Same identity, different MAC - this is Android MAC rotation RNS.log( f"{self} duplicate identity detected: {identity_hash[:8]} already connected via {existing_address}, " f"rejecting connection from {address} (Android MAC rotation)", RNS.LOG_WARNING ) return True # Either new identity or same MAC - allow connection return False def _mtu_negotiated_callback(self, address: str, mtu: int): """ Driver callback: Handle MTU negotiation completion. Creates or updates the fragmenter for this peer with the negotiated MTU. """ RNS.log(f"{self} MTU negotiated with {address}: {mtu} bytes", RNS.LOG_INFO) # Get peer identity peer_identity = self.address_to_identity.get(address) if not peer_identity: RNS.log(f"{self} no identity for {address}, cannot create fragmenter", RNS.LOG_WARNING) return # Create or update fragmenter frag_key = self._get_fragmenter_key(peer_identity, address) with self.frag_lock: # Create fragmenter with MTU self.fragmenters[frag_key] = BLEFragmenter(mtu=mtu) # Create reassembler if not exists if frag_key not in self.reassemblers: self.reassemblers[frag_key] = BLEReassembler() # Spawn peer interface if not exists identity_hash = self._compute_identity_hash(peer_identity) if identity_hash not in self.spawned_interfaces: # Get peer name from discovered peers peer_name = None if address in self.discovered_peers: peer_name = self.discovered_peers[address].name else: peer_name = f"BLE-{address[-8:]}" # Determine connection type based on MAC sorting connection_type = "central" if self.driver.get_local_address(): local_mac = self.driver.get_local_address().lower() peer_mac = address.lower() if local_mac > peer_mac: connection_type = "peripheral" self._spawn_peer_interface( address=address, name=peer_name, peer_identity=peer_identity, mtu=mtu, connection_type=connection_type ) def _handle_identity_handshake(self, address: str, data: bytes) -> bool: """ Handle identity handshake from central device (peripheral role only). When a central connects to us (we're peripheral), it sends exactly 16 bytes as the first packet - its identity hash. This allows the peripheral to learn the central's identity without requiring discovery/scanning. Args: address: MAC address of the central device data: Received data bytes Returns: True if data was handled as identity handshake, False otherwise """ # Check if we already have peer identity peer_identity = self.address_to_identity.get(address) if peer_identity: return False # Already have identity, not a handshake # Identity handshake detection: exactly 16 bytes, no existing identity if len(data) != 16: return False # Not a handshake try: # Store central's identity central_identity = bytes(data) identity_hash = self._compute_identity_hash(central_identity) self.address_to_identity[address] = central_identity self.identity_to_address[identity_hash] = address RNS.log(f"{self} received identity handshake from {address}: {identity_hash}", RNS.LOG_INFO) # Get MTU for this connection (should be negotiated by now) mtu = self.driver.get_peer_mtu(address) if not mtu: mtu = 23 # BLE 4.0 minimum MTU # Create fragmenter/reassembler frag_key = self._get_fragmenter_key(central_identity, address) with self.frag_lock: self.fragmenters[frag_key] = BLEFragmenter(mtu=mtu) if frag_key not in self.reassemblers: self.reassemblers[frag_key] = BLEReassembler() # Spawn peer interface if not already spawned if identity_hash not in self.spawned_interfaces: peer_name = f"Central-{address[-8:]}" connection_type = "peripheral" # We're the peripheral self._spawn_peer_interface( address=address, name=peer_name, peer_identity=central_identity, mtu=mtu, connection_type=connection_type ) RNS.log(f"{self} identity handshake complete for {address}", RNS.LOG_INFO) return True # Handshake processed successfully except Exception as e: RNS.log(f"{self} failed to process identity handshake from {address}: {e}", RNS.LOG_ERROR) return True # Still consumed the data, don't pass it on def _data_received_callback(self, address: str, data: bytes): """ Driver callback: Handle received data from peer. First checks for identity handshake (peripheral role), then passes normal data to reassembly and routing logic. """ # Handle identity handshake if applicable if self._handle_identity_handshake(address, data): return # Handshake handled, done # Normal data processing self._handle_ble_data(address, data) def _device_disconnected_callback(self, address: str): """ Driver callback: Handle device disconnection. Cleans up peer state, interfaces, and fragmentation buffers. """ RNS.log(f"{self} disconnected from {address}", RNS.LOG_INFO) # Clean up peer connection state with self.peer_lock: if address in self.peers: del self.peers[address] # Detach interface peer_identity = self.address_to_identity.get(address) if peer_identity: identity_hash = self._compute_identity_hash(peer_identity) if identity_hash in self.spawned_interfaces: peer_if = self.spawned_interfaces[identity_hash] peer_if.detach() del self.spawned_interfaces[identity_hash] RNS.log(f"{self} detached interface for {address}", RNS.LOG_DEBUG) # Clean up identity mappings to prevent stale connections if address in self.address_to_identity: del self.address_to_identity[address] RNS.log(f"{self} cleaned up address_to_identity for {address}", RNS.LOG_DEBUG) if identity_hash in self.identity_to_address: del self.identity_to_address[identity_hash] RNS.log(f"{self} cleaned up identity_to_address for {identity_hash}", RNS.LOG_DEBUG) # Clean up fragmenter/reassembler if peer_identity: frag_key = self._get_fragmenter_key(peer_identity, address) with self.frag_lock: if frag_key in self.fragmenters: del self.fragmenters[frag_key] if frag_key in self.reassemblers: del self.reassemblers[frag_key] def _error_callback(self, severity: str, message: str, exc: Exception = None): """ Driver callback: Handle driver errors. Logs errors with appropriate severity level. Some errors are downgraded to debug level if they're expected race conditions that are handled gracefully. Also triggers blacklist mechanism for connection failures to prevent infinite retry loops with MAC address randomization. """ # Check for race condition errors that should be downgraded to DEBUG should_blacklist = False if exc and severity == "error": exc_str = str(exc) # "Operation already in progress" - race condition from concurrent connection attempts # This should no longer happen with our fixes, but if it does, it's not a critical error if "Operation already in progress" in exc_str or "In Progress" in exc_str: severity = "debug" log_level = RNS.LOG_DEBUG # "br-connection-canceled" - BR/EDR fallback was attempted but canceled # This is expected behavior when ConnectDevice() retry happens elif "br-connection-canceled" in exc_str: severity = "debug" log_level = RNS.LOG_DEBUG else: log_level = RNS.LOG_ERROR should_blacklist = True elif severity == "critical": log_level = RNS.LOG_CRITICAL elif severity == "error": log_level = RNS.LOG_ERROR should_blacklist = True elif severity == "warning": log_level = RNS.LOG_WARNING # Connection timeouts should also trigger blacklist if "Connection timeout" in message: should_blacklist = True else: log_level = RNS.LOG_DEBUG if exc: RNS.log(f"{self} driver {severity}: {message} - {type(exc).__name__}: {exc}", log_level) else: RNS.log(f"{self} driver {severity}: {message}", log_level) # Extract address from connection failure messages and trigger blacklist if should_blacklist: import re # Match patterns like "Connection failed to XX:XX:XX:XX:XX:XX:" or "Connection timeout to XX:XX:XX:XX:XX:XX" match = re.search(r'(?:Connection (?:failed|timeout) to|to) ([0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2}:[0-9A-Fa-f]{2})', message) if match: address = match.group(1).upper() RNS.log(f"{self} recording connection failure for {address} to activate blacklist", RNS.LOG_INFO) self._record_connection_failure(address) def _score_peer(self, peer): """ Calculate priority score for peer selection. Scoring is weighted as follows: - Signal strength (RSSI): 60% (0-70 points based on signal quality) - Connection history: 30% (0-50 points based on success rate) - Recency: 10% (0-25 points based on how recently seen) Algorithm Design Decisions: --------------------------- 1. RSSI Dominance (60% weight): In BLE networks, signal strength is the most reliable predictor of connection success and data throughput. A peer at -40 dBm will consistently outperform one at -90 dBm, regardless of history. This weight ensures we prioritize physically close or unobstructed peers. 2. History Matters (30% weight): Past reliability is important but shouldn't override current signal conditions. A previously reliable peer that has moved away (poor RSSI) should be deprioritized. The 30% weight balances this appropriately. 3. Recency Bonus (10% weight): Recently seen peers are more likely to be currently available. This small weight gives a tiebreaker advantage to active peers without dominating the score. 4. New Peer Benefit: Peers with no history get 25/50 points (50%) on history scoring. This "benefit of the doubt" allows new peers to compete while requiring them to have good RSSI to be selected. 5. Clamping RSSI: We clamp RSSI to [-100, -30] dBm range based on real-world BLE behavior. Below -100 is essentially no signal, above -30 is uncommon and offers no practical benefit. 6. Linear Recency Decay: Recent peers (<5s) get full points, then decay linearly to 0 over 30 seconds. This matches typical BLE discovery intervals (5-10s) and prevents stale peer selection. Args: peer: DiscoveredPeer object Returns: float: Priority score (higher = better), typically 0-145 - Perfect score: 70 (RSSI) + 50 (history) + 25 (recent) = 145 - New peer: 70 (RSSI) + 25 (new bonus) + 25 (recent) = 120 - Poor peer: 0 (RSSI) + 0 (history) + 0 (old) = 0 """ score = 0.0 # Validate RSSI - reject peers with invalid/sentinel values if peer.rssi is None or peer.rssi in (-127, -128, 0): RNS.log(f"{self} peer {peer.address} has invalid RSSI {peer.rssi}, returning minimum score", RNS.LOG_DEBUG) return 0.0 # Signal strength component (0-100 points) # RSSI typically ranges from -30 (excellent) to -100 (poor) # Convert to 0-100 scale if peer.rssi is not None: # Clamp RSSI to reasonable range rssi_clamped = max(-100, min(-30, peer.rssi)) # Convert to 0-70 range (-100 → 0, -30 → 70) rssi_normalized = (rssi_clamped + 100) * (70.0 / 70.0) score += rssi_normalized # Connection history component (0-50 points) # Reward peers with good connection history if peer.connection_attempts > 0: success_rate = peer.get_success_rate() score += success_rate * 50.0 else: # New peers get a moderate score (benefit of the doubt) score += 25.0 # Recency component (0-25 points) # Prefer recently seen peers age_seconds = time.time() - peer.last_seen if age_seconds < 5.0: # Very recent (< 5 seconds) - full points score += 25.0 elif age_seconds < 30.0: # Recent (< 30 seconds) - decay linearly score += 25.0 * (1.0 - (age_seconds - 5.0) / 25.0) # Older peers get 0 recency points return score def _select_peers_to_connect(self): """ Select which peers to connect to based on scoring. This method: 1. Scores all discovered peers 2. Filters out already-connected peers 3. Filters out blacklisted peers 4. Selects top N peers up to max_peers limit Algorithm Design Decisions: --------------------------- 1. Greedy Selection: We select the top N highest-scoring peers rather than using a threshold. This ensures we always utilize available connection slots even if all peers have mediocre scores. 2. Already-Connected Filter: Skip peers we're already connected to. This prevents redundant connection attempts and allows the discovery process to focus on finding new peers. 3. Blacklist Respect: Temporarily blacklisted peers are excluded entirely. This prevents connection churn from repeatedly attempting to connect to consistently failing peers. 4. Sort by Score: Sorting ensures deterministic selection and allows for easy debugging (highest-scored peers are always chosen first). 5. Slot-Based Limits: We calculate available_slots = max_peers - current rather than a fixed number. This adapts to disconnections and ensures we maintain target connection count. Returns: list: List of DiscoveredPeer objects to connect to """ # Calculate how many connection slots are available available_slots = self.max_peers - len(self.peers) if available_slots <= 0: return [] # Score all discovered peers scored_peers = [] for address, peer in self.discovered_peers.items(): # Skip if already connected if address in self.peers: continue # Skip if connection is already in progress if hasattr(self.driver, '_connecting_peers'): with self.driver._connecting_lock: if address in self.driver._connecting_peers: # Diagnostic: Show ALL addresses currently being connected to all_connecting = list(self.driver._connecting_peers) RNS.log(f"{self} [v2.2] skipping {peer.name} ({address}) - connection already in progress", RNS.LOG_DEBUG) RNS.log(f"{self} [DIAGNOSTIC] Currently connecting to {len(all_connecting)} address(es): {all_connecting}", RNS.LOG_INFO) continue # Rate limiting: Skip if we recently attempted connection to this peer time_since_attempt = time.time() - peer.last_connection_attempt if peer.last_connection_attempt > 0 and time_since_attempt < 5.0: RNS.log(f"{self} [v2.2] skipping {peer.name} - connection attempted {time_since_attempt:.1f}s ago (rate limit: 5s)", RNS.LOG_DEBUG) continue # Protocol v2.2: Skip if interface exists for this identity (any connection type) # This prevents dual connections (central + peripheral to same peer) peer_identity = self.address_to_identity.get(address) if peer_identity: identity_hash = self._compute_identity_hash(peer_identity) if identity_hash in self.spawned_interfaces: RNS.log(f"{self} [v2.2] skipping {peer.name} - interface exists for identity {identity_hash[:8]}", RNS.LOG_DEBUG) continue # Protocol v2.2: MAC address sorting - deterministic connection direction # Lower MAC initiates (central), higher MAC only accepts (peripheral) # This prevents simultaneous connection attempts from both sides if self.local_address is not None: try: # Normalize addresses (remove colons) my_mac = self.local_address.replace(":", "") peer_mac = address.replace(":", "") my_mac_int = int(my_mac, 16) peer_mac_int = int(peer_mac, 16) if my_mac_int > peer_mac_int: # Our MAC is higher - let them connect to us (we stay peripheral only) RNS.log(f"{self} [v2.2] skipping {peer.name} (MAC {address[:17]}) - " f"connection direction: they initiate (lower MAC connects to higher)", RNS.LOG_DEBUG) continue except (ValueError, AttributeError) as e: # MAC parsing failed - fall through to normal connection logic RNS.log(f"{self} MAC sorting failed for {peer.name}: {e}", RNS.LOG_DEBUG) # Skip if blacklisted if self._is_blacklisted(address): continue # Calculate score score = self._score_peer(peer) scored_peers.append((score, peer)) # Sort by score (highest first) scored_peers.sort(reverse=True, key=lambda x: x[0]) # Select top N peers selected = [peer for score, peer in scored_peers[:available_slots]] if selected: RNS.log(f"{self} selected {len(selected)} peers to connect from {len(scored_peers)} candidates", RNS.LOG_DEBUG) for score, peer in scored_peers[:available_slots]: RNS.log(f"{self} -> {peer.name} (score: {score:.1f}, RSSI: {peer.rssi})", RNS.LOG_EXTREME) return selected def _is_blacklisted(self, address): """ Check if a peer is temporarily blacklisted. Args: address: BLE address to check Returns: bool: True if peer is blacklisted """ if address not in self.connection_blacklist: return False blacklist_until, failure_count = self.connection_blacklist[address] # Check if blacklist has expired if time.time() >= blacklist_until: # Blacklist expired, remove it del self.connection_blacklist[address] RNS.log(f"{self} blacklist expired for {address}", RNS.LOG_DEBUG) return False return True def _record_connection_success(self, address): """ Record a successful connection. Args: address: BLE address of peer """ if address in self.discovered_peers: self.discovered_peers[address].record_connection_success() # Clear blacklist on success if address in self.connection_blacklist: del self.connection_blacklist[address] RNS.log(f"{self} cleared blacklist for {address} after successful connection", RNS.LOG_DEBUG) def _record_connection_failure(self, address): """ Record a failed connection and update blacklist. Algorithm Design Decisions: --------------------------- 1. Exponential Backoff: Blacklist duration increases exponentially with consecutive failures. This prevents connection churn while still allowing eventual retries if conditions improve. Formula: backoff * min(failures - threshold + 1, 8) Example: 60s, 120s, 240s, 480s (capped at 8x = 480s) 2. Threshold-Based Activation: We only blacklist after N failures (default 3) to tolerate temporary issues like brief signal loss or interference without permanently marking peers as bad. 3. Capped Multiplier: We cap the backoff multiplier at 8x to prevent excessively long blacklist periods (e.g., hours). After 480s, a peer is likely to have moved or conditions changed enough to retry. 4. Failure Counter Persists: We track total failed_connections rather than resetting on blacklist. This provides long-term reliability data for scoring even after blacklist expires. Args: address: BLE address of peer """ if address in self.discovered_peers: peer = self.discovered_peers[address] peer.record_connection_failure() # Check if we should blacklist this peer if peer.failed_connections >= self.max_connection_failures: # Blacklist with exponential backoff backoff_multiplier = min(peer.failed_connections - self.max_connection_failures + 1, 8) blacklist_duration = self.connection_retry_backoff * backoff_multiplier blacklist_until = time.time() + blacklist_duration self.connection_blacklist[address] = (blacklist_until, peer.failed_connections) RNS.log(f"{self} blacklisted {peer.name} for {blacklist_duration:.0f}s after {peer.failed_connections} failures", RNS.LOG_WARNING) # Clean up BlueZ device state after blacklisting to prevent persistent errors # This ensures that when the blacklist expires, the device can reconnect cleanly if hasattr(self.driver, '_remove_bluez_device'): try: import asyncio # Run cleanup in driver's event loop with timeout future = asyncio.run_coroutine_threadsafe( self.driver._remove_bluez_device(address), self.driver.loop ) # Wait up to 5 seconds for cleanup to complete cleanup_result = future.result(timeout=5.0) if cleanup_result: RNS.log(f"{self} cleaned up BlueZ device state for blacklisted peer {address}", RNS.LOG_DEBUG) except Exception as e: RNS.log(f"{self} device cleanup failed for blacklisted peer {address}: {e}", RNS.LOG_DEBUG) def _get_fragmenter_key(self, peer_identity, peer_address): """ Compute fragmenter/reassembler dictionary key using full identity hash. Args: peer_identity: 16-byte peer identity peer_address: BLE MAC address (unused, kept for compatibility) Returns: str: Full 16-byte identity as 32 hex characters """ return peer_identity.hex() def _compute_identity_hash(self, peer_identity): """ Compute 16-character hex identity hash for interface tracking. Args: peer_identity: 16-byte peer identity Returns: str: Identity hash (16 hex chars) """ return RNS.Identity.full_hash(peer_identity)[:16].hex()[:16] def _spawn_peer_interface(self, address, name, peer_identity, client=None, mtu=None, connection_type="central"): """ Create a peer interface for a BLE connection. Args: address: BLE address of peer name: Name of peer device peer_identity: 16-byte peer identity client: BleakClient instance (for central connections) mtu: Negotiated MTU (for central connections) connection_type: "central" (we connected to them) or "peripheral" (they connected to us) Returns: BLEPeerInterface: The spawned interface """ # Compute lookup key using identity hash identity_hash = self._compute_identity_hash(peer_identity) # Check if interface already exists (MAC sorting should prevent this) if identity_hash in self.spawned_interfaces: RNS.log(f"{self} interface already exists for {name} ({identity_hash[:8]}), reusing", RNS.LOG_WARNING) return self.spawned_interfaces[identity_hash] # Create new peer interface peer_if = BLEPeerInterface(self, address, name, peer_identity) peer_if.OUT = self.OUT peer_if.IN = self.IN peer_if.parent_interface = self peer_if.bitrate = self.bitrate peer_if.HW_MTU = self.HW_MTU peer_if.online = True # Register with transport RNS.Transport.interfaces.append(peer_if) # Store in tracking dict self.spawned_interfaces[identity_hash] = peer_if RNS.log(f"{self} created peer interface for {name} ({identity_hash[:8]}), type={connection_type}", RNS.LOG_INFO) return peer_if def _handle_ble_data(self, peer_address, data): """ Handle incoming BLE data from a peer (may be fragment). Args: peer_address: Address of peer that sent data data: Raw bytes received (might be fragment) """ RNS.log(f"{self} received {len(data)} bytes from peer {peer_address}", RNS.LOG_EXTREME) # Filter 1-byte keep-alive packets from Columba (Android) peers # Columba sends 0x00 every 15 seconds to prevent Android BLE supervision timeout if len(data) == 1 and data[0] == 0x00: RNS.log(f"{self} received keep-alive from peer {peer_address}, ignoring", RNS.LOG_EXTREME) return # Look up peer identity to compute fragmenter key peer_identity = self.address_to_identity.get(peer_address) if not peer_identity: RNS.log(f"{self} no identity for peer {peer_address}, dropping data", RNS.LOG_WARNING) return # Compute identity-based fragmenter key (matches peripheral data handler) frag_key = self._get_fragmenter_key(peer_identity, peer_address) # Attempt reassembly complete_packet = None peer_name = None # HIGH #2: Lock ordering - get reassembler reference with frag_lock, release before processing # This prevents holding frag_lock during reassembly which could block other threads with self.frag_lock: if frag_key not in self.reassemblers: RNS.log(f"{self} no reassembler for {peer_address} (key: {frag_key[:16]}), dropping data", RNS.LOG_WARNING) return reassembler = self.reassemblers[frag_key] # Process fragment without holding lock (reassemblers are per-peer, no contention) try: # Ensure data is bytes (Bleak notifications may return bytearray) data_bytes = bytes(data) if not isinstance(data, bytes) else data complete_packet = reassembler.receive_fragment(data_bytes, peer_address) # Periodic cleanup of stale buffers (if packet complete) if complete_packet: cleaned = reassembler.cleanup_stale_buffers() if cleaned > 0: RNS.log(f"{self} cleaned {cleaned} stale reassembly buffers for {peer_address}", RNS.LOG_DEBUG) # Log fragmentation statistics for this peer stats = reassembler.get_statistics() # Get peer name from interface lookup peer_identity = self.address_to_identity.get(peer_address, None) peer_name = peer_address[-8:] # Default to address if peer_identity: identity_hash = self._compute_identity_hash(peer_identity) peer_if = self.spawned_interfaces.get(identity_hash, None) if peer_if: peer_name = peer_if.peer_name RNS.log(f"{self} reassembled packet from {peer_name}: " f"total_packets={stats['packets_reassembled']}, " f"total_fragments={stats['fragments_received']}, " f"pending={stats['pending_packets']}, " f"timeouts={stats['packets_timeout']}", RNS.LOG_DEBUG) except Exception as e: RNS.log(f"{self} error reassembling fragment from {peer_address}: {type(e).__name__}: {e}", RNS.LOG_ERROR) return # If we have a complete packet, route to peer interface if complete_packet: peer_identity = self.address_to_identity.get(peer_address, None) if not peer_identity: RNS.log(f"{self} no identity for peer {peer_address}, packet dropped", RNS.LOG_WARNING) return identity_hash = self._compute_identity_hash(peer_identity) peer_if = self.spawned_interfaces.get(identity_hash, None) if peer_if: peer_if.process_incoming(complete_packet) else: RNS.log(f"{self} no interface found for peer {peer_address}, packet dropped", RNS.LOG_WARNING) def handle_peripheral_data(self, data, sender_address): """ Handle incoming data from a central device connected to our GATT server. This is called by the BLEGATTServer when a central writes to the RX characteristic. Args: data: Raw bytes received from central sender_address: BLE address of the central device """ RNS.log(f"{self} received {len(data)} bytes from central {sender_address}", RNS.LOG_EXTREME) # Filter 1-byte keep-alive packets from Columba (Android) peers # Columba sends 0x00 every 15 seconds to prevent Android BLE supervision timeout if len(data) == 1 and data[0] == 0x00: RNS.log(f"{self} received keep-alive from central {sender_address}, ignoring", RNS.LOG_EXTREME) return # Check if we have peer identity peer_identity = self.address_to_identity.get(sender_address) # Identity handshake detection: If no identity and exactly 16 bytes, treat as handshake # Protocol: Central sends its 16-byte identity hash as first packet after connection if not peer_identity and len(data) == 16: try: # Store central's identity central_identity = bytes(data) central_identity_hash = RNS.Identity.full_hash(central_identity)[:16].hex()[:16] self.address_to_identity[sender_address] = central_identity self.identity_to_address[central_identity_hash] = sender_address RNS.log(f"{self} received identity handshake from central {sender_address}: {central_identity_hash}", RNS.LOG_INFO) RNS.log(f"{self} stored identity mapping for {sender_address}", RNS.LOG_DEBUG) # Create fragmenter/reassembler FIRST (before interface) to prevent race condition # where data arrives before reassembler exists frag_key = self._get_fragmenter_key(central_identity, sender_address) with self.frag_lock: # Use default MTU for peripheral connections (GATT server manages MTU) # The actual MTU will be determined by the central device mtu = 23 # BLE 4.0 minimum MTU self.fragmenters[frag_key] = BLEFragmenter(mtu=mtu) self.reassemblers[frag_key] = BLEReassembler(timeout=self.connection_timeout) RNS.log(f"{self} created fragmenter/reassembler for central (key: {frag_key[:16]})", RNS.LOG_DEBUG) # Now create peer interface (after fragmenter/reassembler is ready) self._spawn_peer_interface( address=sender_address, name=f"Central-{sender_address[-8:]}", peer_identity=central_identity, client=None, # No client for peripheral connections mtu=None, # MTU managed by GATT server connection_type="peripheral" ) return # Handshake processed, done except Exception as e: RNS.log(f"{self} failed to process identity handshake from {sender_address}: {type(e).__name__}: {e}", RNS.LOG_ERROR) return # If still no identity after handshake check, drop the data if not peer_identity: RNS.log(f"{self} no identity for central {sender_address}, dropping data", RNS.LOG_WARNING) return # Get fragmenter key frag_key = self._get_fragmenter_key(peer_identity, sender_address) # Attempt reassembly complete_packet = None with self.frag_lock: if frag_key not in self.reassemblers: RNS.log(f"{self} no reassembler for {sender_address}, dropping data", RNS.LOG_WARNING) return reassembler = self.reassemblers[frag_key] try: # Ensure data is bytes (bluezero may pass different types) data_bytes = bytes(data) if not isinstance(data, bytes) else data complete_packet = reassembler.receive_fragment(data_bytes, sender_address) # Periodic cleanup if complete_packet: cleaned = reassembler.cleanup_stale_buffers() if cleaned > 0: RNS.log(f"{self} cleaned {cleaned} stale reassembly buffers for {sender_address}", RNS.LOG_DEBUG) except Exception as e: RNS.log(f"{self} error reassembling fragment from {sender_address}: {type(e).__name__}: {e}", RNS.LOG_ERROR) return # Route complete packet to interface if complete_packet: identity_hash = self._compute_identity_hash(peer_identity) peer_if = self.spawned_interfaces.get(identity_hash) if peer_if: peer_if.process_incoming(complete_packet) else: RNS.log(f"{self} no interface for {sender_address}, packet dropped", RNS.LOG_WARNING) def handle_central_connected(self, address): """ Handle a central device connecting to our GATT server. With the unified interface architecture, this either creates a new interface or adds a peripheral connection to an existing interface for this peer. Args: address: BLE address of the central device """ RNS.log(f"{self} central {address} connected to our peripheral", RNS.LOG_INFO) # Look up peer identity # Identity should be available via: # 1. Discovery: If we previously scanned and discovered this central # 2. Handshake: Central will send 16-byte identity as first write to RX characteristic # At this point (connection established), we may not have identity yet - it arrives via handshake peer_identity = self.address_to_identity.get(address, None) if not peer_identity: RNS.log(f"{self} peer identity not yet available for {address} (will be provided via handshake)", RNS.LOG_DEBUG) # Don't create interface yet - wait for identity handshake in handle_peripheral_data() return # Create peer interface with peripheral connection self._spawn_peer_interface( address=address, name=f"Central-{address[-8:]}", peer_identity=peer_identity, client=None, # No client for peripheral connections mtu=None, # MTU managed by GATT server connection_type="peripheral" ) def handle_central_disconnected(self, address): """ Handle a central device disconnecting from our GATT server. Args: address: BLE address of the central device """ RNS.log(f"{self} central disconnected: {address}", RNS.LOG_INFO) # Look up peer identity peer_identity = self.address_to_identity.get(address, None) if not peer_identity: RNS.log(f"{self} no identity for disconnected central {address}", RNS.LOG_WARNING) return # Find and detach interface identity_hash = self._compute_identity_hash(peer_identity) if identity_hash in self.spawned_interfaces: peer_if = self.spawned_interfaces[identity_hash] peer_if.detach() del self.spawned_interfaces[identity_hash] RNS.log(f"{self} detached interface for {address}", RNS.LOG_DEBUG) # Clean up identity mappings to prevent stale connections if address in self.address_to_identity: del self.address_to_identity[address] RNS.log(f"{self} cleaned up address_to_identity for {address}", RNS.LOG_DEBUG) if identity_hash in self.identity_to_address: del self.identity_to_address[identity_hash] RNS.log(f"{self} cleaned up identity_to_address for {identity_hash}", RNS.LOG_DEBUG) # Clean up fragmenter/reassembler frag_key = self._get_fragmenter_key(peer_identity, address) with self.frag_lock: if frag_key in self.reassemblers: del self.reassemblers[frag_key] RNS.log(f"{self} cleaned up reassembler for {address}", RNS.LOG_DEBUG) if frag_key in self.fragmenters: del self.fragmenters[frag_key] RNS.log(f"{self} cleaned up fragmenter for {address}", RNS.LOG_DEBUG) def process_incoming(self, data): """ Process incoming data from BLE (called by peer interface). Args: data: Raw packet data """ # This will be called by spawned peer interfaces # For now, just pass to owner if self.online and self.owner: self.rxb += len(data) RNS.log(f"{self} RX: {len(data)} bytes from peer interface", RNS.LOG_DEBUG) self.owner.inbound(data, self) def process_outgoing(self, data): """ Process outgoing data to be sent over BLE. WORKAROUND: Transport.py (lines 987-1069) doesn't forward locally-originated packets (hops=0) to physical interfaces - they skip the forwarding block entirely. When this method is called by Transport, we manually forward to all connected BLE peer interfaces. This catches both: - Packets that Transport DOES forward (hops>0, received from other interfaces) - Packets that Transport DOESN'T forward (hops=0, local programs) - if workaround enabled Args: data: Raw packet data to transmit """ if not self.online: return # Get snapshot of peers without holding lock during I/O operations # This prevents deadlock when peer_if.process_outgoing() tries to acquire the same lock with self.peer_lock: peers_to_send = [(address, peer_if) for address, peer_if in self.spawned_interfaces.items() if peer_if.online] # Log packet transmission RNS.log(f"{self} TX: {len(data)} bytes to {len(peers_to_send)} peer(s)", RNS.LOG_DEBUG) # Send to each peer WITHOUT holding the lock (avoid deadlock) for address, peer_if in peers_to_send: peer_if.process_outgoing(data) def detach(self): """Detach and shutdown the interface.""" RNS.log(f"{self} detaching interface", RNS.LOG_INFO) self.online = False # Cancel periodic cleanup timer if self.cleanup_timer: self.cleanup_timer.cancel() self.cleanup_timer = None # Detach spawned interfaces for peer_if in list(self.spawned_interfaces.values()): peer_if.detach() self.spawned_interfaces.clear() # Clear fragmentation state with self.frag_lock: self.fragmenters.clear() self.reassemblers.clear() # Stop the driver (handles graceful disconnection and cleanup) try: self.driver.stop() RNS.log(f"{self} driver stopped", RNS.LOG_DEBUG) except Exception as e: RNS.log(f"{self} error stopping driver: {e}", RNS.LOG_ERROR) RNS.log(f"{self} detached", RNS.LOG_INFO) def should_ingress_limit(self): """ BLE uses point-to-point connections with dedicated channels per peer. Ingress limiting is designed for shared-medium interfaces (LoRa, etc.) where multiple nodes compete for airtime. Disable for BLE. Bug #12 fix: Ingress limiting was holding announces indefinitely, preventing them from being validated and processed by Transport. """ return False def __str__(self): return f"BLEInterface[{self.name}]" class BLEPeerInterface(Interface): """ Spawned interface representing a single BLE peer connection. This follows the pattern used by AutoInterface to create per-peer interfaces for routing and statistics tracking. """ def __init__(self, parent, peer_address, peer_name, peer_identity=None): """ Initialize peer interface. Args: parent: Parent BLEInterface peer_address: BLE address of peer peer_name: Name of peer device peer_identity: 16-byte peer identity from GATT characteristic (optional, can be set later) Note: Connection type (central vs peripheral) and MTU are now managed by the driver. """ super().__init__() self.parent_interface = parent self.peer_address = peer_address self.peer_name = peer_name self.peer_identity = peer_identity # 16-byte identity for stable tracking self.online = True # Copy settings from parent self.HW_MTU = parent.HW_MTU self.bitrate = parent.bitrate # Set interface mode (required by Transport for routing decisions) self.mode = Interface.MODE_FULL # Full mode: can send and receive # Announce rate limiting (required by Transport.inbound announce processing) self.announce_rate_target = None # No announce rate limiting for BLE peer interfaces RNS.log(f"BLEPeerInterface initialized for {peer_name} ({peer_address}), identity={'set' if peer_identity else 'pending'}", RNS.LOG_DEBUG) def process_incoming(self, data): """ Process incoming data from this peer. Args: data: Raw bytes received from peer """ if self.online and self.parent_interface.online: self.rxb += len(data) self.parent_interface.rxb += len(data) # Log packet reception RNS.log(f"{self} RX: {len(data)} bytes from {self.peer_name}", RNS.LOG_DEBUG) # Pass to Reticulum transport self.parent_interface.owner.inbound(data, self) def process_outgoing(self, data): """ Process outgoing data to send to this peer (with fragmentation). Args: data: Raw packet data to transmit """ if not self.online: return # Log packet transmission RNS.log(f"{self} TX: {len(data)} bytes to {self.peer_name}", RNS.LOG_DEBUG) # Get fragmenter for this peer (using identity-based key for MAC rotation immunity) frag_key = self.parent_interface._get_fragmenter_key(self.peer_identity, self.peer_address) with self.parent_interface.frag_lock: if frag_key not in self.parent_interface.fragmenters: RNS.log(f"No fragmenter for peer {self.peer_name} (key: {frag_key})", RNS.LOG_WARNING) return fragmenter = self.parent_interface.fragmenters[frag_key] # Fragment the data try: fragments = fragmenter.fragment_packet(data) if len(fragments) > 1: RNS.log(f"Fragmenting {len(data)} byte packet into {len(fragments)} fragments for {self.peer_name}", RNS.LOG_EXTREME) except Exception as e: RNS.log(f"Failed to fragment data for {self.peer_name}: {e}", RNS.LOG_ERROR) return # Send fragments via driver (driver handles role-aware routing) for i, fragment in enumerate(fragments): try: self.parent_interface.driver.send(self.peer_address, fragment) self.txb += len(fragment) self.parent_interface.txb += len(fragment) except Exception as e: RNS.log(f"Failed to send fragment {i+1}/{len(fragments)} to {self.peer_name}: {e}", RNS.LOG_ERROR) return def detach(self): """Detach this peer interface.""" self.online = False # Remove from transport if self in RNS.Transport.interfaces: RNS.Transport.interfaces.remove(self) RNS.log(f"BLEPeerInterface detached for {self.peer_name}", RNS.LOG_DEBUG) def should_ingress_limit(self): """Inherit ingress limiting from parent.""" return self.parent_interface.should_ingress_limit() @property def connection_id(self): """Get the unique connection ID for this peer interface""" # For unified interfaces, use identity hash if available, otherwise address if self.peer_identity: try: import RNS identity_hash = RNS.Identity.full_hash(self.peer_identity)[:16].hex()[:8] return f"{identity_hash}" except: pass return f"{self.peer_address}" def __str__(self): return f"BLEPeerInterface[{self.peer_name}]" # Register interface for Reticulum interface_class = BLEInterface