torlando-tech 9a3bfec5c7 fix(ble): Add BlueZ state cleanup to prevent persistent "Operation already in progress" errors

Implements comprehensive BlueZ device state cleanup after connection failures
to prevent persistent "Operation already in progress" errors. This addresses
the issue where BlueZ maintains stale connection state after timeouts or
failures, preventing successful reconnection even after blacklist periods expire.

BlueZ State Cleanup Implementation:
- **Explicit client disconnect**: Call client.disconnect() in timeout and failure
  exception handlers to release BlueZ resources
- **D-Bus device removal**: New _remove_bluez_device() method removes stale device
  objects via BlueZ RemoveDevice() API
- **Post-blacklist cleanup**: Trigger BlueZ cleanup when peer is blacklisted after
  reaching max_connection_failures (7 failures)

Impact:
- Enables successful reconnection after temporary connection failures
- Fixes persistent errors across blacklist periods
- Prevents BlueZ from maintaining corrupted connection state
- Particularly important for Android devices with MAC address rotation

Implementation Details:
- linux_bluetooth_driver.py:786-830: New _remove_bluez_device() method
- linux_bluetooth_driver.py:1029-1044: Timeout cleanup (disconnect + removal)
- linux_bluetooth_driver.py:1051-1066: Failure cleanup (disconnect + removal)
- BLEInterface.py:1270-1285: Post-blacklist cleanup hook
- tests/test_bluez_state_cleanup.py: 10 new tests (all passing)

Documentation Updates:
- BLE_PROTOCOL_v2.2.md: New troubleshooting section for persistent InProgress errors
- CLAUDE.md: Added to recent fixes list
- CHANGELOG.md: Comprehensive fix description

Related Issues:
- Addresses "Operation already in progress" errors persisting after connection timeouts
- Fixes reconnection failures after peer blacklisting
- Prevents BlueZ state machine corruption from abandoned BleakClient instances

Testing:
- All 10 new unit tests pass
- Cleanup methods properly handle missing devices and D-Bus unavailability
- Integration testing on Raspberry Pi pending

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-10 00:51:27 -05:00

3.5 KiB

Raw Blame History

Claude Code Reference Guide

Quick reference for AI assistants working on the BLE-Reticulum project.

Project Overview

A Bluetooth Low Energy (BLE) interface for Reticulum Network Stack, enabling mesh networking over BLE on Linux devices with BlueZ 5.x. Supports dual-mode operation (central + peripheral), multi-peer mesh networking, and automatic peer discovery.

Key Documentation

Protocol & Architecture

BLE_PROTOCOL_v2.2.md - Complete protocol specification
- 5 comprehensive lifecycle sequence diagrams (Mermaid format)
- Configuration reference (13 parameters)
- Platform-specific workarounds (BlueZ patches)
- MAC sorting, identity handshake, fragmentation details
- Use this as the authoritative technical reference
REFACTORING_GUIDE.md - Driver abstraction architecture
- Reference for implementing new platform drivers
- Explains BLEDriverInterface contract

User Documentation

README.md - Installation, quick start, troubleshooting
TESTING.md - Test execution and procedures
CONTRIBUTING.md - Code style and PR process

Architecture

Main Components:

BLEInterface.py - High-level Reticulum interface logic
linux_bluetooth_driver.py - Linux platform driver (Bleak + bluezero)
bluetooth_driver.py - Abstract driver interface
BLEGATTServer.py - Peripheral mode GATT server
BLEFragmentation.py - MTU-based packet fragmentation/reassembly

Driver Abstraction: The interface uses a driver-based architecture to separate Reticulum protocol logic from platform-specific BLE implementations.

Current Status

Branch: refactor/abstraction-layer (driver abstraction complete, awaiting merge)

Technologies:

Bleak - BLE central operations
bluezero - GATT server (peripheral mode)
BlueZ 5.x - Linux Bluetooth stack

Development Workflow

Understanding the protocol: Read BLE_PROTOCOL_v2.2.md sequence diagrams
Making changes: Follow code patterns in existing driver implementations
Testing: See TESTING.md for test execution
Contributing: Follow guidelines in CONTRIBUTING.md

Key Files by Function

Discovery & Connection:

BLEInterface.py:_perform_discovery() - Peer discovery and scoring
BLEInterface.py:_connect_to_peer() - Connection establishment

Data Flow:

BLEFragmentation.py - Packet fragmentation/reassembly
BLEInterface.py:handle_*_data() - Data routing

Platform Integration:

linux_bluetooth_driver.py - BlueZ interaction
linux_bluetooth_driver.py:apply_bluez_*_patch() - Platform workarounds

Quick Debugging

Check documentation first:

Protocol issues → BLE_PROTOCOL_v2.2.md
Connection failures → BLE_PROTOCOL_v2.2.md § Troubleshooting
BlueZ quirks → BLE_PROTOCOL_v2.2.md § Platform-Specific Workarounds

Common issues are documented in the protocol spec with solutions.

Recent fixes:

Connection race conditions ("Operation already in progress") - Fixed in v2.2.1+ with connection state tracking and 5-second rate limiting (see BLE_PROTOCOL_v2.2.md § Platform-Specific Workarounds → Connection Race Condition Prevention)
BlueZ state corruption - Fixed in v2.2.2+ with explicit client disconnect on failures and BlueZ D-Bus device removal. Prevents persistent "InProgress" errors after connection timeouts/failures by cleaning up stale BlueZ device objects (see CHANGELOG.md)

3.5 KiB Raw Blame History