Repository files navigation

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 inJapanese (日本語版はこちら).

• No iPhone app is required
• Works with any BLE devices that periodically transmits signal fromstatic 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 hasstatic MAC address and transmits signal periodically

brew install bleunlock

Download the zip file fromReleases, unzip and move to the Applications folder.

On the first launch, it asks for the following permissions, which you must grant:

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, selectDevice.It starts scanning nearby BLE devices.Select your device, and you're done!

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 seeany device in the list, try resetting the Bluetooth module as described below.

Make sure BLEUnlock is turned on inSystem 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 chooseAlways Allow, because it is needed while the screen is locked.

IncreaseNo-Signal Timeout.Or tryPassive Mode.

Firstly, Shift + Option + Click the Bluetooth icon in the menubar or Control Center, then clickReset 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 onPassive Mode.

Unlike classic Bluetooth, Bluetooth Low Energy devices can useprivate 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.

For other devices, including Android, the way to resolve the address is unknown.If your non-Apple device changes its MAC address over time, unfortunately BLEUnlock can't support it.

To check if the MAC address is resolved correctly, compare the MAC address displayed in theDevice scan list of BLEUnlock with the one that is displayed on your device.

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:

NOTE: forintruded event works properly, you have to setRequire passwordimmediately after sleep inSecurity & 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/bashset -eo pipefailLINE_TOKEN=xxxxxnotify() {local message=$1local image=$2if ["$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$1in    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)        ;;esac

SnapshotUnlocker 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.

The annual Apple Developer Program fee is funded by donations.

If you like this app, I'd appreciate it if you could make a donation viaBuy Me a Coffee orPayPal Me so I can keep up.

• peiit: Chinese translation
• wenmin-wu: Minimum RSSI and moving average
• stephengroat: CI
• joeyhoer: Homebrew Cask
• Skyearn: Big Sur style icon
• 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.