GitHub - philocalyst/blueboy: Manage your bluetooth devices on the command line!

5 min read Original article ↗

Welcome to BlueBoy

Swift Version Apple Platform

BlueBoy(bboy) is a command-line utility for controlling Bluetooth on macOS. Who doesn't hate clicking through out-of-the way, poorly-designed, swiftUI menus on macOS? Here, we love the CLI. You may have heard of blueutil? This is its spirtual successor. It provides a simple and effective way to manage Bluetooth devices, check system states, and list available, paired, or connected devices directly from your terminal. Very powerful for automation.

With a modern CLI interface with slightly more readable errors, this is the beginnning of a bright future for bluetooth management on macOS. It uses a whole new high-level bluetooth library that you can integrate into your own app. So hip hip hooray for bluetooth!

A note on feature-parity with blueutil: there are some hyper-private frameworks that blueutil uses that I haven't been able to get to work here. This means all of the set methods, and the discoverability getter. If you happen to be skilled in briding obj-c and swift, and especially interfacing with private frameworks from Swift, please open a PR, or shoot me an email!

Brief Summary

bboy allows users to interact with macOS Bluetooth functionalities such as:

  • Querying Bluetooth power state.
  • Listing paired, connected, or discoverable devices.
  • Getting detailed information about specific devices.
  • Connecting to, disconnecting from, pairing with, and unpairing devices.
$ bboy list paired
Address: 00-11-22-33-44-55, Name: My Bluetooth Keyboard, Connected: Yes, RSSI: -50 dbm, Incoming: No
Address: AA-BB-CC-DD-EE-FF, Name: My Bluetooth Mouse, Connected: Yes, RSSI: -65 dbm, Incoming: No

Get Started

Get started by following the installation instructions below. Once installed, you can explore the available commands and options.

Tutorial

bboy follows a standard command-line structure:

bboy [global-options] <subcommand> [subcommand-options-and-arguments]

Global Options:

  • --debug: Enable debug logging for more detailed output.
  • --verbose: Enable verbose logging (implies debug) for maximum output.

Core Subcommands:

1. get: Get Bluetooth system states

Used to retrieve system-level Bluetooth information.

  • Get Power State: Check if Bluetooth is currently powered on. Outputs 1 for on, 0 for off. If no specific state is requested, it will prompt you: 
    $ bboy get
No state retrieval specified

2. list: List Bluetooth devices

This command has several sub-subcommands to list different categories of devices. If no sub-subcommand is specified, it defaults to list paired.

  • List Paired Devices (list paired - default): Shows all devices that are paired with your Mac.

    bboy list
bboy list paired

    Output includes Address, Name, Connected status, RSSI, and Incoming status.

  • List Connected Devices (list connected): Shows only the devices currently connected to your Mac.

    Output includes Address, Name, RSSI, Paired status, and Incoming status.

  • Inquire Devices in Range (list in-range): Scans for nearby Bluetooth devices.

    By default, it scans for 10 seconds. You can specify a custom duration:

    bboy list in-range <duration_in_seconds>
# Example: Scan for 15 seconds
bboy list in-range 15

    Output includes Address, Name, Connected status, RSSI, Paired status, and Incoming status.

3. device: Manage Bluetooth devices

Interact with specific Bluetooth devices using their ID (MAC address or name).

  • Device Actions: The device command takes a device ID and an action to perform.

    • info: Show detailed information for a device.

      bboy device <device_id> info
# Example: bboy device 00-11-22-33-44-55 info
# Example: bboy device "My Bluetooth Keyboard" info

    • is-connected: Check if a specific device is connected. Outputs 1 for connected, 0 for not connected.

      bboy device <device_id> is-connected

    • connect: Connect to a device.

      bboy device <device_id> connect

    • disconnect: Disconnect from a device.

      bboy device <device_id> disconnect

    • pair: Pair with a device. A PIN may be required for some devices.

      bboy device <device_id> pair
bboy device <device_id> pair --pin <your_pin>

    • unpair: Unpair a device.

      bboy device <device_id> unpair

Example Workflow:

  1. List paired devices:

    (Identify the device ID, e.g., AA-BB-CC-DD-EE-FF)

  2. Check if it's connected:

    bboy device AA-BB-CC-DD-EE-FF is-connected

  3. If not connected, connect to it:

    bboy device AA-BB-CC-DD-EE-FF connect

Design Philosophy

bboy aims to be:

  • Focused: A dedicated utility for macOS Bluetooth control.
  • Intuitive: Leveraging ArgumentParser for a clear and standard CLI experience.
  • Effective: Providing direct access to common Bluetooth operations.
  • Informative: Offering useful feedback and logging options for troubleshooting.

Building and Debugging

Building

  1. Ensure you have Xcode Command Line Tools installed.
  2. Clone the repository (if applicable) or navigate to the project directory.
  3. Build the project using Swift Package Manager:
    • For a debug build: The executable will be located at .build/debug/bboy.
    • For a release build: The executable will be located at .build/release/bboy.

Debugging

bboy includes logging flags to help with debugging:

  • --debug: Enables general debug messages.
  • --verbose: Enables more detailed verbose messages (implies debug). 
    bboy --verbose device <device_id> connect
    Logs are managed by bboyLogger and will be printed to standard error/output.

Install

Install from Homebrew

brew install philocalyst/tap/blueboy

Build from Source

Follow the Building instructions to create a release build:

Then, copy the executable to a directory in your PATH, for example /usr/local/bin:

sudo cp .build/release/bboy /usr/local/bin/

Ensure /usr/local/bin is in your shell's PATH environment variable.

Changelog

For a detailed list of changes, please see the CHANGELOG.md file.

Libraries Used

  • swift-argument-parser: For parsing command-line arguments.
  • swift-log: A Logging API for Swift.
  • BlueKit:A library for handling bluetooth interactions.
  • Foundation: Standard Apple framework.
  • IOBluetooth: Standard macOS framework for Bluetooth communication.

Acknowledgements

  • This tool builds upon the capabilities provided by Apple's CoreBluetooth and IOBluetooth frameworks.
  • Thanks to the Swift community for excellent tools and libraries (YAH).

License

This project is licensed under the [MIT] - see the LICENSE file for details.