diff --git a/README.md b/README.md index db209ed..b587720 100644 --- a/README.md +++ b/README.md @@ -209,9 +209,11 @@ ls ~/.local/pipx/venvs/ sudo setcap 'cap_net_raw,cap_net_admin+eip' ~/.local/pipx/venvs/rns/bin/python3 ``` -#### 5. Enable BlueZ Experimental Mode +#### 5. Configure BlueZ -The BLE interface requires BlueZ experimental features for proper BLE connectivity: +The BLE interface requires BlueZ experimental features and automatic pairing configuration: + +**Enable Experimental Mode:** ```bash # Edit BlueZ service configuration @@ -225,13 +227,28 @@ ExecStart= ExecStart=/usr/lib/bluetooth/bluetoothd --experimental ``` -Then reload and restart: +**Enable JustWorksRepairing for Automatic Pairing:** + +Edit `/etc/bluetooth/main.conf` and add to the `[General]` section: + +```ini +[General] +JustWorksRepairing = always +``` + +This enables automatic pairing for peer-initiated connections, which is required for zero-touch mesh networking. Reticulum provides its own cryptographic security on top of the BLE transport. + +**Apply Changes:** + ```bash sudo systemctl daemon-reload sudo systemctl restart bluetooth.service # Verify experimental mode is enabled systemctl status bluetooth.service | grep -i experimental + +# Verify JustWorksRepairing is set +grep JustWorksRepairing /etc/bluetooth/main.conf ``` #### Why pipx Requires Special Handling @@ -346,6 +363,37 @@ These errors occur when BlueZ attempts Classic Bluetooth (BR/EDR) connections in **Solution:** Enable BlueZ experimental mode (see Installation → Manual Installation → step 4). If you used the automated installer, re-run it without `--skip-experimental`. +### BLE pairing failures / "JustWorksRepairing: never" warning +The BLE interface logs a warning that BlueZ's JustWorksRepairing is set to "never", which may cause pairing failures in the mesh network. + +**Symptoms:** +- Warning: `BlueZ JustWorksRepairing: never (default - may cause pairing failures)` +- Recommendation message: `Set JustWorksRepairing=always in /etc/bluetooth/main.conf` +- Intermittent connection failures with peer devices +- Pairing requests rejected by BlueZ + +**Cause:** +BlueZ's default `JustWorksRepairing` setting is "never", which blocks automatic pairing for peer-initiated connections. This breaks zero-touch mesh networking. + +**Solution:** +Enable JustWorksRepairing in BlueZ configuration (see Installation → Manual Installation → step 5). If you used the automated installer, this is configured automatically. To verify or fix manually: + +```bash +# Edit BlueZ configuration +sudo nano /etc/bluetooth/main.conf + +# Add to [General] section: +JustWorksRepairing = always + +# Restart Bluetooth service +sudo systemctl restart bluetooth + +# Verify the setting +grep JustWorksRepairing /etc/bluetooth/main.conf +``` + +**Note:** Just Works pairing provides unauthenticated BLE encryption. This is acceptable because Reticulum provides its own cryptographic security on top of the BLE transport layer. + ### Bluetooth adapter not powered / "No powered Bluetooth adapters found" The Bluetooth adapter exists but is powered off, preventing BLE operations. diff --git a/install.sh b/install.sh index bd35b8c..84bc9d6 100755 --- a/install.sh +++ b/install.sh @@ -920,6 +920,105 @@ fi echo +# Step 5D: BlueZ JustWorksRepairing Configuration +print_header "BlueZ JustWorksRepairing Configuration" + +BLUEZ_CONF="/etc/bluetooth/main.conf" + +if [ -f "$BLUEZ_CONF" ]; then + print_info "Checking JustWorksRepairing setting in $BLUEZ_CONF..." + + # Extract current JustWorksRepairing setting (handle commented lines) + CURRENT_SETTING=$(grep -E "^#?\s*JustWorksRepairing\s*=" "$BLUEZ_CONF" 2>/dev/null | tail -1 | sed 's/.*=\s*//' | tr -d '[:space:]') + + if [ "$CURRENT_SETTING" = "always" ]; then + print_success "JustWorksRepairing is already set to 'always'" + else + if [ -z "$CURRENT_SETTING" ]; then + print_info "JustWorksRepairing not found in config (using BlueZ default: never)" + else + print_info "JustWorksRepairing is currently set to: $CURRENT_SETTING" + fi + + print_info "Setting JustWorksRepairing to 'always' for automatic BLE mesh pairing..." + echo + print_info "Background: BlueZ's JustWorksRepairing controls automatic pairing" + print_info "for peer-initiated connections. Setting to 'always' enables zero-touch" + print_info "mesh networking. Reticulum provides its own cryptographic security." + echo + + # Modify the configuration file + if [ "$EUID" -eq 0 ]; then + # Running as root - no sudo needed + # First, comment out any existing JustWorksRepairing lines + sed -i 's/^\s*JustWorksRepairing\s*=.*/#&/' "$BLUEZ_CONF" + + # Add our setting to the [General] section or append if no section exists + if grep -q "^\[General\]" "$BLUEZ_CONF"; then + # Insert after [General] section header + sed -i '/^\[General\]/a JustWorksRepairing = always' "$BLUEZ_CONF" + else + # No [General] section, append at end + echo "" >> "$BLUEZ_CONF" + echo "[General]" >> "$BLUEZ_CONF" + echo "JustWorksRepairing = always" >> "$BLUEZ_CONF" + fi + + # Restart bluetooth service (non-fatal in container/CI environments) + print_info "Restarting bluetooth service to apply changes..." + systemctl daemon-reload 2>/dev/null || true + systemctl restart bluetooth 2>/dev/null || true + else + # Not root - use sudo + # First, comment out any existing JustWorksRepairing lines + sudo sed -i 's/^\s*JustWorksRepairing\s*=.*/#&/' "$BLUEZ_CONF" + + # Add our setting to the [General] section or append if no section exists + if grep -q "^\[General\]" "$BLUEZ_CONF"; then + # Insert after [General] section header + sudo sed -i '/^\[General\]/a JustWorksRepairing = always' "$BLUEZ_CONF" + else + # No [General] section, append at end + echo "" | sudo tee -a "$BLUEZ_CONF" > /dev/null + echo "[General]" | sudo tee -a "$BLUEZ_CONF" > /dev/null + echo "JustWorksRepairing = always" | sudo tee -a "$BLUEZ_CONF" > /dev/null + fi + + # Restart bluetooth service (non-fatal in container/CI environments) + print_info "Restarting bluetooth service to apply changes..." + sudo systemctl daemon-reload 2>/dev/null || true + sudo systemctl restart bluetooth 2>/dev/null || true + fi + + # Verify the setting was applied + sleep 1 + VERIFY_SETTING=$(grep -E "^JustWorksRepairing\s*=\s*always" "$BLUEZ_CONF" 2>/dev/null) + if [ -n "$VERIFY_SETTING" ]; then + print_success "JustWorksRepairing set to 'always' successfully" + + # Verify bluetooth service is running (skip in container environments) + if systemctl is-active --quiet bluetooth 2>/dev/null; then + print_success "Bluetooth service restarted successfully" + elif command -v systemctl &> /dev/null && [ ! -f /.dockerenv ]; then + # Only show warning if systemctl exists and we're not in a container + print_warning "Bluetooth service may need manual restart" + print_info "Check status with: sudo systemctl status bluetooth" + else + # Container environment or systemd not available + print_info "Configuration updated (service restart skipped in container environment)" + fi + else + print_error "Failed to set JustWorksRepairing in $BLUEZ_CONF" + print_warning "You may need to manually add 'JustWorksRepairing = always' to [General] section" + fi + fi +else + print_warning "$BLUEZ_CONF not found" + print_info "JustWorksRepairing configuration skipped (BlueZ may not be installed)" +fi + +echo + # Step 6: Configuration print_header "Configuration"