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>
Implements comprehensive connection state tracking to prevent "Operation
already in progress" errors and connection retry storms.
BLE Interface changes:
- Record connection attempts before calling driver.connect()
- Add 5-second rate limiting between attempts to same peer
- Skip connections already in progress via _connecting_peers check
- Downgrade expected race conditions to DEBUG level
- Auto-blacklist MAC addresses on connection failures
- Add diagnostic logging for concurrent connection tracking
BLE Driver changes:
- Add _connecting_peers set to track in-progress connections
- Prevent concurrent connection attempts to same address
- Attach cleanup callbacks to connection Futures
- Add defense-in-depth cleanup in finally blocks
- Detailed logging for connection state debugging
Documentation updates:
- Add deployment workflow documentation to README.md
- Update .github/workflows/README.md with CD workflow details
- Document containerized runner SSH configuration
- Update reference documentation (CLAUDE.md, BLE_PROTOCOL, etc.)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes "Failed to register advertisement" error (BlueZ error 0x03) caused by
device name exceeding 31-byte BLE advertisement packet limit.
Changes:
- Make device_name optional (default: None) to save advertisement space
- Remove auto-generation of long identity-based names (RNS-{32-hex-identity})
- Update driver to handle None device names when creating peripheral
- Use full 16-byte identity (32 hex chars) for fragmenter keys to avoid collisions
- Update documentation to reflect device name is optional and discovery is UUID-based
Discovery is based on service UUID matching only. Identity is obtained from
the Identity GATT characteristic after connection, not from device name.
Tested on Raspberry Pi Zero W with BlueZ 5.82 - advertisement now registers
successfully (ActiveInstances: 1).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
torlando-tech