Implement automatic device name generation from Transport.identity hash
to enable reliable peer discovery when bluezero service_uuid exposure
is unreliable.
Changes:
- Auto-generate device_name as RNS-{32-hex-identity} if not configured
- Parse peer identity from device name pattern (RNS-[0-9a-f]{32})
- Update GATT server device_name before advertising
- Store parsed identities in address_to_identity mapping
Limitations discovered:
- bluezero Peripheral uses system hostname for BLE local_name, not
the device_name parameter we set
- BlueZ D-Bus cache issues cause service_uuid exposure to be unreliable
- Reboot + cache clear (/var/lib/bluetooth/*/cache) temporarily fixes
service_uuid visibility
Current status:
- Bidirectional discovery works via service_uuid after fresh reboot
- Identity parsing infrastructure ready for future manufacturer_data approach
- Fallback to Protocol v1 address-based tracking remains functional
Tested on Raspberry Pi 4 with BlueZ 5.76, bluezero 0.9.1, bleak 1.1.1
Generated with Claude Code (https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enable BLE peripheral connections to send data by creating fragmenters
in handle_peripheral_data() after identity handshake. Previously,
fragmenters were only created for central connections (_connect_to_peer),
which caused "No fragmenter for peer" warnings when peripheral-only
connections attempted to transmit data.
This fix ensures bidirectional data flow works correctly regardless of
which device initiates the BLE connection, completing the unified
interface architecture.
Impact: Fixes announce rebroadcasting from peripheral-only connections
and enables full mesh networking over BLE.
Tested on Raspberry Pi 4 with BlueZ 5.76.
Generated with Claude Code (https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Critical fix for message delivery and Android MAC rotation support.
**Problem:**
- Fragmenters keyed by MAC address
- Failed with "dev:" prefix mismatch
- Would break on Android MAC rotation
**Solution:**
Use identity_hash for fragmenter/reassembler keys (with Protocol v1 MAC fallback).
**Changes:**
1. Added _get_fragmenter_key() helper - returns identity_hash or normalized MAC
2. Updated _connect_to_peer() - creates fragmenters with identity keys
3. Updated BLEPeerInterface.processOutgoing() - looks up fragmenters with identity keys
**Benefits:**
- ✅ Fixes immediate "No fragmenter" bug
- ✅ Survives Android MAC address rotation
- ✅ Consistent with unified interface architecture
- ✅ One fragmenter per peer identity (not per ephemeral MAC)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enhances BLE Protocol v2 handshake to include the central's identity (16 bytes)
instead of empty bytes. This enables the peripheral side to create identity-based
unified interfaces even without discovering the central via scanning.
**Problem Solved:**
- Peripheral couldn't create identity-based interface without scanning the central
- Resulted in separate "legacy" and identity-based interfaces for same peer
- Prevented true interface unification in asymmetric discovery scenarios
**Solution:**
1. Central sends its own identity (16 bytes) in handshake write
2. Peripheral detects identity handshake (16 bytes, first write)
3. Peripheral extracts identity and migrates interface from legacy to identity-based
4. Both sides now have identity-based interfaces that can unify!
**Changes:**
**_connect_to_peer() (line 1487):**
```python
# OLD: await client.write_gatt_char(RX_UUID, b'', response=True)
# NEW: Send our own identity in handshake
our_identity = self.gatt_server.identity_value if self.gatt_server else b'\x00' * 16
await client.write_gatt_char(RX_UUID, our_identity, response=True)
```
**handle_peripheral_data() (line 1792):**
```python
# Detect identity handshake (16 bytes, first write)
if len(data) == 16 and sender_address not in self.address_to_identity:
central_identity = bytes(data)
central_identity_hash = RNS.Identity.full_hash(central_identity)[:16].hex()[:16]
# Store identity mapping
self.address_to_identity[sender_address] = central_identity
self.identity_to_address[central_identity_hash] = sender_address
# Migrate interface from legacy to identity-based tracking
legacy_conn_id = f"{sender_address}-peripheral"
if legacy_conn_id in self.spawned_interfaces:
legacy_if = self.spawned_interfaces[legacy_conn_id]
del self.spawned_interfaces[legacy_conn_id]
legacy_if.peer_identity = central_identity
self.spawned_interfaces[central_identity_hash] = legacy_if
return # Don't process handshake as fragment data
```
**Flow:**
1. Pi1 connects to Pi2 as central
2. Pi1 reads Pi2's identity → creates identity-based interface
3. Pi1 sends handshake WITH Pi1's identity
4. Pi2 receives handshake, extracts Pi1's identity
5. Pi2 migrates interface to identity-based tracking
6. When Pi2 later discovers Pi1, adds central connection to SAME interface
7. Result: Both Pis have unified "central+peripheral" interfaces!
**Benefits:**
- ✅ Works with asymmetric discovery (only one side scans)
- ✅ Enables true unified interfaces in all scenarios
- ✅ Solves Android backgrounding (peripheral gets central's identity immediately)
- ✅ Faster interface unification (don't wait for bidirectional discovery)
**Backward Compatibility:**
- Protocol v1 devices send/receive empty handshake, work as before
- Handshake size detection (0 vs 16 bytes) determines protocol version
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major architectural improvement enabling one BLEPeerInterface to handle BOTH
central and peripheral connections for a given peer identity, eliminating
duplicate interfaces and fixing ACK routing issues.
**Key Changes:**
1. **BLEPeerInterface Dual-Connection Support:**
- Added has_central_connection/has_peripheral_connection flags
- Added add_central_connection() and add_peripheral_connection() methods
- Intelligent routing in processOutgoing() - prefers central, falls back to peripheral
- Graceful degradation when only one connection type exists
2. **Identity-Based Interface Tracking:**
- Changed spawned_interfaces key from address-based to identity_hash
- Added address_to_identity and identity_to_address mapping dicts
- Enables stable peer tracking despite MAC address rotation
3. **Unified Spawning Method:**
- Created _spawn_or_update_peer_interface() to replace old _spawn_peer_interface()
- Checks if interface exists, adds new connection type if so
- Creates new interface with first connection type otherwise
4. **Updated Connection Handlers:**
- handle_central_connected(): Uses unified interface spawning for peripheral connections
- handle_central_disconnected(): Removes peripheral connection, only detaches if no connections remain
- Disconnect callback in _connect_to_peer(): Removes central connection with graceful cleanup
5. **Updated Data Routing:**
- _handle_ble_data(): Routes by identity_hash instead of address-based conn_id
- handle_peripheral_data(): Routes by identity_hash with Protocol v1 fallback
**Benefits:**
- ✅ Fixes ACK routing issue (only 1 interface per peer instead of 2-4)
- ✅ Identity-based tracking immune to MAC rotation
- ✅ Path redundancy - can use both connections if available
- ✅ Android backgrounding ready - peripheral path survives when app can't scan
- ✅ Backward compatible with Protocol v1 devices
**Testing:**
- Pi-to-Pi bidirectional discovery
- Round-trip LXMF messaging with ACK verification
- Connection dynamics (loss/recovery)
Fixes ACK routing issue discovered in testing session 2025-10-31.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Sends empty WRITE to RX characteristic immediately after connection
to guarantee remote side's on_central_connected callback fires.
Problem: Peripheral callback triggered by WRITE events, not connections.
When central connects and only READs (Identity characteristic), the
peripheral's on_central_connected never fires, preventing peer interface
spawning on the peripheral side.
Solution: After reading Identity, write empty bytes to RX characteristic.
This triggers the WRITE callback which calls _handle_central_connected(),
ensuring bidirectional peer interface spawning.
Benefits:
- Works for Pi-to-Pi (ensures both sides spawn interfaces)
- Works for Android-to-Pi (Pi spawns interface when Android connects)
- Minimal overhead (single empty GATT write)
- Backwards compatible (empty write is harmless)
Implementation:
- Added after Identity read in _connect_to_peer()
- Uses write_gatt_char() with response=True for reliability
- Non-critical failure (logged as warning, doesn't block connection)
- TODO comment for future handshake protocol enhancements
This solves the asymmetric peer spawning issue seen in testing where
only the central side had a peer interface.
Tested: Enables bidirectional data flow for single-direction discoveries.
Removed calls to self.owner.tunnel(peer_if) which caused AttributeError.
Root cause: Transport class doesn't have a tunnel() method. The tunnel()
method was incorrectly assumed based on other interface patterns, but
direct peer interfaces (like I2PInterface) only use:
RNS.Transport.interfaces.append(peer_if)
No tunnel registration is needed for direct peer connections.
Changes:
- Removed tunnel() call from central connection spawn (~line 1607)
- Removed tunnel() call from peripheral connection spawn (~line 1778)
- Added explanatory comment about I2PInterface pattern
This fixes the AttributeError seen in Pi logs:
"failed to connect: AttributeError: type object 'Transport'
has no attribute 'tunnel'"
Peer interfaces still register correctly via RNS.Transport.interfaces[].
Tested: Interface spawning works, AttributeError eliminated.
Fixes critical discovery issues caused by BlueZ/Bleak limitations.
Root cause analysis (via nRF Connect + debug logging):
1. Bleak doesn't parse service UUIDs from advertisement data (service_uuids=[])
despite UUIDs being present (verified with nRF Connect showing correct UUID)
2. Name-based fallback works but RSSI -127 caused rejection
3. BlueZ hides connected/known devices from scan results
Changes:
- Added debug logging to detection_callback to diagnose Bleak data parsing
- Accept RSSI -127 as valid (BlueZ sentinel for "RSSI unknown")
- Confirmed name fallback pattern (RNS-*) works when service UUID fails
Test results:
- nRF Connect confirms correct UUID in advertisement: 37145b00-442d-4a94-917f-8f42c5da28e3
- Bleak sees device name "RNS-Pi1" but service_uuids=[]
- After bluetoothctl remove + RSSI fix: discovered via name pattern
- Asymmetric success: Pi 1→Pi 2 peer interface spawned, 72 bytes transmitted
Known issues:
- Bleak/BlueZ doesn't populate service_uuids from advertisement (Linux limitation)
- BlueZ auto-reconnects and hides devices from scans (requires bluetoothctl remove)
- Asymmetric discovery due to scan-hiding issue
Related: BLE_TEST_RESULTS_2025_10_31.md, BLE_DISCOVERY_TROUBLESHOOTING.md
Fixed discovery failure caused by GATT server advertising wrong service UUIDs.
Root cause: BLEGATTServer and BLEInterface were using placeholder/test UUIDs
(00000001-5824-4f48-9e1a-3b3e8f0c1234 etc.) instead of the Reticulum standard
UUID namespace (37145b00-442d-4a94-917f-8f42c5da28e*).
This caused Pis to advertise services that scanners couldn't recognize,
blocking all BLE discovery and connection attempts.
Changes:
- BLEGATTServer.py: Updated all 4 service/characteristic UUIDs
- BLEInterface.py: Updated all 4 service/characteristic UUIDs
Diagnosed using nRF Connect mobile app which showed wrong UUIDs being advertised.
Related: BLE_TEST_RESULTS_2025_10_31.md
Problem:
- BLEPeerInterface was spawning but never calling owner.tunnel(self)
- Result: 0 tunnel table entries, no data transmission
- Peer interfaces showed as "reachable" but Transport couldn't route through them
Solution:
- Added owner.tunnel(peer_if) call after interface creation
- Applied to both spawn locations (central and peripheral connections)
- Pattern matches Android implementation in android_ble_interface.py
Changes:
- Line 1599-1601: Added tunnel registration for central connections
- Line 1770-1772: Added tunnel registration for peripheral connections
Testing:
- Peer interfaces now appear in rnstatus output
- BLEPeerInterface[RNS-Pi2/central] visible and marked as "reachable"
- AttributeError logged during tunnel() but interface still spawns
- Further investigation needed for data transmission
References:
- BLE_DATA_ROUTING_ISSUE.md - Root cause analysis
- BLE_SESSION_2025_10_31_PROGRESS.md - Detailed session notes
- android_ble_interface.py:403 - Reference implementation
🤖 Generated with Claude Code (https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace timeout-based polling with cleaner event-driven approach using Interface.final_init() lifecycle hook. Launches background thread that waits indefinitely for Transport.identity (which is guaranteed to load), then starts GATT server with valid 16-byte identity value.
Benefits:
- No arbitrary timeout (Transport.identity WILL load, just timing varies)
- Uses proper Interface lifecycle hook (final_init)
- Non-blocking background thread
- GATT server guaranteed to have valid identity when it starts
- Cleaner separation of concerns
Same polling mechanism as I2PInterface, but better integrated with Interface lifecycle.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Move self.online = True BEFORE waiting for Transport.identity to break circular dependency. Reticulum loads Transport.identity only after interfaces are online, so blocking before self.online = True creates infinite wait.
New sequence:
1. Set self.online = True (unblocks Reticulum startup)
2. Reticulum loads Transport.identity from storage
3. Wait completes successfully
4. Identity set on GATT server
5. GATT server starts with valid 16-byte identity
Reduced timeout from 30s to 10s since identity should load within 1s once interface is online.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Change from async deferred loading to synchronous wait before GATT server startup. This ensures the Identity characteristic is created with a valid 16-byte value instead of empty [], preventing BlueZ from rejecting or corrupting the advertisement which caused "0 matching service UUID" discovery failures.
The bug: Identity characteristic was being created with value=[] because the GATT server thread started before Transport.identity was loaded from storage (~1s timing window). BlueZ may silently reject advertisements when validating GATT databases with empty READ characteristics.
The fix: Block interface startup for up to 30s waiting for Transport.identity (typically available within 0.5-1s), then set it on GATT server BEFORE starting the server thread. Identity characteristic now always has valid 16-byte value when registered with BlueZ.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Move Transport.identity extraction from synchronous startup to async background task. The identity is loaded from storage AFTER interface initialization, causing "Transport.identity not available yet" warning. Now polls for identity every 1s for up to 30s and sets it when available.
Fixes Protocol v2 identity characteristic serving on GATT server.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements BLE Protocol v2 with Transport identity GATT characteristic to solve Android MAC address rotation issues. Adds IDENTITY_CHAR_UUID (00000004-...) that serves the 16-byte RNS.Transport.identity.hash, enabling reliable bidirectional mesh connectivity with Android devices whose BLE MAC addresses rotate every ~15 minutes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add intelligent test selection to save CI minutes:
- Added 'detect-changes' job using paths-filter to determine what changed
- Unit/integration tests only run when Python source files change
- Installer tests only run when install.sh or test_installer.sh changes
This prevents running unnecessary tests:
- Changing install.sh won't trigger Python unit/integration tests
- Changing Python source won't trigger all 5 installer tests
- Workflow changes trigger installer tests (to verify CI changes)
Saves approximately 3-4 minutes of CI time per push when only one
category of files is changed.
Add path-based triggers to workflow to run tests only when relevant files
change. This saves CI resources on documentation-only or README changes
while maintaining broad coverage for code and configuration changes.
Tests now run when these files change:
- install.sh (installer script)
- src/** (all source code)
- tests/** (test files)
- .github/workflows/** (CI configuration)
- *.txt, *.toml, *.cfg (dependency/config files)
- *.py (Python files in root)
Tests skip when only these change:
- README.md, docs, examples
- Other markdown or documentation files
This is especially beneficial for ARM tests which take 5-10 minutes due
to QEMU emulation overhead.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
All installer test failures have been resolved. Re-enabling the full test
suite now that the install.sh script works correctly in Docker containers.
Installer tests are now passing on all platforms:
- debian:12 ✓
- debian:trixie ✓
- ubuntu:22.04 ✓
- ubuntu:24.04 ✓
- archlinux:latest ✓
Move system dependencies installation (Step 1) before Reticulum installation
(Step 2) to ensure libffi-dev is available when RNS installs its dependency
cryptography, which requires cffi compilation on armhf (32-bit ARM).
Root cause: RNS dependency chain (RNS -> cryptography -> cffi) triggered
cffi source compilation during pip install rns, before libffi-dev was
installed in the old Step 2.
New order:
1. Basic prerequisites (python3, pip, git)
2. System dependencies (including conditional libffi-dev for armhf)
3. Reticulum installation
4. Python dependencies (bleak, bluezero)
The libffi-dev package remains conditional for armhf only - x86_64 and
arm64 have pre-built cffi wheels and don't need compilation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add debug output to show:
- Detected architecture value from dpkg
- Whether armhf condition is matched
- Final package list being installed
This will help diagnose why libffi-dev isn't being installed on armhf
systems in the CI environment.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Only install libffi-dev on armhf (32-bit ARM) systems where cffi needs
to compile from source. x86_64 and arm64 have pre-built cffi wheels
available, so they don't need the development headers.
Changes:
- install.sh: Detect architecture and conditionally add libffi-dev for armhf
- test_installer.sh: Show libffi-dev in output only for armhf systems
- test.yml: Update ARM CI summary to reflect conditional dependency
This reduces unnecessary dependencies on x86_64 and arm64 systems while
maintaining full compatibility with 32-bit Raspberry Pi devices.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add libffi-dev to system dependencies for Debian/Ubuntu/Raspberry Pi OS
to provide FFI headers needed when cffi compiles from source on ARM
platforms. This fixes ARM 32-bit and 64-bit installation failures.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add QEMU-based ARM testing for both armhf (32-bit) and arm64 (64-bit)
architectures to validate installer on Raspberry Pi OS Lite. Tests run
only on PRs to main branch to conserve CI resources while ensuring
compatibility with ARM platforms before merge.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The systemctl commands (daemon-reload, restart bluetooth) were causing CI
failures in Docker containers where systemd is not running as PID 1.
Changes:
- Added '|| true' and '2>/dev/null' to systemctl commands to make them non-fatal
- Updated verification logic to detect container environments (/.dockerenv)
- Added appropriate messages for container environments
- Systemd override file is still created, but service restart is skipped
This allows the installer to complete successfully in containers while still
properly configuring BlueZ experimental mode on real systems with systemd.
The test script was failing because it changed directories during execution
(to /tmp/test-config/interfaces) and then tried to use a relative path
to navigate back to the repo root, which failed.
Fix: Save the absolute path to repo root at the beginning and reuse it
when needed instead of calculating it relative to the current directory.
Fixes the error: 'cd: tests/..: No such file or directory'
Disabling unit and integration test jobs to save GitHub Actions minutes
while troubleshooting installer test failures in Docker containers.
This reduces CI runtime from ~4-5 minutes to ~1 minute per run.
To re-enable: remove the 'if: false' lines from unit-tests and
integration-tests jobs in .github/workflows/test.yml
The setcap command was causing "Operation not permitted" errors when trying
to run Python in Docker containers after capabilities were applied. This is
because setcap can cause security restrictions that are incompatible with
container environments.
Root users don't need capabilities anyway - they already have full permissions
to access Bluetooth hardware. This change:
- Detects when running as root (EUID == 0)
- Skips the entire setcap process for root users
- Adds informative messages explaining why it's being skipped
- Simplifies the code by removing nested root checks
This allows the installer tests to pass in CI while still properly granting
capabilities for non-root users on real systems.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The bluetoothctl command was causing CI failures with abort signal (exit 134)
in Docker containers where D-Bus is not running or Bluetooth hardware is not
available. This is expected behavior in container/CI environments.
Changes:
- Added `|| true` to bluetoothctl power on command to prevent script failure
- Added `2>/dev/null` to bluetoothctl show commands to suppress D-Bus errors
- Added clarifying comment about container/CI environment behavior
This allows the installer to complete successfully in CI while still attempting
to configure Bluetooth on real systems where the hardware is available.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The installer was failing in CI Docker containers with "sudo: command
not found" because Docker containers run as root and don't have sudo
installed. Added root detection (checking $EUID) before setcap and
rfkill commands, following the same pattern used elsewhere in the script.
This allows the installer to work correctly in both scenarios:
- User systems: Uses sudo when needed (non-root users)
- Docker/CI containers: Runs commands directly as root (no sudo required)
Fixes the CI failure at install.sh:458 where setcap was unconditionally
using sudo, and prevents future failures at the rfkill command.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Automatically detect and unblock soft-blocked Bluetooth adapters during
installation, preventing "Failed to set power on" errors on Raspberry Pi
and other systems where rfkill may block the adapter by default.
Changes:
- Add rfkill soft-block detection in install.sh Step 5B
- Automatically run 'sudo rfkill unblock bluetooth' when needed
- Verify unblock succeeded before attempting power-on
- Provide clear feedback during unblock process
Fixes the root cause of power-on failures when adapter is soft-blocked,
which was discovered during testing on Raspberry Pi Zero 2 W.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Addresses the common "Not Powered" error where Bluetooth adapters are
powered off, preventing BLE operations. This issue is particularly common
on Raspberry Pi after boot or system updates.
Changes:
1. README.md - Added comprehensive troubleshooting section
- New section: "Bluetooth adapter not powered"
- Documented symptoms, causes, and 4 solution methods
- Instructions for automatic power-on at boot
- Cross-referenced from other sections
2. BLEInterface.py - Enhanced error handling in _discover_peers()
- Detect "Not Powered" errors specifically
- Show clear, actionable error messages instead of stack traces
- Provide direct solution commands
- Link to troubleshooting documentation
- Gracefully handle error without crashing
3. install.sh - Automatic power state checking
- New "Step 5B: Bluetooth Adapter Power State" section
- Check if adapter is powered using `bluetoothctl show`
- Automatically power on adapter if needed
- Verify operation succeeded
- Provide troubleshooting steps if power-on fails
- Check for rfkill blocks
4. examples/bluetooth-power-on.service - New systemd service
- Ensures Bluetooth is powered on at boot
- Optional but recommended for production
- Includes installation instructions in README
5. examples/config_example.toml - Added troubleshooting entry #7
- Documents power state issue in config comments
- Cross-references systemd service example
- Notes that installer (v1.x+) handles this automatically
Impact:
- Users get clear guidance instead of cryptic stack traces
- Installer automatically fixes the issue during setup
- Reduces support burden for common power state errors
- Enables automatic recovery at boot via systemd service
Fixes: "Not Powered" / "No powered Bluetooth adapters found" errors
Tested on: Raspberry Pi Zero 2 W with Raspberry Pi OS Lite 64-bit
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The fancy box border (┌─┐│└┘) around the configuration example made it
difficult to copy-paste into the config file. Users had to manually remove
the vertical line characters from each line.
Changes:
- Removed box border characters (┌, ─, ┐, │, └, ┘)
- Kept the same indentation and formatting
- Added "(copy-paste ready)" note to clarify it can be directly pasted
- Maintains visual structure with proper spacing
The configuration example is now directly copy-pasteable into the Reticulum
config file without any manual editing required.
Before:
┌─────────────────────────────────────────┐
│ [[BLE Interface]] │
│ type = BLEInterface │
...
After:
[[BLE Interface]]
type = BLEInterface
enabled = yes
...
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
When pip installs RNS to ~/.local/bin (user-local installation), the rnsd
command is not immediately available because ~/.local/bin is not in PATH.
This required users to manually add it to their .bashrc.
Changes:
- Automatically add ~/.local/bin to PATH in .bashrc after RNS user installation
- Check if .local/bin is already in .bashrc before adding (avoid duplicates)
- Show clear message about reloading shell: "source ~/.bashrc"
- Update final "Next steps" to conditionally show PATH setup
- Only show manual PATH instructions if auto-add didn't happen
This makes installation fully automated - users can run rnsd immediately
after reloading their shell, without manual PATH configuration.
User experience:
✓ Reticulum installed successfully (user installation)
ℹ rnsd location: /home/user/.local/bin/rnsd
ℹ Adding ~/.local/bin to PATH in ~/.bashrc...
✓ Added ~/.local/bin to PATH in ~/.bashrc
⚠ Reload your shell to use rnsd command:
source ~/.bashrc
# Or open a new terminal
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The setcap command fails on symlinks with "Invalid file 'setcap' for capability operation".
On many systems (including Raspberry Pi OS), /usr/bin/python3 is a symlink to the versioned
binary (e.g., /usr/bin/python3.13). The interactive prompt also required manual intervention
during installation.
Changes:
- Automatically grant Bluetooth permissions (removed y/N prompt)
- Detect if python3 is a symlink and resolve to actual binary using readlink -f
- Verify resolved path is valid before applying setcap
- Use getcap to verify capabilities were actually set
- Added --skip-bt-permissions flag for users who want to skip this step
- Improved error messages with specific troubleshooting steps
- Show detected and resolved Python paths for transparency
This makes installation fully automated while handling the symlink issue that was
causing setcap failures on Raspberry Pi OS and other Debian-based systems.
Fixes: "Invalid file 'setcap' for capability operation" error
Tested on: Raspberry Pi Zero 2 W with Raspberry Pi OS Lite 64-bit (Debian Trixie)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The setcap command (used to grant Bluetooth capabilities to Python)
requires the libcap2-bin package on Debian/Ubuntu or libcap on Arch.
Fresh Raspberry Pi OS Lite installations don't include this by default,
causing "Invalid file 'setcap' for capability operation" errors.
Changes:
- Added libcap2-bin to Debian/Ubuntu/Raspberry Pi OS dependencies
- Added libcap to Arch Linux dependencies
- Added setcap availability check before Bluetooth permissions step
- Auto-install libcap2-bin/libcap if setcap is not found
- Improved error handling with clear error messages
- Verify setcap command succeeded before showing success
This ensures setcap is available before attempting to grant capabilities,
preventing installation failures on minimal OS installations.
Fixes error encountered on: Raspberry Pi Zero 2 W with Raspberry Pi OS Lite 64-bit
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
When pip installs RNS to ~/.local/bin (user installation), the rnsd
command is not immediately available in PATH, causing the installer
to incorrectly report "Reticulum installation failed" even though
installation succeeded.
Changes:
- Add ~/.local/bin to PATH at the start of Reticulum check
- Add ~/.local/bin to PATH after pip install rns
- Check multiple locations for rnsd command:
1. In PATH (command -v rnsd)
2. In ~/.local/bin directly
3. As Python package (python3 -c "import RNS")
- Make rnsd executable if found in ~/.local/bin
- Add PATH configuration instructions in final setup steps
- Dynamic step numbering based on whether PATH note is needed
This fixes false installation failures on Raspberry Pi OS and other
systems where pip defaults to user-local installation.
Tested on: Raspberry Pi Zero 2 W with Raspberry Pi OS Lite 64-bit
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#3
BlueZ experimental mode is required for proper BLE connectivity. Without it,
BlueZ attempts Classic Bluetooth (BR/EDR) connections instead of BLE (LE)
connections, causing connection errors like "br-connection-profile-unavailable"
and immediate disconnections after pairing.
Changes:
- install.sh: Automatically enables BlueZ experimental mode during installation
- Detects BlueZ version (requires >= 5.49)
- Creates systemd override to add -E flag to bluetoothd
- Checks if already enabled to avoid duplicate configuration
- Shows strong warning if user skips with --skip-experimental flag
- Added --skip-experimental flag to opt-out (not recommended)
- Updated help text to document new flag
- tests/test_installer.sh: Added tests for experimental mode configuration
- README.md: Documented BlueZ experimental mode in installation sections
- Added to automated installation description
- Added as required step in manual installation
- Added troubleshooting section for BR/EDR connection errors
- examples/config_example.toml: Added troubleshooting entry for BR/EDR errors
The installer now:
1. Detects BlueZ version >= 5.49 (required for experimental mode)
2. Checks if already enabled (graceful skip)
3. Enables experimental mode by default unless --skip-experimental is used
4. Shows prominent warning if skipped (may cause BLE to break)
5. Handles edge cases (no systemd, old BlueZ, container environments)
This addresses the root cause reported in issue #3 where devices were
connecting then immediately disconnecting with BR/EDR profile errors.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
PyGObject compilation on Arch requires gobject-introspection package
which provides the development files and .pc files needed by meson.
Error was: Dependency 'gobject-introspection-1.0' is required but not found.
Changes:
- install.sh: Add gobject-introspection to Arch system dependencies
- install.sh: Add comment explaining it's needed for PyGObject compilation
- README.md: Document gobject-introspection requirement for Arch
This completes the Arch Linux dependency chain for PyGObject compilation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
