Skip to main content

Quick Start

Get B.R.I.O.S. up and running in under 5 minutes.

Important: About Distance Accuracy

B.R.I.O.S. estimates distance using RSSI (Received Signal Strength Indicator) and a Log-Distance Path Loss Model. This is the best approach available with the Bluetooth hardware built into consumer Macs — however, RSSI-based distance estimation is inherently imprecise.

Factors that affect accuracy include:

  • Physical obstacles (walls, furniture, people)
  • Device orientation and antenna position
  • Radio interference from Wi-Fi, microwaves, other Bluetooth devices
  • Multipath propagation (signal reflections off surfaces)
  • Body absorption when the device is in a pocket

Unlike UWB (Ultra-Wideband) or Time-of-Flight chips, Bluetooth RSSI does not measure distance directly — it infers it from signal attenuation. Expect typical accuracy of ±0.5–1.0 meters in real-world conditions.

For best results, calibrate your setup by measuring TX_POWER_AT_1M and adjusting PATH_LOSS_EXPONENT for your specific environment. See the Configuration Reference for details.

Step 1: Discover Your Device​

First, scan for nearby BLE devices to find your target device's MAC address:

brios --scanner 15 -m
  • --scanner 15 scans for 15 seconds (range: 5–60s).
  • -m uses real MAC addresses instead of macOS privacy UUIDs (recommended).

Example output:

🥐 B.R.I.O.S. Device Scanner
──────────────────────────────────────────────────────────────────────
Duration:   15 seconds
Mode:       BD_ADDR (MAC addresses)
──────────────────────────────────────────────────────────────────────

● Scanning...

Scan Results (3 devices found)
──────────────────────────────────────────────────────────────────────
 1. iPhone                         │ AA:BB:CC:DD:EE:FF │  -52 dBm │ ~ 0.85m
 2. AirPods Pro                    │ 11:22:33:44:55:66 │  -68 dBm │ ~ 2.10m
 3. (Unknown)                      │ 77:88:99:AA:BB:CC │  -85 dBm │ ~ 6.30m

Note the MAC address of your target device from the output.

Step 2: Configure​

Create a .env configuration file. B.R.I.O.S. loads configuration from these locations (in order):

  1. .env in the current working directory
  2. ~/.brios.env
  3. ~/.brios/config or ~/.brios/.env
  4. ~/.config/brios/config

Create a ~/.brios.env file with your device settings:

cat > ~/.brios.env << 'EOF'
# Target Device
TARGET_DEVICE_MAC_ADDRESS=AA:BB:CC:DD:EE:FF
TARGET_DEVICE_NAME=My iPhone
TARGET_DEVICE_TYPE=phone

# Distance & Signal (calibrate for your environment)
DISTANCE_THRESHOLD_M=2.0
TX_POWER_AT_1M=-59
PATH_LOSS_EXPONENT=2.8
SAMPLE_WINDOW=12
EOF

Replace AA:BB:CC:DD:EE:FF with the MAC address from Step 1, and adjust the signal parameters as needed for your environment (see Configuration).

Using the Example Configuration​

If installed via Homebrew:

cp $(brew --prefix brios)/share/brios/.env.example ~/.brios.env

If installed from source:

cp .env.example ~/.brios.env

Then edit ~/.brios.env with your device's MAC address.

Step 3: Start Monitoring​

Foreground Mode (Interactive)​

Run B.R.I.O.S. in the foreground with verbose output:

brios --target-mac -v

You will see real-time RSSI readings, smoothed signal values, and distance estimates:

Starting 🥐 B.R.I.O.S. Monitor
──────────────────────────────────────────────────────
Target:     iPhone (phone)
Address:    AA:BB:CC:DD:EE:FF
Threshold:  2.0m
TX Power:   -59 dBm @ 1m
Path Loss:  2.8
Samples:    12 readings
──────────────────────────────────────────────────────

● Monitoring active - Press Ctrl+C to stop

[14:32:01] RSSI:  -52 dBm → Smoothed: -53.2 dBm │ Distance:  0.85m │ Signal: Strong
[14:32:02] RSSI:  -55 dBm → Smoothed: -53.8 dBm │ Distance:  0.92m │ Signal: Strong

Quick Start (Auto-Resolve from .env)​

If your .env file is fully configured with a target address, you can simply run:

brios --start

B.R.I.O.S. will automatically resolve the target device from your configuration and start as a background daemon.

Background Mode (Daemon)​

Start B.R.I.O.S. as a background service with explicit flags:

brios --target-mac -v -f --start

Check status:

brios --status

Stop the service:

brios --stop

What Happens When You Walk Away​

  1. Signal weakens — RSSI drops as you move away from your Mac.
  2. Distance exceeds threshold — When the estimated distance surpasses DISTANCE_THRESHOLD_M (default: 2.0m), B.R.I.O.S. triggers a lock.
  3. Mac locks — The screen locks immediately via pmset displaysleepnow.
  4. Grace period — After you unlock, a configurable grace period (default: 30s) prevents immediate re-locking while the signal stabilizes.
  5. Monitoring resumes — B.R.I.O.S. continues tracking automatically.

Next Steps​