Bluetooth Access

Bluetooth Access

Bluetooth access is used for BLE sensors, controllers, audio accessories, serial devices, and paired peripherals. WendyOS keeps Bluetooth interfaces unavailable to apps unless the app declares a Bluetooth entitlement.

Add the entitlement from your project directory:

wendy project entitlements add bluetooth

If your app needs a specific Bluetooth mode, use the detailed entitlement options:

wendy project entitlements add bluetooth --mode kernel
wendy project entitlements add bluetooth --mode bluez

Use kernel for low-level HCI socket access. Use bluez for standard Linux Bluetooth workflows through BlueZ.

Scan for Devices

Run the Bluetooth command without subcommands to open an interactive table for browsing and managing peripherals:

wendy device bluetooth

The table shows device name, address, type, pairing state, and connection state. Use arrow keys to navigate, enter to connect, d to disconnect, f to forget, r to rescan, and q to quit.

For scripting or CI, use the list subcommand:

wendy device bluetooth list

Connect and Pair

In the interactive table, select a device and press enter to connect.

To connect from a script, specify the address:

wendy device bluetooth connect AA:BB:CC:DD:EE:FF

By default, the CLI pairs and trusts the device. You can disable either behavior:

wendy device bluetooth connect AA:BB:CC:DD:EE:FF --pair=false --trust=false

Disconnect without forgetting the pairing:

wendy device bluetooth disconnect AA:BB:CC:DD:EE:FF

Or select the connected device in the interactive table and press d.

Forget a paired device:

wendy device bluetooth forget AA:BB:CC:DD:EE:FF

Or select the paired device in the interactive table and press f.

Audio Peripherals

A trusted speaker, headset, or microphone reconnects on its own in the cases that matter for an unattended device:

Reconnection after a reboot happens once per boot, and only for peripherals that are trusted — the default when you connect with wendy device bluetooth connect. It will not undo a deliberate disconnect, and it waits for the audio stack to be ready, so on a Raspberry Pi expect it a minute or two after boot rather than immediately.

At most one output and one input are reconnected automatically. Connect any others yourself.

Playback and capture need the audio entitlement, not just bluetooth; see Speaker Access and Microphone Access.

App Configuration

A minimal Bluetooth app uses:

{
  "appId": "com.example.bluetooth",
  "platform": "linux",
  "version": "1.0.0",
  "entitlements": [
    { "type": "bluetooth", "mode": "bluez" }
  ]
}

Then deploy:

wendy run