app.bluetooth - Bluetooth API

Query Bluetooth status, enumerate paired/connected devices, and listen for Bluetooth events.

Permission: L2 sensitive, requires system Bluetooth permission. The system will prompt for authorization on first use.

Methods

app.bluetooth.isEnabled()

Check whether Bluetooth is enabled.

Returns: boolean

if app.bluetooth.isEnabled() then
    app.log.info("Bluetooth is enabled")
end

app.bluetooth.pairedDevices()

Get the list of all paired Bluetooth devices.

Returns: array<table> - each item contains:

• name (string) - device name
• address (string) - device address
• isConnected (boolean) - whether currently connected

local devices = app.bluetooth.pairedDevices()
for _, d in ipairs(devices) do
    local status = d.isConnected and "Connected" or "Disconnected"
    app.log.info(d.name .. " (" .. d.address .. "): " .. status)
end

app.bluetooth.connectedDevices()

Get the list of currently connected Bluetooth devices.

Returns: array<table> - each item contains:

• name (string) - device name
• address (string) - device address

local devices = app.bluetooth.connectedDevices()
app.log.info("Connected devices: " .. #devices)
for _, d in ipairs(devices) do
    app.log.info(d.name .. " - " .. d.address)
end

app.bluetooth.watch(event, callback)

Watch for Bluetooth device events.

Parameters:

• event (string) - event name:
  • "deviceConnected" - fired when a device connects
  • "deviceDisconnected" - fired when a device disconnects
• callback (function) - callback function, receives an event table:
  • name (string) - device name
  • address (string) - device address

Returns: string, error - watcher handle ID

local handle, err = app.bluetooth.watch("deviceConnected", function(e)
    app.notification.show("Bluetooth", e.name .. " connected")
end)

local handle2 = app.bluetooth.watch("deviceDisconnected", function(e)
    app.log.info("Device disconnected: " .. e.name)
end)

app.bluetooth.stopAllWatchers()

Stop all Bluetooth watchers registered by the current plugin.

Returns: boolean

app.bluetooth.stopAllWatchers()

app.bluetooth.listWatchers()

List all Bluetooth watchers registered by the current plugin.

Returns: array<table> - each item contains:

• id (string) - watcher handle ID
• event (string) - event name being watched

local watchers = app.bluetooth.listWatchers()
for _, w in ipairs(watchers) do
    app.log.info(w.id .. " -> " .. w.event)
end

Description

• The Bluetooth API requires system Bluetooth permission; the user will be prompted to authorize on first use
• pairedDevices() returns all paired devices regardless of whether they are currently connected
• connectedDevices() returns only actively connected devices
• Watchers registered via watch() are automatically cleaned up when the plugin is unloaded; no need to call stopAllWatchers() manually
• Bluetooth events are fired on a background thread; avoid long-running operations inside callbacks

Examples

Monitor Headphone Connection Status

function MyPlugin:onLoad()
    app.bluetooth.watch("deviceConnected", function(e)
        -- Only care about headphone-type devices
        if e.name:find("AirPods") or e.name:find("Headphone") then
            app.audio.setVolume(0.5)
            app.notification.show("Headphones Connected", e.name .. " — volume adjusted")
        end
    end)

    app.bluetooth.watch("deviceDisconnected", function(e)
        if e.name:find("AirPods") or e.name:find("Headphone") then
            app.notification.show("Headphones Disconnected", e.name)
        end
    end)
end

Display Bluetooth Device Information

function MyPlugin:handleBluetoothInfo(context)
    if not app.bluetooth.isEnabled() then
        app.dialog.alert("Bluetooth", "Bluetooth is not enabled")
        return
    end

    local paired = app.bluetooth.pairedDevices()
    local connected = app.bluetooth.connectedDevices()

    local lines = {
        "Bluetooth Devices",
        "Paired: " .. #paired .. ", Connected: " .. #connected,
        "",
    }

    for _, d in ipairs(paired) do
        local status = d.isConnected and "[Connected]" or "[Disconnected]"
        table.insert(lines, status .. " " .. d.name)
    end

    app.dialog.alert("Bluetooth Devices", table.concat(lines, "\n"))
end