_{Official ZPE/YASS documentation}BluetoothDevice

Represents a connected Bluetooth Low Energy device. Use BluetoothDevice::available() and BluetoothDevice::scan() to discover devices, then construct one directly to use its GATT services and characteristics.

Availability: ZPE 1.14.11 is the first version to support the BluetoothDevice object. Scanning and device operations require permission level 4; available() may be called at any level.

Discovery and construction

Discovery is provided by the object itself; there is no Bluetooth module. The constructor uses the default 15-second connection timeout and accepts an optional YAML template path.

$device = new BluetoothDevice("device-identifier")

Public properties

identifier contains the identifier used to connect to the device. template contains the loaded template path when a YAML template was supplied.

Static functions

These functions are called on the object type itself and do not require a connected device instance.

• available [1.14.11+]

  Returns whether native Bluetooth Low Energy discovery is available on this platform.

• scan [1.14.11+]

  Scans for nearby Bluetooth Low Energy devices, optionally filtering the results.

Instance functions

The following functions provide connection management, GATT discovery, binary communication, and notification handling for a connected device.

• _construct [1.14.11+]

  Connects directly to a Bluetooth Low Energy device using exactly one identifier argument. Templates are not accepted by the constructor.

• characteristics [1.14.11+]

  Returns the characteristics discovered for a service UUID, including their UUIDs and supported properties.

• disconnect [1.14.11+]

  Disconnects from the Bluetooth device and releases its native connection.

• is_connected [1.14.11+]

  Returns whether the Bluetooth device is still connected.

• load_template [1.14.11+]

  Loads a YAML Bluetooth template and adds its actions to this device instance.

• notify [1.14.11+]

  Enables or disables notifications for a characteristic. Notifications are enabled by default when the optional flag is omitted.

• on_notification [1.14.11+]

  Registers a callback that receives notification maps asynchronously.

• read [1.14.11+]

  Reads a characteristic and returns its value as a ByteStream.

• read_notification [1.14.11+]

  Waits for the next notification and returns a map containing the service, characteristic, and data.

• services [1.14.11+]

  Returns the discovered services as a list of maps containing UUID and primary status.

• write [1.14.11+]

  Writes a ByteStream or list of byte values to a characteristic. The optional final argument selects whether the write requests a response.

Discover services and characteristics

$device = new BluetoothDevice("device-identifier")
$services = $device->services()
for ($service in $services)
  print($service)
  print($device->characteristics($service["uuid"]))
end for

Read and write binary data

read() returns a ByteStream. A write can use a list of byte values or a ByteStream. Set the optional final argument to false for a write without response.

$service = "22BB746F-2BA0-7554-2D6F-726568705327"
$characteristic = "22BB746F-2BA1-7554-2D6F-726568705327"
$value = $device->read($service, $characteristic)
$device->write($service, $characteristic, [1, 2, 3], false)

Notifications

Call notify() to enable notifications on a characteristic. Use read_notification() when the program should wait synchronously, or register a function with on_notification() for asynchronous delivery. Notification maps contain service, characteristic, and data.

function received($notification)
  print($notification["data"])
end function

$device->notify($service, $characteristic)
$device->on_notification(received)

YAML device templates

A template gives a connected device named actions. The service and characteristic values identify the default command endpoint. setup contains writes performed when the template is loaded. Each action has an id and a byte data payload. params is optional; when present, it explicitly declares the action's numeric parameters. A placeholder in data must be declared in params and supplied when the action is called—parameters are never inferred.

name: SpheroBB8

service: 22BB746F-2BA0-7554-2D6F-726568705327
characteristic: 22BB746F-2BA1-7554-2D6F-726568705327

setup:
  - [22BB746F-2BB0-7554-2D6F-726568705327, 22BB746F-2BBD-7554-2D6F-726568705327, "011i3"]
  - [22BB746F-2BB2-7554-2D6F-726568705327, 22BB746F-2BBF-7554-2D6F-726568705327, [1]]

actions:
  move:
    id: 48
    params: [speed]
    data: [speed, 0, 0, 1]
  stop:
    id: 48
    data: [0, 0, 0, 1]

After loading this template, the device exposes move(speed) and stop() as actions. A template may be supplied to the constructor or loaded later with load_template().

Disconnect

$device->disconnect()