blerc

Troubleshooting & Security

Common Issues

“Adapter not found”

# Check adapter status
hciconfig

# Power on adapter
sudo hciconfig hci0 up

# List adapters
bluetoothctl list

“Permission denied”

# Add user to bluetooth group
sudo usermod -aG bluetooth $USER

# Log out and back in, then verify
groups

# Alternative: run with sudo (not recommended for production)

“WebBluetooth not supported”

• Use Chrome or Edge browser (Firefox/Safari don’t support WebBluetooth)
• Ensure site is served over HTTPS (localhost is exempt)
• Enable experimental features: chrome://flags/#enable-experimental-web-platform-features

“GLIBC_X.XX not found”

Your Pi’s OS is too old. Check version:

cat /etc/*release
ldd --version

Solution: Upgrade to Raspberry Pi OS Bullseye (Debian 11) or newer.

Or rebuild targeting your OS:

cd blerc
make build-bullseye   # For Debian 11 (glibc 2.31)
make build-bookworm   # For Debian 12 (glibc 2.36)

“requires rustc X.XX”

Update Rust:

rustup update stable

Minimum required: Rust 1.83+

Cross-compilation fails on Apple Silicon

Use Docker-based cross-compilation:

cd blerc
make build  # Uses --platform linux/amd64

Yarn PnP resolution errors

cd webapp
rm -rf .yarn/cache .pnp.*
yarn install

BLE connection drops

• Check adapter power: hciconfig hci0
• Reduce distance to device
• Check for Wi-Fi interference (2.4GHz)
• Restart BlueZ: sudo systemctl restart bluetooth

Security Considerations

App Execution

• Apps must be explicitly defined in config — no arbitrary command execution
• Parameter values are templated but not executed as shell commands
• Validate app paths point to trusted executables

Authentication

For sensitive operations, enable passkey authentication:

[bluetooth]
auth_mode = "passkey"

Permissions

• Run blerc with minimal privileges (non-root when possible)
• Use the bluetooth group instead of root
• Limit app definitions to necessary commands only

Network

• HTTP apps use configurable timeout to prevent hanging
• Consider firewall rules if HTTP apps call external APIs
• WebBluetooth requires HTTPS in production (protects against MITM)

Variable Storage

• Variables stored in ~/.config/blerc/<app>/config.toml
• Ensure appropriate file permissions (600 recommended)
• Don’t store sensitive data (passwords, tokens) in variables