Earbud Remote

A tiny Windows service that lets an iPhone Shortcut briefly turn a laptop's Bluetooth radio off and back on. The purpose is to release earbuds that automatically connected to the wrong Windows computer.

What it does

When the iPhone sends an authorized request:

1. Windows turns Bluetooth off.
2. It waits 2 seconds.
3. Windows turns Bluetooth back on.

This releases all Bluetooth connections on that laptop. No administrator privileges are required.

Requirements

• Windows 11
• Python 3.9+
• iPhone and laptop on the same local network
• A Windows Bluetooth adapter exposed through Windows.Devices.Radios

Install on each Windows laptop

Download/clone the whole repo, open PowerShell in the folder, and run:

python install.py

The installer will:

• install the required PyWinRT packages;
• create config.json with a random secret token;
• detect your current /24 home LAN;
• start Earbud Remote silently with pythonw.exe;
• add it to your Windows user startup so it starts when you sign in;
• print the exact iPhone Shortcut URL and token.

No Administrator terminal is needed.

If Windows Firewall asks about Python, allow Private networks only.

Important: laptop IP address

The Shortcut uses the laptop's local IP address. For long-term reliability, give each laptop a DHCP reservation in your router (recommended) or otherwise make its local IP stable.

Create the iPhone Shortcut

In Apple's Shortcuts app, create a shortcut named Release Earbuds.

For one laptop:

1. Add a URL action:

   http://LAPTOP_IP:8765/release
   

2. Add Get Contents of URL.
3. Set Method to POST.
4. Under Headers, add:
   • Key: X-Earbud-Token
   • Value: the token printed by install.py

Run the Shortcut. The laptop's Bluetooth should turn off for about 2 seconds and then return.

Two laptops

Repeat the URL + Get Contents of URL actions for Laptop 2.

Each laptop may use its own token. Put the matching token in that laptop's request header. If you prefer one shared token, manually set the same token value in both laptops' config.json files and restart both services.

Test / status

From a device on the allowed LAN, open:

http://LAPTOP_IP:8765/status

A healthy service returns JSON containing:

{
  "ok": true,
  "service": "Earbud Remote",
  "version": "1.0.0"
}

The log file is:

%LOCALAPPDATA%\EarbudRemote\earbud_remote.log

Configuration

install.py creates a private config.json:

{
  "token": "...",
  "allowed_network": "10.0.0.0/24",
  "port": 8765,
  "bluetooth_off_seconds": 2.0
}

config.json is excluded by .gitignore. Do not commit it.

After changing configuration, restart the background service (or restart Windows).

Security

• /release accepts only POST.
• Authentication uses the X-Earbud-Token header, not a token in the URL.
• Requests outside the configured LAN are rejected.
• The service exposes no arbitrary command-execution endpoint.
• Traffic is plain HTTP, so use this only on a trusted private LAN.
• Do not port-forward TCP 8765 or expose it to the public Internet.
• Keep config.json private.

Uninstall startup entry

Run:

python uninstall.py

This removes Earbud Remote from Windows auto-start. It does not delete your config or uninstall Python packages.

Notes

This intentionally toggles the entire Bluetooth radio, so Bluetooth mice, keyboards, controllers, and other devices on the laptop will disconnect briefly too.

Windows radio control can be limited by user permission, hardware capability, or system policy.

References

• Microsoft Windows.Devices.Radios.Radio: https://learn.microsoft.com/en-us/uwp/api/windows.devices.radios.radio
• Microsoft Radio.SetStateAsync: https://learn.microsoft.com/en-us/uwp/api/windows.devices.radios.radio.setstateasync
• Microsoft Run/RunOnce registry keys: https://learn.microsoft.com/en-us/windows/win32/setupapi/run-and-runonce-registry-keys
• PyWinRT winrt-Windows.Devices.Radios: https://pypi.org/project/winrt-Windows.Devices.Radios/

License

MIT