jlpoole/ble-reticulum
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
ble-reticulum/CLAUDE.md
torlando-tech 12ff03d2fa fix(ble): Add connection race condition prevention and improve error handling 
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>
2025-11-07 22:32:00 -05:00

3.3 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

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

  1. Understanding the protocol: Read BLE_PROTOCOL_v2.2.md sequence diagrams
  2. Making changes: Follow code patterns in existing driver implementations
  3. Testing: See TESTING.md for test execution
  4. 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)