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:

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

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

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

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

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 Uuid

Retrieves the CCCD Uuid

Returns:

  • Uuid

    Uuid Object for the Client Characteristic Configuration Descriptor

See Also:

Since:

API Level 3.1.0

getAvailableConnectionCount() as Number

Accessor for determining the number of available connections

Returns:

  • Number

    The number of available connections

Since:

API Level 3.1.0

getPairedDevices() as Iterator

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

Returns:

  • Iterator

    All paired devices available to the App

Since:

API Level 3.1.0

longToUuid(mostSigBits as Long, leastSigBits as Long) as Uuid

Converts long representation of a UUID to a Uuid object

Parameters:

  • mostSigBits(Long)

    Most Significant 64-bits of the UUID

  • leastSigBits(Long)

    Least Significant 64-bits of the UUID

Returns:

  • Uuid

    Uuid Object

See Also:

Since:

API Level 3.1.0

pairDevice(scanResult as ScanResult) as 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:

  • scanResult(ScanResult)

    A scan result for the device that should be paired. Cannot be null.

Returns:

  • Device

    the device that was added to the paired list or null if the device could not be paired.

Since:

API Level 3.1.0

Throws:

  • (DevicePairException)

    Raised if 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 Uuid, :characteristics as Array<{ :uuid as Uuid, :descriptors as Array<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(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 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(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 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 String) as Uuid

Converts the String Representation of a UUID into a Uuid Object

Parameters:

  • str(String)

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

Returns:

  • Uuid

    Uuid Object

See Also:

Since:

API Level 3.1.0

Throws:

unpairDevice(device as 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:

  • device(Device)

    the device to remove from the paired device store. Cannot be null

Since:

API Level 3.1.0


Generated Apr 22, 2021 10:10:31 AM