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:

  • Audio Content Provider

  • Background

  • Data Field

  • Glance

  • Watch App

  • 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 See Also
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

STATUS_GATT_INSUFFICIENT_AUTHENTICATION_FAIL 18

API Level 4.2.5

GATT operation failed due to insufficent authentication

STATUS_GATT_INSUFFICIENT_ENCRYPTION_FAIL 19

API Level 4.2.5

GATT operation failed due to insufficent encryption

STATUS_ENCRYPTION_BOND_FAIL 100

API Level 4.2.5

Initial Bond Procedure Failed

STATUS_ENCRYPTION_PEER_KEYS_LOST 101

API Level 4.2.5

Peer reports that its keys have been lost.

STATUS_ENCRYPTION_SECURITY_INSUFFICIENT 102

API Level 4.2.5

Peer Attempted to Reduce Key Security Level from a previous bond

ScanState

Since:

API Level 3.1.0

Name Value Since Description See Also
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 See Also
CONNECTION_STATE_DISCONNECTED 0

API Level 3.1.0

Device is Disconnected

CONNECTION_STATE_CONNECTED 1

API Level 3.1.0

Device is Connected

CONNECTION_STATE_REJECTED 2

API Level 5.1.0

Device connection is rejected by the user because of insufficient security

WriteType

Since:

API Level 3.1.0

Name Value Since Description See Also
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)

ConnectionStrategy

Since:

API Level 3.1.0

Name Value Since Description See Also
CONNECTION_STRATEGY_DEFAULT 0

API Level 5.1.0

Pair the device, bonding may be requested later.

CONNECTION_STRATEGY_SECURE_PAIR_BOND 1

API Level 5.1.0

Pair the device and establish secure bonding. Device may be bonded as part of the pairing process.

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

getBondedDevices() as BluetoothLowEnergy.Iterator

Retrieve an Iterator of devices that the Application has bonded with that the system has saved bond information for.

Supported Devices:

Returns:

Since:

API Level 4.2.5

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:

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, onProfileRegister() will be called on the registered BleDelegate 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:

setConnectionStrategy(connectionStrategy as BluetoothLowEnergy.ConnectionStrategy) as Void

Set the connection type used to connect to the BLE device.

Note:

The default value is CONNECTION_TYPE_DEFAULT. Using the value of CONNECTION_TYPE_SECURE_PAIR_BOND will pair and bond the device as part of the pairing process.

Parameters:

Since:

API Level 5.1.0

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:

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 May 15, 2025, 11:15:41 AM