ProximityShortcuts User Guide

What is ProximityShortcuts?

ProximityShortcuts is a macOS menu bar app that automatically triggers shortcuts based on your iPhone or Apple Watch proximity. When your device moves away from your Mac, it can run shortcuts like locking your screen, pausing music, or turning off lights. When you return, it can resume playback, or turn lights back on, etc. (It can't unlock your Mac due to security reasons)

Think of it as "presence detection" for your Mac - it knows when you're nearby and when you've left, then takes actions you define.

Quick Start

1. First Launch

1. Launch ProximityShortcuts from Applications
2. Click the menu bar icon (multiple circles with dot inside)
3. Click "Continue" to grant Bluetooth permission
4. Wait a few seconds for devices to appear

2. Select Your Device

1. Choose your iPhone or Apple Watch from the list
2. The app will start monitoring its proximity
3. Watch the signal graph to see real-time signal strength

3. Configure Actions

1. Click the gear icon (⚙️) to open Settings
2. Enable "Device Went Away" and enter a shortcut name
3. Enable "Device Is Back" and enter a shortcut name
4. Create these shortcuts in the macOS Shortcuts app

4. Test It

1. Walk away from your Mac with your device
2. After a few seconds, your "away" shortcut will run
3. Return to your Mac
4. Your "back" shortcut will run

How It Works

Bluetooth Signal Monitoring

ProximityShortcuts uses Bluetooth Low Energy (BLE) to continuously monitor the signal strength (RSSI) from your iPhone or Apple Watch. The signal strength indicates how close your device is:

• Strong signal (-30 to -50 dBm): Device very close (on desk, in pocket)
• Medium signal (-50 to -70 dBm): Device nearby (across room)
• Weak signal (-70 to -90 dBm): Device far away (different room)
• No signal (-100+ dBm): Device out of range or powered off

Signal Processing

The app uses advanced signal processing to distinguish between:

• You walking away: Gradual signal degradation
• Normal movement: Small signal fluctuations (wrist movement, shifting in chair)
• Temporary interference: Brief signal drops that recover quickly
• Device powered off: Sudden signal loss without degradation

This prevents false triggers when you're just moving around normally.

State Machine

The app tracks three device states:

1. Present (Green dot): Device is in range with good signal
2. Weak Signal (Red dot): Signal is degrading but device still detected
3. Absent (Red dot): Device is out of range or signal lost

Note: Both Weak Signal and Absent states show a red indicator. The difference is internal - Weak Signal means the device is still being detected but below threshold, while Absent means no signal is received at all.

Shortcuts are triggered when transitioning between these states, with configurable delay to further prevent false triggers.

Setup Guide

Prerequisites

• macOS 14.0 or later
• iPhone or Apple Watch signed in with same Apple ID as your Mac
• Bluetooth enabled on your Mac
• macOS Shortcuts app

Initial Configuration

1. Grant Bluetooth Permission

On first launch, you'll see a permission screen. Click "Continue" to grant permission. If you accidentally deny permission, you can grant it later in System Settings > Privacy & Security > Bluetooth.

2. Select Your Device

After granting permission, you'll see a list of nearby Bluetooth devices:

• iPhone: Usually shows as "Your Name's iPhone"
• Apple Watch: Usually shows as "Your Name's Apple Watch"
• Other devices: AirPods, keyboards, mice, etc.

Tip: Can't see your device? Make sure it's signed in with the same Apple ID as your Mac, Bluetooth is enabled, within range (same room), and not in Airplane Mode.

3. Adjust Proximity Threshold

The proximity threshold determines how close your device needs to be to be considered "present":

• Slider position: Drag left for less sensitive (device can be farther), right for more sensitive (device must be closer)
• Current value: Shows in dBm (e.g., "-65 dBm")
• Real-time feedback: Green dot = device present, red dot = device absent

Recommended starting point: -65 dBm (default)

4. Set Action Delay

The action delay is how long to wait before executing shortcuts after detecting a state change:

• Slider position: 1 to 90 seconds
• Purpose: Prevents false triggers from brief signal drops
• Recommended: 15 seconds for most users

Example: If set to 15 seconds, when you walk away, the app waits 15 seconds to confirm you're really gone before running the "away" shortcut.

5. Enable Auto-Adjust (Optional)

Auto-adjust automatically learns your device's typical signal strength and optimizes the threshold. See Advanced Features for details.

Features & Settings

Main Window

Device Status Section (Top)

• Status indicator: Green/orange/red dot showing device state
• Device name: Currently selected device
• Signal strength: Current RSSI in dBm
• Signal graph: Real-time visualization of signal strength over time

Device List Section (Middle)

• Available devices: All discovered Bluetooth devices
• Selection: Click checkbox to select a device
• Auto-refresh: List updates automatically as devices appear/disappear

Controls Section (Bottom)

• Proximity threshold: Slider to adjust sensitivity
• Auto-adjust: Toggle and slider for automatic threshold optimization
• Action delay: How long to wait before executing shortcuts
• Settings button: Opens settings panel
• Quit button: Exits the app

Settings Panel

Click the gear icon (⚙️) to access settings:

Launch at Login

Toggle: Start ProximityShortcuts automatically when you log in. Recommended - Enable so you don't have to manually launch the app each time you restart your Mac.

Kalman Filter Presets

ProximityShortcuts uses Kalman filtering to distinguish genuine movement from signal noise. These presets control how aggressively the filter balances detection speed vs reliability:

• Responsive: Reacts immediately to signal changes. Best when you need quick responses, but may occasionally trigger on brief interference or signal fluctuations.
• Balanced (Recommended): Filters out most signal noise while maintaining good responsiveness. Good for typical everyday use.
• Stable: Heavily filters signal noise, requiring clear and sustained changes before acting. Prevents false triggers but takes longer to react.

Tip: Start with Balanced. If you experience false triggers from brief interference, switch to Stable. If detection feels too slow, try Responsive.

Device Went Away

• Toggle: Enable/disable away shortcut
• Shortcut name: Name of the shortcut to run when device goes away
• Skip when screen is locked: Prevent execution if Mac is already locked
• Skip on sudden signal loss: Prevent execution if signal disappears suddenly (device powered off, interference) rather than gradually (walking away)

Device Is Back

• Toggle: Enable/disable back shortcut
• Shortcut name: Name of the shortcut to run when device returns
• Skip when screen is locked: Prevent execution if Mac is locked

Settings Profiles

Settings Profiles allow you to save and quickly switch between different monitoring configurations. Perfect for managing multiple scenarios like "Work", "Home", or "Travel" without manually reconfiguring all settings each time.

What Are Profiles?

A profile saves all your current settings including:

• Proximity threshold and action delay
• Auto-threshold configuration (enabled, aggressiveness, min/max bounds)
• Detection mode (Responsive/Balanced/Stable)
• Shortcut actions (away/back shortcuts and their names)
• Shortcut preferences (screen lock prevention, sudden signal loss detection)
• Action delays for away/back shortcuts

Creating a Profile

1. Configure your settings exactly how you want them for this scenario
2. Click Settings (gear icon)
3. Scroll to Settings Profiles section
4. Click Create New button
5. Enter a profile name (e.g., "Work", "Home")
6. Optionally add a description
7. Click Create

Managing Profiles

Switching Profiles

From Main Window: Click the Profile dropdown (below device list) and select the profile you want to apply. All settings instantly change to match that profile.

From Settings Panel: Find the profile in the list and click the Apply button.

Example Use Cases

Understanding the Interface

Signal Graph

The signal graph shows real-time signal strength over the last ~40 seconds:

• Blue line: Filtered signal strength (smoothed for stability)
• Orange dashed line: Current proximity threshold
• Y-axis: Signal strength in dBm (higher = stronger)
• X-axis: Time (right = most recent)

Reading the graph:

• Line above orange threshold = Device present (green indicator)
• Line below orange threshold = Device weak/absent (red indicator)
• Steep downward slope = Walking away
• Steep upward slope = Approaching
• Flat line = Stable signal

Status Indicators

Green Dot - Device Present

• Signal is above threshold
• Device is in range
• "Back" shortcuts can trigger when transitioning from weak/absent

Red Dot - Weak Signal or Absent

• Weak Signal: Signal is below threshold but still detected (transitional state)
• Absent: No signal detected or very weak signal (device out of range)
• "Away" shortcuts can trigger when transitioning from present to weak/absent

Orange Dot - Bluetooth Off

• Special indicator when Bluetooth is disabled on your Mac
• Enable Bluetooth in System Settings to use the app

Creating Shortcuts

ProximityShortcuts triggers shortcuts you create in the macOS Shortcuts app. Here's how to create effective shortcuts:

Opening Shortcuts App

1. Open Spotlight (⌘ + Space)
2. Type "Shortcuts"
3. Press Enter

Or find it in Applications folder.

Example: Lock Screen When Away

1. In Shortcuts app, click "+" to create new shortcut
2. Name it "Lock Screen" (or whatever you entered in ProximityShortcuts settings)
3. Search for "Lock Screen" action
4. Drag it into your shortcut

Example: Smart Home Integration

Turn off lights when away:

1. Create shortcut named "Lights Off"
2. Add "Toggle Accessory or Scene" action (HomeKit)
3. Choose your "Away" scene

Testing Shortcuts

Before using with ProximityShortcuts:

1. Run the shortcut manually in Shortcuts app
2. Verify it does what you expect
3. Check for any permission prompts
4. Grant necessary permissions

Important: Shortcuts must be named exactly as entered in ProximityShortcuts settings (case-sensitive).

Troubleshooting

Device Not Appearing in List

Possible causes:

1. Device not signed in with same Apple ID
2. Bluetooth disabled on device
3. Device in Airplane Mode
4. Device too far away

Solutions:

1. Verify Apple ID on both devices
2. Enable Bluetooth in device settings
3. Disable Airplane Mode
4. Move device closer to Mac
5. Wait 30 seconds for scan to complete

Shortcuts Not Executing

Check these:

1. Shortcut name matches exactly - Open Shortcuts app, verify name matches what you entered in settings (case-sensitive)
2. Shortcut works manually - Run shortcut in Shortcuts app, fix any errors before using with ProximityShortcuts
3. Permissions granted - Some shortcuts need permissions (HomeKit, Music, etc.), run manually first to grant permissions
4. Screen lock prevention - If "Skip when screen is locked" is enabled, shortcuts won't run when Mac is locked

False Triggers

Symptoms: Away shortcut runs when you're still at desk, or back shortcut runs when you haven't returned.

Solutions:

1. Increase action delay - Settings → Action delay slider, try 20-30 seconds instead of 15
2. Adjust threshold - Make it less sensitive (move slider left) or enable auto-adjust
3. Enable "Skip on sudden signal loss" - Settings → Device Went Away → Enable to prevent false triggers from interference
4. Check signal graph - Watch the graph while moving around to ensure threshold is appropriate

Advanced Features

Auto-Adjust Feature

Auto-adjust automatically optimizes the proximity threshold based on your device's typical signal strength.

How It Works

1. Learning Phase (first 40 seconds) - Collects signal samples when device is present, requires 20 samples minimum, shows "Learning... (X/20)" status
2. Calculation - Analyzes collected samples, selects appropriate percentile based on slider position, adds safety buffer, updates every 30 seconds
3. Continuous Adaptation - Maintains 3-minute rolling window of signal history, recalculates threshold every 30 seconds, adapts to changing conditions

Aggressiveness Slider

Controls how aggressively the threshold adapts to your device's signal:

Signal Loss Classification

The app can distinguish between different types of signal loss:

• Sudden Signal Loss: Signal was strong and stable, then suddenly disappeared. Likely causes: Device powered off, interference, Bluetooth issue. Not caused by walking away.
• Gradual Signal Loss: Signal showed declining trend, degraded over several seconds. Likely cause: Walking away with device.

Enable "Skip on sudden signal loss" to prevent away shortcuts from running when signal disappears suddenly. Recommended if you experience false triggers from temporary Bluetooth issues.

Best Practices

Device Selection

iPhone vs Apple Watch:

• iPhone: Stronger, more stable signal. Better for desk/pocket scenarios. Faster detection. May not always be with you.
• Apple Watch: Always on your wrist. More reliable presence indicator. Often weaker, more variable signal. Needs auto-adjust set to Tolerant mode.

Recommendation: Use iPhone if it's always with you (enable auto-adjust with Stable mode for better detection). Use Apple Watch if you always wear it (enable auto-adjust with Tolerant mode to handle signal variations).

Threshold Configuration

Start with defaults:

1. Use -65 dBm threshold
2. Use 15-second action delay
3. Enable auto-adjust after testing

Adjust based on experience:

• Too many false triggers → Increase delay or enable "Skip on sudden signal loss"
• Too slow to detect → Decrease delay or adjust threshold
• Signal varies a lot → Enable auto-adjust with "Tolerant" setting

Shortcut Design

Keep shortcuts simple:

• Single action shortcuts are most reliable
• Test shortcuts manually before using
• Avoid shortcuts that require user interaction

Privacy & Security

ProximityShortcuts only requires Bluetooth access on your Mac. All processing happens locally - no data is stored or sent anywhere. The app runs in macOS sandbox with restricted permissions, only having access to Bluetooth. All processing happens locally on your Mac.

FAQ

General Questions

Technical Questions

Profile Questions

Troubleshooting Questions

Support & Resources

Reporting Issues

When reporting issues, include:

1. macOS version
2. Device type (iPhone/Watch model)
3. Steps to reproduce
4. Relevant log messages from Console app
5. Screenshots if applicable

For support inquiries, email [email protected]

Learning More

About Bluetooth Low Energy:
Bluetooth SIG - BLE Overview

About macOS Shortcuts:
Apple Support - Shortcuts User Guide

Appendix

RSSI Reference Chart

Default Settings

System Requirements

• macOS: 14 or later
• Device: iPhone or Apple Watch with iOS/watchOS 14 or later
• Shortcuts: macOS Shortcuts app (pre-installed)

Glossary

BLE (Bluetooth Low Energy)

Low-power version of Bluetooth designed for IoT devices and continuous monitoring.

dBm (Decibel-milliwatts)

Unit of measurement for signal strength. Higher (less negative) values indicate stronger signals.

RSSI (Received Signal Strength Indicator)

Measurement of Bluetooth signal strength in dBm.

Kalman Filter

Mathematical algorithm that smooths noisy sensor data to provide stable, accurate readings.

Threshold

The RSSI value that determines whether a device is considered "present" or "absent".

Profile

Saved configuration containing all app settings that can be quickly applied.