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.

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()