🔒 hyprproxlock

A proximity-based daemon for Hyprland that triggers screen locking and unlocking through hyprlock based on Bluetooth device proximity. It monitors connected devices' signal strength to automatically control your screen lock state.

✨ Features

• 🔵 Bluetooth Proximity Detection: Monitors Bluetooth device signal strength to determine when to lock/unlock
• ⚡ hyprlock Integration: Uses hyprlock for actual screen locking/unlocking
• 🔄 Configurable Thresholds: Customize signal strength thresholds for locking/unlocking
• ⏱️ Adjustable Timings: Fine-tune lock/unlock hold times and polling intervals
• 🚀 Optimized Performance: Lightweight Rust implementation with minimal dependencies, efficient resource usage, and battery-friendly Bluetooth polling
• 🔌 Auto-Connect: Automatically reconnect to configured devices at specified intervals

📋 Dependencies

Package	Role
Hyprland (hyprctl)	DPMS / session integration
hyprlock	Screen lock
bluez-deprecated-tools (hcitool)	RSSI reads
bluez (bluetoothctl)	Connect attempts
libnotify (notify-send)	Optional notifications

🚀 Get Started

1. Installation

You can install hyprproxlock from the AUR:

yay -S hyprproxlock

This will automatically install hyprlock and bluez-deprecated-tools as a dependency.

2. Configuration

Create a configuration file at ~/.config/hypr/hyprproxlock.conf:

# Device Configuration
device {
   mac_address = "XX:XX:XX:XX:XX:XX"
   name = "My Device"
   enabled = true
   auto_connect = true
}

device {
   mac_address = "XX:XX:XX:XX:XX:XX"
   name = "My Watch"
   enabled = true
   auto_connect = false
}

# Threshold Settings
thresholds {
   lock_threshold = -25
   unlock_threshold = -15
}

# Timing Configuration
timings {
   lock_hold_seconds = 3
   unlock_hold_seconds = 3
   poll_interval = 1
   reconnect_interval = 20
}

# Desktop notifications (notify-send); set enabled = false to disable
notifications {
   enabled = true
}

3. Usage

1. Start the daemon:

hyprproxlock

2. The screen will automatically:
   • 🔒 Lock (using hyprlock) when all configured devices are out of range
   • 🔓 Unlock (using hyprlock) when a configured device comes back in range

4. Autostart with Hyprland

To automatically start hyprproxlock when Hyprland starts, add it to your Hyprland configuration:

1. Edit ~/.config/hypr/hyprland.conf:

exec-once = hyprproxlock

🤔 How It Works

🔵 Bluetooth Connection

• The tool only works when your Bluetooth is turned ON
• Your device (phone, watch, etc.) must be paired and connected
• If Bluetooth is off or no devices are connected, the tool won't do anything
• With auto_connect = true, the tool will attempt to reconnect to devices when connectivity is lost
• The reconnect_interval setting controls how often reconnection attempts are made (in seconds)
• Auto-connect attempts are only made for:
  • Devices that are enabled in the configuration
  • Devices with auto_connect = true specified
  • Devices that appear to be disconnected (no valid RSSI readings)
• This feature is useful for maintaining consistent connectivity with devices that may disconnect

📶 Signal Strength (RSSI)

• Stronger signal (higher dBm) means closer; weaker means farther
• Rough guide: -15 dBm ≈ very close, -70 dBm ≈ far
• Each reading falls into a zone:

Zone	Condition	Effect
Disconnected	no valid RSSI	skipped for lock; may auto-connect
Far	rssi < lock_threshold	lock candidate
Mid	between thresholds	connected; no lock/unlock action
Close	rssi > unlock_threshold	unlock candidate

• Keep unlock_threshold greater than lock_threshold so Mid has a gap

⏱️ Locking Behavior

1. When all enabled, connected devices' signals get weaker than the lock_threshold (Far):

   • The tool starts a timer (set by lock_hold_seconds)
   • It keeps checking the signal during this time
   • Only triggers hyprlock to lock the screen if every connected device stays Far for the full timer duration
   • This prevents accidental locks if you just briefly walk away

2. The screen won't lock if:

   • Bluetooth is turned off
   • No devices are connected (no valid RSSI)
   • Any connected device's signal is Mid or Close (stronger than lock_threshold)
   • The timer hasn't completed yet

🔓 Unlocking Behavior

1. When any enabled device's signal gets stronger than the unlock_threshold (Close):

   • The tool starts a timer (set by unlock_hold_seconds)
   • It keeps checking the signal during this time
   • Only unlocks the screen if that device stays Close for the full timer duration
   • Unlock exits hyprlock and turns the displays back on via hyprctl DPMS
   • This prevents accidental unlocks from brief signal fluctuations

2. The screen won't unlock if:

   • Bluetooth is turned off
   • Your device is not connected
   • No device's signal is stronger than unlock_threshold
   • The timer hasn't completed yet

🔄 Continuous Monitoring

• Signal is polled every poll_interval seconds
• Desktop notifications (notify-send) report lock, unlock, and reconnect events when available and notifications.enabled is true

📊 Logging

Sink	Path / stream	Level
File	$XDG_STATE_HOME/hyprproxlock/logs/hyprproxlock.log.YYYY-MM-DD	INFO
Console	stdout when run in a terminal	DEBUG

Typical $XDG_STATE_HOME is ~/.local/state. File logs stay focused on important events; the console includes DEBUG detail for troubleshooting.

Caution

Currently, the project uses hcitool from the bluez-deprecated-tools package for Bluetooth signal strength measurement. This is a temporary solution as attempts to use the Rust bluez implementation bluer did not return valid RSSI values. Future versions will aim to replace this with a more modern solution.

📝 License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🙏 Acknowledgments

• Hyprland for the amazing window manager
• hyprlock for the screen locker