Bluetooth

The Bluetooth object allows communicating with nearby Bluetooth devices via the Web Bluetooth API.

You can find a simple example of using the Bluetooth object in the Bluetooth - device name example.

Specifying services and characteristics

When specifying services and characteristics in the Bluetooth object, there are a few ways of identifying them:

  • Use their standard e.g. "heart_rate" for the standard heart rate service. See the standard service names and standard characteristic names. Note the prefixes are omitted, e.g. org.bluetooth.characteristic.gap.device_name is specified just as gap.device_name in the Bluetooth object.
  • Use their 16-bit hexadecimal IDs e.g. "0x1802". These can also be found in the linked standard lists, or vendor-specific IDs used.
  • Use the full UUID, e.g. "c48e6067-5295-48d3-8d5c-0395f61792b1". This is usually used to refer to a vendor specific characteristic or service.

Where a standard service is specified as a UUID, Construct will turn it back in to its standard name, e.g. gap.device_name.

Device IDs can also usually be omitted: if left empty, the first connected device will be used.

Bluetooth conditions

Is device connected
Test if a bluetooth device is currently connected by its device ID.
Is supported
True if bluetooth is supported on the current platform. The plugin will not work if this is false.
On device connected
On device disconnected
Triggered as devices connect (after Request device completes successfully) and disconnect. The DeviceID expression is set to the ID of the relevant device.
On request device failed
Triggered after the Request device action if the user cancels or a Bluetooth connection was unable to be established.
On characteristic notification
On any characteristic notification
Triggered after starting notifications for a characteristic whenever a notification is received. The notification data is loaded in to the provided Binary Data object. The any variant is triggered for all characteristics rather than a specific one, and sets the CharacteristicID expression accordingly
On characteristic read
On any characteristic read
On any characteristic read error
Triggered after the Read value or Read binary actions that attempt to read a characteristic value. If the read fails the error trigger fires. The any variant is triggered for any characteristic that successfully completes a read rather than a specific one, and sets the CharacteristicID expression accordingly. Once the read completes successfully, the characteristic value expressions are set, or if binary was read the data is now available in the chosen Binary Data object.
On characteristic written
On any characteristic written
On characteristic write error
Triggered after the Write binary action after the operation completes. If the write fails the error trigger fires. The any variant is triggered for any characteristic that successfully completes a write rather than a specific one, and sets the CharacteristicID expression accordingly.
On charactersitics loaded
On characteristics error
Triggered after the Request characteristics action depending on the outcome. If successful the characteristic list is available with the CharacteristicCount and CharacteristicAt expressions.
On primary services loaded
On primary services error
Triggered after the Request primary services action depending on the outcome. If successful the primary service list is available with the PrimaryServiceCount and PrimaryServiceAt expressions.

Bluetooth actions

Request device
Prompt the user to choose a nearby Bluetooth device to connect to. This must be used in a user input trigger. The listed Bluetooth devices must be filtered by providing one of Services (or Optional services), Device name or Device name prefix; only matching devices will be shown. For possible ways to specify services, see Specifying services and characteristics above. On device connected triggers if successful, else On request device failed.
Disconnect device
Disconnect a connected Bluetooth device by its device ID.
Read value
Read binary
Read data from a Bluetooth characteristic. The device ID can be left blank to use the default device (the first device that is connected). For the service and characteristic, see Specifying services and characteristics above. One of the characteristic read triggers will run depending on the outcome. If successful, the selected Binary Data object will have the read data loaded for the binary variant, or the characteristic value expressions will be set for the value variant.
Write binary
Write data to a Bluetooth characteristic from a Binary Data object. The device ID can be left blank to use the default device (the first device that is connected). For the service and characteristic, see Specifying services and characteristics above. One of the characteristic write triggers will run depending on the outcome.
Start/stop notifications
Start or stop notifications for a Bluetooth characteristic. The device ID can be left blank to use the default device (the first device that is connected). For the service and characteristic, see Specifying services and characteristics above. While notifications are started, the notification triggers will run whenever a notification is received.
Request primary services
Request a list of primary services available for a device ID (which can be left blank to use the default device). If successful triggers On primary services loaded, and the primary service expressions can be used.
Request characteristics
Request a list of characteristics available for a service. If successful triggers On characteristics loaded, and the characteristic expressions can be used.

Bluetooth expressions

DeviceID
PrimaryServiceID
CharacteristicID
In a trigger, the ID of the relevant device, primary service, or characteristic, where applicable.
DeviceName
In On device connected, a string with the name of the device that connected.
CharacteristicSignedInteger
CharacteristicUnsignedInteger
CharacteristicFloat
CharacteristicText
After a successful Read value action, these expressions return the read value in a variety of different types. Construct will attempt to deduce the type from the length of the data, e.g. if the data is 1, 2 or 4 bytes long it will read it as both a signed and unsigned integer and set the expressions accordingly; if 4 or 8 bytes long set the float value; and always attempt to read the value as text. These values will only be meaningful if they match the type of value the characteristic really stores. For other data types, use the Read binary action instead.
PrimaryServiceCount
PrimaryServiceAt(index)
After On primary services loaded, use these expressions to retrieve the number of services and the service identifier at each index in the list.
CharacteristicCount
CharacteristicAt(index)
After On characteristics loaded, use these expressions to retrieve the number of characteristics and the characteristic identifier at each index in the list.
Construct 3 Manual 2022-07-18