torlando-tech 971f9e47bb docs: Add CLAUDE.md reference guide for AI assistants

- Quick project overview and architecture summary
- Links to key documentation (BLE_PROTOCOL_v2.2.md, README, etc.)
- Development workflow guidance
- File-by-function quick reference

Helps AI assistants quickly orient to the project without duplicating
existing documentation.

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

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

2025-11-05 22:49:14 -05:00

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

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.

3 KiB Raw Blame History