Dbochman/bluetooth

Bluetooth & Audio Control

Control Bluetooth devices and audio routing on the Mac Mini (macOS Tahoe 26.x).

Known Devices

| Name | MAC Address | Type | |------|-------------|------| | Kitchen speaker | ${KITCHEN_SPEAKER_MAC} | Audio | | Magic Keyboard with Numeric Keypad | ${MAGIC_KEYBOARD_MAC} | Keyboard | | Magic Trackpad 2 | ${MAGIC_TRACKPAD_MAC} | Trackpad |

Important: macOS Tahoe Workaround

On macOS 26.x, the IOBluetooth API reports wrong power/connection state over SSH. All connect/disconnect operations must run via open /tmp/bt_op.command which launches in the GUI (Aqua) session where IOBluetooth works correctly.

Read operations (list devices, check status, audio switching) work directly over SSH via system_profiler and SwitchAudioSource.

Connect a Bluetooth Device

ssh dylans-mac-mini "echo 'connect ${KITCHEN_SPEAKER_MAC}' > /tmp/bt_command.txt && rm -f /tmp/bt_result.txt /tmp/bt_exit.txt && open /tmp/bt_op.command && sleep 12 && cat /tmp/bt_exit.txt"

Exit code 0 = success. Wait 12 seconds for the Bluetooth connection to establish.

Connect + Switch Audio (Full Pattern)

ssh dylans-mac-mini "echo 'connect ${KITCHEN_SPEAKER_MAC}' > /tmp/bt_command.txt && rm -f /tmp/bt_result.txt /tmp/bt_exit.txt && open /tmp/bt_op.command"
sleep 12
ssh dylans-mac-mini "export PATH=/opt/homebrew/bin:\$PATH && SwitchAudioSource -s 'Kitchen speaker' -t output"

Disconnect a Bluetooth Device

ssh dylans-mac-mini "echo 'disconnect ${KITCHEN_SPEAKER_MAC}' > /tmp/bt_command.txt && rm -f /tmp/bt_result.txt /tmp/bt_exit.txt && open /tmp/bt_op.command && sleep 12 && cat /tmp/bt_exit.txt"

Disconnect + Reset Audio

ssh dylans-mac-mini "export PATH=/opt/homebrew/bin:\$PATH && SwitchAudioSource -s 'Mac mini Speakers' -t output"
ssh dylans-mac-mini "echo 'disconnect ${KITCHEN_SPEAKER_MAC}' > /tmp/bt_command.txt && rm -f /tmp/bt_result.txt /tmp/bt_exit.txt && open /tmp/bt_op.command"

List Paired Devices

ssh dylans-mac-mini "system_profiler SPBluetoothDataType -json" | python3 -c "
import json, sys
data = json.load(sys.stdin)
bt = data.get('SPBluetoothDataType', [{}])[0]
for section in ['device_connected', 'device_not_connected']:
    devices = bt.get(section, [])
    if isinstance(devices, list):
        for group in devices:
            if isinstance(group, dict):
                for name, props in group.items():
                    connected = 'Yes' if section == 'device_connected' else 'No'
                    addr = props.get('device_address', '?')
                    print(f'{name}: {addr} connected={connected}')
"

Check Device Connection Status

ssh dylans-mac-mini "system_profiler SPBluetoothDataType 2>&1 | grep -B2 'Kitchen speaker'"

If it appears under "Connected:" it's connected. Under "Not Connected:" it's not.

Audio Output Control

These work directly over SSH (no GUI workaround needed).

List Audio Outputs

ssh dylans-mac-mini "export PATH=/opt/homebrew/bin:\$PATH && SwitchAudioSource -a -t output"

Check Current Audio Output

ssh dylans-mac-mini "export PATH=/opt/homebrew/bin:\$PATH && SwitchAudioSource -c -t output"

Switch Audio Output

# To Kitchen speaker
ssh dylans-mac-mini "export PATH=/opt/homebrew/bin:\$PATH && SwitchAudioSource -s 'Kitchen speaker' -t output"

# To Mac Mini speakers
ssh dylans-mac-mini "export PATH=/opt/homebrew/bin:\$PATH && SwitchAudioSource -s 'Mac mini Speakers' -t output"

Mute / Unmute

ssh dylans-mac-mini "export PATH=/opt/homebrew/bin:\$PATH && SwitchAudioSource -m toggle"
ssh dylans-mac-mini "export PATH=/opt/homebrew/bin:\$PATH && SwitchAudioSource -m mute"
ssh dylans-mac-mini "export PATH=/opt/homebrew/bin:\$PATH && SwitchAudioSource -m unmute"

Check Bluetooth Power

ssh dylans-mac-mini "system_profiler SPBluetoothDataType 2>&1 | grep 'State:'"

How It Works

The /tmp/bt_op.command file is a shell script that:

1. Reads the command from /tmp/bt_command.txt
2. Runs blueutil --connect or --disconnect with the MAC address
3. Writes exit code to /tmp/bt_exit.txt
4. Auto-closes its Terminal window

Using open to launch it ensures it runs in the macOS GUI session where blueutil has proper IOBluetooth API access and TCC (Bluetooth) permission.

Troubleshooting

• Connect/disconnect hangs or fails over direct SSH: Use the open /tmp/bt_op.command pattern instead. Direct SSH calls to blueutil fail on Tahoe because IOBluetooth reports power=0.
• blueutil --paired returns empty: Use BLUEUTIL_USE_SYSTEM_PROFILER=1 blueutil --paired or system_profiler SPBluetoothDataType.
• Audio not switching after connect: Wait 5-10 seconds after connect for the audio device to register in CoreAudio, then call SwitchAudioSource.
• Speaker not connecting: Make sure the speaker is powered on and in range. Check system_profiler for RSSI signal strength.

Files on Mac Mini

| Path | Purpose | |------|---------| | /tmp/bt_op.command | Reusable GUI-session launcher for blueutil | | /tmp/bt_command.txt | Input: command + MAC address | | /tmp/bt_result.txt | Output: command result | | /tmp/bt_exit.txt | Output: exit code | | ~/.openclaw/bin/bt_connect | Swift IOBluetooth helper (used by launchd agent) | | ~/Library/LaunchAgents/com.openclaw.bt-connect.plist | LaunchAgent for Bluetooth ops |