When a peer reconnects from a new MAC address (common with Android MAC
rotation, also possible on Linux after adapter reset), the old interface
state may become stale. This change adds:
1. _cleanup_stale_interface() method:
- Detaches old interface
- Cleans up identity mappings
- Removes fragmenter/reassembler for old address
- Clears pending MTU for old address
2. MAC rotation detection in _select_peers_to_connect():
- If interface exists for identity but old address is not in peers
(connection dead), clean up stale state and allow reconnection
- If old connection still active, skip as before (no change)
This is defensive code that handles edge cases like:
- Android MAC rotation (~15 min intervals)
- Linux adapter reset while peer state is tracked
- Connection timeout without proper disconnect callback
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Two critical fixes ported from Android testing:
1. HW_MTU instance attribute fix:
- Base Interface.__init__() sets self.HW_MTU = None
- BLEInterface.HW_MTU = 500 is a CLASS attribute, not instance
- After super().__init__(), self.HW_MTU is None (instance shadows class)
- BLEPeerInterface copies: self.HW_MTU = parent.HW_MTU (gets None)
- When HW_MTU is None, Transport.py truncates packet.data incorrectly
- Result: Link establishment fails with mismatched link_id
- Fix: Explicitly set self.HW_MTU = BLEInterface.HW_MTU after super().__init__()
2. MTU/identity race condition fix:
- MTU negotiation can complete before identity is received
- Previously: Warning logged, fragmenter not created
- Now: Store pending MTU, create fragmenter when identity arrives
- Adds pending_mtu dict to track deferred MTU values
- _device_connected_callback checks for pending MTU after storing identity
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update CHANGELOG.md with release notes for v0.2.2
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Removed .github/workflows/deploy.yaml which was a byte-for-byte duplicate
of deploy.yml. Both workflows were executing independently, causing:
- Duplicate deployments to Raspberry Pi devices
- Potential race conditions from concurrent SSH sessions
- Unnecessary resource usage
Kept deploy.yml as it uses the more standard extension in the GitHub
Actions ecosystem.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enhances the installation script to automatically detect and handle
pipx installations of RNS, eliminating the need for manual dependency
injection in most cases.
Changes to install.sh:
- Add pipx detection logic that checks for RNS in pipx paths
- Verify pipx command availability and RNS listing
- Install build dependencies (build-essential, python3-dev, libdbus-dev)
for Debian/Ubuntu and (base-devel, gobject-introspection) for Arch
- Implement automated pipx inject for all BLE dependencies
(bleak, bluezero, dbus-python)
- Add progress messages for long-running dbus-python compilation
- Verify all dependencies after injection
- Use correct Python executable for setcap based on install mode
Changes to README.md:
- Update Option A description to mention pipx detection
- Add note to Option C that install.sh now handles pipx automatically
- Keep manual instructions for troubleshooting/fallback
Benefits:
- Consistent "one-command installation" experience for all users
- Reduces user errors from manual pipx injection
- Provides clear error messages with recovery instructions
- Maintains manual documentation as fallback
Related to #11🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#11
When RNS is installed via pipx, the BLE interface cannot access
system-installed packages like python-dbus due to pipx's isolated
virtual environments. This commit adds comprehensive documentation
for pipx users.
Changes:
- Add new "Option C: pipx Installation" section with step-by-step
instructions for installing BLE dependencies via pipx inject
- Include system dependency installation for both Arch and Debian/Ubuntu
- Document how to find and grant capabilities to pipx Python executable
- Add BlueZ experimental mode configuration steps
- Explain why pipx requires special handling
- Add troubleshooting entry for ModuleNotFoundError issues with pipx
The documented solution uses `pipx inject rns bleak==1.1.1 bluezero dbus-python`
to install BLE dependencies into the isolated RNS environment.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes integration test failures where TestRealWorldScenario tests
couldn't access the mock_driver fixture.
The mock_driver fixture was defined inside TestPeripheralDisconnectCleanup
class, making it unavailable to TestRealWorldScenario class. This caused
pytest fixture lookup errors:
- test_both_monitoring_mechanisms_detect_disconnect_idempotent
- test_polling_catches_missed_dbus_signal
Solution: Move mock_driver to module level (outside class) so all test
classes can access it as a shared fixture.
All integration tests now pass locally.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes installer failures in container environments due to missing sudo command.
The BlueZ LE-only mode configuration section was attempting to modify
/etc/bluetooth/main.conf using sudo, even in container environments where:
1. Bluetooth hardware is not available
2. sudo is often not installed (containers run as root)
3. BlueZ configuration is not applicable
Now detects container environments using is_container() and skips the
LE-only mode configuration entirely, consistent with the Bluetooth
adapter power state checks.
This prevents "sudo: command not found" errors in Debian/Ubuntu CI containers.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes three CI failures identified in workflow run #19395416465:
1. **Missing threading import** (test_peripheral_disconnect_cleanup.py)
- Added missing `import threading` to fix NameError during test setup
- Tests use threading.RLock() but import was missing
2. **Timing race condition** (test_stale_connection_polling.py)
- Increased sleep from 0.15s to 1.5s in test_polling_interval_30_seconds
- Test expects 2 polling cycles at 0.6s each, was timing out in CI
3. **Container-aware Bluetooth checks** (install.sh)
- Added is_container() helper to detect Docker/container environments
- Skip Bluetooth adapter power checks in containers (no hardware access)
- Prevents false failures from bluetoothctl crashes in CI environments
All changes are test/installer infrastructure only - no production code changes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This workflow automates the deployment of code to multiple Raspberry Pi devices and validates the BLE interface after deployment. It includes setup, deployment, validation, and summary steps.
Filter BLE scanner to only detect devices advertising the Reticulum service
UUID, reducing noise from non-Reticulum BLE devices and improving scan efficiency.
Changes:
- Pass service_uuids parameter to BleakScanner initialization
- Only detects devices with our service UUID (37145b00-442d-4a94-917f-8f42c5da28e3)
- Reduces callback invocations for irrelevant BLE devices
Benefits:
- More efficient scanning (fewer devices to process)
- Less CPU usage processing non-Reticulum devices
- Faster peer discovery
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add filtering for Android Columba's 15-second keepalive packets to prevent
unnecessary processing. Keepalive packets are 1 byte (0x00) and should be
ignored by the BLE interface.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix stale connection issue where identity mappings persist after disconnect,
preventing automatic reconnection when peer returns with different MAC address.
ROOT CAUSE:
- _device_disconnected_callback() cleaned up spawned_interfaces but NOT:
- address_to_identity mapping
- identity_to_address mapping
- handle_central_disconnected() had same issue
- Result: Laptop thinks it's still connected after Android restarts
- Manual rnsd restart required to clear stale state
THE FIX (TDD Approach):
1. RED: Wrote 5 tests demonstrating the bug (all FAILED initially)
2. GREEN: Added identity mapping cleanup to both disconnect methods
3. GREEN: All 5 tests now PASS
Changes:
- BLEInterface.py _device_disconnected_callback():
- Added del address_to_identity[address]
- Added del identity_to_address[identity_hash]
- BLEInterface.py handle_central_disconnected():
- Added del address_to_identity[address]
- Added del identity_to_address[identity_hash]
- linux_bluetooth_driver.py:
- Added RNS warning handler for better logging
- tests/test_identity_mapping_cleanup.py (NEW):
- 5 tests verifying identity mapping cleanup
- Tests both central and peripheral disconnect modes
- Reproduces real-world stale connection scenario
- Verifies automatic reconnection after fix
Test Results:
✅ All 5 tests PASS after fix
✅ Mappings properly cleaned up on disconnect
✅ Automatic reconnection enabled
Impact:
- No more manual rnsd restart needed
- Android MAC rotation handled correctly
- Stale connections automatically cleaned up
- Reconnection works without intervention
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The original D-Bus monitoring implementation (from peripheral disconnect fix)
wasn't receiving signals due to improper low-level API usage. This commit
replaces it with two reliable solutions:
Solution A: High-Level ObjectManager API
- Uses proper D-Bus proxy interface with automatic signal subscription
- Discovers and subscribes to all BlueZ devices (existing + new)
- PropertiesChanged callbacks properly integrated with asyncio event loop
- Signals now correctly delivered when centrals disconnect
Solution B: Timeout-Based Polling Fallback
- Polls BlueZ device state every 30 seconds as safety net
- Detects stale connections missed by D-Bus signals
- Uses sync dbus-python for simplicity and reliability
- Guaranteed cleanup within 30s even if signals fail
Implementation:
- Replaced _monitor_device_disconnections() with ObjectManager-based approach
- Added _poll_stale_connections() as polling fallback
- Both threads run concurrently for dual-layer monitoring
- Cleanup is idempotent (both detecting same disconnect is safe)
Testing:
- Added test_dbus_disconnect_monitoring.py (10 test cases)
- Added test_stale_connection_polling.py (8 test cases)
- Added 2 integration tests to test_peripheral_disconnect_cleanup.py
- All tests mock D-Bus libraries, no real D-Bus required
- Manual validation script (test_monitoring.py) verified locally
Impact:
- Peripheral disconnects now detected within ~1s (D-Bus) or 30s max (polling)
- Prevents "max peers (7) reached" blocking after multiple disconnect cycles
- System can handle unlimited connect/disconnect cycles without memory leaks
Reference: DBUS_MONITORING_FIX.md for complete analysis and troubleshooting
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes a critical bug where Android devices (acting as BLE centrals) disconnecting
from Pi GATT servers (acting as peripherals) never triggered cleanup, causing stale
peer entries to accumulate until the 7-peer limit was reached and blocked all new
connections.
## Root Cause
- When centrals disconnected from peripheral mode, no cleanup occurred
- `BLEGATTServer._handle_central_disconnected()` method didn't exist
- `on_central_disconnected` callback was never wired to driver
- No D-Bus signal monitoring for device disconnections
- Stale entries remained in `_peers` dict until daemon restart
## Implementation (TDD Approach)
**New Methods:**
- `LinuxBluetoothDriver._handle_peripheral_disconnected()` (line 852)
- Removes peer from `_peers` dictionary
- Notifies on_device_disconnected callback
- Triggers full cleanup chain in BLEInterface
- `BluezeroGATTServer._handle_central_disconnected()` (line 1945)
- Removes from `connected_centrals` dictionary
- Logs connection duration
- Invokes driver callback
- `BluezeroGATTServer._monitor_device_disconnections()` (line 1645)
- Monitors D-Bus PropertiesChanged signals
- Detects when Connected property becomes False
- Runs in separate daemon thread
- Automatically triggers cleanup on disconnect
**Callback Wiring:** (line 1558)
`on_central_disconnected = driver._handle_peripheral_disconnected`
## Testing
- Created comprehensive test suite (9 tests, all passing)
- `tests/test_peripheral_disconnect_cleanup.py`:
- Callback wiring verification
- Peer dictionary cleanup
- D-Bus signal handling simulation
- Edge cases (multiple disconnects, race conditions, shutdown)
- Reproduces real-world bug from production logs
- No regressions in existing tests (test_bluez_state_cleanup.py passes)
## Current Status
✅ Core cleanup logic implemented and tested
✅ Deployed to 4 production devices (10.0.0.80, .242, .39, .246)
⚠️ D-Bus monitoring thread needs debugging (not logging yet)
**Known Issue:** D-Bus signal subscription may need alternative approach.
See PERIPHERAL_DISCONNECT_FIX_SUMMARY.md for troubleshooting steps.
**Fallback Option:** Timeout-based polling can be implemented if D-Bus proves difficult.
Reference: Production logs showed device 4A:87:8C:C7:E3:F3 repeatedly blocked
by "max peers (7) reached" due to uncleaned peripheral disconnections.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes false validation failures when "interface online" message scrolls
out of view due to verbose BLE startup logging (100+ lines in first minute).
Changes:
- Clear logfile before starting rnsd (new step 7/8)
- Separate stop and start into distinct steps for cleaner restart
- Validate from first 200 lines (head) instead of last 100 (tail)
- Rename RECENT_LOGS to STARTUP_LOGS for clarity
This ensures "interface online" is always in the validation window
regardless of time delay between deployment and validation jobs.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Detect when Bluetooth/BlueZ/D-Bus enters corrupted state where scanner
starts successfully but callbacks are never invoked. This manifests as
Bleak working in standalone scripts but failing within RNS's async context.
Detection mechanism:
- Track callback invocations during each scan cycle
- Count consecutive scans with 0 callbacks
- Log WARNING after first empty scan
- Log CRITICAL ERROR after 3 consecutive empty scans
- Invoke on_error callback with "reboot required" message
- Reset counter when callbacks resume
This provides clear diagnostics instead of silent failure, allowing users
to identify the issue and take corrective action (system reboot).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Prevent invalid RSSI values (-127, -128, 0) from causing connection issues
by filtering them at three stages: scanner detection, discovery handler, and
peer scoring. These sentinel values indicate Bleak cache/state issues rather
than actual signal strength.
Add comprehensive debug logging to scanner lifecycle for troubleshooting:
- Callback invocations with device details
- Scanner start/stop/duration events
- Filtering stages (UUID matching, RSSI thresholds)
- Device discovery counts
Logging uses INFO level (via "EXTRA" fallback) for visibility without
requiring DEBUG log level configuration.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Adds Step 5C to install.sh to automatically configure BlueZ for
LE-only mode by setting ControllerMode=le in /etc/bluetooth/main.conf.
This prevents "br-connection-profile-unavailable" errors on dual-mode
Bluetooth hardware (e.g., Raspberry Pi Zero 2 W with BCM43430).
Fixes issue where dual-mode adapters advertise as "CLASSIC and LE"
without the "BR\EDR Not Supported" BLE flag, causing connection
failures from BLE-only devices.
The configuration step:
- Checks prerequisites (bluetoothctl, main.conf exists)
- Is idempotent (detects existing configuration)
- Creates timestamped backup before modification
- Handles commented/existing ControllerMode settings
- Adds [General] section if missing
- Restarts BlueZ service to apply changes
- Verifies configuration was applied
Generated with Claude Code https://claude.com/claude-code
Co-Authored-By: Claude <noreply@anthropic.com>
Fixed race condition where started_event fires before peripheral.publish()
fully exports GATT services to D-Bus, causing "Reticulum service not found"
errors when central devices connect immediately after server startup.
Root cause:
- started_event.set() called on line 1665
- peripheral_obj.publish() called on line 1669 (exports to D-Bus)
- 50-200ms gap where server thinks it's ready but services aren't on D-Bus yet
- Central connects during gap -> "service not found" error
Fix:
- Added _verify_services_on_dbus() method to poll D-Bus adapter introspection
- Polls every 200ms with 5-second timeout after started_event fires
- Only returns from start() after confirming services are exported
- Graceful degradation: warns on timeout but doesn't fail startup
Impact:
- Eliminates "service not found" errors during server startup
- Ensures services are actually available before accepting connections
- Typical verification time: 100-300ms
- No runtime performance impact (only affects startup)
Files changed:
- src/RNS/Interfaces/linux_bluetooth_driver.py: Add D-Bus polling
- tests/test_gatt_server_readiness.py: Add test coverage
- BLE_PROTOCOL_v2.2.md: Document initialization race fix
- CHANGELOG.md: Record fix details
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
ConnectDevice() D-Bus method returns an object path (signature 'o') which
should be treated as success, not error. Previously, the return value was
not captured or logged, causing confusion when error messages like
"br-connection-profile-unavailable" appeared (which is expected for LE-only
connections).
Changes:
- Capture object path returned by call_connect_device()
- Log object path for debugging visibility
- Document that object path indicates successful LE connection initiation
- Clarify that BR/EDR profile unavailable is expected for BLE-only connections
Impact:
- Eliminates confusion from "profile unavailable" error messages
- Confirms LE connection was successfully initiated
- Improved debugging visibility through object path logging
Files changed:
- src/RNS/Interfaces/linux_bluetooth_driver.py: Capture and log object path
- tests/test_breddr_fallback_prevention.py: Add test coverage
- BLE_PROTOCOL_v2.2.md: Document object path behavior
- CHANGELOG.md: Record fix details
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Remove inaccurate release dates from unreleased versions.
Only v0.1.1 has an actual release date (2025-11-10).
Changes:
- [0.1.0]: Never released, marked as Unreleased
- [2.2.0]: Not yet released, marked as Unreleased
- [2.1.0]: Not yet released, marked as Unreleased
- [0.1.1]: Keep actual release date (2025-11-10)
Dates will be added when versions are actually released.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Resolve merge conflicts by:
- Keeping version 0.2.2 from refactor branch (next release)
- Using fixed gh CLI release workflow from main (atomic release creation)
- Merging CHANGELOG histories: installer releases (0.1.x) and protocol work (2.x)
Conflicts resolved:
- .github/workflows/release.yml: Use gh CLI for atomic releases
- CHANGELOG.md: Merged both release histories chronologically
- pyproject.toml: Keep 0.2.2 for next refactor release
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Bump version to test fixed release workflow with atomic release creation.
Changes:
- Update pyproject.toml version from 0.1.0 to 0.1.1
- Add CHANGELOG entry documenting release workflow fix
This allows testing the corrected workflow (gh release create) without
being blocked by v0.1.0 tag recreation restrictions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace softprops/action-gh-release with gh CLI to create releases
and upload assets in a single atomic operation. This prevents issues
with repository rules that make releases immutable immediately,
which was causing asset upload failures.
Previous error:
- Release created successfully but became immutable
- Asset upload failed with "Cannot upload assets to an immutable release"
Solution:
- gh release create uploads all assets in one operation
- Avoids the gap between release creation and asset upload
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add Python packaging and automated release workflow to enable
versioned releases of the BLE interface.
Changes:
- Add pyproject.toml with package metadata and dependencies
- Add GitHub Actions release workflow with validation and artifact generation
- Add CHANGELOG.md documenting v0.1.0 installation system features
The release workflow validates version consistency, runs tests,
generates release artifacts (installer, config, source tarball),
and creates GitHub releases automatically from git tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
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>
The validation script checks ~/.reticulum/logfile for BLE interface
status, but this file is only created when rnsd is started with the
-s (service/syslog) flag.
Without -s flag:
- rnsd runs but doesn't write to ~/.reticulum/logfile
- Validation script fails: "Log file not found"
- Deployment appears successful but validation always fails
With -s flag:
- rnsd writes logs to ~/.reticulum/logfile
- Validation can check for "interface online" message
- Full deployment + validation cycle works
Note: Only affects manual rnsd startup (non-systemd path). Systemd
installations should have -s configured in the service file.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enable subclassing BLEInterface with custom platform-specific drivers by
introducing a class-level driver_class attribute that can be overridden.
Changes:
- Import LinuxBluetoothDriver optionally with HAS_LINUX_DRIVER flag
- Add driver_class class attribute (defaults to LinuxBluetoothDriver)
- Check driver_class is not None before instantiation
- Use self.driver_class() instead of hardcoded LinuxBluetoothDriver()
- Log which driver is being used at initialization
This pattern enables platform-specific implementations like:
class AndroidBLEInterface(BLEInterface):
driver_class = AndroidBLEDriver
Without this pattern, subclasses would need to override __init__ entirely
to use a different driver, duplicating all initialization logic.
Implementation details:
- LinuxBluetoothDriver import wrapped in try/except with fallback to None
- Raises ImportError if driver_class is None and no override provided
- Maintains backward compatibility (LinuxBluetoothDriver used by default)
- All production features preserved (logging redirect, blacklist, rate
limiting, service UUID filtering, connection management)
Use case:
This pattern is used by the Columba Android app to integrate the Android
BLE stack via Chaquopy, overriding driver_class with AndroidBLEDriver
that bridges to Kotlin BLE APIs.
Testing:
- Default behavior unchanged (uses LinuxBluetoothDriver)
- Subclass override tested in columba/python/android_ble_interface.py
- No functional changes to existing BLE interface behavior
Completely refactored the deployment workflow to create separate
GitHub Actions nodes for each Pi, with independent deploy and
validation steps. This provides much better visibility and control.
New Architecture:
1. **setup** job: Parses PI_HOSTS into JSON matrix
2. **deploy** job: Matrix execution (one instance per Pi)
3. **validate** job: Matrix execution (one instance per Pi)
4. **summary** job: Aggregate results
GitHub Actions Graph View (2 Pis):
```
setup ━┳━> deploy-pi-0 ━> validate-pi-0
┗━> deploy-pi-1 ━> validate-pi-1
```
Features:
- **Parallel execution**: All Pis deploy simultaneously
- **Independent nodes**: Each Pi has its own deploy + validate node
- **fail-fast: false**: One Pi failure doesn't block others
- **Per-Pi logs**: Clean, isolated logs for each device
- **Comprehensive validation**:
* Wait 5s for startup
* Check rnsd process
* Verify BLE interface online (retry 3x with 3s delay)
* Check Bluetooth adapter powered
* Display adapter MAC address
- **Better error reporting**: Shows which specific Pi failed
- **Granular status**: See each Pi's status independently
Validation Checks:
✓ rnsd process running
✓ Log file exists
✓ No critical errors in logs
✓ "interface online" message found
✓ Bluetooth adapter powered
✓ Retry logic for startup delays
Benefits:
- Easier to identify which Pi has issues
- Can re-run individual Pi jobs
- Faster deployment (parallel vs sequential)
- Clearer progression in GitHub UI
- Each Pi's logs are isolated and clean
Example UI with failure:
```
setup ✓
├─ deploy-pi-0 ✓
│ └─ validate-pi-0 ✗ (BLE failed to start)
└─ deploy-pi-1 ✓
└─ validate-pi-1 ✓ (BLE online)
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The deploy workflow was failing to start rnsd because the SSH session's
PATH doesn't include ~/.local/bin where rnsd is installed.
Issue:
- rnsd installed at ~/.local/bin/rnsd (pip install --user)
- Non-interactive SSH session doesn't have ~/.local/bin in PATH
- Command "nohup rnsd" failed: "command not found"
- Deployment reported "Failed to start rnsd"
Fix:
- Define RNSD_BIN="$HOME/.local/bin/rnsd"
- Use full path when starting rnsd via nohup
- Works regardless of SSH session PATH configuration
Now deployment will successfully restart rnsd after copying updated files.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The deploy workflow was failing when manually triggered via workflow_dispatch
because it only checked for github.event.workflow_run.head_branch, which is
empty for manual triggers.
Issue:
- Manual trigger: gh workflow run deploy.yml --ref refactor/abstraction-layer
- BRANCH_NAME was empty ("")
- git checkout "" failed: "empty string is not a valid pathspec"
- Deployment failed on all Pis
Fix:
- Use fallback operator: github.event.workflow_run.head_branch || github.ref_name
- workflow_run trigger: uses head_branch (branch that triggered the tests)
- workflow_dispatch trigger: uses ref_name (branch being run on)
Now works for both:
- Automatic deployment after tests complete
- Manual deployment via workflow_dispatch or gh CLI
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Remove GitHub workflow documentation as it was specific to personal infrastructure setup and not relevant for general users of the BLE interface.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update version to align with BLE Protocol v2.2 implementation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added workflow_dispatch trigger to allow manual deployment without
waiting for test workflow completion. This is useful for:
- Testing the deployment workflow
- Deploying when automatic trigger doesn't fire
- Re-deploying without pushing new code
Usage:
- Go to Actions → Deploy to Raspberry Pi → Run workflow
- Or via CLI: gh workflow run deploy.yml
Updated the if condition to run on either:
- Automatic trigger when tests complete successfully
- Manual trigger via workflow_dispatch
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The branches filter in workflow_run triggers can cause workflow validation
errors: "The workflow must contain at least one job with no dependencies."
According to GitHub Actions documentation, the branches/branches-ignore
filters are not well-supported in workflow_run triggers and can cause
validation issues.
Removed the branches filter - the workflow will now trigger when the
"Tests" workflow completes on any branch, which is the intended behavior.
Fixes workflow validation error on Line 11, Col 3.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Host pre-built dbus_fast wheel on GitHub Releases to significantly speed
up installation on 32-bit ARM devices like Raspberry Pi Zero W.
Changes:
- Created GitHub Release (armv6l-wheels-v1) with dbus_fast 2.44.5 wheel
- Python 3.13 on ARMv6l architecture
- 874KB wheel file saves ~20 minutes of compilation on Pi Zero W
- Release URL: https://github.com/torlando-tech/ble-reticulum/releases/tag/armv6l-wheels-v1
- Modified install.sh to auto-download pre-built wheels:
- Detects Python 3.13 on 32-bit ARM (armhf/armv6l/armv7l)
- Downloads dbus_fast wheel from GitHub Releases
- Falls back gracefully to source build if download fails
- Saves ~20 minutes installation time on Pi Zero W
- Updated README.md with comprehensive documentation:
- Added "Pre-built Wheels for Raspberry Pi Zero W" section
- Documented automatic installation behavior
- Provided manual installation instructions
- Explained why pre-built wheels matter for low-power devices
- Added quick reference in automated installation section
Time savings on Pi Zero W:
- Before: 15-30 minutes (compile dbus_fast C extensions from source)
- After: < 10 seconds (download and install pre-built wheel)
The installer now transparently optimizes for Pi Zero W while maintaining
compatibility with all other platforms.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated install.sh to copy the new driver abstraction files
(bluetooth_driver.py and linux_bluetooth_driver.py) that were added
during the driver refactor. These files are required by BLEInterface.py
and were causing import failures in the installer integration test.
Changes:
- Copy bluetooth_driver.py to ~/.reticulum/interfaces/
- Copy linux_bluetooth_driver.py to ~/.reticulum/interfaces/
- Update success message to list the new driver files
Fixes installer test failure:
ModuleNotFoundError: No module named 'bluetooth_driver'
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
