Bluetooth: Managing a Bluetooth Low Energy Device

- - -

This tutorial demonstrates how you can manage Bluetooth Low Energy and exchange data with a peer device.

- - - - - - - - - - - - - -

Note
The Bluetooth API is optional for both Tizen mobile and wearable profiles, which means that it may not be supported in all mobile and wearable devices.
The Bluetooth API is not supported on any Tizen Emulators.

- -

Warm-up

Become familiar with the Bluetooth API basics by learning about:

Managing the Local Bluetooth Adapter
Enable and disable the local Bluetooth adapter, and change the device name for it.
Discovering Bluetooth Low Energy Devices
Search for remote devices.
Managing the Advertising Options
Manage what information is advertised to any Bluetooth Low Energy device in the proximity.
Connecting to a Bluetooth Low Energy Device
Connect to one of the detected Bluetooth Low Energy devices.
Receiving Notifications on Connection State Change
Monitor the state of connection to a remote Bluetooth Low Energy device.
Retrieving Bluetooth GATT Services
Check information about Bluetooth GATT services provided by a remote device.
Accessing Bluetooth GATT Characteristic Value
Read and write a value of Bluetooth GATT characteristic of a remote device.
Receiving Notification on Characterictic Value Change
Monitor changes in a Bluetooth GATT characteristic value.
Accessing Bluetooth GATT Descriptor Value
Read and write a value of Bluetooth GATT characteristic descriptor of a remote device.

- -

Show All
Hide All

- -

-
-
Managing the Local Bluetooth Adapter
- Hide -
-
- -
To enable the Bluetooth device, request a built-in Settings application to present the relevant switch to the user so that they can enable or disable the Bluetooth. For details see the Managing the Local Bluetooth Adapter section of the Bluetooth Tutorial.
- -
-
-
-
Discovering Bluetooth Low Energy Devices
- Hide -
-
- -
Learning how to search for remote devices is a basic Bluetooth management skill:
-
1. Define a scan events handler by implementing the BluetoothLEScanCallback (in mobile and wearable applications). - A callback is invoked to notify that the scan has started, a remote device has been detected, and when the scan is finished.
  -
```
-var callbacks = {
-   onstarted: function() {
-      console.log("Scan started");
-   },
-   ondevicefound: function(device) {
-      console.log("Found device: " + device.name + " [" + device.address + "]");
-   },
-   onfinished: function(devices) {
-      console.log("Scan finished. Found " + devices.length + " devices.");
-   }
-};
-
```
  - - - - - - - - - -
  Note
  To allow other Bluetooth devices to find your device, you must set the device to be visible through the system settings.
2. Retrieve a BluetoothLEAdapter object with the getLEAdapter() method (in mobile and wearable applications) method:
  -
```
var adapter = tizen.bluetooth.getLEAdapter();
```
  -
3. To search for remote devices, use the startScan() method (in mobile and wearable applications) of the BluetoothLEAdapter interface.
  -
```
adapter.startScan(callbacks);
```
  -
4. Finally, when you find the right remote device or the user cancels the scanning, disable the scan using the stopScan() method (in mobile and wearable applications) of the BluetoothLEAdapter interface.
  -
```
adapter.stopScan();
```
  -
- -
-
-
-
Managing the Advertising Options
- Hide -
-
- -
Learning how to control what information are advertised by the device is a usefull Bluetooth Low Energy skill:
-
Bluetooth Low Energy technology allows a device to broadcast some information without any need of connection between devices. Bluetooth Low Energy API provides methods to control this advertising/broadcasting.
-
1. Retrieve a BluetoothLEAdapter object with the getLEAdapter() method (in mobile and wearable applications):
  -
```
var adapter = tizen.bluetooth.getLEAdapter();
```
  -
2. Setup options and start advertising with the startAdvertise() method (in mobile and wearable applications) of the BluetoothLEAdapter interface
  -
```
-var advertiseData = new tizen.BluetoothLEAdvertiseData({
-    includeName: true,
-    serviceuuids: ["180f"]  // 180F is 16bit Battery Service UUID
-});
-var connectable = true;
-
-adapter.startAdvertise(
-   advertiseData,
-   "ADVERTISE",
-   function onstate(state)
-   {
-      console.log("Advertising configured: " + state);
-   },
-   function(error)
-   {
-      console.log("startAdvertise() failed: " + error.message);
-   },
-   "LOW_LATENCY",
-   connectable
-);
-
```
  - - - - - - - - - -
  Note
  To learn how to make your mobile device visible to other Bluetooth devices see the Managing the Local Bluetooth Adapter section of the Bluetooth Tutorial.
  -
3. To disable the advertising stopAdvertise() method (in mobile and wearable applications) of the BluetoothLEAdapter interface.
  -
```
adapter.stopAdvertise();
```
  -
-
-
-
-
Connecting to a Bluetooth Low Energy Device
- Hide -
-
- -
Learning how to connect to other devices is a basic Bluetooth Low Energy management skill:
-
1. Retrieve a BluetoothLEAdapter object with the getLEAdapter() method (in mobile and wearable applications): -
  -
```
var adapter = tizen.bluetooth.getLEAdapter();
-
```
2. Define a success and error callbacks for a connect operation:
  -
```
-function connectFail(error) {
-     console.log("Failed to connect to device: " + e.message);
-}
-
-function connectSuccess() {
-    console.log("Connected to device");
-}
-
```
  -
3. Define a callback for scan operation which will connect to any device found and stop the scan.
  -
  Within the callback request establishing a connection with the found device using the connect() method (in mobile and wearable applications) of the BluetoothLEDevice interface (in mobile and wearable applications): -
```
-var remoteDevice = null;
-
-function onDeviceFound(device)
-{
-   if (remoteDevice === null) {
-      remoteDevice = device;
-      console.log("Found device " + device.name + ". Connecting...");
-
-      device.connect(connectSuccess, connectFail);
-   }
-
-   adapter.stopScan();
-}
-
```
  -
4. Having all callbacks ready, initiate the Bluetooth Low Energy scan using the startScan() method (in mobile and wearable applications) of the BluetoothLEAdapter adapter:
  -
```
adapter.startScan({
-   ondevicefound: onDeviceFound
-});
```
5. When the connection to the remote device is no longer required, disconnect from the device by calling the disconnect() method (in mobile and wearable applications) of the BluetoothLEDevice interface:
  -
```
remoteDevice.disconnect();
```
-
-
-
-
Receiving Notifications on Connection State Change
-Hide -
-
- -
Learning how to receive notifications whenever the device connection is established or lost is a useful Bluetooth management skill:
-
1. Retrieve a BluetoothLEAdapter object with the getLEAdapter() method (in mobile and wearable applications): -
  -
```
var adapter = tizen.bluetooth.getLEAdapter();
-
```
2. Define a connection state change listener by implementing the BluetoothLEConnectChangeCallback (in mobile and wearable applications):
  -
```
-var connectionListener = {
-    onconnected: function(device) {
-        console.log("Connected to the device: " + device.name + " [" + device.address + "]");
-    },
-    ondisconnected: function(device) {
-        console.log("Disconnected from the device " + device.name + " [" + device.address + "]");
-    }
-};
-
```
  -
3. Define a callback for scan operation which will connect to any device found and stop the scan.
  -
  Within the callback register a connection state change listener using the addConnectStateChangeListener() method (in mobile and wearable applications) of the BluetoothLEDevice interface: -
```
-var remoteDevice = null;
-var watchId;
-
-function onDeviceFound(device)
-{
-   if (remoteDevice === null) {
-      remoteDevice = device;
-      console.log("Found device " + device.name + ". Connecting...");
-
-      watchId = remoteDevice.addConnectStateChangeListener(connectionListener);
-
-      remoteDevice.connect();
-   }
-
-   adapter.stopScan();
-}
-
```
  -
4. Having all callbacks ready, initiate the Bluetooth Low Energy scan:
  -
```
adapter.startScan({
-   ondevicefound: onDeviceFound
-});
```
5. When the notifications about the connection are no longer required, unregister the listener from the device by calling the removeConnectStateChangeListener() method (in mobile and wearable applications) of the BluetoothLEDevice interface:
  -
```
remoteDevice.removeConnectStateChangeListener(watchId);
```
-
-
-
-
Retrieving Bluetooth GATT Services
-Hide -
-
- -
Learning how to retrieve a list of GATT services (Generic Attribute) provided by a device is basic Bluetooth Low Energy management skill:
-
1. Connect to any Bluetooth Low Energy device as described in the Connecting to a Bluetooth Low Energy Device section.
2. Define a connection state change listener by implementing the BluetoothLEConnectChangeCallback (in mobile and wearable applications):
  -
```
-function showGATTService(service, indent)
-{
-   if (indent === undefined) {
-      indent = "";
-   }
-
-   console.log(indent + "Service " + service.uuid + ". Has " + service.characteristics.length + " characteristics and " + service.services.length + " sub-services.");
-
-   for (var i = 0; i < service.services.length; i++) {
-      showGATTService(service.services[i], indent + "   ");
-   }
-}
-
```
  -
3. Retrieve a list of GATT service uuids from the uuids attribute (in mobile and wearable applications) of the BluetoothLEDevice interface:
  -
```
var serviceUUIDs = remoteDevice.uuids;
```
  -
4. Retrieve GATT service information using the getService() method (in mobile and wearable applications) of the BluetoothLEDevice interface for every service uuid:
  -
```
-var i = 0, service = null;
-
-for (i; i < serviceUUIDs.length; i++) {
-
-   service = remoteDevice.getService(serviceUUIDs[i]);
-
-   showGATTService(service);
-}
```
  -
-
-
-
-
Accessing Bluetooth GATT Characteristic Value
-Hide -
-
- -
Learning how to read and write a value of Bluetooth Characteristic is a useful Bluetooth Low Energy management skill:
-
1. Connect to any Bluetooth Low Energy device as described in the Connecting to a Bluetooth Low Energy Device section.
2. Retrieve a list of GATT service uuids from the uuids attribute (in mobile and wearable applications) of the BluetoothLEDevice interface:
  -
```
var serviceUUIDs = remoteDevice.uuids;
```
  -
3. Select one of the GATT services and use the getService() method (in mobile and wearable applications) of the BluetoothLEDevice interface to retrieve an object representing the service. In this example we use the first service:
  -
```
var gattService = remoteDevice.getService(serviceUUIDs[0]);
```
  -
4. Select the interesting characteristic from the characteristics attribute (in mobile and wearable applications) of the BluetoothGATTService interface (in mobile and wearable applications). In this example we use the first of them:
  -
```
var property = gattService.characteristics[0];
```
  -
5. Define a callback implementing the ReadValueSuccessCallback which (in mobile and wearable applications) will receive the value of the characteristic:
  -
```
-function readSuccess(value)
-{
-   console.log("Characteristic value: " + value);
-}
-
-function readFail(error)
-{
-   console.log("readValue() failed: " + error);
-}
-
```
  -
6. To retrieve GATT Characteristic value, use the readValue() method (in mobile and wearable applications) of the BluetoothGATTCharacteristic interface:
  -
```
-if (!property.isReadable) {
-   console.log("Property seems not to be readable. Attempting to read...");
-}
-property.readValue(readSuccess, readFail);
```
  -
7. To change the characteristic value, define callbacks and use the writeValue() method (in mobile and wearable applications) of the BluetoothGATTCharacteristic interface:
  -
```
-function writeSuccess(value)
-{
-   console.log("Written");
-}
-
-function writeFail(error)
-{
-   console.log("writeValue() failed: " + error);
-}
-
-if (!property.isWritable) {
-   console.log("Property seems not to be writable. Attempting to write...");
-}
-var newValue = [82];
-
-property.writeValue(newValue, writeSuccess, writeFail);
-
```
  -
-
-
-
-
Receiving Notification on Characterictic Value Change
- Hide -
-
- -
Learning how to monitor a changes of a Bluetooth characteristic is a useful Bluetooth Low Energy management skill:
-
1. Connect to any Bluetooth Low Energy device as described in the Connecting to a Bluetooth Low Energy Device section.
2. Retrieve a list of GATT service uuids from the uuids attribute (in mobile and wearable applications) of the BluetoothLEDevice interface:
  -
```
var serviceUUIDs = remoteDevice.uuids;
```
  -
3. Select one of the GATT services and use the getService() method (in mobile and wearable applications) of the BluetoothLEDevice interface to retrieve an object representing the service. In this example we use the first service:
  -
```
var gattService = remoteDevice.getService(serviceUUIDs[0]);
```
  -
4. Select the interesting characteristic from the characteristics attribute (in mobile and wearable applications) of the BluetoothGATTService interface (in mobile and wearable applications). In this example we use the first of them:
  -
```
var property = gattService.characteristics[0];
```
  -
5. Define a callback implementing the ReadValueSuccessCallback which (in mobile and wearable applications) will receive the value of the characteristic every time the value changes:
  -
```
-function onValueChange(value)
-{
-   console.log("Characteristic value is now: " + value);
-}
-
```
  -
6. Register a value change listener using the addValueChangeListener() method (in mobile and wearable applications) of the BluetoothGATTCharacteristic interface:
  -
```
var watchId = property.addValueChangeListener(onValueChange);
```
7. When the notifications about the connection are no longer required, unregister the listener from the device by calling the removeValueChangeListener() method (in mobile and wearable applications) of the BluetoothGATTCharacteristic interface:
  -
```
property.removeValueChangeListener(watchId);
```
- -
-
-
-
Accessing Bluetooth GATT Descriptor Value
- Hide -
-
- -
Learning how to read and write a value of Bluetooth Descriptor is a useful Bluetooth Low Energy management skill:
-
1. Connect to any Bluetooth Low Energy device as described in the Connecting to a Bluetooth Low Energy Device section.
2. Retrieve a list of GATT service uuids from the uuids attribute (in mobile and wearable applications) of the BluetoothLEDevice interface:
  -
```
var serviceUUIDs = remoteDevice.uuids;
```
  -
3. Select one of the GATT services and use the getService() method (in mobile and wearable applications) of the BluetoothLEDevice interface to retrieve an object representing the service. In this example we use the first service:
  -
```
var gattService = remoteDevice.getService(serviceUUIDs[0]);
```
  -
4. Select the interesting characteristic from the characteristics attribute (in mobile and wearable applications) of the BluetoothGATTService interface (in mobile and wearable applications). In this example we use the first of them:
  -
```
var characteristic = gattService.characteristics[0];
```
  -
5. Select the interesting descriptor from the descriptors attribute (in mobile and wearable applications) of the BluetoothGATTCharacteristic interface (in mobile and wearable applications). In this example we use the first of them:
  -
```
var descriptor = characteristic.descriptors[0];
```
  -
6. Define a callback implementing the ReadValueSuccessCallback (in mobile and wearable applications) which will receive the value of the descriptor:
  -
```
-function readSuccess(value)
-{
-   console.log("Descriptor value: " + value);
-}
-
-function readFail(error)
-{
-   console.log("readValue() failed: " + error);
-}
-
```
  -
7. To retrieve GATT Descriptor value, use the readValue() method (in mobile and wearable applications) of the BluetoothGATTDescriptor interface:
  -
```
-descriptor.readValue(readSuccess, readFail);
```
  -
8. To change the descriptor value, define callbacks and use the writeValue() method (in mobile and wearable applications) of the BluetoothGATTDescriptor interface:
  -
```
-function writeSuccess(value)
-{
-   console.log("Written");
-}
-
-function writeFail(error)
-{
-   console.log("writeValue() failed: " + error);
-}
-
-var newValue = [3];
-
-descriptor.writeValue(newValue, writeSuccess, writeFail);
-
```
  -
- -
-

Note
To allow other Bluetooth devices to find your device, you must set the device to be visible through the system settings.

Note
To learn how to make your mobile device visible to other Bluetooth devices see the Managing the Local Bluetooth Adapter section of the Bluetooth Tutorial.

- - - - -

Bluetooth: Managing a Bluetooth Low Energy Device

Warm-up

Managing the Local Bluetooth Adapter

Discovering Bluetooth Low Energy Devices

Managing the Advertising Options

Connecting to a Bluetooth Low Energy Device

Receiving Notifications on Connection State Change

Retrieving Bluetooth GATT Services

Accessing Bluetooth GATT Characteristic Value

Receiving Notification on Characterictic Value Change

Accessing Bluetooth GATT Descriptor Value

Task

Discovering Bluetooth Low Energy Devices

Managing the Advertising Options

Connecting to a Bluetooth Low Energy Device

Receiving Notifications on Connection State Changes

Retrieving Bluetooth GATT Services

Accessing the Bluetooth GATT Characteristic Value

Receiving Notifications on Characteristic Value Changes

Accessing the Bluetooth GATT Descriptor Value