Device Tools

Tools for managing Bluetooth device lifecycle — discovery, pairing, connection, and trust.

bt_list_devices

List known Bluetooth devices.

Parameters:

Name	Type	Required	Default	Description
adapter	string	Yes	-	Adapter name
filter	string	No	”all”	Filter: “all”, “paired”, “connected”, “trusted”

Returns:

[
  {
    "address": "AA:BB:CC:DD:EE:FF",
    "name": "My Headphones",
    "alias": "Work Headphones",
    "paired": true,
    "connected": true,
    "trusted": true,
    "blocked": false
  }
]

Example:

bt_list_devices adapter="hci0" filter="paired"

---

bt_device_info

Get detailed information about a specific device.

Parameters:

Name	Type	Required	Description
adapter	string	Yes	Adapter name
address	string	Yes	Device MAC address

Returns:

{
  "address": "AA:BB:CC:DD:EE:FF",
  "name": "Bose NCH700",
  "alias": "My Headphones",
  "class": 2360344,
  "icon": "audio-headphones",
  "paired": true,
  "bonded": true,
  "trusted": true,
  "blocked": false,
  "connected": true,
  "legacy_pairing": false,
  "rssi": -55,
  "uuids": [
    "0000110b-0000-1000-8000-00805f9b34fb",
    "0000110e-0000-1000-8000-00805f9b34fb"
  ],
  "modalias": "bluetooth:v009Ep4020d0134",
  "adapter": "/org/bluez/hci0"
}

Example:

bt_device_info adapter="hci0" address="AA:BB:CC:DD:EE:FF"

---

bt_device_set_alias

Set a friendly name for a device.

Parameters:

Name	Type	Required	Description
adapter	string	Yes	Adapter name
address	string	Yes	Device MAC address
alias	string	Yes	New friendly name

Returns: Updated device info

Example:

bt_device_set_alias adapter="hci0" address="AA:BB:CC:DD:EE:FF" alias="Work Headphones"

---

bt_pair

Initiate pairing with a device.

Parameters:

Name	Type	Required	Default	Description
adapter	string	Yes	-	Adapter name
address	string	Yes	-	Device MAC address
pairing_mode	string	No	”interactive”	Mode: “interactive”, “auto”, “elicit”
timeout	integer	No	60	Pairing timeout in seconds

Pairing Modes:

• interactive — Returns status; use bt_pair_confirm to respond to prompts
• auto — Auto-accepts all requests (trusted environments only)
• elicit — Uses MCP elicitation for PIN prompts (if supported)

Returns:

{
  "status": "paired",
  "address": "AA:BB:CC:DD:EE:FF",
  "name": "My Device"
}

Or if confirmation needed:

{
  "status": "awaiting_confirmation",
  "method": "numeric_comparison",
  "passkey": 123456
}

Example:

bt_pair adapter="hci0" address="AA:BB:CC:DD:EE:FF" pairing_mode="interactive"

---

bt_pair_confirm

Confirm or reject a pairing request.

Parameters:

Name	Type	Required	Default	Description
adapter	string	Yes	-	Adapter name
address	string	Yes	-	Device MAC address
accept	boolean	No	true	Accept or reject pairing
pin	string	No	-	PIN code if required
passkey	integer	No	-	Numeric passkey (0-999999)

Returns:

{
  "status": "paired",
  "address": "AA:BB:CC:DD:EE:FF"
}

Example:

# Accept with passkey
bt_pair_confirm adapter="hci0" address="AA:BB:CC:DD:EE:FF" passkey=123456 accept=true

# Reject pairing
bt_pair_confirm adapter="hci0" address="AA:BB:CC:DD:EE:FF" accept=false

---

bt_pairing_status

Get status of pending pairing requests.

Parameters: None

Returns:

{
  "pending_requests": [
    {
      "address": "AA:BB:CC:DD:EE:FF",
      "method": "passkey_entry",
      "timestamp": "2024-01-15T10:30:00"
    }
  ]
}

Example:

bt_pairing_status

---

bt_unpair

Remove pairing with a device.

Parameters:

Name	Type	Required	Description
adapter	string	Yes	Adapter name
address	string	Yes	Device MAC address

Returns:

{
  "status": "unpaired",
  "address": "AA:BB:CC:DD:EE:FF"
}

Example:

bt_unpair adapter="hci0" address="AA:BB:CC:DD:EE:FF"

Notes:

• Removes device from known devices
• Deletes all stored pairing information
• Device must be re-paired to connect again

---

bt_connect

Connect to a paired device.

Parameters:

Name	Type	Required	Description
adapter	string	Yes	Adapter name
address	string	Yes	Device MAC address

Returns: Updated device info with connected: true

Example:

bt_connect adapter="hci0" address="AA:BB:CC:DD:EE:FF"

Notes:

• Device must be paired first
• For audio devices, also connects audio profiles

---

bt_disconnect

Disconnect from a device.

Parameters:

Name	Type	Required	Description
adapter	string	Yes	Adapter name
address	string	Yes	Device MAC address

Returns:

{
  "status": "disconnected",
  "address": "AA:BB:CC:DD:EE:FF"
}

Example:

bt_disconnect adapter="hci0" address="AA:BB:CC:DD:EE:FF"

Notes:

• Preserves pairing (device can reconnect)
• Use bt_unpair to fully remove device

---

bt_trust

Set device trust status.

Parameters:

Name	Type	Required	Description
adapter	string	Yes	Adapter name
address	string	Yes	Device MAC address
trusted	boolean	Yes	Trust state

Returns: Updated device info

Example:

# Trust device (auto-connect allowed)
bt_trust adapter="hci0" address="AA:BB:CC:DD:EE:FF" trusted=true

# Untrust device
bt_trust adapter="hci0" address="AA:BB:CC:DD:EE:FF" trusted=false

Notes:

• Trusted devices can connect automatically
• Untrusted devices require explicit connection

---

bt_block

Block or unblock a device.

Parameters:

Name	Type	Required	Description
adapter	string	Yes	Adapter name
address	string	Yes	Device MAC address
blocked	boolean	Yes	Block state

Returns: Updated device info

Example:

# Block device
bt_block adapter="hci0" address="AA:BB:CC:DD:EE:FF" blocked=true

# Unblock device
bt_block adapter="hci0" address="AA:BB:CC:DD:EE:FF" blocked=false

Notes:

• Blocked devices cannot connect
• Existing connection is terminated when blocked