BLEUnlock

BLEUnlock is a small menu bar utility that locks and unlocks your Mac with your iPhone, Apple Watch, or any other Bluetooth Low Energy devices.

This document is also available in Japanese.

Features

• No iPhone app is required
• Works with any BLE devices that periodically send signal
• Unlocks your Mac for you when the device is near Mac, no need to enter password again
• Locks your Mac when the device is away from Mac
• Optionally runs your script on lock/unlock
• Optionally wakes from display sleep state
• Optionally pauses and unpauses music/video playback when you're away and back
• Password is securely stored in Keychain

Requirements

• Mac with Bluetooth Low Energy support
• macOS 10.13 (High Sierra) or later
• iPhone 5s or later, Apple Watch (all), or other BLE device that transmits signal periodically

Installation

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

On the first launch, it asks your login password, which is required to unlock the lock screen. It's safe because it's stored in Keychain.

Then it asks for permission for Accessibility. In System Preferences, click the lock icon to unlock and turn BLEUnlock on. This permission is also required to unlock the lock screen.

Finally, from the menu bar icon, select "Device". It starts scanning nearby BLE devices. Select your device, and you're done!

Troubleshooting

If it fails to unlock, check 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, click "Always Allow", because it is needed while the screen is locked.

If "Signal is lost" occurs frequently, turn Bluetooth of Mac off then on. Or use a device that sends signal more frequently.

Why does it sometimes take long time to unlock?

Short answer: wake your iPhone.

From version 1.4.1, BLEUnlock assumes the device is away when Mac enters system sleep and Bluetooth hardware is powered off (typically 15-30 seconds after the lid is closed). This is required for security. Consequently, it sometimes takes up to several seconds to unlock when Mac wakes from system sleep.

This is because BLEUnlock has lost connection to the device and has to wait for the device to send signal. Usually, devices send signal less frequently when it is in sleep mode. Thus, if you wake the device, in most cases it sends signal promptly, and BLEUnlock unlocks.

Passive mode and Bluetooth Personal Hotspot

By default BLEUnlock actively connects to the device to read RSSI (signal strength). It is the best way to steadily read RSSI for devices such as iPhone that support it. However, it does not play nice with Bluetooth Personal Hotspot.

With Passive Mode, BLEUnlock only passively receives signals that the deveice broadcasts. That does not interfere with Bluetooth Personal Hotspot.

If you use Bluetooth Personal Hotspot on the same device, turn Passive Mode on. Otherwise, turn it off.

Notes on Now Playing

BLEUnlock can pause apps that support Media Remote framework while locking. These apps include Apple Music, QuickTime Player, Spotify, and Youtube on Safari. Unfortunately Google Chrome doesn't seem to react to play/pause command at the moment.

If an app can be controlled via "Now Playing" widget, or by the ⏯️ key on the keyboard, BLEUnlock should be able to control it.

Using screensaver to lock

If you turn on Use Screensaver to Lock option, to lock the computer properly, you have to set Require pasword immediately after sleep or screen saver begins option in Security & Privacy preference pane.

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 LINE Notify message, with a photo of the person in front of Mac when 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 is required because BLEUnlock does not have Camera permission. Giving permission to this app resolve the problem.

Funding

Since 1.9.0, binary releases are not notarized by Apple. Because of this, you have to right-click and Open to start, and you have to re-authorize Keychain and other permissions.

My company is not developing iOS/Mac app at the moment, so I don't have access to a paid Apple Developer account.

If you like this app, I'd appreciate it if you could make a donation via Buy Me a Coffee or PayPal.Me so that I can pay for the Apple Developer Program myself!

Credits

• peiit: Chinese translation
• wenmin-wu: Minimum RSSI and moving average
• stephengroat: CI

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-2020 Takeshi Sone.