BLEUnlock

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

Features

• 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

Requirements

• 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

Installation

Using Homebrew Cask

$ brew install bleunlock

Manual installation

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

Setting up

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

Options

Troubleshooting

Can't find my device in the 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.

It fails to unlock

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.

"Signal is lost" occurs frequently

Increase No-Signal Timeout. Or try Passive Mode.

My Bluetooth keyboard, mouse, Personal Hotspot, or whatever Bluetooth, went nuts!

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.

Notes on MAC address

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.

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 the Device scan list of BLEUnlock with the one that is displayed on your device.

Run script on lock/unlock

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: for intruded event works properly, you have to set Require password immediately after sleep in Security & Privacy preference pane.

Example

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)
        ;;
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.

Funding

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 via Buy Me a Coffee or PayPal Me so I can keep up.

Credits

• 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

Icons are based on SVGs downloaded from materialdesignicons.com. They are originally designed by Google LLC and licensed under Apache License version 2.0.

License

MIT

Copyright © 2019-2022 Takeshi Sone.