Module: Toybox.BluetoothLowEnergy

Overview

The BluetoothLowEnergy module provides access to Generic BLE communication functionality in the central role. Including the ability to scan for peripheral devices, pair with sensors, and performing GATTC operations on a peripheral

This module also provides several sets of constants:

Since:

API Level 3.1.0

App Types:

  • Watch App

  • Audio Content Provider

  • Background

  • Data Field

  • Widget

Supported Devices:

Requires Permission:

  • BluetoothLowEnergy

Classes Under Namespace

Classes: BleDelegate, Characteristic, Descriptor, Device, DevicePairException, InvalidRequestException, Iterator, ProfileRegistrationException, ScanResult, Service, Uuid, UuidFormatException

Constant Summary

Status

Since:

API Level 3.1.0

Name Value Since Description
STATUS_SUCCESS 0

API Level 3.1.0

Operation Successful

STATUS_NOT_ENOUGH_RESOURCES 1

API Level 3.1.0

Operation failed due to lack of resources

STATUS_READ_FAIL 12

API Level 3.1.0

Read Request Failed

STATUS_WRITE_FAIL 14

API Level 3.1.0

Write Request Failed

ScanState

Since:

API Level 3.1.0

Name Value Since Description
SCAN_STATE_OFF 0

API Level 3.1.0

BLE scanning disabled

SCAN_STATE_SCANNING 1

API Level 3.1.0

BLE scanning active

ConnectionState

Since:

API Level 3.1.0

Name Value Since Description
CONNECTION_STATE_DISCONNECTED 0

API Level 3.1.0

Device is Disconnected

CONNECTION_STATE_CONNECTED 1

API Level 3.1.0

Device is Connected

WriteType

Since:

API Level 3.1.0

Name Value Since Description
WRITE_TYPE_WITH_RESPONSE 0

API Level 3.1.0

Write with response

WRITE_TYPE_DEFAULT 1

API Level 3.1.0

Write without response (Default write type)

Instance Method Summary collapse

Instance Method Details

cccdUuid() as BluetoothLowEnergy.Uuid

Retrieves the CCCD Uuid

Returns:

See Also:

Since:

API Level 3.1.0

getAvailableConnectionCount() as Lang.Number

Accessor for determining the number of available connections

Returns:

Since:

API Level 3.1.0

getPairedDevices() as BluetoothLowEnergy.Iterator

Retrieve an Iterator of all currently paired devices accessible to the Application

Returns:

Since:

API Level 3.1.0

longToUuid(mostSigBits as Lang.Long, leastSigBits as Lang.Long) as BluetoothLowEnergy.Uuid

Converts long representation of a UUID to a Uuid object

Parameters:

  • mostSigBits — (Lang.Long) —

    Most Significant 64-bits of the UUID

  • leastSigBits — (Lang.Long) —

    Least Significant 64-bits of the UUID

Returns:

See Also:

Since:

API Level 3.1.0

pairDevice(scanResult as BluetoothLowEnergy.ScanResult) as BluetoothLowEnergy.Device or Null

Pairs a peripheral device seen in scanning with the system.

The BLE Subsystem will begin to search for the device specified by the scanResult parameter. Once the device is found and connected, onConnectedStateChanged() will be called on the registered BleDelegate with the associated device object

This pairing does not persist across application instances.

Parameters:

Returns:

Since:

API Level 3.1.0

Throws:

  • (BluetoothLowEnergy.DevicePairException) —

    Thrown if the requested device is already paired, if the maximum number of paired devices has already been reached, or if pairing failed for unkown reason

registerProfile(profile as { :uuid as BluetoothLowEnergy.Uuid, :characteristics as Lang.Array<{ :uuid as BluetoothLowEnergy.Uuid, :descriptors as Lang.Array<BluetoothLowEnergy.Uuid> }> }) as Void

Registers a Bluetooth Profile Definition

Call this function to define all of the Profiles that will be used in the application. Only registered characteristics and descriptors will be available when performing GATT operations

When the operation is completed BleDelegate.onProfileRegister() will be called on the registered delegate with the UUID and a Status

Registration can fail if too many profiles are registered, the current limit is 3.

Parameters:

  • profile — (Lang.Dictionary) —

    Profile Definition. Defines the expected Profile UUID, Profile Characteristics and Characteristic Descriptors. Cannot be null.

Example:

using Toybox.BluetoothLowEnergy;

   function registerProfiles() {
       var profile = {                                                  // Set the Profile
           :uuid => Ble.stringToUuid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
           :characteristics => [ {                                      // Define the characteristics
                   :uuid => Ble.stringToUuid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),     // UUID of the first characteristic
                   :descriptors => [                                    // Descriptors of the characteristic
                       Ble.stringToUuid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"),
                       Ble.stringToUuid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") ] }, {
                   :uuid => Ble.stringToUuid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") }]   // UUID of the second characteristic
       };

       // Make the registerProfile call
       BluetoothLowEnergy.registerProfile( profile );
  }

Since:

API Level 3.1.0

Throws:

setDelegate(delegate as BluetoothLowEnergy.BleDelegate) as Void

Sets the Delegate Handler for Bluetooth Asynchronous Callbacks

An application can only have 1 registered delegate. Subsequent calls to this function will override the current delegate

Parameters:

  • delegate — (BluetoothLowEnergy.BleDelegate) —

    An implementation of the BleDelegate Class to register as the handler for callbacks, or null to deregister the current handler.

Example:

using Toybox.BluetoothLowEnergy as Ble;
class Handler extends Ble.BleDelegate {
    function initialize() {
        BleDelegate.initialize();
    }
}

var handler = new Handler();
Ble.setDelegate(handler);

Since:

API Level 3.1.0

setScanState(scanState as BluetoothLowEnergy.ScanState) as Void

Starts the BLE Scanning Operations

Once scanning is started onScanResults() will be called on the registered BleDelegate as Advertising data is received.

Since:

API Level 3.1.0

stringToUuid(str as Lang.String) as BluetoothLowEnergy.Uuid

Converts the String Representation of a UUID into a Uuid Object

Parameters:

  • str — (Lang.String) —

    String Representation of the Uuid formatted as "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

Returns:

See Also:

Since:

API Level 3.1.0

Throws:

unpairDevice(device as BluetoothLowEnergy.Device) as Void

Unpairs a peripheral device from the system

If the device is connected the BLE Subsystem will disconnect from the device and will not attempt to reconnect. If the device is not connected the system will stop searching for the device.

Parameters:

Since:

API Level 3.1.0

Generated Sep 25, 2023 12:31:45 PM