BLEUnlock is a small menu bar utility that locks and unlocks your Mac by proximity of your iPhone, Apple Watch, or any other Bluetooth Low Energy device.
This document is also available in Japanese (日本語版はこちら) and Simplified Chinese (简体中文).
This repository is a fork of the original ts1/BLEUnlock, created by Takeshi Sone. Many thanks to Takeshi Sone for open-sourcing BLEUnlock under the MIT license, and to all contributors who made the original project possible.
- No iPhone app is required
- Works with any BLE devices that periodically transmits signal from static MAC address
- Unlocks your Mac for you when the BLE device is near your Mac, without entering password
- Locks your Mac when the BLE device is away from your Mac
- Optionally runs your own script upon lock/unlock
- Optionally wakes from display sleep
- Optionally pauses and unpauses music/video playback when you're away and back
- Password is securely stored in Keychain
- A Mac with Bluetooth Low Energy support
- macOS 10.13 (High Sierra) or later
- iPhone 5s or newer, Apple Watch (all), or another BLE device that has static MAC address and transmits signal periodically
brew install bleunlock
This fork does not maintain the Homebrew Cask, so please use the manual installation method below.
Download the zip file from Releases, unzip and move to the Applications folder.
NOTE: This fork is not enrolled in the Apple Developer Program, so release builds cannot be distributed with Apple Developer ID signing and notarization. macOS may therefore block the app on first launch.
If macOS prevents BLEUnlock from opening:
- Move
BLEUnlock.appto/Applications.- Control-click the app and choose Open.
- If it is still blocked, open System Settings -> Privacy & Security, scroll down, and click Open Anyway for BLEUnlock.
- Launch the app again and confirm Open.
- After the app starts, grant the requested Bluetooth, Accessibility, Keychain, and Notification permissions.
To reduce repeated permission prompts when updating, replace the existing
/Applications/BLEUnlock.appinstead of running copies from different folders.
On the first launch, it asks for the following permissions, which you must grant:
| Permission | Description |
|---|---|
| Bluetooth | Obviously, Bluetooth access is required. Choose OK. |
| Accessibility | This is required to unlock the locked screen. Click Open System Preferences, click the lock icon on the bottom left to unlock, and turn on BLEUnlock. |
| Keychain | (Not always asked) If asked, you have to choose Always Allow because it is required while the screen is locked. |
| Notification | (Optional) BLEUnlock shows a message on the lock screen when it locks the screen. It is helpful to know if it's working properly. Additionally, to see the message on the lock screen, you need to set Show previews to always in the Notification preference pane. |
NOTE: The number of permissions required increases with each version of macOS, so if you are using an older OS, you may not be asked for one or more permissions.
Then it asks your login password to unlock the lock screen. It will be stored safely in Keychain.
Finally, from the menu bar icon, select Device. It starts scanning nearby BLE devices. Select your device, and you're done!
| Option | Description |
|---|---|
| Lock Screen Now | It locks the screen regardless of whether the BLE device is nearby or not; it will unlock once the BLE device moves away and then moves closer again. This is useful to ensure that the screen is locked before you leave your seat. |
| Unlock Settings | Groups the unlock logic and unlock RSSI settings in one submenu. The logic chooses whether any selected device or all selected devices must be near. The RSSI value controls how close the BLE device needs to be before unlocking. Choose Disable there to disable unlocking. |
| Lock Settings | Groups the lock logic and lock RSSI settings in one submenu. The logic chooses whether locking happens when any selected device goes away or only when all selected devices are away. The RSSI value controls how far the BLE device needs to be before locking. Choose Disable there to disable locking. |
| Delay to Lock | Duration of time before it locks the Mac when it detects that the BLE device is away. If the BLE device comes closer within that time, no lock will occur. |
| No-Signal Timeout | Time between last signal reception and locking. If you experience frequent "Signal is lost" locking, increase this value. |
| Wake on Proximity | Wakes up the display from sleep when the BLE device approaches while locking. |
| Wake without Unlocking | BLEUnlock will not unlock the Mac when the display wakes up from sleep, whether automatically via "Wake on Proximity" or manually. This allows for compatibility with the macOS built-in unlock with Apple Watch feature (which can operate immediately after BLEUnlock wakes the screen), or if you just prefer the lock screen to appear more quickly but don't want it to auto-unlock. |
| Pause "Now Playing" while Locked | On lock/unlock, BLEUnlock pauses/unpauses playback of music or video (including Apple Music, QuickTime Player and Spotify) that is controlled by Now Playing widget or the ⏯ key on the keyboard. |
| Use Screensaver to Lock | If this option is set, BLEUnlock launches screensaver instead of locking. For this option to work properly, you need to set Require password immediately after sleep or screen saver begins option in Security & Privacy preference pane. |
| Turn Off Screen on Lock | Turn off the display immediately when locking. |
| Set Password... | If you changed your login password, use this. |
| Passive Mode | By default it actively tries to connect to the BLE device and read the RSSI. Most of the time, the default is recommended and works stably. However, if you are using other Bluetooth things like keyboard, mouse, track pad or most notably Bluetooth Personal Hotspot, the default mode may interfere with each other. 2.4GHz WiFi may interfere as well. If you are experiencing instability of Bluetooth, turn on Passive Mode. |
| Launch at Login | Launches BLEUnlock when you login. |
| Set Minimum RSSI | Devices with RSSI below this value will not be displayed in the device scan list. |
If your BLE device is not from Apple, BLEUnlock may not able to find the device name. If that is the case, your device is displayed as a UUID (long hexadecimal numbers and hyphens). To identify the device, try moving the device closer to or farther away from the Mac and see if the RSSI (dB value) changes accordingly.
If you don't see any device in the list, try resetting the Bluetooth module as described below.
Make sure BLEUnlock is turned on in System Preferences > Security & Privacy > Privacy > Accessibility. If it is already on, try turning it off and on again.
If it asks for permission to access its own password in Keychain, you must choose Always Allow, because it is needed while the screen is locked.
Increase No-Signal Timeout. Or try Passive Mode.
Firstly, Shift + Option + Click the Bluetooth icon in the menubar or Control Center, then click Reset the Bluetooth module.
In macOS 12 Monterey, this option is no longer available. Instead, type the command below in Terminal to reset the Bluetooth module:
sudo pkill bluetoothd
This command will ask your login password.
If the problem persists, turn on Passive Mode.
Unlike classic Bluetooth, Bluetooth Low Energy devices can use private MAC address. That private address can be random, and can be changed from time to time.
Recent smart devices, both iOS and Android, tend to use private addresses that change every 15 minutes or so. This is probably to prevent tracking.
On the other hand, in order for BLEUnlock to track your device, its MAC address must be static.
Fortunately, on Apple devices, if you are signed in with the same Apple ID as your Mac, the MAC address is resolved to the true (public) address.
If a device uses rotating private addresses, you can also try pairing it with your Mac once in System Settings > Bluetooth (or System Preferences > Bluetooth on older macOS versions). After the device is connected and trusted by the system, macOS may keep recognizing it more consistently, and BLEUnlock may then see a stable identity as well.
This is only a workaround that is worth trying. It worked with my RedMagic phone, but I cannot guarantee that every device using rotating private addresses will be supported reliably.
Pairing itself usually has little effect on battery life. The bigger battery impact comes from frequent active Bluetooth connections or polling, not from the one-time pairing step.
On locking and unlocking, BLEUnlock runs a script located here:
~/Library/Application Scripts/jp.sone.BLEUnlock/event
An argument is passed depending on the type of event:
| Event | Argument |
|---|---|
| Locked by BLEUnlock because of low RSSI | away |
| Locked by BLEUnlock because of no signal | lost |
| Unlocked by BLEUnlock | unlocked |
| Unlocked manually | intruded |
NOTE: for
intrudedevent works properly, you have to set Require password immediately after sleep in Security & Privacy preference pane.
Here is an example script which sends a LINE Notify message, with a photo of the person in front of the Mac when it is unlocked manually.
#!/bin/bash
set -eo pipefail
LINE_TOKEN=xxxxx
notify() {
local message=$1
local image=$2
if [ "$image" ]; then
img_arg="-F imageFile=@$image"
else
img_arg=""
fi
curl -X POST -H "Authorization: Bearer $LINE_TOKEN" -F "message=$message" \
$img_arg https://notify-api.line.me/api/notify
}
capture() {
open -Wa SnapshotUnlocker
ls -t /tmp/unlock-*.jpg | head -1
}
case $1 in
away)
notify "$(hostname -s) is locked by BLEUnlock because iPhone is away."
;;
lost)
notify "$(hostname -s) is locked by BLEUnlock because signal is lost."
;;
unlocked)
#notify "$(hostname -s) is unlocked by BLEUnlock."
;;
intruded)
notify "$(hostname -s) is manually unlocked." $(capture)
;;
esacSnapshotUnlocker is an .app created with Script Editor with this script:
do shell script "/usr/local/bin/ffmpeg -f avfoundation -r 30 -i 0 -frames:v 1 -y /tmp/unlock-$(date +%Y%m%d_%H%M%S).jpg"
This app is required because BLEUnlock does not have Camera permission. Giving permission to this app resolves the problem.
This fork is based on the original ts1/BLEUnlock by Takeshi Sone and continues development in this repository for its own releases and changes.
Thank you to Takeshi Sone for the original project, and to everyone who contributed fixes, translations, and ideas over time.
- Takeshi Sone: Original BLEUnlock author and project foundation
- peiit: Chinese translation
- wenmin-wu: Minimum RSSI and moving average
- stephengroat: CI
- joeyhoer: Homebrew Cask
- cyberclaus: German, Swedish, Norwegian (Bokmål) and Danish localizations
- alonewolfx2: Turkish localization
- wernjie: Wake without Unlocking
- tokfrans03: Language fixes
Icons are based on SVGs downloaded from materialdesignicons.com. They are originally designed by Google LLC and licensed under Apache License version 2.0.
MIT
Copyright © 2019-2022 Takeshi Sone.