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>
Arch Linux has PyGObject 3.54.5 in python-gobject package, but bluezero
requires PyGObject <3.52.0, causing pip to fail when trying to replace
the system version.
Solution: Don't install python-gobject system package on Arch. Let pip
compile the compatible PyGObject version (3.50.2) instead.
Changes:
- install.sh: Remove python-gobject from Arch pacman install
- install.sh: Add explanatory warning about PyGObject compilation
- tests/test_installer.sh: Don't check for python-gobject on Arch
- tests/test_installer.sh: Add comment explaining why it's skipped
- tests/test_installer.sh: Update summary for Arch (PyGObject compiled)
- README.md: Remove python-gobject from Arch instructions
- README.md: Explain version incompatibility and compilation requirement
Result:
- Debian/Ubuntu: All system packages, zero compilation (~1 min)
- Arch Linux: System packages + PyGObject compilation (~2-3 min)
Trade-off accepted: Arch users get longer install time in exchange for
compatibility with bluezero's PyGObject version requirement.
Fixes: error: uninstall-no-record-file (PyGObject 3.54.5 conflict)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Arch Linux has unique pip/system package integration where pip doesn't
recognize system python-gobject as satisfying PyGObject dependency,
causing bluezero to try compiling PyGObject from source.
Solution: Install base-devel on Arch to provide build tools (gcc, make, meson)
Changes:
- install.sh: Add base-devel to Arch system dependencies
- install.sh: Add note explaining why build tools needed on Arch
- install.sh: Use --needed flag to skip already installed packages
- README.md: Document base-devel requirement for Arch users
- README.md: Explain Arch vs Debian/Ubuntu compilation differences
- tests/test_installer.sh: Expect build tools on Arch (verify base-devel installed)
- tests/test_installer.sh: Update summary to reflect Arch compilation
Rationale:
- AUR python-bluezero is outdated (v0.9.0 vs pip v0.9.1)
- AUR package has 0 votes (rarely used by community)
- base-devel commonly installed on Arch systems anyway
- Keeps latest bluezero version
- Simpler than full AUR integration
Impact:
- Debian/Ubuntu: No compilation (< 1 min install)
- Arch Linux: Some compilation (~3 min install)
- Still faster than compiling everything on Debian
Fixes Arch Linux CI failure: "Unknown compiler(s): gcc not found"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix two issues preventing installer tests from passing:
1. Arch Linux: Sync package database before installing packages
- Fresh Arch containers have no package database (core, extra)
- Added pacman -Sy before pacman -S in both basic prereqs and system deps
- Error was: "warning: database file for 'core' does not exist"
- Applied to both root and non-root installation paths
2. Debian/Ubuntu: Fix package check pattern for architecture suffixes
- dpkg shows packages as "python3-cairo:amd64" not "python3-cairo "
- Changed grep pattern from "^ii $pkg " to "^ii $pkg"
- Now matches packages with or without :amd64/:arm64 suffixes
- Error was: "FAIL: python3-cairo not installed" (even though it was)
Changes:
- install.sh lines 132-134, 233-234: Add pacman -Sy sync before install
- tests/test_installer.sh line 41: Fix dpkg grep pattern
This allows all 5 OS versions to pass:
- Debian 12 (Bookworm)
- Debian Trixie (testing)
- Ubuntu 22.04 LTS
- Ubuntu 24.04 LTS
- Arch Linux (rolling) [NEW]
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive Arch Linux testing to installer-test job.
Changes to .github/workflows/test.yml:
- Add archlinux:latest to test matrix (5 OS versions tested now)
- Set continue-on-error for Arch (rolling release can expose bleeding-edge issues)
- Arch tests run in parallel with Debian/Ubuntu tests
Changes to tests/test_installer.sh:
- Refactored to be OS-agnostic (supports Debian/Ubuntu AND Arch Linux)
- Added OS type detection (apt-get vs pacman)
- Added check_package() helper function (uses dpkg or pacman based on OS)
- Conditional Debian environment setup (DEBIAN_FRONTEND only for Debian/Ubuntu)
- OS-specific package name verification:
- Debian/Ubuntu: python3-gi, python3-dbus, python3-cairo, bluez
- Arch Linux: python-gobject, python-dbus, python-cairo, bluez, bluez-utils
- OS-specific build tool checks (dpkg -l vs pacman -Q)
- Updated summary output to show correct packages per OS
install.sh changes:
- NONE - Arch Linux support already complete and correct!
CI Matrix now tests:
- Debian 12 (Bookworm - current stable)
- Debian Trixie (testing - next release) [non-blocking]
- Ubuntu 22.04 LTS (Jammy)
- Ubuntu 24.04 LTS (Noble)
- Arch Linux (rolling release) [non-blocking] [NEW]
Benefits:
- Validates install.sh Arch support works in practice
- Tests with newer BlueZ/Python versions (rolling release)
- Forward compatibility testing
- Broader Linux distribution coverage
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
bleak doesn't always expose __version__ attribute, causing test failures.
Changed to just verify the module can be imported successfully.
Fixes: AttributeError: module 'bleak' has no attribute '__version__'
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Debian containers run as root without sudo installed by default.
The script was trying to use sudo to install packages (including sudo itself),
which failed with "sudo: command not found".
Changes:
- Check if running as root ($EUID -eq 0) before using sudo
- If root: use package managers directly (apt-get, pacman)
- If not root: use sudo as before
Applied to:
- Basic prerequisites installation (lines 108-113)
- Arch prerequisites installation (lines 131-135)
- System dependencies installation (lines 215-221)
- Arch system dependencies (lines 228-232)
This fixes installation in:
- Fresh Debian containers (root, no sudo)
- Fresh Ubuntu containers (root, has sudo but not needed)
- User Debian/Ubuntu systems (not root, uses sudo)
- User Arch systems (not root, uses sudo)
Fixes Debian 12 CI failure: "sudo: command not found"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major architectural improvement: install.sh now handles all prerequisites,
eliminating duplicate logic and making CI test exactly what users run.
## Changes to install.sh:
**1. Added pip_install() helper function (lines 37-49)**
- Detects pip version capabilities
- Uses --break-system-packages flag on pip 23.0+ (Debian 12+, Ubuntu 24.04+)
- Falls back to no flag on pip 22.x (Ubuntu 22.04)
- Single source of truth for all pip operations
- Fixes compatibility across all OS versions
**2. Added basic system package installation (lines 91-128)**
- Checks and installs: python3, python3-pip, git, sudo
- Supports both Debian/Ubuntu (apt-get) and Arch (pacman)
- Only installs missing packages (idempotent)
**3. Changed Reticulum check to auto-install (lines 171-190)**
- Previously: exited with error if Reticulum not found
- Now: automatically installs Reticulum using pip_install()
- Verifies installation succeeded
- Falls back to manual instructions if auto-install fails
**4. Updated all pip install commands to use helper (lines 242, 251)**
- Consistent --break-system-packages handling
- Works on Ubuntu 22.04, Debian 12, Trixie, Ubuntu 24.04
**5. Updated header comment**
- Reflects that script is now self-contained
- Documents all responsibilities
## Changes to tests/test_installer.sh:
**Simplified from 127 lines to 126 lines, but more importantly:**
**Removed (no longer needed):**
- Manual apt-get install of base packages
- Manual pip install of Reticulum
- Duplicate pip compatibility logic
**Kept:**
- Non-interactive environment setup
- Verification tests
- BLE interface import test
**Added:**
- Reticulum verification check
- Updated summary to reflect self-contained nature
## Benefits:
1. ✅ **Single source of truth** - No duplicate pip logic
2. ✅ **CI tests real workflow** - Exactly what users run
3. ✅ **Better user experience** - One command does everything
4. ✅ **Cross-version compatibility** - Works on all OS/pip versions
5. ✅ **Easier maintenance** - Changes in one place
6. ✅ **Self-contained** - install.sh has zero external dependencies
## Testing:
Works across all CI matrix OS versions:
- Ubuntu 22.04 (pip 22.0.2 - no --break-system-packages)
- Debian 12 (pip 23.0+ - requires --break-system-packages)
- Debian Trixie (pip 23.0+ - requires --break-system-packages)
- Ubuntu 24.04 (pip 24.0+ - supports --break-system-packages)
Fixes#4🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix two issues preventing Ubuntu 22.04 CI from passing:
1. Remove --break-system-packages flag from pip install
- Ubuntu 22.04 has pip 22.0.2 (flag added in pip 22.3)
- Container runs as root, so no permission issues
- Flag not needed for compatibility
2. Fix /workspace absolute path to use relative path
- GitHub Actions containers use different workspace structure
- Changed to: cd "$(dirname "$0")/.." to navigate from tests/ to repo root
- More portable across CI environments
These changes make the test script compatible with:
- Ubuntu 22.04 (pip 22.0.2)
- Ubuntu 24.04 (pip 24.0+)
- Debian 12 and Trixie
- Any environment where script location may vary
Fixes Ubuntu 22.04 installer-test CI failure.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add forward compatibility testing with Debian 13 "Trixie" (testing release).
Changes:
- Add debian:trixie to installer-test matrix
- Set continue-on-error for Trixie (testing can be unstable)
- Add fail-fast: false to run all OS tests even if one fails
- Update comments to clarify Debian/Ubuntu versions
Benefits:
- Early detection of BlueZ/DBus API changes
- Test compatibility with newer system packages
- Forward compatibility assurance before Trixie stable release
- Non-blocking (Trixie failures won't block merges)
Matrix now tests:
- Debian 12 (Bookworm - current stable)
- Debian Trixie (testing - next release) [NEW]
- Ubuntu 22.04 LTS (Jammy)
- Ubuntu 24.04 LTS (Noble)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Ubuntu 24.04 CI was hanging on tzdata interactive timezone prompt.
Changes:
- tests/test_installer.sh: Set DEBIAN_FRONTEND=noninteractive, pre-configure timezone
- tests/test_installer.sh: Add apt-get options to suppress prompts
- .github/workflows/test.yml: Set environment variables in installer-test container
- install.sh: Auto-detect CI environment and enable non-interactive mode
This follows Debian/Ubuntu best practices for containerized environments and
prevents interactive prompts from blocking CI runs.
Fixes Ubuntu 24.04 installer-test CI failure.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Strategy 1: Use pre-compiled system packages instead of building from source
- install.sh: Add python3-gi, python3-cairo to apt-get install
- install.sh: Add python-gobject, python-cairo to pacman install
- install.sh: Install only bleak and bluezero via pip (skip compiled packages)
- README.md: Update dependency instructions with system packages
- README.md: Add explanation of why system packages are preferred
Strategy 2: Add CI integration test for fresh Debian/Ubuntu systems
- tests/test_installer.sh: New integration test script
- .github/workflows/test.yml: Add installer-test job with matrix for Debian 12, Ubuntu 22.04, 24.04
- Tests reproduce real user experience and catch missing dependencies
Benefits:
- Zero compilation time (seconds vs minutes)
- No build tools needed (meson, cmake)
- No dev headers needed (libglib2.0-dev, libcairo2-dev, etc.)
- Faster installation on resource-constrained devices (Raspberry Pi)
- Prevents future dependency documentation issues
Fixes#4🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
