BLE GATT

Service URI - luna://com.webos.service.blegatt

All methods return responses containing errorCode (Number) and errorText (String) when returnValue contains false. All responses from methods that have been subscribed to (i.e., were passed subscribe:true) contain subscribed.
The service informs the client that it will not send any further subscription responses by setting it to false (including the case when it rejects the initial subscription request in the method call). When the client receives a false value for subscribed, it must always call LSCallCancel() or handle.cancel().

Check out the BLE GATT sample app, developed with Enact, for how to call the BLE GATT API.

Methods

MethodDescriptionSupported in Emulator
isEnabledCheck if Bluetooth is currently enabled and ready for use.No
startScanStarts scanning only for ble devices.No
stopScanStops ongoing ble scanning.No
getStateGets information about the scanning status and connected/paired devices.No
pairPairs a specific remote Bluetooth device.No
unpairDisconnects the paired remote device. All pairing information about the device will be removed.No
client/connectConnects the specified remote device to the GATT profile.No
client/disconnectDisconnects an established connection.No
client/discoverServicesDiscovers services offered by a remote device as well as their characteristics and descriptors.No
client/getServicesReturns a list of GATT services offered by the remote device.No
client/setCharacteristicNotificationEnables or disables notifications/indications for a given characteristic.No
client/readCharacteristicReads the requested characteristic from the associated remote device.No
client/readDescriptorReads the value for a given descriptor from the associated remote device.No
client/writeCharacteristicWrites a given characteristic and its values to the associated remote device.No
client/writeDescriptorWrites the value of a given descriptor to the associated remote device.No

isEnabled

Description

Checks if Bluetooth is currently enabled and ready for use.
If the TV device’s Bluetooth adapter is enabled, the isEnabled return is true; or else, it is false. If the isEnabled return is false, BLE operations cannot be done. You should call the isEnabled method first and check if the isEnabled return is returned as true before running any BLE operations.

Parameters

NameRequiredTypeDescription
subscribeOptionalBooleanWhether to subscribe for notifications on changes. Possible values are:
  • true: Subscribe.
  • false: Do not subscribe. Call the method only once. (Default).

Call returns

NameRequiredTypeDescription
subscribedOptionalBooleanIndicates if subscribed to get notifications.
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
isEnabledRequiredBooleantrue if the local adapter is currently enabled and ready for use.

Error reference

Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 312, 313, 314, 315See Error Code Reference for more details.See Error Code Reference for more details.

Example

// One-time call
var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "isEnabled",
  parameters: {},
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});
// Subscription
var subscriptionHandle = webOS.service.request(
  "luna://com.webos.service.blegatt",
  {
    method: "isEnabled",
    parameters: {
      subscribe: true,
    },
    onSuccess: function (inResponse) {
      if (typeof inResponse.subscribed !== "undefined") {
        if (!inResponse.subscribed) {
          console.log("Failed to subscribe");
          return;
        }
      }
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
    },
  }
);
 
// If you need to unsubscribe the data, use cancel() method as below
subscriptionHandle.cancel();

Return Example

Success return

{
  "subscribed": true,
  "returnValue": true,
  "isEnabled": false
}
{
  "returnValue": true,
  "isEnabled": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 105,
  "errorText": "Failed to parse incoming message"
}

startScan

Description

Starts scanning only for BLE devices.
If you want to search for a certain device containing a specific service UUID, include the service UUID in the uuid parameter when calling this method.
To avoid getting information about too many devices, it also allows picking out devices that include name in their advertising information only. To do so, include “scanType”:”name”in the parameter when calling the startScan method.
The return data contains name, rssi, mac address, manufacturer data, scan record of each searched device in a array format, and every time there is a change to the data, the subscribed return is delivered.
If there is no explicit call of the stopScan method after the startScan method is called, the scanning operation works for 60 seconds and then stops. After that, to resume scanning, you need to call the startScan method again.
To check if the scanning operation is underway, see the value of the isScan return of the getState method.
If the startScan method is called again while scanning is already underway, the returnValue will be false with errorCode:1003 and errorText: Scan is already in progress.

Parameters

NameRequiredTypeDescription
subscribeRequiredBooleanWhether to subscribe for notifications on changes. Possible values are:
  • true: Subscribe.
  • false: Do not subscribe. Call the method only once. (Default).
uuidOptionalStringTo search for a certain device with a specific service UUID, enter the service uuid of the device.
scanTypeOptionalStringTo search for devices containing certain information, enter the information. Currently, only “name” is supported.

Call returns

NameRequiredTypeDescription
subscribedOptionalBooleanIndicates if subscribed to get notifications.
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
devicesRequiredObject array: deviceStatus"devices" will contain status information for all the devices known to the system, not just the ones whose status has been changed.
The name, rssi, mac address, manufacturer data, scan record of each device are delivered in an array format.

Error reference

Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 200, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315See Error Code Reference for more details.See Error Code Reference for more details.

Example

// Subscription
var subscriptionHandle = webOS.service.request(
  "luna://com.webos.service.blegatt",
  {
    method: "startScan",
    parameters: {
      subscribe: true,
    },
    onSuccess: function (inResponse) {
      if (typeof inResponse.subscribed !== "undefined") {
        if (!inResponse.subscribed) {
          console.log("Failed to subscribe");
          return;
        }
      }
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
    },
  }
);
// If you need to unsubscribe the data, use cancel() method as below
subscriptionHandle.cancel();

Return Example

Suceess return

{
  "subscribed": true,
  "returnValue": true
}
{
  "returnValue": true,
  "devices": [
    {
      "manufactureData": {
        "companyId": [87, 0],
        "value": [79, 32, 1, 52, 0, 0, 65, 58]
      },
      "name": "JBL Flip 6",
      "address": "55:fd:b4:8f:52:86",
      "scanRecord": [
        11, 255, 87, 0, 79, 32, 1, 52, 0, 0, 65, 58, 3, 22, 223, 253, 11, 9, 74,
        66, 76, 32, 70, 108, 105, 112, 32, 54
      ],
      "rssi": -57
    },
    {
      "manufactureData": {
        "companyId": [196, 0],
        "value": [64, 192, 64, 215, 75]
      },
      "name": "LG_Speaker_S90QY",
      "address": "7e:e4:c4:64:2c:bc",
      "scanRecord": [
        2, 1, 0, 8, 255, 196, 0, 64, 192, 64, 215, 75, 17, 7, 27, 197, 213, 165,
        2, 0, 8, 186, 229, 17, 190, 19, 208, 119, 32, 176, 17, 9, 76, 71, 95,
        83, 112, 101, 97, 107, 101, 114, 95, 83, 57, 48, 81, 89
      ],
      "rssi": -55
    }
  ]
}

Failure return

{
  "returnValue": false,
  "errorCode": 200,
  "errorText": "Blegatt already scanning"
}

stopScan

Description

Stops ongoing ble scanning.
If the stopScan method is called while scanning is underway, the ongoing scanning operation stops and no more information about device searching is sent as return of the startScan method. The scanning operation also stops when 60 seconds elapse after the startScan method is called or if another app goes foreground. The state of the scanning operation can be checked in the isScan return of the getState method.

Parameters

N/A

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315See Error Code Reference for more details.See Error Code Reference for more details.

Example

var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "stoptScan",
  parameters: {},
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 101,
  "errorText": "Invalid JSON input"
}

getState

Description

Gets information about the scanning state, connected devices, and paired devices.
If the value of the subscribe parameter is true, every time there is a change to the return data, the updated information will be delivered.
The isScan return indicates whether the scanning operation is currently underway. If the value is true, the scanning operation is underway, or false, the operation has stopped.
The connectedDevice return delivers information about the currently-connected GATT server device. If this method is called with the subscribe parameter as true, the data will be updated every time there is a change to the connected device. The data includes the mac address and name, and if two or more devices are connected, the information of each device is delivered in an array format.
The pairedDevice return delivers information about the currently-paired device. If the method is called with the subscribe parameter as true, the data is updated every time there is a change to the paired device. The data includes the mac address and name, and if two or more devices are paired, the information of each device is delivered in an array format.

Parameters

NameRequiredTypeDescription
subscribeOptionalBooleanWhether to subscribe for notifications on changes. Possible values are:
  • true: Subscribe.
  • false: Do not subscribe. Call the method only once. (Default).

Call returns

NameRequiredTypeDescription
subscribedOptionalBooleanIndicates if subscribed to get notifications.
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
VersionRequiredStringThe version of the SDK
isScanRequiredBooleanCurrent state of the scanning operation.
  • true: The scanning operation is underway.
  • false: The scanning operation has stopped.
connectedDeviceOptionalObject array: connectedDeviceCurrently connected device information.
The data includes the mac address and name. If two or more devices are connected, the information of each device is delivered in an array format.
pairedDeviceObject array: pairedDeviceStringThe reason for the failure of the operation.

Error reference

Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315See Error Code Reference for more details.See Error Code Reference for more details.

Example

// One-time call
var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "getState",
  parameters: {},
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});
 
// Subscription
var subscriptionHandle = webOS.service.request(
  "luna://com.webos.service.blegatt",
  {
    method: "getState",
    parameters: {
      subscribe: true,
    },
    onSuccess: function (inResponse) {
      if (typeof inResponse.subscribed !== "undefined") {
        if (!inResponse.subscribed) {
          console.log("Failed to subscribe");
          return;
        }
      }
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
    },
  }
);
 
// If you need to unsubscribe the data, use cancel() method as below
subscriptionHandle.cancel();

Return Example

Success return

{
  "subscribed": true,
  "returnValue": true,
  "version": "1.0",
  "isScan": false,
  "connectedDevice": [
    {
      "address": "45:8b:7f:e0:56:45",
      "name": "LG TV"
    },
    {
      "address": "aa:bb:cc:dd:ee:ff",
      "name": "soundbar"
    }
  ],
  "pairedDevice": [
    {
      "address": "45:8b:7f:e0:56:45",
      "name": "LG TV"
    },
    {
      "address": "aa:bb:cc:dd:ee:ff",
      "name": "soundbar"
    }
  ]
}

Failure return

{
  "returnValue": false,
  "errorCode": 105,
  "errorText": "Failed to parse incoming message"
}

pair

Description

Pairs a specific remote Bluetooth device with a specific Bluetooth adapter.
Only one pairing request can be active for an adapter at a given time. When the pair method is called, the mac address of a device to pair should be added. If no or wrong address, an error will be returned. If the subscribe parameter is true when this method is called, the result of pairing - success or failure- will be delivered in the subscribed return. The pairing state can be checked in the state return: if the value is “pairing”, it means pairing is underway; if “successPairing”, the pairing is successful; and if “failPairing”, the pairing failed. When pairing is successful, the information about the successfully-paired device is added and updated to the pairedDevice return of the getState method.

Parameters

NameRequiredTypeDescription
subscribeOptionalBooleanWhether to subscribe for notifications on changes. Possible values are:
  • true: Subscribe.
  • false: Do not subscribe. Call the method only once. (Default).
addressRequiredStringThe address (bdaddr) of the remote device with which pairing is being attempted.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
stateRequiredStringPairing state. Possible values are:
  • pairing: Pairing is in progress.
  • successPairing: Pairing is successful.
  • failPairing: Pairing failed.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 300, 301, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 316, 317See Error Code Reference for more details.See Error Code Reference for more details.

Example

// One-time call
var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "pair",
  parameters: {
    address: "4f:6b:40:db:5b:b2"
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});
 
// Subscription
var subscriptionHandle = webOS.service.request(
  "luna://com.webos.service.blegatt",
  {
    method: "pair",
    parameters: {
      address: "4f:6b:40:db:5b:b2",
      subscribe: true,
    },
    onSuccess: function (inResponse) {
      if (typeof inResponse.subscribed !== "undefined") {
        if (!inResponse.subscribed) {
          console.log("Failed to subscribe");
          return;
        }
      }
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
    },
  }
);
 
// If you need to unsubscribe the data, use cancel() method as below
subscriptionHandle.cancel();

Return Example

Success return

{
  "returnValue": true,
  "subscribe": true,
  "state": "pairing"
}
{
  "returnValue": true,
  "state": "successPairing"
}

Failure return

{
  "returnValue": false,
  "state": "failPairing"
}

unpair

Description

Disconnects from the paired remote device.
All pairing information about the remote device will be removed and any open connections will be closed. However, the remote device is still discoverable. When this method is called, the mac address of a device to delete from the pairing history should be included. When the pairing history is deleted, the information about the device of which unpairing is requested is deleted and updated to the pairedDevice return of the getState method.

Parameters

NameRequiredTypeDescription
addressRequiredStringThe address (bdaddr) of the remote device to unpair.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 318See Error Code Reference for more details.See Error Code Reference for more details.

Example

var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "unpair",
  parameters: {
    address: "4f:6b:40:db:5b:b2",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 318,
  "errorText": "Failed to unpair"
}

client/connect

Description

Connects to the GATT profile on the specified remote device.
When this method is called, the mac address of a device to connect should be included. Also to receive all events while the connection is on, the value of the subscribe parameter should be true.
The event return delivers not only the connection state but also information about all GATT client operations. Information and values required for each event are delivered in the values object.
If the connection state changes, onConnectionStateChange is delivered as the event return, and the state information - connecting, connected, or disconnected - is delivered in the values object. While connection is being made, the values will be connecting: true and connected: false. When the connection is successfully made, they will be connecting: false and connected:true. When the the connection is closed, the values will be connecting:false and connected:false. If connection to the GATT server is successfully made, information about the connected device is added to the connectedDeviceparameter of the getState method and delivered.
If the discoverServices or getServices method is called and the service of the GATT server is successfully discovered, an onServicesDiscovered event is delivered with the information about the searched service, characteristic, and descriptor in thevalues object.
If the readCharacteristic method is called and the information about the requesting characteristic is read successfully, an onCharacteristicRead event is delivered and information about the characteristic that requests reading is delivered in the values object.
If the writeCharacteristic method is called and the information about the requesting characteristic is successfully written, an onCharacteristicWrite event is delivered. If the readDescriptor method is called and information about the requesting descriptor is successfully read, an onDescriptorRead event is delivered, and the information about the descriptor that requests read is delivered in the values object.
If the writeDescriptor method is called and information about the requesting descriptor is successfully written, an onDescriptorWrite event is delivered. If the setCharacteristicNotification method is called and notification of changes to certain characteristic’s information is requested, every time there is a change to the corresponding characteristic’s information, an onCharacteristicChanged event is delivered, and the changed information about the characteristic is delivered in the values object.

Parameters

NameRequiredTypeDescription
subscribeRequiredBooleanWhether to subscribe for notifications on changes. Possible values are:
  • true: Subscribe.
  • false: Do not subscribe. Call the method only once. (Default).
addressRequiredStringThe address of the remote device.

Call returns

NameRequiredTypeDescription
subscribedOptionalBooleanIndicates if subscribed to get notifications.
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
eventRequiredStringThe value is used to deliver results to Caller, such as connection status as well as any further GATT client operations
  • onConnectionStateChange: Indicating the GATT client has connected/disconnected to/from a remote GATT server.
  • onServicesDiscovered: Indicating the list of remote services, characteristics, and descriptors for the remote device has been updated.
  • onCharacteristicChanged: Triggered as a result of a remote characteristic notification.
  • onCharacteristicRead: Reporting the result of a characteristic read operation.
  • onCharacteristicWrite: Indicating the result of a characteristic write operation.
  • onDescriptorRead: Reporting the result of a descriptor read operation.
  • onDescriptorWrite: Indicating the result of a descriptor write operation.
valuesOptionalObject: valuesData corresponding to each event.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413See Error Code Reference for more details.See Error Code Reference for more details.

Example

// Subscription
var subscriptionHandle = webOS.service.request(
  "luna://com.webos.service.blegatt",
  {
    method: "client/connect",
    parameters: {
      subscribe: true,
      address: "4f:8f:d7:c4:e3:e1",
    },
    onSuccess: function (inResponse) {
      if (typeof inResponse.subscribed !== "undefined") {
        if (!inResponse.subscribed) {
          console.log("Failed to subscribe");
          return;
        }
      }
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
    },
  }
);
 
// If you need to unsubscribe the data, use cancel() method as below
subscriptionHandle.cancel();

Return Example

Success return

{
  "subscribed": true,
  "returnValue": true
}

Connecting status

{
  "event": "onConnectionStateChange",
  "returnValue": true,
  "values": {
    "connected": false,
    "address": "4f:8f:d7:c4:e3:e1",
    "connecting": true
  }
}

Device connected

{
  "event": "onConnectionStateChange",
  "returnValue": true,
  "values": {
    "connected": true,
    "address": "4f:8f:d7:c4:e3:e1",
    "connecting": false
  }
}

Discover service

{
  "event": "onServicesDiscovered",
  "returnValue": true,
  "values": {
    "returnValue": true,
    "address": "4f:8f:d7:c4:e3:e1"
  }
}

Get service

{
  "event": "onServicesDiscovered",
  "returnValue": true,
  "values": {
    "address": "4f:8f:d7:c4:e3:e1",
    "services": [
      {
        "includes": [],
        "characteristics": [
          {
            "properties": {
              "authenticatedSignedWrites": false,
              "extendedProperties": false,
              "write": false,
              "read": false,
              "notify": false,
              "broadcast": false,
              "writeWithoutResponse": false,
              "indicate": true
            },
            "characteristic": "00002a05-0000-1000-8000-00805f9b34fb",
            "instanceId": "003",
            "permissions": {},
            "value": {
              "bytes": []
            },
            "descriptors": []
          },
          {
            "properties": {
              "authenticatedSignedWrites": false,
              "extendedProperties": false,
              "write": false,
              "read": true,
              "notify": false,
              "broadcast": false,
              "writeWithoutResponse": false,
              "indicate": false
            },
            "characteristic": "00002b3a-0000-1000-8000-00805f9b34fb",
            "instanceId": "005",
            "permissions": {},
            "value": {
              "bytes": []
            },
            "descriptors": []
          },
          {
            "properties": {
              "authenticatedSignedWrites": false,
              "extendedProperties": false,
              "write": true,
              "read": true,
              "notify": false,
              "broadcast": false,
              "writeWithoutResponse": false,
              "indicate": false
            },
            "characteristic": "00002b29-0000-1000-8000-00805f9b34fb",
            "instanceId": "007",
            "permissions": {},
            "value": {
              "bytes": []
            },
            "descriptors": []
          },
          {
            "properties": {
              "authenticatedSignedWrites": false,
              "extendedProperties": false,
              "write": false,
              "read": true,
              "notify": false,
              "broadcast": false,
              "writeWithoutResponse": false,
              "indicate": false
            },
            "characteristic": "00002b2a-0000-1000-8000-00805f9b34fb",
            "instanceId": "009",
            "permissions": {},
            "value": {
              "bytes": []
            },
            "descriptors": []
          }
        ],
        "service": "00001801-0000-1000-8000-00805f9b34fb",
        "type": "primary"
      }
    ]
  }
}

Receive notification

{
  "event": "onCharacteristicChanged",
  "returnValue": true,
  "values": {
    "address": "4f:8f:d7:c4:e3:e1",
    "changed": {
      "characteristic": "0000fff4-0000-1000-8000-00805f9b34fb",
      "instanceId": "055",
      "value": {
        "bytes": [
          125, 71, 69, 95, 121, 99, 36, 86, 42, 110, 87, 70, 70, 83, 117, 19,
          92, 91, 93
        ]
      }
    }
  }
}

Read characteristic

{
  "event": "onCharacteristicRead",
  "returnValue": true,
  "values": {
    "service": "0000fff0-0000-1000-8000-00805f9b34fb",
    "address": "4f:8f:d7:c4:e3:e1",
    "values": [
      {
        "properties": {
          "authenticatedSignedWrites": false,
          "extendedProperties": false,
          "write": false,
          "read": true,
          "notify": false,
          "broadcast": false,
          "writeWithoutResponse": false,
          "indicate": false
        },
        "characteristic": "0000fff1-0000-1000-8000-00805f9b34fb",
        "instanceId": "042",
        "permissions": {},
        "value": {
          "bytes": []
        },
        "descriptors": [
          {
            "instanceId": "044",
            "descriptor": "00002901-0000-1000-8000-00805f9b34fb",
            "permissions": {},
            "value": {
              "bytes": []
            }
          },
          {
            "instanceId": "043",
            "descriptor": "00002904-0000-1000-8000-00805f9b34fb",
            "permissions": {},
            "value": {
              "bytes": []
            }
          }
        ]
      }
    ]
  }
}

Read descriptor

{
  "event": "onDescriptorRead",
  "returnValue": true,
  "values": {
    "characteristic": "0000fff4-0000-1000-8000-00805f9b34fb",
    "service": "0000fff0-0000-1000-8000-00805f9b34fb",
    "address": "4f:8f:d7:c4:e3:e1",
    "values": [
      {
        "instanceId": "058",
        "descriptor": "00002901-0000-1000-8000-00805f9b34fb",
        "permissions": {},
        "value": {
          "bytes": []
        }
      },
      {
        "instanceId": "057",
        "descriptor": "00002902-0000-1000-8000-00805f9b34fb",
        "permissions": {},
        "value": {
          "bytes": [1, 0]
        }
      },
      {
        "instanceId": "056",
        "descriptor": "00002904-0000-1000-8000-00805f9b34fb",
        "permissions": {},
        "value": {
          "bytes": []
        }
      }
    ]
  }
}

Write characteristic

{
  "event": "onCharacteristicWrite",
  "returnValue": true,
  "values": {
    "adapterAddress": "ac:f1:08:d4:6f:eb",
    "returnValue": true,
    "address": "4f:8f:d7:c4:e3:e1"
  }
}

Device disconnected

{
  "event": "onConnectionStateChange",
  "returnValue": true,
  "values": {
    "connected": false,
    "address": "4f:8f:d7:c4:e3:e1",
    "connecting": false
  }
}

Failure return

{
  "returnValue": false,
  "errorCode": 400,
  "errorText": "Device is already connected"
}

client/disconnect

Description

Disconnects GATT connection.
When calling this method, you should include the mac address to disconnect in the address parameter. When the connection is closed, an onConnectionStateChange event is delivered as an event return of the client/connect method. The values of connecting and connected of thevalues object will be false. Also, when the connection is closed, the disconnected device is removed from the connectedDevicereturn of the getState method. If an app with connected device(s) goes background without disconnecting the device(s), all the connected device(s) will be disconnected.

Parameters

NameRequiredTypeDescription
addressRequiredStringThe address of the remote device.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
Error codeError textError description
100, 101, 102, 103,104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413See Error Code Reference for more details.See Error Code Reference for more details.

Example

var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "disconnect",
  parameters: {
    address: "4f:6b:40:db:5b:b2",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 401,
  "errorText": "Device is not connected"
}

client/discoverServices

Description

Discovers available services for the given remote device.
When calling this method, you should include the mac address of the connected device in the address parameter. When searching of the supported service of the connected device is complete, an onServicesDiscovered event is delivered as an event return of the client/connect method. To check the information about the searched service, call the client/getServices method.

Parameters

NameRequiredTypeDescription
addressRequiredStringThe address of the remote device.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413See Error Code Reference for more details.See Error Code Reference for more details.

Example

var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "discoverServices",
  parameters: {
    address: "4f:6b:40:db:5b:b2",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 404,
  "errorText": "Failed to start service discovery"
}

client/getServices

Description

Gets available services for remote device.
When calling this method, you should include the mac address of the connected device in the address parameter. The service information of the connected device is delivered in an onServicesDiscovered event as an event return of the client/connect method, and information about the service, characteristic, and descriptor is delivered in the values object.

Parameters

NameRequiredTypeDescription
addressRequiredStringThe address of the remote device.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413See Error Code Reference for more details.See Error Code Reference for more details.

Example

var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "getServices",
  parameters: {
    address: "4f:6b:40:db:5b:b2",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 405,
  "errorText": "Adapter Address is not valid"
}

client/setCharacteristicNotification

Description

Enables or disables notifications/indications for a given characteristic.
When calling this method, you should include the mac address of the connected device in the address parameter and include the service UUID where the characteristic for notification belongs in the service parameter. Also, you should include the characteristic UUID for notification in the characteristic parameter and set whether to enable notification in the enable parameter. When there is a change to the characteristic’s information for which notification is on, an onCharacteristicChanged event is delivered as an event return of theclient/connect method, and the changed values are delivered in the values object.

Parameters

NameRequiredTypeDescription
addressRequiredStringThe address of the remote device.
serviceRequiredStringUUID of the service the characteristic belongs to.
characteristicRequiredStringUUID of the characteristic to be monitored.
enableRequiredBooleanEnable or disable notifications.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413See Error Code Reference for more details.See Error Code Reference for more details.

Example

var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "setCharacteristicNotification",
  parameters: {
    address: "4f:6b:40:db:5b:b2",
    characteristic: "0000fff4-0000-1000-8000-00805f9b34fb",
    service: "0000fff0-0000-1000-8000-00805f9b34fb",
    enable: true,
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 408,
  "errorText": "GATT monitor characteristic failed for characteristic"
}

client/readCharacteristic

Description

Reads the value of a specific characteristic.
When calling this method, you should include the mac address of the connected device in the address parameter, include the service UUID where the characteristic for reading belongs in the service parameter, and include the characteristic UUID for read in the characteristic parameter. Information about the read characteristic is delivered in an onCharacteristicRead event as an event return of the client/connect method, and information about the characteristic is delivered in the values object.

Parameters

NameRequiredTypeDescription
addressRequiredStringThe address of the remote device.
serviceRequiredStringUUID of the service the characteristic belongs to.
characteristicRequiredStringUUID of the characteristic to read.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413See Error Code Reference for more details.See Error Code Reference for more details.

Example

var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "readCharacteristic",
  parameters: {
    address: "4f:6b:40:db:5b:b2",
    characteristic: "0000fff4-0000-1000-8000-00805f9b34fb",
    service: "0000fff0-0000-1000-8000-00805f9b34fb",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 410,
  "errorText": "GATT read characteristics failed"
}

client/readDescriptor

Description

Reads the value of descriptor of a service characteristic.
When calling this method, you should include the mac address of the connected device in the address parameter, include the descriptor UUID for reading in the descriptor parameter, and include the characteristic UUID where the descriptor belongs in the characteristic parameter, and include the service UUID where the characteristic belongs in the service parameter. Information about the read descriptor is delivered in an onDescriptorRead event as an event return of the client/connect method, and the descriptor information is delivered in the values object.

Parameters

NameRequiredTypeDescription
addressRequiredStringThe address of the remote device.
serviceRequiredStringUUID of the service the characteristic belongs to.
characteristicRequiredStringUUID of the characteristic the descriptor belongs to.
descriptorRequiredStringUUID of the descriptor.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413See Error Code Reference for more details.See Error Code Reference for more details.

Example

var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "readDescriptor",
  parameters: {
    address: "4f:6b:40:db:5b:b2",
    descriptor: "00002902-0000-1000-8000-00805f9b34fb",
    characteristic: "0000fff4-0000-1000-8000-00805f9b34fb",
    service: "0000fff0-0000-1000-8000-00805f9b34fb",
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 411,
  "errorText": "Required 'characteristic' uuid parameter is not supplied"
}

client/writeCharacteristic

Description

Writes the value for a remote characteristic.
When calling this method, you should include the mac address of the connected device in the addressparameter, include the service UUID where the characteristic to write belongs in the service parameter, and include the characteristic UUID in the characteristic parameter. Also, you should include the value to write in the value object, and the value should be of a single type, among string, number and bytes. If two or more types are included, the call of the method will fail. If writing to a certain characteristic is successful, an onCharacteristicWrite event is delivered as an event return of the client/connect method.

Parameters

NameRequiredTypeDescription
addressRequiredStringThe address of the remote device.
serviceRequiredStringUUID of the service the characteristic belongs to.
characteristicRequiredStringUUID of the characteristic.
valueRequiredObject: gattValueInfoValue of the characteristic.
A value can only have one type, and depending on this type, one of the fields "string", "number" or "bytes" should be passed. If multiple fields are passed, the method will fail.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413See Error Code Reference for more details.See Error Code Reference for more details.

Example

var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "writeCharacteristic",
  parameters: {
    address: "4f:6b:40:db:5b:b2",
    characteristic: "0000fff4-0000-1000-8000-00805f9b34fb",
    service: "0000fff0-0000-1000-8000-00805f9b34fb",
    value: { bytes: [0] },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 413,
  "errorText": "GATT write characteristic failed"
}

client/writeDescriptor

Description

Writes the value of a specific descriptor of a service characteristic in the remote device.
When calling this method, you should include the mac address of the connected device in the addressparameter, include the descriptor UUID for write in the descriptor parameter, include the characteristic UUID where the descriptor belongs in the characteristic parameter, and include the service UUID where the characteristic belongs in the service parameter. Also, you should include the value to write in the value object, and the value should be of a single type, among string, number and bytes. If two or more types are included, the call of the method will fail. If writing to a certain descriptor is successful, an onDescriptorWrite event is delivered as an event return of the client/connect method.

Parameters

NameRequiredTypeDescription
addressRequiredStringThe address of the remote device.
serviceRequiredStringUUID of the service the characteristic belongs to.
characteristicRequiredStringUUID of the characteristic the descriptor belongs to.
descriptorRequiredStringUUID of the descriptor.
valueOptionalObject: gattValueInfoValue of the characteristic.
A value can only have one type, and depending on this type, one of the fields "string", "number" or "bytes" should be passed. If multiple fields are passed, the method will fail.
notificationOptionalStringIf you want to receive or reject notification, set the corresponding value in Client Characteristic Configuration Descriptor(CCCD).
Available values are:
  • ENABLE_NOTIFICATION_VALUE: Receive notification.
  • DISABLE_NOTIFICATION_VALUE: Do not receive notification.

Call returns

NameRequiredTypeDescription
returnValueRequiredBooleanIndicates success/failure of the request.
  • true: Operation is successful.
  • false: Operation failed.
errorCodeOptionalNumberThe error code for the failed operation.
errorTextOptionalStringThe reason for the failure of the operation.
Error codeError textError description
100, 101, 102, 103, 104, 105, 106, 107, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413See Error Code Reference for more details.See Error Code Reference for more details.

Example

var request = webOS.service.request("luna://com.webos.service.blegatt", {
  method: "writeDescriptor",
  parameters: {
    address: "4f:6b:40:db:5b:b2",
    descriptor: "00002902-0000-1000-8000-00805f9b34fb",
    characteristic: "0000fff4-0000-1000-8000-00805f9b34fb",
    service: "0000fff0-0000-1000-8000-00805f9b34fb",
    value: { bytes: [0] },
  },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

Success return

{
  "returnValue": true
}

Failure return

{
  "returnValue": false,
  "errorCode": 414,
  "errorText": "Invalid value input for GATT characteristic"
}

Error code reference

Error CodeError TextDescription
-1Unknown method or Service does not existUnknown method or service does not exist.
0Unkonwn errorUnkonwn error.
100Bluetooth adapter is not available.The underlying Bluetooth daemon is not running or isn't attached to the hardware.
101Invalid JSON inputThe JSON input has an invalid format and cannot be parsed.
102The JSON input does not match the expected schemaOne or more of the parameters do not have the correct parameter type. See the 'Parameters' table to know the expected data type for each input parameter.
103This app is not have permission.The requested app does not have permission to control nearby devices.
104Unknown device addressThe remote Bluetooth device's address for performing the requested operation is not available in the list of found remote devices or is invalid.
105Failed to parse incoming messageThe JSON payload passed to the method cannot be parsed and the input parameters' values cannot be determined.
106Required 'address' parameter is not suppliedThe address parameter is mandatory, but was not supplied by the caller of the method.
107Device with supplied address is not availableThe remote Bluetooth device with the supplied address is not available (in the discovered devices list) to continue the operation of this method.
108BLEGATT version is not matched, please check the versionBLEGATT version is not matched, please check the version.
200Blegatt already scanningBlegatt already scanning
300Device is already pairedThe remote device with which we are trying to pair is already paired to the local device adapter.
301Device is not pairedDevice is not paired
302The operation failed for an unspecified or generic reasonThe requested Bluetooth operation failed for an unspecified or generic reason in the Bluetooth stack.
303The device is not ready to perform the requested operationThe Bluetooth adapter (local device) is not ready to perform the requested operation.
304The SIL failed to allocate memoryThe Bluetooth SIL (Stack Interface Layer) which interacts with the underlying stack has failed to allocate the required amount of memory to perform the requested operation.
305The operation can not be performed at this timeThe requested operation can not be performed by the adapter at this time since the adapter or SIL (Stack Interface Layer) is busy with a different operation.
306The requested operation is not supported by the stack or deviceThe requested operation is not supported by the Bluetooth stack or adapter.
307An invalid value was passed for one of the parametersAn invalid value was passed for one of the parameters while calling the SIL (Stack Interface Layer) from the Bluetooth service.
308An unhandled error was encounteredAn unhandled error was encountered at the SIL (Stack Interface Layer) while performing the requested operation.
309Authentication with a remote device was canceledAuthentication with a remote Bluetooth device was canceled by the remote Bluetooth device.
310Authentication with a remote device failedAuthentication with a remote Bluetooth device has failed either at the underlying stack.
311Authentication with a remote was rejectedAuthentication with a remote Bluetooth device was rejected by the remote Bluetooth device.
312Authentication with a remote device timed outAuthentication with a remote Bluetooth device has timed out before getting a valid response from the remote device.
313Failed to parse incoming messageThe JSON payload passed to the method cannot be parsed and the input parameters' values cannot be determined.
314Method needs to be subscribedThe API method needs to be called with an input parameter subscribe set to true, in order to get multiple responses for the LS call to this method. If subscribe is not set to true, this error is thrown.
315Only one subscription allowedOnly one client is allowed to subscribe to this method
316Pairing canceled by userThe ongoing pairing with a remote Bluetooth device has been canceled. The cancel is initiated by the client at the local device.
317Pairing already in progressOnly one remote device can be pairing with the bluetooth adapter at any given time. This error indicates that the adapter is already pairing with a remote Bluetooth device, either with incoming or outgoing. Hence another pair cannot be initiated.
318Failed to unpairFailed to unpair the Bluetooth adapter with the paired remote Bluetooth device.
400Device is already connectedThe remote Bluetooth device is already connected
401Device is not connectedThe remote Bluetooth device is not connected to our Bluetooth adapter via the profile.
402Profile backend is not availableThe SIL (Stack Interface Layer) module used doesn't provide any implementation for the profile.
403Bandwidth is not enough, please remove connected devices and try againBandwidth is not enough, please remove connected devices and try again
404Failed to start service discovery.GATT service discovery cannot be started, one of adapterAddress or address should be supplied
405Adapter Address is not validThe adapter address given is not valid.
406Required 'service' uuid parameter is not suppliedThe mandatory Service name parameter required by this method call is not supplied.
407Invalid GATT characteristic for the given serviceThe characteristic ID supplied does not belong to the service.
408GATT monitor characteristic failed for characteristicFailed to monitor GATT characteristic.
409Invalid GATT ServiceThe supplied GATT service is not available or is not configured.
410GATT read characteristics failedFailed to read the requested characteristics.
411Required 'characteristic' uuid parameter is not suppliedRequired 'characteristic' uuid parameter is not supplied
412Invalid value input for GATT characteristicThe supplied value for GATT characteristics is invalid.
413GATT write characteristic failedFailed to write characteristic the specified value.
414Invalid value input for GATT characteristicThe supplied value for GATT characteristics is invalid.

Objects

deviceStatus

Description

Object containing information about the state of the device identified by address.
This object is returned upon calling of the startScan method and contains information about the searched device. It includes the mac address, name, rssi, manufacturer, and service data of the searched device.

Properties

NameRequiredTypeDescription
addressRequiredStringThe address of the device.
nameRequiredStringThe name of the device.
rssiRequiredNumberSignal strength level of the device.
scanRecordRequiredNumber arrayService data of the remote device.
manufactureDataRequiredNumber arrayManufacturer-specific company ID and data (if advertised from the remote device, else it will be blank).

connectedDevice

Description

Object containing information about the connected device.
This object is returned upon calling of the getState method and contains information about the connected remote device. It includes the mac address and name of the connected device.

Properties

NameRequiredTypeDescription
addressRequiredStringThe address of the connected device.
nameOptionalStringThe name of the connected device.

pairedDevice

Description

Object containing information about paired device.
This object is returned upon calling of the getState method and contains information about the paired (bonded) remote device. It includes the mac address and name of the paired (bonded) device.

Properties

NameRequiredTypeDescription
addressRequiredStringThe address of the paired device.
nameOptionalStringThe name of the paired device.

values

Description

Values about connection status as well as any further GATT client operations.
This object is returned upon calling of the client/connect method and contains information to be delivered during operations of the GATT client. It includes the connection state information, characteristic information, and the changed value of the characteristic for notification.

Properties

NameRequiredTypeDescription
connectingOptionalBooleanIndicates whether the connection request is currently being processed.
Possible values are:
  • true: Request is being processed.
  • false: Not being processed.
connectedOptionalBooleanIndicates if the connection is open.
Possible values are:
  • true: Connection is open.
  • false: Connection is not open.
serviceClassesOptionalObjectArray of Service Classes supported by this device.
connectRequestOptionalBooleanIndicates whether the request is a connection request.
Possible values are:
  • true: Request is a connection request.
  • false: Request is a disconnection request.
serviceOptionalStringUUID of the service the characteristic belongs to.
characteristicOptionalStringUUID of the characteristic the descriptor belongs to.
servicesOptionalObject array: serviceInfoList of the available services.
changedOptionalObject array: characteristicInfoObject containing information about the characteristic uuid and values.

serviceInfo

Description

Object containing the GATT service configuration.
Supported services of the remote device are provided in an array format. Each array includes service UUID, service type, and characteristics included in the service.

Properties

NameRequiredTypeDescription
serviceRequiredStringUUID of the service.
typeRequiredStringUUID which describes the type of the service.
The following types are defined:
  • primary (UUID 0x2800
  • secondary (UUID 0x2801)
includesOptionalString arrayList of service UUIDs this services includes in its definition.
characteristicsOptionalObject array: characteristicInfoList of characteristics which are part of the service.

characteristicInfo

Description

Object containing information about a GATT characteristic.
Information about characteristics included in a certain service is provided in an array format. Each array includes characteristic UUID, value, property, permission, and descriptors included in the characteristic.

Properties

NameRequiredTypeDescription
characteristicRequiredStringUUID of the characteristic.
valueRequiredObject array: gattValueInfoValue of the characteristic.
propertiesRequiredObject array: propertiesInfoConfigured properties for the characteristic.
permissionsRequiredObject array: permissionsInfoConfigured permissions for the characteristic.
descriptorsRequiredObject array: descriptorInfoList of descriptors for the characteristic.

descriptorInfo

Description

Object containing information about a GATT descriptor.
Information about descriptors included in a certain characteristic is provided in an array format. Each array includes descriptor UUID and value.

Properties

NameRequiredTypeDescription
descriptorRequiredStringUUID of the descriptor.
valueRequiredObject array: gattValueInfovalue of the descriptor.

gattValueInfo

Description

Object containing information about a GATT value.
As a GATT characteristic can be extended with a descriptor which describes the type of the stored value, we have three different representations of a value currently:

  • string
  • number
  • array of numbers
The last one is used only when a non-value type descriptor is present.

Properties

NameRequiredTypeDescription
stringOptionalStringPresent when the value is from type string. Not present otherwise.
numberOptionalNumberPresent when the value is from type number. Not present otherwise.
bytesOptionalNumber arrayIf the type of the value is not specified then the value is returned as a sequence of bytes.

propertiesInfo

Description

Object containing information about the set properties of a characteristic.
All properties are defined in Bluetooth Core Specification 4.1 vol. 4 Part G chapter 3.3.1.1.

Properties

NameRequiredTypeDescription
broadcastOptionalBooleanIf set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor.
If set, the Server Characteristic Configuration Descriptor shall exist.
readOptionalBooleanIf set, permits reads of the Characteristic Value.
writeWithoutResponseOptionalBooleanIf set, permit writes of the Characteristic Value without response.
writeOptionalBooleanIf set, permits writes of the Characteristic Value with response.
notifyOptionalBooleanIf set, permits notifications of a Characteristic Value without acknowledgement.
If set, the Client Characteristic Configuration Descriptor shall exist.
indicateOptionalBooleanIf set, permits indications of a Characteristic Value with acknowledgement.
authenticatedSignedWritesOptionalBooleanIf set, permits signed writes to the Characteristic Value.
extendedPropertiesOptionalBooleanIf set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor.
If set, the Characteristic Extended Properties Descriptor shall exist.

permissionsInfo

Description

Object containing information about the permissions allowed for a client to use a particular characteristic value.
All properties are defined in Bluetooth Core Specification 4.1 vol. 4 Part G chapter 3.3.1.1.

Properties

NameRequiredTypeDescription
readOptionalBooleanIf set, clients are allowed to read the characteristic value.
readEncryptedOptionalBooleanIf set, allows encrypted read operations.
readEncryptedMitmOptionalBooleanIf set, permits writes of the Characteristic Value with response.
notifyOptionalBooleanIf set, allows reading with man-in-the-middle protection.
writeOptionalBooleanIf set, clients are allowed to write the characteristic value.
writeEncryptedOptionalBooleanIf set, allows encrypted writes.
writeEncryptedMitmOptionalBooleanIf set, allows encrypted writes with man-in-the-middle protection.
writeSignedOptionalBooleanIf set, allows signed write operations.
writeSignedMitmOptionalBooleanIf set, allows signed write operations with man-in-the-middle protection.
No Headings