com.webos.service.bluetooth2

API Summary

This API allows webOS to use remote Bluetooth devices. 

Overview of the API

(click to expand)

Bluetooth Service Categories

  • adapter: Provides methods for discovering and pairing with remote Bluetooth devices and for querying their status and Bluetooth adapters available in the system. Both outgoing and incoming pairing is supported.
  • device: Provides methods for getting status of remote Bluetooth devices known to the system and for setting the local values for their state.
  • gatt: Provides methods for using the GATT profile. 
  • le: Provides methods for using Low Energy (LE) functionality. 
  • spp: Provides methods for using the SPP profile. The SPP defines two roles, that of a Server and Client device. 
  • a2dp: Provides methods for using the A2DP profile. 
  • opp: Provides methods for using the OPP profile. 


Method Behavior

  • 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 a 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().

 

Glossary


Open All


a2dp/connect

Description

Connect to A2DP profile on the specified remote device.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device.

subscribe Optional Boolean
  • To be notified when the connection is closed, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false.
adapterAddress Optional String

The address of the adapter to use for connecting to A2DP profile on a remote device.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the connection is successfully open, returnValue will contain true.
  • Otherwise, returnValue will contain false.
subscribed Required Boolean
  • If the method is subscribed, subscribed will contain true.
  • If the method is not subscribed, subscribed will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the connection is successfully open, returnValue will contain true.
  • Otherwise, returnValue will contain false.
subscribed Required Boolean

If the method is subscribed, subscribed will contain true until the final response is sent by the service before stopping. 

If the method is not subscribed, subscribed will contain false.

disconnectByRemote Required String
  • If the remote device initiated the disconnect, disconnectByRemote will contain true.
  • If the local user initiated the disconnect, disconnectByRemote will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 103, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

128 Device is already connecting

The remote Bluetooth device is already connecting to A2DP profile, so another connection cannot be opened.

129 Device is not paired

The remote Bluetooth device is not paired, so A2DP connection cannot be opened.

130 Failed to connect with remote device

The remote Bluetooth device cannot be connected to A2DP profile.

131 Already connected

The remote Bluetooth device is already connected to the adapter's A2DP profile, so another connection cannot be opened.

Example

# luna-send -i -f luna://com.webos.service.bluetooth2/a2dp/connect '{
      "address":"00:18:6b:49:db:86",
      "subscribe":true
}'

 

Example response for a successful call:

{

"subscribed": true,

"adapterAddress": "00:00:45:0e:48:9b",

"returnValue": true

}

 

Example response for a failed call: If address is not valid,

{

"errorCode": 106,

"returnValue": false,

"errorText": "Device with supplied address is not available"

}

 

Subscription return: If connection is successful,

{

"subscribed": true,

"adapterAddress": "00:00:45:0e:48:9b",

"returnValue": true

}


a2dp/disconnect

Description

Drop the connection to the given remote device on A2DP profile.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device.

adapterAddress Optional String

The address of the adapter to use for disconnecting from A2DP profile on a remote device.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the connection is successfully closed, returnValue will contain true.
  • Otherwise, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

132 Failed to disconnect from remote device

The A2DP connection with the remote Bluetooth device could not be closed.

Example

# luna-send -i -f luna://com.webos.service.bluetooth2/a2dp/disconnect '{
       "address":"aa:bb:cc:dd:ee:00"
}'

 

Example response for a successful call:

{

"adapterAddress": "11:22:33:44:55:66",

"returnValue": true

}

 

Example response for a failed call: If address is not valid,

{

"errorCode": 106,

"returnValue": false,

"errorText": "Device with supplied address is not available"

}


a2dp/getStatus

Description

Return the status of A2DP connection to a remote device.

If address input parameter is not specified, the method will return the information of the device whose connection or playing status has been changed. 

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device.

subscribe Optional Boolean
  • To be notified of changes to the connection, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false.
adapterAddress Optional String

The address of the adapter to use for getting status from A2DP profile on a remote device.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the status is successfully returned, returnValue will contain true.
  • Otherwise, returnValue will contain false.
subscribed Required Boolean
  • If the method is subscribed, subscribed will contain true.
  • If the method is not subscribed, subscribed will contain false
connecting Required Boolean
  • If the connection request is currently being processed, connecting will contain true.
  • Otherwise, connecting will contain false. For example, the Bluetooth stack is no longer processing the connection request.
connected Required Boolean
  • If the connection is open, connected will contain true.
  • Otherwise, connected will contain false.
playing Required Boolean
  • If either adapter or remote device is streaming music, playing will contain true.
  • Otherwise, playing will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

address Optional String

The address (bdaddr) of the remote device.

Only when address input parameter is not specified, address will be returned.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the status is successfully returned, returnValue will contain true.
  • Otherwise, returnValue will contain false.
subscribed Required Boolean
  • If the method is subscribed, subscribed will contain true until the final response is sent by the service before stopping.
  • If the method is not subscribed, subscribed will contain false
connecting Required Boolean
  • If the connection request is currently being processed, connecting will contain true.
  • Otherwise, connecting will contain false.
connected Required Boolean
  • If the connection is open, connected will contain true.
  • Otherwise, connected will contain false.
playing Required Boolean
  • If either adapter or remote device is streaming music,playing will contain true.
  • Otherwise, playing will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

address Optional String

The address (bdaddr) of the remote device.

Only when address input parameter is not specified, address will be returned.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

133 Failed to retrieve state for remote device

The A2DP connection status of the remote Bluetooth device cannot be retrieved.

Example

# luna-send -i -f luna://com.webos.service.bluetooth2/a2dp/getStatus '{
      "address":"aa:bb:cc:dd:ee:00",
      "subscribe":true
}'

 

Example response for a failed call: If address is not valid,

{

       "errorCode": 106,

       "returnValue": false,

       "errorText": "Device with supplied address is not available"

}

 

Subscription return: If user connects to remote device, connected field is changed from false to true when remote device is connected.

{

       "playing": false,

       "adapterAddress": "11:22:33:44:55:66",

       "address": "aa:bb:cc:dd:ee:00",

       "connected": false,

       "subscribed": true,

       "returnValue": true,

       "connecting": true

}

{

       "playing": false,

       "adapterAddress": "11:22:33:44:55:66",

       "address": "aa:bb:cc:dd:ee:00",

       "connected": true,

       "subscribed": true,

       "returnValue": true,

       "connecting": false

}

 

Subscription return : If user disconnects the connected device,

{

       "subscribed": false,

       "disconnectByRemote": true,

       "returnValue": false

}


adapter/awaitPairingRequests

Description

Await incoming pairing requests on the default Bluetooth adapter (only) by setting its state to be pairable. The caller must subscribe to this method. It expects the caller will stay subscribed to this method across multiple pairing requests for as long as the webOS device wishes to accept pairing requests.

Only one pairing request, either incoming or outgoing, can be active for an adapter at a given time.

  • An outgoing pairing request is active until the service ends the subscription to adapter/pair by sending a subscription response containing request:endPairing.
  • An incoming pairing request is active once a subscription response to this method contains request:displayPinCoderequest:displayPasskeyrequest:confirmPasskeyrequest:enterPinCode, or request:enterPinCode
  • An incoming pairing request becomes inactive
    • When a subscription response to this method contains request:endPairing.
    • When the pairing succeeds (with the corresponding device having paired field as true). In this case, there is no request:endPairing response. So that the user or client needs to monitor the paired field of the remote device with device/getStatus

If the client calls LSCallCancel(), any active incoming pairing request is cancelled the same way as if the adapter/cancelPairing​ method had been called.

A remote device can only be paired to a single adapter.

NOTE: If it is ever possible to allow incoming pairing on adapters other than the default, an optional adapterAddress parameter will be added to the parameter list.

Parameters

Name

Required

Type

Description

subscribe Required Boolean

Must set subscribe to trueThe caller must subscribe to this method.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the adapter/awaitPairingRequests method succeeds, returnValue will contain true.
  • If the adapter/awaitPairingRequests method fails, returnValue will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the pairing process succeeds, returnValue will contain true.
  • If the pairing process fails, returnValue will contain false.
subscribed Required Boolean

subscribed will always contain true since subscription ends only when the client chooses to close it.

address Required String

The address (bdaddr) of the remote device with which pairing is being attempted.

request Required String

request will contain one of:

  • incomingPairRequest - display an incoming pairing request received from the remote device.
  • displayPinCode - display pinCode until the endPairing response is sent by the service.
  • displayPasskey - display passkey until the endPairing response is sent by the service.
  • confirmPasskey - request the user to confirm passkey; only used with devices supporting Simple Secure Pairing (SSP) and Bluetooth version 2.1 or later.​
  • enterPinCode - request the user to enter a PIN code.
  • enterPasskey - request the user to enter a passkey.
  • continuePairing - the request to cancel pairing from adapter/cancelPairing failed.
  • endPairing - the pairing process has been cancelled; returnValue will contain falseerrorCode and errorText​ will explain the failure.
passkey Optional String

The passkey for request:displayPasskey or request:confirmPasskey.

pinCode Optional String

The PIN code for request:displayPinCode.

name Required String

The friendly name of the device displayed to the user.

When a previously undiscovered device is first discovered, the system makes up a reasonable value for this.

Error References

Error Code

Error Text

Error Description

101-104, 107, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

123 Failed to make device pairable

The Bluetooth stack could not set the pairable property of the adapter to true.

124 Pairing canceled or timed out

The ongoing incoming pairing with a remote device has been either canceled at the remote device or timed out before receiving a response from the remote device.

125 Device for incoming pairing request is not available

The remote Bluetooth device from which incoming pairing request has been received is not currently available.

126 Pairable timeout reached

The set pairable timeout has reached, hence the pairing operation cannot continue and the adapter is no longer pairable. The client should subscribe to adapter/awaitPairingRequests method again to make the adapter pairable.

Example

# luna-send -i -f luna://com.webos.service.bluetooth2/adapter/awaitPairingRequests '{
      "subscribe":true
}'

 

Example response for a successful call:

{

"subscribe":true

"returnValue": true

}

 

Example response for a failed call: If device is not pairable

{

"errorCode": 123,

"returnValue": false,

"errorText": "Failed to make device pairable"

}

 

Subscription return : If remote device request pairing.

{

"address": "34:4d:f7:f9:52:f7",

"name":"XYZ DEVICE",

"subscribeed":true,

"request":incommingPairRequest",

"returnValue": true

}

{

"returnValue": true,

"subscribeed":true,

"passkey":952197,

"address": "34:4d:f7:f9:52:f7",

"name":"XYZ DEVICE",

"request":"confirmPasskey"

}


adapter/cancelDiscovery

Description

Cancel discovering remote Bluetooth devices. Only one adapter can be discovering at a time.

Parameters

None

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the default adapter will be returned always.

returnValue Required Boolean

returnValue will always contain true (even if there was no active discovery scan).

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

101 See API Error Codes Reference

See API Error Codes Reference.

116 Can't stop discovery when adapter is turned off

The adapter needs to be powered on with adapter/setState to stop discovering other remote devices.

117 Failed to cancel discovery

The Bluetooth stack could not terminate discovering remote devices.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/adapter/cancelDiscovery '{ }'

 

Example response for a successful call:

{

"adapterAddress": "00:00:45:0e:48:9b",

"returnValue": true

}

 

Example response for a failed call: If cancel discovery fail.

{

"errorCode": 117,

"returnValue": false,

"errorText": "Failed to cancel discovery"

}


adapter/cancelPairing

Description

Cancel the pairing request with a remote device, either incoming or outgoing. The method sends a success response immediately.

Once the SIL calls back,

  • if the cancel succeeds, it causes a request:endPairing subscription response to adapter/pair or adapter/awaitPairingRequests with a "Pairing canceled by user" error.
  • if the cancel fails, it cause a request:continuePairing subscription response.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device with which pairing is being attempted.

adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain true.

subscribed Required Boolean
  • To be notified of changes to the connection, set subscribe to true.
  • Otherwise, set subscribe to false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

101, 102, 105, 106, 108, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/adapter/cancelPairing '{
      "address": "34:4d:f7:f9:52:f7"
}'

 

Example response for a successful call:

{

"returnValue": true,

"subscribed":false,

"adapterAddress": "00:00:45:0e:48:9b"

}

 

Example response for a failed call: if address is invalid.

{

"errorCode": 8,

"returnValue": false,

"errorText": "Unknown device address"

}


adapter/getStatus

Description

Return status information about the Bluetooth adapters available in the system.

Parameters

Name

Required

Type

Description

subscribe Optional Boolean
  • To be informed of changes to adapter state, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false.

Call Returns

Name

Required

Type

Description

subscribed Required Boolean
  • If the method is subscribed, subscribed will contain true.
  • If the method is not subscribed, subscribed will contain false
returnValue Required Boolean

returnValue will always contain true unless the request for subscription has failed.

adapters Required Object array: bluetooth2AdapterStatus

adapters will contain information for all the Bluetooth adapters available in the system, not just the ones whose status has been changed.

If there are no available adapters, the array will be empty.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain true unless the request for subscription has failed.

subscribed Required Boolean
  • If the method is subscribed, subscribed will contain true until the final response is sent by the service before stopping.
  • If the method is not subscribed, subscribed will contain false
adapters Required Object array: bluetooth2AdapterStatus

adapters will contain status information for all the Bluetooth adapters available in the system, not just the ones whose status has been changed.

If there are no available adapters, the array will be empty.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

101, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -i -f luna://com.webos.service.bluetooth2/adapter/getStatus '{
       "subscribe":true
}'

 

Example response for a successful call:

{

"subscribed":false,

"adapters":[

{

"powered": true,

"discoveryTimeout": 20,

"pairing": true,

"discoverableTimeout": 30,

"name": "LG",

"adapterAddress": "00:00:dd:41:6b:ef",

"discovering": false,

"discoverable": false,

"pairable": true,

"pairableTimeout": 30

}

]

"returnValue": true

}

 

Example response for a failed call: if bluetooth stack is invalid.

{

"errorCode": 101,

"returnValue": false,

"errorText": "Bluetooth adapter is not available"

}

 

Subscription return: If subscription call succeeds.

{

"subscribed":true,

"adapters":[

{

"powered": true,

"discoveryTimeout": 20,

"pairing": true,

"discoverableTimeout": 30,

"name": "LG",

"adapterAddress": "00:00:dd:41:6b:ef",

"discovering": false,

"discoverable": false,

"pairable": true,

"pairableTimeout": 30

}

]

"returnValue": true

}


adapter/pair

Description

Pair a specific remote Bluetooth device with a specific Bluetooth adapter. The caller must subscribe to this method.

Only one pairing request, either incoming or outgoing, can be active for an adapter at a given time.

  • An outgoing pairing request is active until the service ends the subscription to this method by sending a subscription response containing request:endPairing.
  • An incoming pairing request is active once a subscription response to adapter/awaitPairingRequests contains request:displayPinCoderequest:displayPasskeyrequest:confirmPasskeyrequest:enterPinCode, or request:enterPinCode.
  • An incoming pairing becomes inactive when a subscription response contains request:endPairing

If the client calls LSCallCancel(), the pairing is cancelled the same way as if adapter/cancelPairing had been called.

A remote device can only be paired to a single adapter.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device with which to attempt to pair.

subscribe Required Boolean

Must set subscribe to true. The caller must subscribe to this method.

adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain false. The callers must subscribe to this method.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain falseUse errorCode/errorText to discovery why.

subscribed Required Boolean
  • If the subscription request succeeds, subscribed will contain true until the request:endPairing response is sent by the service.
  • If the subscription request fails, subscribed will contain false.
address Optional String

The address (bdaddr) of the paired remote Bluetooth device.

request Optional String

The value will be one of the followings:

  • displayPinCode - display pinCode until the endPairing response is sent by the service.
  • displayPasskey - display passkey until the endPairing response is sent by the service.
  • confirmPasskey - request the user to confirm passkey; only used with devices supporting Simple Secure Pairing (SSP) and Bluetooth version 2.1 or later. ​
  • enterPinCode - request the user to enter a PIN code.
  • enterPasskey - request the user to enter a passkey.
  • continuePairing - the request to cancel pairing from adapter/cancelPairing failed.
  • endPairing - the pairing process is complete; subscribed will contain false and returnValue indicates whether pairing succeeded; errorCode and errorText​ will explain the failure.
passkey Optional Number

The passkey for request:displayPasskey or request:confirmPasskey.

pinCode Optional String

The PIN code for request:displayPinCode.

Error References

Error Code

Error Text

Error Description

1-13, 101-107, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

118 Pairing already in progress

Only 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.

Example

# luna-send -i -f luna://com.webos.service.bluetooth2/adapter/pair '{
      "address": "34:4d:f7:f9:52:f7",
      "subscribe":true
}'

 

Example response for a failed call: If device is pairing already.

{

"errorCode": 118,

"returnValue": false,

"errorText": "Pairing already in progress"

}

 

Subscription return : If remote device request pairing.

{

"returnValue": true,

"subscribeed":true,

"passkey":952197,

"address": "34:4d:f7:f9:52:f7",

"request":"confirmPasskey"

}


adapter/queryAvailable

Description

Return information of the Bluetooth adapters currently available in the system. The caller subscribes to this method to get informed of added/removed adapters (e.g., Bluetooth dongles) dynamically. The information returned for an adapter doesn't change while it is available.

Parameters

Name

Required

Type

Description

subscribe Optional Boolean
  • To be informed of added/removed adapters dynamically, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false.

Call Returns

Name

Required

Type

Description

subscribed Required Boolean
  • If the method is subscribed, subscribed will contain true.
  • If the method is not subscribed, subscribed will contain false
returnValue Required Boolean

 returnValue will always contain true unless the request for subscription failed. 

adapters Required Object array: bluetooth2Adapter

Constant information of all the adapters currently available in the system, not just the ones that have been added/removed. The information of the adapter does not change by user or by any operations. The information returned for an adapter does not change while it is available. 

If there are no available adapters, the array will be empty.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain true unless the request for subscription failed.

subscribed Required Boolean
  • If the method is subscribed, subscribed will contain true until the final response is sent by the service before stopping.
  • If the method is not subscribed, subscribed will contain false
adapters Required Object array: bluetooth2AdapterStatus

Constant information of all the adapters currently available in the system, not just the ones that have been added/removed. The information of the adapter does not change by user or by any operations. The information returned for an adapter does not change while it is available. 

If there are no available adapters, the array will be empty.

errorCode Optional String

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. 

Error References

Error Code

Error Text

Error Description

101, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -i -f luna://com.webos.service.bluetooth2/adapter/queryAvailable '{
        "subscribe":true
}'

 

Example response for a successful call:

{

"subscribed": false,

"adapters": [

{

"stackName": "mock",

"stackVersion": "",

"adapterAddress": "00:00:dd:41:6b:ef",

"classOfDevice": 5898764,

"firmwareVersion": "",

"serviceClasses": [],

"default": true

}

],

"returnValue": true

}

 

Example response for a failed call: If bluetooth daemon is not running

{

"errorCode": 101,

"returnValue": false,

"errorText": "Bluetooth adapter is not available"

}

 

Subscription return: If subscription call is success.

{

"subscribed": false,

"adapters": [

{

"stackName": "mock",

"stackVersion": "",

"adapterAddress": "00:00:dd:41:6b:ef",

"classOfDevice": 5898764,

"firmwareVersion": "",

"serviceClasses": [],

"default": true

}

],

"returnValue": true

}


adapter/setState

Description

Set the state of the specified Bluetooth adapter.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

name Optional String

The friendly name of the adapter​.

powered Optional Boolean
  • To power on the adapter radio, set powered to true.
  • To power off the adapter radio, set powered to false.
discoveryTimeout Optional Number

The discovery timeout in seconds.

After discoveryTimeout seconds, the adapter will stop discovering remote Bluetooth devices.

A value of 0 means that the timeout is disabled and the adapter will run the discovery process until the adapter/cancelDiscovery​ method is called. Negative values are illegal. 

discoverable Optional Boolean
  • To allow the adapter can be discovered by remote devices, set discoverable to true.
  • Otherwise, set discoverable to false.
  • The default value of discoverable is false.

NOTE. If discoverableTimeout is set to a non-zero value, discoverable will be set back to false when the timer expires.

discoverableTimeout Optional Number

The discoverable timeout in seconds.

A value of 0 means that the timeout is disabled and the adapter will stay in discoverable mode until discoverable is set to false. Negative values are illegal.

pairable Optional Boolean
  • To enable the adapter to be paired to a remote device, set pairable to true.
  • To disable the adapter to be paired to a remote device, set pairable to false.
  • The default value of pairable is true.
pairableTimeout Optional Number

The pairable timeout in seconds.

After pairableTimeout seconds, the adapter is no longer pairable and false is returned for pairable​.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the state was successfully set, returnValue will contain true.
  • If the method fails, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

5, 101, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

109 Invalid negative value for discoveryTimeout:

The discoveryTimeout parameter value cannot be negative, hence invalid. The passed value is also mentioned in the error message.

110 Invalid negative value for discoverableTimeout:

The discoverableTimeout parameter value cannot be negative, hence invalid. The passed value is also mentioned in the error message.

111 Invalid negative value for pairableTimeout:

The pairableTimeout parameter value cannot be negative, hence invalid. The passed value is also mentioned in the error message.

112 Failed to change bluetooth power status

The default Bluetooth adapter cannot be either enabled or disabled as requested in the method.

113 Failed to set adapter properties

The Bluetooth adapter properties cannot be set to the stack(bluez5/bsa) as requested in this method.

Example

# luna-send -f -n 1 palm://com.webos.service.bluetooth2/adapter/setState '{"powered":true}'

 

Example response for a successful call:

{

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

 

Example response for a failed call: if fail to change power status

{

"errorCode": 112,

"returnValue": false,

"errorText": "Failed to change bluetooth power status"

}


adapter/startDiscovery

Description

Start discovering remote Bluetooth devices. Discovering continues until adapter/cancelDiscovery​ is called or for bluetooth2AdapterStatus.discoveryTimeout​ seconds (if non-zero). Only one adapter can be discovering at a time.

To receive which devices are found, subscribe to device/getStatus.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If scanning was successfully started or was previously started by an earlier call, returnValue will contain true.
  • Otherwise (including another adapter is already scanning), returnValue will contain false.
adapterAddress Required String

The address of the adapter which executed this method.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

101 See API Error Codes Reference

See API Error Codes Reference.

114 Can't start discovery when adapter is turned off

Bluetooth adapter needs to be powered on with adapter/setState to start discovering other remote Bluetooth devices.

115 Failed to start discovery

The Bluetooth stack could not initiate discovery of remote Bluetooth devices.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/adapter/startDiscovery '{ }'

 

Example response for a successful call:

{

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

 

Example response for a failed call: if fail to start discovery

{

"errorCode": 115,

"returnValue": false,

"errorText": "Failed to start discovery"

}


adapter/supplyPasskey

Description

Supply the user-entered passkey. The passkey is entered when adapter/pair sends a subscription response containing request:enterPasskey​.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device with which pairing is being attempted.

passkey Required Number

The passkey entered by the user.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the default adapter will be always returned.

returnValue Required Boolean

returnValue will always contain true.

If the passkey is incorrect, the adapter/pair method will send a final subscription response containing returnValue:false indicating pairing has failed.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

1-13, 101, 102, 105, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

119 Required 'passkey' parameter not supplied

The passkey parameter is mandatory to this method, but was not supplied by the caller of the method.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/adapter/supplyPasskey '{
       "address": "34:4d:f7:f9:52:f7",
       "passkey":842280
}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:45:0e:48:9b",

"returnValue": true

}

 

Example response for a failed call: if bluetooth daemon is not running

{

"errorCode": 101,

"returnValue": false,

"errorText": "Bluetooth adapter is not available"

}


adapter/supplyPasskeyConfirmation

Description

Supply the user's confirmation of the passkey. The user confirms the passkey when adapter/pair sends a subscription response containing request:confirmPasskey​.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device with which pairing is being attempted.

accept Required Boolean
  • If the user confirmed the passkey, set accept to true.
  • If the user didn't confirm the passkey, set accept to false.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the default adapter will be always returned.

returnValue Required Boolean

returnValue will always contain true.

If the accept is false, the adapter/pair method will send a final subscription response containing returnValue:false indicating pairing has failed.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

1-13, 101, 102, 105, 108, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

121 Required 'accept' parameter not supplied

The accept parameter is mandatory for this method, but was not supplied by the caller of the method.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/adapter/supplyPasskeyConfirmation '{
      "address": "34:4d:f7:f9:52:f7",
      "accept":true
}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:45:0e:48:9b",

"returnValue": true

}

 

Example response for a failed call: if bluetooth daemon is not running

{

"errorCode": 101,

"returnValue": false,

"errorText": "Bluetooth adapter is not available"

}


adapter/supplyPinCode

Description

Supply the user-entered PIN code. The PIN code is entered when adapter/pair sends a subscription response containing request:enterPinCode.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device with which pairing is being attempted.

pin Required String

The PIN code entered by the user.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the default adapter will be always returned.

returnValue Required Boolean

returnValue will always contain true.

If the pin is incorrect, the adapter/pair method will send a final subscription response containing returnValue:false indicating pairing has failed.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

1-13, 101, 102, 105, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

120 Required 'pin' parameter not supplied

The pin parameter is mandatory to this method, but was not supplied by the caller of the method.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/adapter/supplyPinCode '{
      "address": "34:4d:f7:f9:52:f7",
      "pin":"2345"
}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:45:0e:48:9b",

"returnValue": true

}

 

Example response for a failed call: if bluetooth daemon is not running

{

"errorCode": 101,

"returnValue": false,

"errorText": "Bluetooth adapter is not available"

}


adapter/unpair

Description

Disconnect 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.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device to unpair.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the remote device was successfully unpaired, returnValue will contain true.
  • If the remote device was not unpaired, returnValue will contain false. (e.g., address wasn't paired to start with)
adapterAddress Required String

The address of the default adapter will be always returned.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

101, 102, 105, 106, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

122 Failed to unpair

Failed to unpair the Bluetooth adapter with the paired remote Bluetooth device.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/adapter/unpair '{
      "address": "34:4d:f7:f9:52:f7"
}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:45:0e:48:9b",

"returnValue": true

}

 

Example response for a failed call: if unpairing is failed

{

"errorCode": 122,

"returnValue": false,

"errorText": "Failed to unpair"

}


device/getStatus

Description

Get the current status of remote Bluetooth devices known to the system.​ 

Parameters

Name

Required

Type

Description

subscribe Optional Boolean
  • To be informed of changes to the status of remote devices, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false.

Call Returns

Name

Required

Type

Description

subscribed Required Boolean
  • If the method is subscribed, subscribed will contain true.
  • If the method is not subscribed, subscribed will contain false
returnValue Required Boolean

returnValue will always contain true unless the request for subscription failed.

adapterAddress Required String

The address of the default adapter will be always returned.

devices Required Object array: bluetooth2DeviceStatus

devices will contain status information for all the devices known to the system, not just the ones whose status has been changed.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

subscribed Required Boolean
  • If it is subscribed, subscribed will contain true until the final response is sent by the service before stopping.
  • If it is not subscribed, subscribed will contain false
returnValue Required Boolean

returnValue will always contain true unless the request for subscription failed.

adapterAddress Required String

The address of the default adapter will be always returned.

devices Required Object array: bluetooth2DeviceStatus

devices will contain status information for all the devices known to the system, not just the ones whose status has been changed.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

101, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

Example

Example response for a successful call:

{

"subscribed": false,

"adapterAddress": "00:00:dd:41:6b:ef",

"returnValue": true,

"devices": [

{

"serviceClasses": [

],

"trusted": false,

"connectedProfiles": [

],

"pairing": false,

"rssi": -68,

"name": "Music Flow H3(32:CB)",

"address": "08:ef:3b:0e:a8:17",

"paired": true,

"typeOfDevice": "dual",

"adapterAddress": "00:00:dd:41:6b:ef",

"classOfDevice": 0,

"blocked": false

}

]

}

 

Example response for a failed call: if Bluetooth daemon is not running

{

"errorCode": 101,

"returnValue": false,

"errorText": "Bluetooth adapter is not available"

}

 

Subscription return: If subscription call is successful.

{

"subscribed": true,

"adapterAddress": "00:00:dd:41:6b:ef",

"returnValue": true,

"devices": [

{

"serviceClasses": [

],

"trusted": false,

"connectedProfiles": [

],

"pairing": false,

"rssi": -68,

"name": "Music Flow H3(32:CB)",

"address": "08:ef:3b:0e:a8:17",

"paired": true,

"typeOfDevice": "dual",

"adapterAddress": "00:00:dd:41:6b:ef",

"classOfDevice": 0,

"blocked": false

}

]

}


device/setState

Description

Set the local values for the state of a remote device.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device.

adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

trusted Optional Boolean
  • To set a remote device as a trusted device, set trusted to true.
  • Otherwise, set trusted to false.
  • The default value of trusted is false.
blocked Optional Boolean

blocked is used to block (if set) or unblock (if reset) a remote device for pairing and profile connections.

  • To block incoming connections, set blocked to true. Any incoming connections from the device will be immediately rejected. Any device drivers will also be removed and no new ones will be probed as long as the device is blocked.
  • Otherwise, set blocked to false.
  • The default value of blocked is false.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the state of a remote device is successfully set, subscribed will contain true.
  • If the state of a remote device is not set, subscribed will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

5, 101, 105, 106, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

148 No property state has changed

Either no parameters are supplied to the device/setState method or the parameters have no state change from their earlier value.

149 Failed to set device properties

The Bluetooth stack fails to set the supplied device properties for the given device.

Example

# luna-send -f -n 1 palm://com.webos.service.bluetooth2/device/setState '{"address":"34:4d:f7:f9:52:f7", "trusted":true}'

Example response for a successful call:

{

"returnValue": true

}

Example response for a failed call: if fail to set the supplied properties

{

"errorCode": 149,

"returnValue": false,

"errorText": "Failed to set device properties"

}


gatt/addService

Description

Add a new service definition to the local database.

The new service will be directly exposed to clients which are discovering available services.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter to create a service on.

service Required String

Unique identifier of the service.

type Required String

Type of the service. The value can be one of "primary" or "secondary".

includes Required String array

An array that contains a list of UUIDs the service includes.

characteristics Required Object array: bluetooth2GattCharacteristicInfo

Information about GATT characteristics of the service.

serverId Optional String

The server identifier to add the service to. If not specified, the default value of serverId is made automatically.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of adapter on which the service is added.

returnValue Required Boolean
  • If the service is successfully added, returnValue will contain true.
  • Otherwise, returnValue will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

serverId Required String

The server identifier to add the service.

Error References

Error Code

Error Text

Error Description

127,143,144,175,170 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/addService '{
     "service":"6161",
     "type":"primary",
     "includes":[],
     "characteristics":[
                    {
                        "characteristic":"1a4ef224-f27a-11e4-b9b2-1697f925ec7b",
                        "properties":{"broadcast":true,"read":true,"indicate":true,"write":true,"notify":true},
                        "permissions":{"read":true,"write":true},
                        "value":{"bytes":[34,0,12,99]},
                        "descriptors":[
                                     {
                                          "descriptor":"f000ffc1-0451-4000-b000-000000000000",
                                          "value":{"bytes":[0]}
                                     }
                                 ]
                            }
                     ]

  }'

 

Example response for a successful call:

{

"adapterAddress": "00:00:68:64:d1:30",

"returnValue": true,

"serverId":"006"

}


gatt/closeServer

Description

Closes BluetoothGattServer.

Parameters

Name

Required

Type

Description

serverId Required String

Unique identifier of a server to remove on the stack.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorCode Optional String

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/closeServer '{ "serverId":"001" }'

return:

{

    "adapterAddress": "00:00:9a:1d:89:5d",

    "returnValue": true

}


gatt/connect

Description

Connect to GATT profile on the specified remote device.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter to use for connecting to GATT profile on a remote device.

If not specified, the default adapter will be used.

address Required String

The address of the remote device.

subscribe Optional Boolean
  • To be notified when the remote device drops the connection, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false

Note. Disconnection can also happen when local adapter calls the gatt/disconnect method (initiated by the local user)

autoConnect Optional Boolean

Possible values are:
true: To automatically connect as soon as the remote device becomes available.

false: To directly connect to the remote device.

Default value: false

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the connection is successfully opened, returnValue will contain true.
  • Otherwise, returnValue will contain false.
adapaterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

address Required String

The address of the remote device the connection is established to.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

clientId Required String

Unique ID of a remote device, which has the following format: "nnn", 3 digit number increasing sequentially.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain false, indicating that the remote device has closed the connection.

adapaterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

address Required String

The address of the remote device the connection is established to.

subscribed Required Boolean

subscribed will always contain false, indicating that the service will not send any further subscription responses.

disconnectByRemote Optional Boolean
  • If the remote device initiated the disconnect, disconnectByRemote will contain true.
  • If the local user initiated the disconnect, disconnectByRemote will contain false.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/connect '{"address":"f6:04:af:d2:87:32"}'

 

Example response for a successful call:

{

"address": "f6:04:af:d2:87:32",

"clientId":"007",

"subscribed": false,

"adapterAddress": "00:00:68:64:d1:30",

"returnValue": true

}

 

Example response for a failed call:

{

"errorCode": 130,

"returnValue": false,

"errorText": "Failed to connect with remote device"

}


gatt/disconnect

Description

Drop the connection to the given remote device on GATT profile.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter to use for disconnecting from GATT profile on a remote device.

If not specified, the default adapter will be used.

clientId Required String

Unique identifier of the remote device.

Format:"nnn", 3 digit number increasing sequentially.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the connection is successfully closed, returnValue will contain true.
  • Otherwise, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

address Required String

The address of the remote device which is disconnected.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/disconnect '{"clientId":"002"}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:68:64:d1:30",

"clientId": "002",

"returnValue": true

}

 

Example response for a failed call:

{

"errorCode": 136,

"returnValue": false,

"errorText": "Device is not connected to profile"

}


gatt/discoverServices

Description

Discover available services for the given remote device.

Pre-requisite

  • The given remote device should be connected through gatt/connect method. Otherwise, the method will fail.

Remark

  • When a discovery process is already running, any further call to this method will succeed but will not restart the discovery.
  • Current discovery state is notified through gatt/getStatus method.
  • Discovered services are notified through gatt/getServices method. 

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

address Optional String

The address of the remote device to discover services for.

If not specified, the method will discovery for all available remote devices connected to the adapterAddress.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

address Optional String

The address of the remote device which discovers services for.

If not specified, the method will discovery for all available remote devices connected to the adapterAddress.

returnValue Required Boolean
  • If the service discovery is successfully started, returnValue will contain true.
  • Otherwise, returnValue will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/discoverServices '{"address":"f6:04:af:d2:87:32"}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:68:64:d1:30",

"address": "f6:04:af:d2:87:32",

"returnValue": true

}

 

Example response for a failed call:

{

"errorCode": 136,

"returnValue": false,

"errorText": "Device is not connected to profile"

}


gatt/getServices

Description

Get available services for either the given local Bluetooth adapter or remote device.

Remark

  • Depending on the passed parameter, a list of services is returned:
    • If adapterAddress is passed, a list of services for the given adapter will be returned.
    • If address is passed, a list of services for the given remote device will be returned.
    • If both address and adapterAddress are passed, the method will return an error.
    • If none of both is passed, the method will return an error.

Parameters

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter to list services for. Either this, or address is required.

address Required String

The address of the remote device to list services for. Either this, or adapterAddress is required.

subscribe Optional Boolean
  • To be notified of new services added, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter the operation was performed on.

address Required String

The address of the remote device.

services Required Object array: bluetooth2GattServiceInfo

List of the available services.

returnValue Required Boolean
  • If available services are successfully returned, returnValue will contain true.
  • Otherwise, returnValue will contain false.
subscribed Optional Boolean
  • If the method is subscribed, subscribed will contain true.
  • If the method is not subscribed, subscribed will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter the operation was performed on.

address Required String

The address of the remote device.

services Required Object: bluetooth2GattServiceInfo

List of the available services.

returnValue Required Boolean
  • If available services are successfully returned, returnValue will contain true.
  • Otherwise, returnValue will contain false.
subscribed Optional Boolean
  • If the method is subscribed, subscribed will contain true.
  • If the method is not subscribed, subscribed will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

127,144,162,169,106,136 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/getServices '{"address":"f6:04:af:d2:87:32"}'

Example response for a failed call:

{

"errorCode": 136,

"returnValue": false,

"errorText": "Device is not connected to profile"

}

Example response for a successful call:

{

"adapterAddress": "00:00:68:64:d1:30",

"address": "f6:04:af:d2:87:32",

"returnValue": true,

"services": [

{

"characteristics": [

{

"permissions": {},

"properties": {

"notify": false,

"read": true,

"writeWithoutResponse": false,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "00002a00-0000-1000-8000-00805f9b34fb",

"value": {"bytes": []},

"descriptors": []

},

{

"permissions": {},

"properties": {

"notify": false,

"read": true,

"writeWithoutResponse": false,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "00002a01-0000-1000-8000-00805f9b34fb",

"value": {"bytes": []},

"descriptors": []

},

{

"permissions": {},

"properties": {

"notify": false,

"read": true,

"writeWithoutResponse": false,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "00002a04-0000-1000-8000-00805f9b34fb",

"value": {"bytes": []},

"descriptors": []

}

],

"service": "00001800-0000-1000-8000-00805f9b34fb",

"type": "primary",

"includes": []

},

{

"characteristics": [],

"service": "00001801-0000-1000-8000-00805f9b34fb",

"type": "primary",

"includes": []

},

{

"characteristics": [

{

"permissions": {},

"properties": {

"notify": true,

"read": true,

"writeWithoutResponse": false,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "adabfb01-6e7d-4601-bda2-bffaa68956ba",

"value": {"bytes": []},

"descriptors": [

{

"permissions": {},

"value": {"bytes": []},

"descriptor": "00002902-0000-1000-8000-00805f9b34fb"

}

]

},

{

"permissions": {},

"properties": {

"notify": false,

"read": true,

"writeWithoutResponse": true,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "adabfb02-6e7d-4601-bda2-bffaa68956ba",

"value": {"bytes": []},

"descriptors": []

}

],

"service": "adabfb00-6e7d-4601-bda2-bffaa68956ba",

"type": "primary",

"includes": []

},

{

"characteristics": [

{

"permissions": {},

"properties": {

"notify": true,

"read": true,

"writeWithoutResponse": false,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "558dfa01-4fa8-4105-9f02-4eaa93e62980",

"value": {"bytes": []},

"descriptors": [

{

"permissions": {},

"value": {"bytes": [] },

"descriptor": "00002902-0000-1000-8000-00805f9b34fb"

}

]

}

],

"service": "558dfa00-4fa8-4105-9f02-4eaa93e62980",

"type": "primary",

"includes": []

},

{

"characteristics": [

{

"permissions": {},

"properties": {

"notify": false,

"read": true,

"writeWithoutResponse": false,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "00002a29-0000-1000-8000-00805f9b34fb",

"value": {"bytes": []},

"descriptors": [

{

"permissions": {},

"value": {"bytes": []},

"descriptor": "00002904-0000-1000-8000-00805f9b34fb"

}

]

},

{

"permissions": {},

"properties": {

"notify": false,

"read": true,

"writeWithoutResponse": false,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "0000fb00-0000-1000-8000-00805f9b34fb",

"value": {"bytes": [] },

"descriptors": []

}

],

"service": "0000180a-0000-1000-8000-00805f9b34fb",

"type": "primary",

"includes": []

},

{

"characteristics": [

{

"permissions": {},

"properties": {

"notify": true,

"read": true,

"writeWithoutResponse": false,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "00002a19-0000-1000-8000-00805f9b34fb",

"value": {"bytes": []},

"descriptors": [

{

"permissions": {},

"value": {"bytes": []},

"descriptor": "00002902-0000-1000-8000-00805f9b34fb"

}

]

}

],

"service": "0000180f-0000-1000-8000-00805f9b34fb",

"type": "primary",

"includes": []

}

]

}


gatt/getStatus

Description

Return the status of GATT connection to the given remote device.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter to use for getting status from GATT profile on a remote device.

If not specified, the default adapter will be used.

address Required String

The address of the remote device to return the status for.

subscribe Optional Boolean
  • To be notified of changes to the connection, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the status is successfully returned, returnValue will contain true.
  • Otherwise, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

address Required String

The address of the remote device the operation was performed for.

connecting Required Boolean

 

  • If the connection request is currently being processed, connecting will contain true.
  • Otherwise, connecting will contain false. For example, the Bluetooth stack is no longer processing the connection request.
connected Required Boolean
  • If the connection is open, connected will contain true.
  • Otherwise, connected will contain false.
discoveringServices Required Boolean
  • If the discovery service request is currently being processed for the given remote device, discoveringServices will contain true.
  • Otherwise, discoveringServices will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

subscribed Required Boolean
  • If it is subscribed, subscribed will contain true.
  • If it is not subscribed, subscribed will contain false.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will contain true until the final response is sent by the service before stopping.

adapterAddress Required String

The address of the adapter the operation was performed on.

address Required String

The address of the remote device the operation was performed for.

connecting Required String
  • If the connection request is currently being processed, connecting will contain true.
  • Otherwise, connecting will contain false. For example, the Bluetooth stack is no longer processing the connection request.
connected Required Boolean
  • If the connection is open, connected will contain true.
  • Otherwise, connected will contain false.
discoveringServices Required Boolean
  • If the discovery service request is currently being processed for the given remote device, discoveringServices will contain true.
  • Otherwise, discoveringServices will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

subscribed Required Boolean
  • If it is subscribed, subscribed will contain true.
  • If it is not subscribed, subscribed will contain false.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/getStatus '{"address":"f6:04:af:d2:87:32"}'

Example response for a successful call:

{

"discoveringServices": false,

"adapterAddress": "00:00:68:64:d1:30",

"address": "f6:04:af:d2:87:32",

"connected": false,

"subscribed": false,

"returnValue": true,

"connecting": false

}

 

Example response for a failed call:

{

"errorCode": 106,

"returnValue": false,

"errorText": "Device with supplied address is not available"

}


gatt/monitorCharacteristic

Description

Monitors specific characteristic value changes.

  • If the characteristic is not marked as being notifiable, the method will fail.
  • If the address is not set, monitors specific characteristics of the local service for value changes.
  • If the address is set, monitors specific characteristics of the given remote device for characteristic value changes.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter to be monitored.

service Optional String

UUID of the service the characteristic belongs to.

Note: Either this and characteristic, or instanceId is required.

characteristic Optional String

UUID of the characteristic to be monitored.

Note: Either this and service, or instanceId is required.

InstanceId Optional String

Unique identifier of a characteristic to monitored, which has the following format: "nnn". Either this, or service and characteristic are required.

serverId Optional String

The identifier of server to get the characteristic from.

  • To read the value of characteristic, set serverId to specific server identifier.
  • Or to read in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find characteristic in the webOS device.
clientId Optional String

The identifier of the remote device (client) to get the characteristic from.

  • To read the value of characteristics, set serverId to specific server identifier.
  • Or to read in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find characteristics in the webOS device.
subscribe Optional Boolean

Indicates if subscribed to get notifications. Possible values are:

  • true - Subscribed for changes
  • false - Not subscribed

Note: Must set subscribe to true.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter the operation was performed on.

address Optional String

The address of the remote device the service exists on.

subscribed Optional Boolean

Indicates if subscribed to get notifications. Possible values are:

  • true - Subscribed for changes
  • false - Not subscribed
returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode Optional String

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
subscribed Required Boolean

Indicates if subscribed to get notifications. Possible values are:

  • true - Subscribed for changes
  • false - Not subscribed
adapterAddress Required String

The address of the adapter the operation was performed on.

address Optional String

The address of the remote device the service exists on.

changed Required Object: bluetooth2GattCharacteristicValueInfo

Object containing information about the characteristic uuid and value.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

105, 106, 127, 136, 143 , 144, 105, 162, 163, 166, 173, 176, 177 See API Error Codes Reference

See the "API Error Codes Reference" section.

Example

# luna-send -f -i luna://com.webos.service.bluetooth2/gatt/monitorCharacteristic '{
       "clientId":"007",
       "service":"7905f431-b5ce-4e99-a40f-4b1e122d00d0",
       "characteristic":"9fbf120d-6301-42d9-8c58-25e699a21dbd",
       "subscribe":true
}'

Returns:

{

"address": "79:ef:2d:a8:31:2c",

"subscribed": true,

"adapterAddress": "00:00:68:64:d1:30",

"returnValue": true

}

Subscription returns:

{

"changed": {

"characteristic": "9fbf120d-6301-42d9-8c58-25e699a21dbd",

"value": {"bytes": [0, 21, 0, 1, 0, 0, 0, 0]}

},

"address": "79:ef:2d:a8:31:2c",

"subscribed": true,

"adapterAddress": "00:00:68:64:d1:30",

"returnValue": true

}


gatt/monitorCharacteristics

Description

Monitors specific characteristic value changes.

  • If the characteristic is not marked as being notifiable, the method will fail.
  • If the address is not set, monitors specific characteristics of the local service for value changes.
  • If the address is set, monitors specific characteristics of the given remote device for characteristic value changes.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter to be monitored.

service Required String

UUID of the service the characteristic belongs to.

characteristics Required String array

Array of strings where each string is a UUID of a characteristic to be monitored.

subscribe Required Boolean

Indicates if subscribed to get notifications. Possible values are:

  • true - Subscribed for changes
  • false - Not subscribed

Note: Must set subscribe to true.

serverId Optional String

The identifier of server to get the characteristic from.

  • To be informed of changes to the value of characteristics, set serverId to specific server identifier.
  • Or to be informed in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find characteristics in the webOS device.
clientId Optional String

The identifier of the remote device (client) to get the characteristics from.

  • To be informed of changes to the value of characteristics, set serverId to specific server identifier.
  • Or to be informed in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find characteristics in the webOS device.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter the operation was performed on.

address Optional String

The address of the remote device the service exists on.

subscribed Required Boolean

Indicates if subscribed to get notifications. Possible values are:

  • true - Subscribed for changes
  • false - Not subscribed
returnValue Required String

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode Optional Number

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
subscribed Required Boolean

Indicates if subscribed to get notifications. Possible values are:

  • true - Subscribed for changes
  • false - Not subscribed
adapterAddress Required String

The address of the adapter the operation was performed on.

address Optional String

The address of the remote device the service exists on.

adapterAddress Required String

The address of the adapter the operation was performed on.

Note: If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

changed Required Object: bluetooth2GattCharacteristicValueInfo

Object containing information about the characteristic uuid and values.

errorCode Optional Number

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

105, 106, 127, 136, 143 , 144, 105, 162, 163, 166, 173, 176, 177 See API Error Codes Reference

See the "API Error Codes Reference" section.

Example

# luna-send -f -i luna://com.webos.service.bluetooth2/gatt/monitorCharacteristics '{
        "clientId":"007",
        "service":"7905f431-b5ce-4e99-a40f-4b1e122d00d0",
        "characteristics":["9fbf120d-6301-42d9-8c58-25e699a21dbd"],
        "subscribe":true
}'

Returns:

{

"address": "79:ef:2d:a8:31:2c",

"subscribed": true,

"adapterAddress": "00:00:68:64:d1:30",

"returnValue": true

}

Subscription returns:

{

"changed": {

"characteristic": "9fbf120d-6301-42d9-8c58-25e699a21dbd",

"value": {"bytes": [0, 21, 0, 1, 0, 0, 0, 0]}

},

"address": "79:ef:2d:a8:31:2c",

"subscribed": true,

"adapterAddress": "00:00:68:64:d1:30",

"returnValue": true

}


gatt/openServer

Description

Opens BluetoothGattServer managing services.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
adapterAddress Required String

The address of the adapter executing this method call. When the field of the argument is not set, the address of the default adapter returns.

serverId Required String

Unique identifier of a server, which has the following format: "nnn", 3 digit number increasing sequentially.

errorCode Optional Number

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/openServer '{}'

return:

{

    "adapterAddress": "00:00:9a:1d:89:5d",

    "serverId":"001",

    "returnValue": true

}


gatt/readCharacteristicValue

Description

Reads the value of a specific characteristic. 

  • When called from client side, the method actively reads and retrieves the latest value from the remote device rather than returning the value from the local cache.
  • When called from server side, the method just returns stored value from the local database.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter the service exists on.

service Optional String

Unique identifier of the service the characteristic belongs to.

Note: Either this and characteristic, or instanceId is required.

characteristic Optional String

Unique identifier of the characteristic to read.

Note: Either this and service, or instanceId is required.

instanceId Optional String

Unique ID of the characteristic to read, which has the following format: "nnn".

Note: Either this, or service and characteristic are required.

serverId Optional String

The identifier of server to get the characteristic from.

  • To read the value of characteristics, set serverId to specific server identifier.
  • Or to read in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find characteristics in the webOS device.
clientId Optional String

The identifier of the remote device (client) to get the characteristic from.

  • To read the value of characteristics, set serverId to specific server identifier.
  • Or to read in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find characteristics in the webOS device.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
address Optional String

The address of the remote device.

service Required String

Unique identifier of the service the characteristic belongs to.

value Required Object: bluetooth2GattCharacteristicInfo

Value for requested characteristic.

errorCode Optional Number

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

106,127,136,143,144,162,163,166,173,174 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/readCharacteristicValue '{
      "address":"b4:99:4c:64:be:fe",
      "service":"f000aa00-0451-4000-b000-000000000000",
      "characteristic":"f000aa01-0451-4000-b000-000000000000"
}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:68:64:d1:30",

"address": "b4:99:4c:64:be:fe",

"returnValue": true,

"service": "f000aa00-0451-4000-b000-000000000000",

"value":

{

"permissions": {},

"properties": {

"notify": true,

"read": true,

"writeWithoutResponse": false,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "f000aa01-0451-4000-b000-000000000000",

"value": {"bytes": [13, 255, 140, 12]},

"descriptors": [

{

"permissions": {},

"value": {"bytes": []},

"descriptor": "00002901-0000-1000-8000-00805f9b34fb"

},

{

"permissions": {},

"value": {"bytes": []},

"descriptor": "00002902-0000-1000-8000-00805f9b34fb"

}

]

}

}


gatt/readCharacteristicValues

Description

Read the value of a specific characteristic. 

  • When called from client side, the method actively reads and retrieves the latest value from the remote device rather than returning the value from the local cache.
  • When called from server side, the method just returns stored value from the local database.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter the service exists on.

service Required String

Unique identifier of the service the characteristic belongs to.

characteristics Required String array

Unique identifiers of the characteristics to read.

serverId Optional String

The identifier of server to get the characteristic from.

  • To read the value of characteristics, set serverId to specific server identifier.
  • Or to read in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find characteristics in the webOS device.
clientId Optional String

The identifier of the remote device (client) to get the characteristic from.

  • To read the value of characteristics, set serverId to specific server identifier.
  • Or to read in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find characteristics in the webOS device.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

address Optional String

The address of the remote device.

service Optional String

Unique identifier of the service the characteristic belongs to.

values Optional Object: bluetooth2GattCharacteristicInfo

Values of the characteristic.

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

106,127,136,143,144,162,163,166,173,174 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/readCharacteristicValues '{
      "clientId":"001",
      "service":"f000aa00-0451-4000-b000-000000000000",
      "characteristics":["f000aa01-0451-4000-b000-000000000000"]
}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:68:64:d1:30",

"address": "b4:99:4c:64:be:fe",

"returnValue": true,

"service": "f000aa00-0451-4000-b000-000000000000",

"values": [

{

"permissions": {},

"properties": {

"notify": true,

"read": true,

"writeWithoutResponse": false,

"indicate": false,

"authenticatedSignedWrites": false,

"write": false,

"broadcast": false,

"extendedProperties": false

},

"characteristic": "f000aa01-0451-4000-b000-000000000000",

"value": {"bytes": [13, 255, 140, 12]},

"descriptors": [

{

"permissions": {},

"value": {"bytes": []},

"descriptor": "00002901-0000-1000-8000-00805f9b34fb"

},

{

"permissions": {},

"value": {"bytes": []},

"descriptor": "00002902-0000-1000-8000-00805f9b34fb"

}

]

}

]

}

 

 

Example response for a failed call: (if the characteristic does not have read permissions (seen with getServices)).

{

"errorCode": 174,

"returnValue": false,

"errorText": "GATT read characteristic failed"

}


gatt/readDescriptorValue

Description

Reads the value of descriptor of a service characteristic either in the local adapter or the remote device. 

  • When called from client side, the method actively reads and retrieves the latest value from the remote device rather than returning the value from the local cache.
  • When called from server side, the method just returns stored value from the local database.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter executing this method call.

If not specified, the default adapter will be used.

service Optional String

Unique identifier of the service the characteristic belongs to.

Note: Either this and characteristic and descriptor, or instanceId is required.

characteristic Optional String

Unique identifier of the characteristic the descriptor belongs to.

Note: Either this and service and descriptor, or instanceId is required.

descriptor Optional String

Uuid of descriptor.

Note: Either this and service and characteristic, or instanceId is required.

instanceId Optional String

Unique identifier of the descriptor to read, which has the following format: "nnn". Either this, or service and characteristic, descriptor are required.

serverId Optional String

The identifier of server to get the descriptors from.

  • To read the value of descriptors, set serverId to specific server identifier.
  • Or to read in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find descriptors in the webOS device.
clientId Optional String

The identifier of remote device (client) to get the descriptors from.

  • To read the value of descriptors, set serverId to specific server identifier.
  • Otherwise, set clientId to specific remote device identifier.
  • if both serverId and clientId not specified, find descriptors in the webOS device.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

address Optional String

The address of the remote device.

service Required String

Unique identifier of the service the descriptor belongs to.

characteristic Required String

Unique identifier of the characteristic the descriptor belongs to

value Required Object: bluetooth2GattDescriptorInfo

Value for requested descriptor.

errorCode Optional Number

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

106,127,136,143,144,162,163,166,173,174 See API Error Codes Reference

See API Error Codes Reference.

Example

Example for reading a descriptor value from the local adapter:

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/readDescriptorValue '{
      "service":"f000aa40-0451-4000-b000-000000000000",
      "characteristic":"f000aa41-0451-4000-b000-000000000000"
      "descriptor":"00002902-0000-1000-8000-00805f9b34fc"
}'

{
    "adapterAddress": "00:00:ba:87:d1:a7",
    "characteristic": "f000aa41-0451-4000-b000-000000000000",
    "returnValue": true,
    "service": "f000aa40-0451-4000-b000-000000000000",
    "value":
    {
        "permissions": {
        },
        "value": {
            "bytes": [0, 0]
        },
        "descriptor": "00002902-0000-1000-8000-00805f9b34fb"
    }   
}


gatt/readDescriptorValues

Description

Read the value of descriptor(s) of a service characteristic either in the local adapter or the remote device. 

  • When called from client side, the method actively reads and retrieves the latest value from the remote device rather than returning the value from the local cache.
  • When called from server side, the method just returns stored value from the local database.

 

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter executing this method call.

If not specified, the default adapter will be used.

service Required String

Unique identifier of the service the descriptor belongs to.

characteristic Required String

Unique identifier of the characteristic the descriptor belongs to.

descriptors Required String array

Array of descriptors UUIDs.

serverId Optional String

The identifier of server to get the descriptors from.

  • To read the value of descriptors, set serverId to specific server identifier.
  • Or to read in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find descriptors in the webOS device.
clientId Optional String

The identifier of the remote device (client) to get the descriptors from.

  • To read the value of descriptors, set serverId to specific server identifier.
  • Otherwise, set clientId to specific remote device identifier.
  • if both serverId and clientId not specified, find descriptors in the webOS device.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

address Optional String

The address of the remote device.

service Required String

Unique identifier of the service the descriptor belongs to.

characteristic Required String

Unique identifier of the characteristic the descriptor belongs to.

values Required Object array: bluetooth2GattDescriptorInfo

Values for requested descriptors.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Example

Example for reading a descriptor value from the local adapter:

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/readDescriptorValues '{
      "serverId":"001",
      "service":"f000aa40-0451-4000-b000-000000000000",
      "characteristic":"f000aa41-0451-4000-b000-000000000000",
      "descriptors":["00002902-0000-1000-8000-00805f9b34fc"]
}'

{
    "adapterAddress": "00:00:ba:87:d1:a7",
    "characteristic": "f000aa41-0451-4000-b000-000000000000",
    "returnValue": true,
    "service": "f000aa40-0451-4000-b000-000000000000",
    "values": [
        {
            "permissions": {
            },
            "value": {
                "bytes": [0, 0]
            },
            "descriptor": "00002902-0000-1000-8000-00805f9b34fb"
        }
    ]
}


Example for reading a descriptor value from the remote device:

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/readDescriptorValues '{
      "clientId":"001",
      "service":"f000aa40-0451-4000-b000-000000000000",
      "characteristic":"f000aa41-0451-4000-b000-000000000000",
      "descriptors":["00002902-0000-1000-8000-00805f9b34fb"]
}'

{
    "adapterAddress": "00:00:ba:87:d1:a7",
    "address": "b4:99:4c:64:30:46",
    "characteristic": "f000aa41-0451-4000-b000-000000000000",
    "returnValue": true,
    "service": "f000aa40-0451-4000-b000-000000000000",
    "values": [
        {
            "permissions": {
            },
            "value": {
                "bytes": [0, 0]
            },
            "descriptor": "00002902-0000-1000-8000-00805f9b34fb"
        }
    ]
}


gatt/removeService

Description

Remove a service definition from the local database. All characteristics which belong to the service will be also removed.

If the given service is included by another service, the method will fail.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter to remove the service from.

service Required String

Unique identifier of the service.

serverId Optional String

The identifier of server to remove the service from.

  • To remove the service, set serverId to specific server identifier.
  • If not specified, find service with uuid in the webOS device.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter from which service is removed.

returnValue Required Boolean
  • If the service was successfully removed, returnValue will contain true.
  • Otherwise, returnValue will contain false.
errorCode Optional Boolean

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

127,143,163,144,171 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/removeService '{"service":"6161"}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:68:64:d1:30",

"returnValue": true

}

 

Example response for a failed call:

{

"errorCode": 171,

"returnValue": false,

"errorText": "GATT remove service failed"

}


gatt/writeCharacteristicValue

Description

Write the value for a local or remote characteristic.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter the service exists on.

service Optional String

UUID of the service the characteristic belongs to.

Note: Either this and service, or instanceId is required.

characteristic Optional String

UUID (unique identifier) of the characteristic.

Note: Either this and service, or instanceId is required.

instanceId Optional String

Unique identifier of the descriptors to read, which has the following format: "nnn".

Note: Either this, or service and characteristic are required.

value Required Object: bluetooth2GattValueInfo

Value 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.

serverId Optional String

The identifier of server to get the characteristic from.

  • To write the value of characteristic, set serverId to specific server identifier.
  • Or to write in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find characteristic in the webOS device.
clientId Optional String

The identifier of the remote device (client) to get the characteristic from.

  • To write the value of characteristic, set serverId to specific server identifier.
  • Or to write in remote device, set clientId to specific remote device identifier.
  • If both serverId and clientId not specified, find characteristic in the webOS device.
writeType Optional String

Write type of the characteristic. Possible values are: "default" or "noresponse", "signed".

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter.

address Optional String

The address of the remote device.

returnValue Optional Boolean
  • If the value was successfully wrote, returnValue will contain true.
  • Otherwise, returnValue will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

106,127,136,143,144,162,163,164,165,173,172,175 See API Error Codes Reference

See API Error Codes Reference.

Example

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/writeCharacteristicValue '{
       "clientId":"001",
       "service":"f000aa00-0451-4000-b000-000000000000",
       "characteristic":"f000aa02-0451-4000-b000-000000000000",
       "value":{"bytes":[1]}
}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:68:64:d1:30",

"address": "b4:99:4c:64:be:fe",

"returnValue": true

}

 

Example response for a failed call:

{

"errorCode": 173,

"returnValue": false,

"errorText": "Invalid GATT characteristic for the given service: "

}


gatt/writeDescriptorValue

Description

Write the value of a specific descriptor of a service characteristic either in the local adapter or the remote device.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter executing this method call.

If not specified, the default adapter will be used.

service Optional String

Unique identifier of the service the descriptor belongs to.

Note: Either this and characteristic and descriptor, or instanceId is required.

characteristic Optional String

Unique identifier of the characteristic the descriptor belongs to.

Note: Either this and service and descriptor, or instanceId is required.

descriptor Optional String

Unique identifier of the descriptor.

Note: Either this and service and characteristic, or instanceId is required.

instanceId Optional String

Unique identifier of the descriptors to read, which has the following format: "nnn".

Note: Either this, or service and characteristic are required.

value Required Object: bluetooth2GattValueInfo

Value of the descriptor.

A value can only have one type. Depending on this type, one of the fields "string", "number" or "bytes" is passed. If multiple fields are passed, the method will fail.

serverId Optional String

The identifier of server to get the descriptor from.

  • To write the value of descriptor, set serverId to specific server identifier.
  • Or to write in remote device, set clientId to specific remote device identifier.
  • if both serverId and clientId not specified, find descriptor in the webOS device.
clientId Optional String

The identifier of the remote device (client) to get the descriptor from.

  • To write the value of descriptor, set serverId to specific server identifier.
  • Or to write in remote device, set clientId to specific remote device identifier.
  • if both serverId and clientId not specified, find descriptor in the webOS device.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

address Optional String

The address of the remote device.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

Example

Example for writing a descriptor value in the remote device:

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/writeDescriptorValue '{
      "clientId":"001",
      "service":"f000aa40-0451-4000-b000-000000000000",
      "characteristic":"f000aa41-0451-4000-b000-000000000000", "descriptor":"00002902-0000-1000-8000-00805f9b34fb",
      "value":{"bytes":[1, 0]}
}'

{

    "adapterAddress": "00:00:ba:87:d1:a7",

    "address": "b4:99:4c:64:30:46",

    "returnValue": true

}

 

Example for writing a descriptor value in the local adapter:

# luna-send -f -n 1 luna://com.webos.service.bluetooth2/gatt/writeDescriptorValue '{
        "serverId": "001",
        "service":"1a4eeedc-f27a-11e4-b9b2-1697f925ec7b",
        "characteristic":"1a4ef224-f27a-11e4-b9b2-1697f925ec7b",
        "descriptor":"f000ffc1-0451-4000-b000-000000000000",
        "value":{"bytes":[65,99,99,46,32,80,101,114,105,111,100]}
}'

{

"adapterAddress": "00:00:ba:87:d1:a7",

"returnValue": true

}


le/startAdvertising

Description

Start the broadcasting of the Bluetooth Low Energy advertisement.

Pre-requisite

  • This method should be called after le/configureAdvertisement or le/stopAdvertising method is called.

Parameters

Name

Required

Type

Description

adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

subscribe Required Boolean

Since subscription ends only when the client chooses to close it, subscribed will always contain true.

Multiple advertisement must set to true this value.

settings Optional Object: bluetooth2AdvertiseSettings

Defines the format for advertiser setting parameters.

advertiseData Optional Object: bluetooth2AdvertiseData

Defines the format for scan request data parameters.

scanResponse Optional Object: bluetooth2AdvertiseData

Defines the format for scan response data parameters.

Call Returns

Name

Required

Type

Description

adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
errorCode Optional Number

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

advertiserId Required Number

The handle ID of a specific advertiser. Multiple advertisement can update with this value.

Error References

Error Code

Error Text

Error Description

1, 101 See API Codes Reference

See API Error Codes Reference.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/le/startAdvertising '{
       "subscribe":true,
       "advertiseData":
                    {
                        "manufacturerData":[1,2,3,4],
                        "proprietaryData":[{"type":27,"data":[5,6,7,8]}],
                        "includeTxPower":true,
                        "services":[{"uuid":"aada","data":[7,8,9,0]}],
                        "includeName":false
                   }
     }'

 

Example response for successful call:

{

"adapterAddress": "00:00:9a:1d:89:5d",

"advertiserId": 1234,

"subscribed": true,

"returnValue": true

}

 

Example response for a failed call: if default adapter is not valid.

{

"adapterAddress": "00:00:9a:1d:89:5d",

"returnValue": false

"errorCode": 101

"errorText": "Bluetooth adapter is not available"

}

Subscription return: If advertiser cancel subscription ,

{

"adapterAddress": "00:00:9a:1d:89:5d,

"advertiserId": 1234,

"subscribed": false,

"returnValue": true

}


le/startScan

Description

Starts scanning only ble devices.

Parameters

Name

Required

Type

Description

address Optional String

MAC address

subscribe Required Boolean

Subscribe for notifications on status of remote devices. Possible values are:

  • true - Get notifications
  • false - Notifications are not required

Default value: false

name Optional String

Device name

serviceUuid Optional Object: bluetooth2LeServiceUuidObject

Object containing information about a service uuid to be advertised

serviceData Optional Object: bluetooth2LeServiceDataObject

Object containing information about a service data to be advertised

manufacturerData Optional Object: bluetooth2LeManufacturerData

Object containing information about a manufacturer data

Call Returns

Name

Required

Type

Description

subscribed Required Boolean

Indicates if subscribed to get notified.

  • true - Subscribed for changes
  • false - Not subscribed
returnValue Required Boolean

returnValue will always contain true unless the request for subscription fails.

adapterAddress Required String

The address of the default adapter will be always returned.

errorCode Optional Number

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Subscription Returns

Name

Required

Type

Description

subscribed Required Boolean

Indicates if subscribed to get notified.

  • true - Subscribed for changes
  • false - Not subscribed
returnValue Required Boolean

returnValue will always contain true unless the request for subscription fails.

adapterAddress Required String

The address of the default adapter will be always returned.

devices Required Object array: bluetooth2DeviceStatus

devices will contain status information for all the devices known to the system, not just the ones whose status has been changed.

errorCode Optional Number

The error code for the failed operation.

errorText Optional String

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

101,143,144 See API Error Codes Reference

See the "API Error Codes Reference" section.

Example

# luna-send -f -n 10 luna://com.webos.service.bluetooth2/le/startScan '{"subscribe":true,"address":"87:62:17:09:05:ae"}'

{
    "returnValue": true,
    "devices": [
        {
            "scanRecord": [
                2,
                1,
                5,
                23,
                255,
                196,
                0,
                83,
                67,
                68,
                32,
                49,
                55,
                46,
                49,
                44,
                66,
                65,
                32,
                51,
                53,
                44,
                119,
                101,
                98,
                79,
                83,
                9,
                9,
                76,
                71,
                69,
                32,
                77,
                82,
                49,
                56
            ],
            "address": "87:62:17:09:05:ae",
            "rssi": -66
        }
    ]
}


opp/acceptTransferRequest

Description

Accept a Bluetooth object push request. This method is available only for a push server.

Parameters

Name

Required

Type

Description

requestId Required String

The unique ID of a request.

adapaterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

Error References

Error Code

Error Text

Error Description

127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

155 Transfers are currently not allowed

OPP file transfers from the remote Bluetooth device are currently not allowed.

156 Required 'requestId' parameter is not supplied

The requestId parameter is mandatory to this method, but was not supplied by the caller of the method.

157 Failed to retrieve state for remote device

The confirmation of object push request from remote Bluetooth device failed.

159 These pushRequest already received the file

The confirmation of object push request from remote Bluetooth device is already done.

158 The requestId does not exist

The supplied requestId does not exist, hence the method cannot be completed.

Example

luna-send -n 1 -f luna://com.webos.service.bluetooth2/opp/acceptTransferRequest '{"requestId":"001"}'

Example response for a successful call: If OPP server awaits for file transfer,
{

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

Example response for a failed call: If requestId is not valid,

{

"errorCode": 158,

"returnValue": false,

"errorText": "The requestId does not exist"

}


opp/awaitTransferRequest

Description

Await incoming transfer requests from push clients. This method is available only for a push server.

Parameters

Name

Required

Type

Description

subscribe Required Boolean

Must set subscribe to true.

adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false. The method may fail because one of the error conditions described in the Error Codes Reference of this method. See the Error Codes Reference for more information.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

subscribed Required Boolean

Since subscription ends only when the client chooses to close it, subscribed will always contain true.

request Optional Object: bluetooth2PushRequest

A request information including request ID, client name, client address, file name, and file size.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

Error References

Error Code

Error Text

Error Description

101, 103, 104, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

161 Adapter is turned off

The Bluetooth adapter is turned off.

Example

luna-send -i -f luna://com.webos.service.bluetooth2/opp/awaitTransferRequest

'{

"subscribe":true

}'

 

Example response for a successful call:

{

"subscribed": true,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

 

Example response for a failed call: If subscribe parameter is not used,

{

"errorCode": 103,

"returnValue": false,

"errorText": "Method needs to be subscribed"

}

 

Subscription return: If remote device sends file to OPP server,

{

"request": {

"requestId": "001",

"address": "34:4d:f7:f9:52:f7",

"fileSize": 3909991,

"fileName": "20150411_162012.jpg",

"name": "Jone Doe's G3"

}

}


opp/cancelTransfer

Description

Cancel an ongoing file transfer. This method is available only for a push server. In a client side, LSCallCancel() is used to cancel the transfer.

Parameters

Name

Required

Type

Description

requestId Required String

The unique ID of a request.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the file transfer is successfully canceled, returnValue will contain true.
  • Otherwise, returnValue will contain false.
errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

155 Transfers are currently not allowed

OPP file transfers from the remote Bluetooth device are currently not allowed.

156 Required 'requestId' parameter is not supplied

The requestId parameter is mandatory to this method, but was not supplied by the caller of the method.

157 Failed to retrieve state for remote device

The confirmation of object push request from remote Bluetooth device failed.

158 The requestId does not exist

The supplied requestId does not exist, hence the method cannot be completed.

Example

luna-send -n 1 -f palm://com.webos.service.bluetooth2/opp/cancelTransfer

'{

"requestId":"001"

}'

 

Example response for a successful call: If file transfer is on going,

{

"returnValue": true

}

 

Example response for a failed call: If requestId is not valid,

{

"errorCode": 158,

"returnValue": false,

"errorText": "The requestId does not exist"

}


opp/connect

Description

Open (or initialize) an OPP connection to a remote Bluetooth device.

In some cases of such as using BSA stack, only initialization of OPP capability is done by this method and the actual Bluetooth connection is created through the opp/pushFile method.

If the client calls LSCallCancel(), the connection is closed and OPP setup is deinitialized (the opp/disconnect method also can be used for the disconnection). This method is available only for a push client.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device.

subscribe Optional Boolean
  • To be notified when the connection is closed, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false.

Call Returns

Name

Required

Type

Description

subscribed Required Boolean
  • If it is subscribed, subscribed will contain true.
  • If it is not subscribed, subscribed will contain false
returnValue Required Boolean
  • If the connection was successfully open (or initialized), returnValue will contain true.
  • Otherwise, returnValue will contain false.
errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

disconnectByRemote Required String
  • If the remote device initiated the disconnect, disconnectByRemote will contain true.
  • If the local user initiated the disconnect, disconnectByRemote will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

returnValue Required Boolean
  • If the connection was successfully open (or initialized), returnValue will contain true.
  • Otherwise, returnValue will contain false.
subscribed Required Boolean
  • If it is subscribed, subscribed will contain true until the final response sent by the service before stopping.
  • If it is not subscribed, subscribed will contain false

Error References

Error Code

Error Text

Error Description

102, 103, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

128 Device is already connecting

The remote Bluetooth device is already connecting to OPP profile, so another connection cannot be open.

130 Failed to connect with remote device

The remote Bluetooth device cannot be connected to the OPP profile.

131 Already connected

The remote Bluetooth device is already connected to the adapter's OPP profile, so another connection cannot be open.

Example

luna-send -i -f luna://com.webos.service.bluetooth2/opp/connect

'{

"address":"34:4d:f7:f9:52:f7",

"subscribe":true

}'

 

Example response for a successful call:

{

"subscribed": true,

"adapterAddress": "00:00:c5:99:f5:87",

"returnValue": true

}

 

Example response for a failed call: If address is not valid,

{

"errorCode": 106,

"returnValue": false,

"errorText": "Device with supplied address is not available"

}

 

Subscription return: If connection is successful,

{

"subscribed": true,

"adapterAddress": "00:00:c5:99:f5:87",

"returnValue": true

}


opp/disconnect

Description

Close (or deinitialize) the connection to the given remote device on OPP profile.

In some cases of such as using BSA stack, this method performs only deinitialization of the OPP-related setup and the actual Bluetooth connection is dropped after finishing file transfer. This method is available only for a push client.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

If the connection is successfully closed (or deinitialized), returnValue will contain true.

Otherwise, returnValue will contain false.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

132 Failed to disconnect from remote device

The OPP connection with the remote Bluetooth device could not be closed.

Example

luna-send -n 1 luna://com.webos.service.bluetooth2/opp/disconnect

'{

"address":"34:4d:f7:f9:52:f7"

}'

 

Example response for a successful call:

{

"adapterAddress":"00:00:1c:93:51:b8",

"returnValue":true

}

 

Example response for a failed call: If address is not valid,

{

"errorCode": 106,

"returnValue": false,

"errorText": "Device with supplied address is not available"

}

 

Subscription return: If disconnection is successful,

{

"adapterAddress":"00:00:1c:93:51:b8",

"returnValue":true

}


opp/getStatus

Description

Return the status of an OPP connection to a remote Bluetooth device. This method is available for both of client and server.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device.

subscribe Optional Boolean
  • To be notified of changes to the connection, set subscribe to true.
  • Otherwise, set subscribe to false.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the status is successfully returned, returnValue will contain true.
  • Otherwise, returnValue will contain false.
connecting Required Boolean
  • If the connection (or push) request is currently being processed, connecting will contain true.
  • Otherwise, connecting will contain false. For example, the Bluetooth stack is no longer processing the connection request.
connected Required Boolean
  • If the connection is open, connected will contain true.
  • Otherwise, connected will contain false.
errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the status is successfully returned, returnValue will contain true.
  • Otherwise, returnValue will contain false.
subscribed Required Boolean
  • If the method is subscribed, subscribed will contain true until the final response is sent by the service before stopping. 
  • If the method is not subscribed, subscribed will contain false.
connecting Required Boolean
  • If the connection (or push) request is currently being processed, connecting will contain true.
  • Otherwise, connecting will contain false. For example, the Bluetooth stack is no longer processing the connection request.
connected Required Boolean
  • If the connection is open, connected will contain true.
  • Otherwise, connected will contain false.
errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

133 Failed to retrieve state for remote device

The OPP connection status of the remote Bluetooth device cannot be retrieved.

Example

luna-send -i -f luna://com.webos.service.bluetooth2/opp/getStatus

'{

"address":"34:4d:f7:f9:52:f7",

"subscribe":true

}'

 

Example response for a successful call:

{

"adapterAddress": "00:00:1c:93:51:b8",

"connected": false,

"subscribed": true,

"returnValue": true,

"connecting": false

}

 

Example response for a failed call: If address is not valid,

{

"errorCode": 106,

"returnValue": false,

"errorText": "Device with supplied address is not available"

}

 

Subscription return: If user connects to remote device, connected field is changed from false to true when remote device is connected.

{

"adapterAddress": "00:00:1c:93:51:b8",

"connected": false,

"subscribed": true,

"returnValue": true,

"connecting": true

}

{

"adapterAddress": "00:00:1c:93:51:b8",

"connected": true,

"subscribed": true,

"returnValue": true,

"connecting": false

}

 

Subscription return : If user disconnects the connected device,

{

"subscribed": false,

"disconnectByRemote": true,

"returnValue": false

}


opp/monitorTransfer

Description

Return the status of ongoing file transfer requests. This method is only available for server.

Parameters

Name

Required

Type

Description

subscribe Required Boolean

Must set subscribe to true.

adapterAddress Optional String

The address of the adapter executing this method call.

If not specified, the default adapter will be used.

Subscription Returns

Name

Required

Type

Description

subscribed Required Boolean

subscribed will always contain true since subscription ends only when the client chooses to close it.

returnValue Required Boolean
  • If the status is successfully returned, returnValue will contain true.
  • Otherwise, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

transfers Optional Object array: bluetooth2PushRequest

Request information including data size transferred so far.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

Error References

Error Code

Error Text

Error Description

101, 103, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

161 Adapter is turned off

The Bluetooth adapter is turned off.

Example

luna-send -i -f luna://com.webos.service.bluetooth2/opp/monitorTransfer

'{

"subscribe":true

}'

 

Example response for a successful call:

{

"subscribed": true,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

 

Example response for a failed call: If subscribe parameter is not used,

{

"errorCode": 103,

"returnValue": false,

"errorText": "Method needs to be subscribed"

}

 

Subscription return: If file transfer is on going,

{

"subscribed": true,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b",

"transfers": [

{

"transferred": 32693,

"requestId": "002",

"address": "34:4d:f7:f9:52:f7",

"fileSize": 73805,

"fileName": "001.jpg",

"name": "Jone Doe's G3"

}

]

}

{

"subscribed": true,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b",

"transfers": [

{

"transferred": 65386,

"requestId": "002",

"address": "34:4d:f7:f9:52:f7",

"fileSize": 73805,

"fileName": "001.jpg",

"name": "Jone Doe's G3"

}

]

}

{

"subscribed": true,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b",

"transfers": [

{

"transferred": 73805,

"requestId": "002",

"address": "34:4d:f7:f9:52:f7",

"fileSize": 73805,

"fileName": "001.jpg",

"name": "Jone Doe's G3"

}

]

}


opp/pushFile

Description

Push a file to a remote Bluetooth device. This method is available only for push client. If the client calls LSCallCancel(), the file transfer is cancelled.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device.

sourceFile Required String

Absolute path of the source file, rooted at /media/internal.

subscribe Optional Boolean
  • To monitor the progress of the transfer, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribed is false.
adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the file transfer succeeds, returnValue will contain true.
  • Otherwise, returnValue will contain false. (The non-subscription response is only sent after the transfer has completed.)
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

subscribed Required Boolean
  • If it is subscribed, subscribed will contain true.
  • If it is not subscribed, subscribed will contain false
errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean
  • In case subscribed contains truereturnValue will always contain true.
  • In case subscribed contains false (indicating the final response from the service),
    • If the file transfer succeeds, returnValue will contain true.
    • Otherwise, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

subscribed Required Boolean
  • If it is subscribed, subscribed will contain true until the final response is sent by the service before stopping.
  • If it is not subscribed, subscribed will contain false
transferred Optional Number

Number of bytes transferred so far.

size Optional Number

Size in bytes of the source file.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

105, 106, 137, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

142 Supplied file does not exist or is invalid

The supplied source file path either does not exist at /media/internal on the device or is invalid. Hence the push operation cannot be completed.

154 Device is not connected

The remote Bluetooth device is not connected to our Bluetooth adapter via the OPP profile.

Example

luna-send -i -f luna://com.webos.service.bluetooth2/opp/pushFile

'{

"address":"34:4d:f7:f9:52:f7",

"sourceFile":"music.mp3",

"subscribe":true

}'

 

Example response for a successful call:

subscription return

{

"transferred": 0,

"subscribed": true,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

 

Example response for a failed call: If subscribe parameter is not used,

{

"errorCode": 103,

"returnValue": false,

"errorText": "Method needs to be subscribed"

}

 

Subscription return: If file transfer starts, subscription return comes immediately.

{

"transferred": 0,

"subscribed": true,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

{

"transferred": 32693,

"size": 4983744,

"subscribed": true,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

{

"transferred": 65386,

"size": 4983744,

"subscribed": true,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

..............................................................................

{

"transferred": 4983744,

"size": 4983744,

"subscribed": true,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

{

"transferred": 4983744,

"size": 4983744,

"subscribed": false,

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}


opp/rejectTransferRequest

Description

Reject a Bluetooth object push request. This method is available only for a push server.

Parameters

Name

Required

Type

Description

requestId Required String

The unique ID of a request.

adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

155 Transfers are currently not allowed

OPP file transfers from the remote Bluetooth device are currently not allowed.

156 Required 'requestId' parameter is not supplied

The requestId parameter is mandatory to this method, but was not supplied by the caller of the method.

157 Failed to retrieve state for remote device

The confirmation of object push request from remote Bluetooth device failed.

158 The requestId does not exist

The supplied requestId does not exist, hence the accept operation cannot be completed.

159 These pushRequest already received the file

The confirmation of object push request from remote Bluetooth device is already done.

Example

luna-send -n 1 -f luna://com.webos.service.bluetooth2/opp/rejectTransferRequest '{"requestId":"001"}'

'{

"requestId":"001"

}'

 

Example response for a successful call: If OPP server awaits for file transfer,

{

"returnValue": true,

"adapterAddress": "00:00:45:0e:48:9b"

}

 

Example response for a failed call: If requestId is not valid,

{

"errorCode": 158,

"returnValue": false,

"errorText": "The requestId does not exist"

}


spp/connect

Description

Open a SPP connection to a remote Bluetooth device.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device.

uuid Required String

The UUID used when the server application opens its SPP channel.

subscribe Optional Boolean
  • To be notified when the connection is closed, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false.
adapterAddress Optional String

The address of the adapter executing this method call.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

subscribed Required Boolean
  • If it is subscribed, subscribed will contain true.
  • If it is not subscribed, subscribed will contain false.
channelId Optional String

Unique ID of a SPP channel, which has the following format: "nnn", 3 digit number increasing sequentially.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
subscribed Required Boolean
  • If it is subscribed, subscribed will contain true until the final response is sent by the service before stopping.
  • If it is not subscribed, subscribed will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

disconnectByRemote Required Boolean
  • If the remote device initiated the disconnect, disconnectByRemote will contain true.
  • If the local user initiated the disconnect, disconnectByRemote will contain false.
channelId Optional String

The unique ID of a SPP channel, which has the following format: "nnn", 3 digit number increasing sequentially.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 103, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

128 Device is already connecting

The remote Bluetooth device is already connecting to SPP profile, so another connection cannot be opened.

129 Device is not paired

The remote Bluetooth device is not paired, so SPP connection cannot be opened.

130 Failed to connect with remote device

The remote Bluetooth device cannot be connected to SPP profile.

131 Already connected

The remote Bluetooth device is already connected to the adapter's SPP profile, so another connection cannot be opened.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/spp/connect '{
        "address":"34:4d:f7:f9:52:f7",
        "uuid":"631e1400-c902-11e3-9c1a-0800200c9a66",
        "subscribe":true
}'

 

Example response for a successful call:

{

"returnValue": true,

"adapterAddress": "00:00:c5:99:f5:87",

"subscribed": true,

"channelId": "001"

}

 

Example response for a failed call: If address is not valid,

{

"errorCode": 130,

"returnValue": false,

"errorText": "Failed to connect with remote device"

}

 

Subscription return: If connection is successful,

{

"returnValue": true,

"adapterAddress": "00:00:c5:99:f5:87",

"subscribed": true,

"diconnectByRemote": false,

"channelId": "001"

}


spp/createChannel

Description

Register a service record in the device service record database with the specified UUID and name. The channel can be removed through LSCallCancel().

Parameters

Name

Required

Type

Description

name Required String

An identifiable name of a SPP service in the server, which the system will automatically write to a new Service Discovery Protocol (SDP) database entry on the device (the name is arbitrary and can simply be your application name).

uuid Required String

The UUID is also included in the SDP entry and will be the basis for the connection agreement with the client device. That is, when the client attempts to connect with this device, it will carry a UUID that uniquely identifies the service with which it wants to connect. These UUIDs must match in order for the connection to be accepted.

subscribe Required Boolean

Must set subscribe to true to be notified of changes to the channel (e.g., connection of client, removal of the channel).

adapterAddress Optional String

The address of the adapter executing this method. 

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

returnValue will always contain false.

The caller must subscribe to this method.

adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

subscribed Required Boolean

subscribe will always contain true.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

errorCoed Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the channel is successfully created, returnValue will contain true.
  • Otherwise, returnValue will contain false.
subscribed Required Boolean
  • If the subscription request succeeds, subscribed will contain true while the channel is alive.
  • If the channel is removed, subscribed will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

channelId Required String

Unique ID of a SPP channel, which has the following format: "nnn", 3 digit number increasing sequentially.

connecting Required Boolean
  • If the connection request is currently being processed, connecting will contain true.
  • Otherwise, connecting will contain false. For example, the Bluetooth stack is no longer processing the connection request.
connected Required Boolean
  • If the connection is open, connected will contain true.
  • Otherwise, connected will contain false.
address Optional String

The address (bdaddr) of the device.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. 

See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

203 Required 'uuid' parameter is not supplied

This method is required the "UUID" parameter.

205 Required 'name' parameter is not supplied

This method is required the "name" parameter.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/spp/createChannel '{
        "name":"service1",
        "uuid":"631e1400-c902-11e3-9c1a-0800200c9a66",
        "subscribe":true
}'

 

Example response for a failed call: If address is not valid,

{

"errorCode": 203,

"returnValue": false,

"errorText": "Required 'uuid' parameter is not supplied."

}

 

Subscription return: If connection is successful,

{

"returnValue": true,

"adapterAddress": "00:00:c5:99:f5:87",

"subscribed": true,

"channelId": "001",

"connecting": false,

"connected": false

}


spp/disconnect

Description

Drop the connection to the given remote device on SPP profile.

Parameters

Name

Required

Type

Description

channelId Required String

Unique ID of a SPP channel, which has the following format: "nnn", 3 digit number increasing sequentially.

adapterAddress Optional String

The address of the adapter executing this method. 

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorText Optional String

errorText contains the error text if the method fails.The method will return errorText only if it fails.See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

132 Failed to disconnect from remote device

The SPP connection with the remote Bluetooth device could not be closed

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/spp/disconnect '{ "channelId": "001" }'

 

Example response for a successful call:

{

"returnValue": true,

"adapterAddress": "00:00:c5:99:f5:87"

}

 

Example response for a failed call: If address is not valid,

{

"errorCode": 132,

"returnValue": false,

"errorText": "Failed to disconnect from remote device."

}


spp/getStatus

Description

Return the status of a SPP connection to a remote device.

Parameters

Name

Required

Type

Description

address Required String

The address (bdaddr) of the remote device.

subscribe Optional Boolean
  • To be notified of changes to the connection, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is false
adapterAddress Optional String

The address of the adapter executing this method call. When the field is not set, the default adapter is used for it.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
connecting Required Boolean
  • If the connection request is currently being processed, connecting will contain true.
  • Otherwise, connecting will contain false. For example, the Bluetooth stack is no longer processing the connection request.
connected Required Boolean
  • If the connection is open, connected will contain true.
  • Otherwise, connected will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

connectedChannels Required String array

Array of channel IDs which are connected currently.

subscribed Required Boolean
  • If it is subscribed, subscribed will contain true.
  • If it is not subscribed, subscribed will contain false
errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
subscribed Optional Boolean
  • If it is subscribed, subscribed will contain true until the final response is sent by the service before stopping.
  • If it is not subscribed, subscribed will contain false
connecting Required Boolean
  • If the connection request is currently being processed, connecting will contain true.
  • Otherwise, connecting will contain false. For example, the Bluetooth stack is no longer processing the connection request.
connected Required Boolean
  • If the connection is open, connected will contain true.
  • Otherwise, connected will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

connectedChannels Required String array

Array of channel IDs which are connected currently.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

133 Failed to retrieve state for remote device

The SPP connection status of the remote Bluetooth device cannot be retrieved.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/spp/getStatus '{
        "address": "34:4d:f7:f9:52:f7",
        "subscribe": false
}'

 

Example response for a successful call:

{

"returnValue": true,

"connecting": false,

"connected": true,

"connectedChannels": "["001"]"

"adapterAddress": "00:00:c5:99:f5:87",

"subscribed": false

}

 

Example response for a failed call: If address is not valid,

{

"errorCode": 133,

"returnValue": false,

"errorText": "Failed to retrieve state for remote device"

}

 

Subscription return: If connection is successful,

{

"returnValue": true,

"connecting": false,

"connected": true,

"connectedChannels": "["001"]"

"adapterAddress": "00:00:c5:99:f5:87",

"subscribed": false

}


spp/readData

Description

Receive data from the connected remote device. 

Parameters

Name

Required

Type

Description

channelId Optional String

Unique ID of a SPP channel.

If channelId is not specified, all connected channel IDs from which the caller received data will be returned. 

subscribe Optional Boolean
  • To read the data continuously, set subscribe to true.
  • Otherwise, set subscribe to false.
  • The default value of subscribe is true.
timeout Optional Number

The receive timeout in seconds.

It is available only when subscribe is set to true. After timeout seconds, the subscription is canceled. A value of 0 means that the timeout is disabled.

adapterAddress Optional String

The address of the adapter executing this method.

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

subscribed Required Boolean
  • If it is subscribed, subscribed will contain true.
  • If it is not subscribed, subscribed will contain false.
channelId Required String

Unique ID of a SPP channel.

data Optional String

BASE64-encoded string data received from the remote device. Before using the data, BASE64 decoding is needed.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

Subscription Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
subscribed Required Boolean
  • If it is subscribed, subscribed will contain true until the final response is sent by the service before stopping.
  • If it is not subscribed, subscribed will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

channelId Required String

Unique ID of a SPP channel.

data Optional String

BASE64-encoded string data received from the remote device. Before using the data, BASE64 decoding is needed.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

209 The supplied 'channelId' is not available

The channelId is not opened or does not exist.

211 The supplied 'timeout' is not available

If value of timeout is smaller than zero, this error is returned.

The value of timeout must be greater than zero.

212 Permission denied

The supplied channel is not connected or there is no authority.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/spp/readData '{
      "channelId": "001",
      "timeout": 10,
      "subscribe": false
}'

 

Example response for a successful call (when the sender sends "aa"):

{

"returnValue": true,

"channelId": "001",

"data": "YWE=",

"adapterAddress": "00:00:c5:99:f5:87",

"subscribed": false

}

 

Example response for a failed call: If address is not valid,

{

"errorCode": 209,

"returnValue": false,

"errorText": "The supplied 'channelId' is not available"

}

 

Subscription return: If connection is successful (when the sender sends "aa")

{

"returnValue": true,

"channelId": "001",

"data": "YWE=",

"adapterAddress": "00:00:c5:99:f5:87",

"subscribed": true

}


spp/writeData

Description

Transfer data to the connected remote device. 

Parameters

Name

Required

Type

Description

channelId Required String

Unique ID of a SPP channel.

data Required String

Data to send. This string data should be encoded to BASE64.

adapterAddress Optional String

The address of the adapter executing this method. 

If not specified, the default adapter will be used.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
adapterAddress Required String

The address of the adapter the operation was performed on.

If adapterAddress input parameter was not specified, the address of the default adapter will be returned.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

Error References

Error Code

Error Text

Error Description

102, 105, 106, 127, 143, 144 See API Error Codes Reference

See API Error Codes Reference.

204 Required 'channelId' parameter is not supplied

This method is required the "channelId" parameter.

206 Required 'data' parameter is not supplied

This method is required the "data" parameter.

207 Required 'size' parameter is not supplied

This method is required the "size" parameter.

208 Failed to write data

Writing Data is failed.

209 The supplied 'channelId' is not available

The channelId is not opened or does not exist.

210 The supplied 'size' is not available

The supplied size is smaller than zero or greater than max_buffer_size.

212 Permission denied

The supplied channel is not connected or there is no authority.

Example

# luna-send -n 1 -f luna://com.webos.service.bluetooth2/spp/writeData '{
       "channelId": "001",
       "data": "YWE=",
}'

 

Example response for a successful call:

{

"returnValue": true,

"adapterAddress": "00:00:c5:99:f5:87"

}

 

Example response for a failed call: If address is not valid,

{

"errorCode": 209,

"returnValue": false,

"errorText": "The supplied 'channelId' is not available"

}


Objects

bluetooth2Adapter

Object containing constant information about the adapter.

Name

Required

Type

Description

adapterAddress Required String

The address (bdaddr) of the adapter.

default Required Boolean

If true, this is the default adapter and adapter/ methods called without an adapterAddress parameter will operate on it.

Note that default (like all of the other values in this object) will not change while the adapter is present. This means if the default adapter is dynamic and is removed, there will no longer be an adapter with default set to true​.

classofDevice Required Number

The class of this Bluetooth adapter.

Values are taken from https://www.bluetooth.org/en-us/specification/assigned-numbers/baseband​.

stackName Required String

The name of the SIL that wraps the Bluetooth stack used by this adapter. 

stackVersion Required String

Version of the Bluetooth stack that the adapter's SIL wraps (not the version of the SIL itself).

firmwareVersion Required String

Version of the firmware used by the adapter's hardware.

serviceClasses Required Object array: bluetooth2ServiceClass

The Bluetooth Service Classes implemented for this adapter.

bluetooth2AdapterStatus

Object containing information about status of the adapter identified by adapterAddress.

The following values are read-only: discovering, pairablepairing​.

Name

Required

Type

Description

adapterAddress Required String

The address (bdaddr) of the adapter.

name Required String

The friendly name of this adapter. The default chosen by the system can be changed by the user.

powered Required Boolean

The adapter radio is powered on and is usable for discovery, connections, etc.

discovering Required Boolean

The adapter is discovering other devices.

discoveryTimeout Required Number

Timeout in seconds after which device discovery will be stopped. A value of zero means that the timeout is disabled and the adapter will run the discovery process forever. Negative values are illegal. 

pairing Required Boolean

The adapter is in the process of pairing to a remote device, either via incoming or outgoing pairing.

discoverable Required Boolean

 Indicates whether the adapter can be discovered by remote devices. If discoverableTimeout has a non-zero value, discoverable be set back to false that number of seconds after the call to adapter/setState set it to ​true.

discoverableTimeout Required Number

The discoverable timeout in seconds. A value of zero means that the timeout is disabled and the adapter will stay in discoverable mode until a call to adapter/setState sets discoverable to false. Negative values are illegal.

pairable Required Boolean

Indicates whether the adapter can be paired to a remote device. It is initially false and is set to true when client is subscribed to adapter/awaitPairingRequests.

There is an exception to this field when the bluetooth capability is "NoInputNoOutput". In this case, pairable is always set to true, since pairing simply works without any responses on awaitPairingRequests. The client need not be subscribed to awaitPairingRequests when the bluetooth capability is "NoInputNoOutput".

pairableTimeout Required Number

The pairable timeout in seconds. This is how long the service will wait for the remote device to send a response after it has responded to an incoming pairing request.

 A value of zero means that the timeout is disabled and it will wait forever for a response. Negative values are illegal.

bluetooth2DeviceStatus

Object containing information about status of the device identified by address.

All but ​name are read-only.

Name

Required

Type

Description

address Required String

The address (bdaddr) of the device.

name Required String

The friendly name of the device displayed to the user. When a previously undiscovered device is first discovered, the system makes up a reasonable value for this.

classOfDevice Required Number

  The class of this Bluetooth device. Values taken from https://www.bluetooth.org/en-us/specification/assigned-numbers/baseband​ 

typeOfDevice Required String

One of:

  • unknown - Unknown device type
  • BREDR - Basic Rate/Enhanced Data Rate
  • BLE - Bluetooth Low Energy
  • dual - supports both Basic Rate/Enhanced Data Rate and Bluetooth Low Energy
serviceClasses Required Object array: bluetooth2ServiceClass

Array of Service Classes supported by this device.

pairing Required Boolean

Device is in the process of pairing. Is set to false once pairing is over (and paired set depending whether the pairing succeeded or failed).

paired Required Boolean

If ​true, then the device is paired to the adapter with address adapterAddress​.

adapterAddress Required String

The address of the adapter to which the device is paired (or was last paired). If never paired, it will be the empty string.

connectedProfiles Optional String array

Array of the lower-cased official abbreviation for the profile to which the service class is associated taken from https://developer.bluetooth.org/TechnologyOverview/Pages/Profiles.aspx.

trusted Required Boolean
  • trusted will contain true if the remote device is seen as a trusted device.
  • Otherwise, trusted will contain false
blocked Required Boolean

Indicates a remote device is blocked (if set) or unblocked (if reset) for pairing and profile connections.

  • If blocked contains true, any incoming connections from the device will be immediately rejected. Any device drivers will also be removed and no new ones will be probed as long as the device is blocked.
  • If blocked contains false, incoming connections are allowed from the remote device.
rssi Required Number

Signal strength level of the device.

txPower Required Number

Transmission power level of the remote device.

Only available for Bluetooth Low Energy devices. Property will not be present for Bluetooth classic devices.

bluetooth2ServiceClass

Bluetooth service class information.

Name

Required

Type

Description

mnemonic Required String

  A mnemonic for the UUID of the Service Class. It is formed by taking the (upper- or mixed-case) official abbreviation for the profile from left-most column on https://developer.bluetooth.org/TechnologyOverview/Pages/Profiles.aspx, and, where there are different UUIDs for different profile roles, appending the capitalized role abbreviation, separated by a hyphen.

category Required String

The LS2 category of the methods that access this Service Class. This is the lower-cased official abbreviation for the profile to which the service class is associated taken from https://developer.bluetooth.org/TechnologyOverview/Pages/Profiles.aspx.

bluetooth2GattServiceInfo

Object containing the GATT service configuration.

Name

Required

Type

Description

service Required String

UUID of the service

type Required String

UUID which describes the type of the service.

The following types are defined:

  • primary (UUID 0x2800)
  • secondary (UUID 0x2801)

 

includes Required String array

List of service UUIDs this services includes in its definition.

characteristics Required Object array: bluetooth2GattCharacteristicInfo

List of characteristics which are part of the service

instanceId Optional String

Unique identifier of the service.

bluetooth2GattValueInfo

Object contains 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 only used when not value type descriptor is present. 

Name

Required

Type

Description

string Optional String

Present when the value is from type string. Not present otherwise.

number Optional Number

Present when the value is from type number. Not present otherwise.

bytes Optional Number array

If the type of the value is not specified then the value is returned as a sequence of bytes.

bluetooth2GattCharacteristicInfo

Object containing information about a GATT characteristic.

Name

Required

Type

Description

characteristic Required String

UUID of the characteristic.

value Required Object: bluetooth2GattValueInfo

Value of the characteristic.

properties Required Object:bluetooth2GattPropertiesInfo

Configured properties for the characteristic.

permissions Required Object: bluetooth2GattPermissionsInfo

Configured permissions for the characteristic.

descriptors Required Object array: bluetooth2GattDescriptorInfo

List of descriptors for the characteristic.

instanceId Optional String

Unique identifier of the characteristic

bluetooth2GattPropertiesInfo

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.

Name

Required

Type

Description

broadcast Optional Boolean

If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor.

If set, the Server Characteristic Configuration Descriptor shall exist.

read Optional Boolean

If set, permits reads of the Characteristic Value.

writeWithoutResponse Optional Boolean

If set, permit writes of the Characteristic Value without response.

write Optional Boolean

If set, permits writes of the Characteristic Value with response

notify Optional Boolean

If set, permits notifications of a Characteristic Value without acknowledgement.

If set, the Client Characteristic Configuration Descriptor shall exist.

indicate Optional Boolean

If set, permits indications of a Characteristic Value with acknowledgement.

authenticatedSignedWrites Optional Boolean

If set, permits signed writes to the Characteristic Value

extendedProperties Optional Boolean

If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor.

If set, the Characteristic Extended Properties Descriptor shall exist.

bluetooth2GattPermissionsInfo

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.

Name

Required

Type

Description

read Optional Boolean

If set, clients are allowed to read the characteristic value.

readEncrypted Optional Boolean

If set, allows encrypted read operations.

readEncryptedMitm Optional Boolean

If set, allows reading with man-in-the-middle protection.

write Optional Boolean

If set, clients are allowed to write the characteristic value.

writeEncrypted Optional Boolean

If set, allows encrypted writes.

writeEncryptedMitm Optional Boolean

If set, allows encrypted writes with man-in-the-middle protection.

writeSigned Optional Boolean

If set, allows signed write operations.

writeSignedMitm Optional Boolean

If set, allows signed write operations with man-in-the-middle protection.

bluetooth2GattDescriptorInfo

Object containing information about a GATT descriptor.

Name

Required

Type

Description

descriptor Required String

Unique identifier of the descriptor

value Required Object: bluetooth2GattValueInfo

Value of the descriptor

instanceId Optional String

Unique identifier of the descriptor

bluetooth2PushRequest

Object containing information about an OPP push request

Name

Required

Type

Description

requestId Required String

Unique ID of a request, which has the following format: "nnn", 3 digit number increasing sequentially from the formerly highest requestId. The logs for 999 numbers of requests are maintained in a system. If a user does not delete the logs of some requests manually, the logs will be deleted (oldest first).

address Required String

The address (bdaddr) of the device where the file came.

name Required String

The name of the device where the file came.

fileName Required String

The name of the file received from a remote device.

fileSize Required Number

The file size in bytes.

transferred Optional Number

Number of bytes transferred so far.

bluetooth2LeServiceObject

Object containing information about a service to be advertised.

Name

Required

Type

Description

uuid Required String

16-bit UUID representing one service.

data Optional Number (uint8_t) array

Array of data pertaining to a service.

bluetooth2TxPower

Object containing txpower information.

Name

Required

Type

Description

txPower Required Number

Transmit power as measured at 1 meter distance from the webOS device.

bluetooth2LeProprietaryDataObject

Defines the format for proprietary data with vendor proprietary advertising type or undefined type in sil-api

Name

Required

Type

Description

type Required Number

proprietary advertising type

data Required Number array

Byte sequence of proprietary data.

bluetooth2GattCharacteristicValueInfo

Object containing information about the characteristic uuid and values.

Name

Required

Type

Description

characteristic Required String

Characteristic uuid

value Required Number (uint8_t) array

Byte sequence of characteristic data.

bluetooth2AdvertiseSettings

Object containing information about the advertisement setting.

Name

Required

Type

Description

connectable Optional Boolean

Possible values:

  • True: Sets the webOS device as a connectable advertising device.
  • False: Advertisements are undirected and non-connectable. 

Note: Default value of connectable is true.

txPower Optional Number (uint8_t)

Two's complement value of transmission power.

Only used if includeTxPower is true.

timeout Optional Number

Connection timeout.

bluetooth2AdvertiseData

Provides a detailed description of the object. Limit to 2-3 paragraphs.

Name

Required

Type

Description

includeTxPower Optional Boolean

Possible values:

True: To include advertisement transmission power.

False:To not include advertisement transmission power.

includeName Optional Boolean

Possible values:

True: To include local device name in advertisement.

False: To not include local device name in advertisement.

Note:Default value is false.

manufacturerData Optional Number (uint8_t) array

Byte sequence of manufacturer specific data. 

services Optional Object array: bluetooth2LeServiceObject

Array of services and data to be included in the advertisement.

Note:

  • Only zero or one bluetooth2LeServiceObject may contain data, all others (if any) must only contain uuid
  • Cannot be passed if manufacturerData is passed.
proprietaryData Optional Object: bluetooth2LeProprietaryDataObject

Used for advertising data with vendor proprietary advertising type or undefined type as parameter (ex. LE Bluetooth Devices (0x1B)).

bluetooth2LeServiceUuidObject

Object containing information about a service uuid to be advertised.

Name

Required

Type

Description

uuid Required String

Service uuid. UUID which is an immutable representation of a 128-bit universally unique identifier.

mask Optional String

The bit mask for the serviceUuid.

Possible values are:

1- Set any bit in the mask to 1 to indicate a match is needed for the bit in serviceUuid.

0- Set any bit in the mask to 0 to ignore that bit.

 

bluetooth2LeServiceDataObject

Object containing information about a service data to be advertised.

Name

Required

Type

Description

uuid Required String

Data uuid. UUID which is an immutable representation of a 128-bit universally unique identifier.

data Required Number array

Array of data pertaining to a service.

mask Optional Number array

Possible values are:

1- Set any bit in the mask to 1 to indicate a match is needed for the bit in service data.

0- Set any bit in the mask to 0 to ignore that bit.

bluetooth2LeManufacturerData

Object containing information about manufacturer data.

Name

Required

Type

Description

id Required Number

Manufacturer ID which is the first two bytes of manufacturer data.

data Required Number array

Array of manufacture data

mask Optional Number array

Possible values are:

1- Set any bit in the mask to 1 to indicate a match is needed for the bit in service data.

0- Set any bit in the mask to 0 to ignore that bit.

 


ERROR REFERENCES

Error Code

Error Text

Error Description

6 An invalid value was passed for one of the parameters

An invalid value was passed for one of the parameters while calling the SIL (Stack Interface Layer) from the Bluetooth service.

7 An unhandled error was encountered

An unhandled error was encountered at the SIL (Stack Interface Layer) while performing the requested operation.

218 Cannot have more than one service with data

Attempted to pass multiple bluetooth2LeServiceObject containing data. Can only pass one that contains data.

10 Authentication with a remote device failed

Authentication with a remote Bluetooth device has failed either at the underlying stack.

12 Authentication with a remote device timed out

Authentication with a remote Bluetooth device has timed out before getting a valid response from the remote device.

9 Authentication with a remote device was canceled

Authentication with a remote Bluetooth device was canceled by the remote Bluetooth device.

11 Authentication with a remote was rejected

Authentication with a remote Bluetooth device was rejected by the remote Bluetooth device.

175 Invalid value input for GATT characteristic

Characteristic value is not valid.

170 GATT add service failed

Failed to add the GATT Service.

251 Failed to disable profile

Failed to disable profile.

250 Failed to enable profile

Failed to enable profile.

176 GATT monitor characteristic failed for characteristic

Failed to monitor GATT characteristic.

169 GATT service discovery cannot be started, one of adapterAddress or address should be supplied

Failed to start service discovery.

172 GATT write characteristic failed

Failed to write characteristic the specified value.

174 GATT read characteristics failed

Failed to read the requested characteristics. 

213 Failed to configure advertisement

Generic advertisement configuration fail.

216 Cannot have both services and manufacturer data, only one should be supplied

Method was called with too many parameters, can only support either services or manufacturerData, not both.

214 Attempted to configure too many services

More than the maximum number of UUIDs were attempted to be put into the advertisement. Using the BSA stack, this limit is 6 UUIDs in one advertisement.

144 The JSON input does not match the expected schema

One 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. Note that any required parameter missing will be a different error return based on the missing key.

104 Only one subscription allowed

Only one client is allowed to subscribe to this method

248 Profile already enabled

Profile already enabled.

249 Profile not enabled

Profile not enabled.

237 Required 'address' parameter is not supplied

Required 'address' parameter is not supplied.

164 Required 'characteristic' uuid parameter is not supplied

Required 'characteristic' uuid parameter is not supplied

105 Required 'address' parameter is not supplied

The address parameter is mandatory, but was not supplied by the caller of the method.

162 Adapter Address is not valid

The adapter address given is not valid.

103 Method needs to be subscribed

The 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.

2 The device is not ready to perform the requested operation

The Bluetooth adapter (local device) is not ready to perform the requested operation.

108 There is no pairing in progress

The Bluetooth adapter is not currently pairing with any remote Bluetooth device.

3 The SIL failed to allocate memory

The 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.

173 Invalid GATT characteristic for the given service

The characteristic ID supplied does not belong to the service.

143 Invalid JSON input

The JSON input has an invalid format and cannot be parsed.

102 Failed to parse incoming message

The json payload passed to the method cannot be parsed and the input parameters' values cannot be determined.

163 Required 'service' uuid parameter is not supplied

The mandatory Service name parameter required by this method call is not supplied.

215 Services and manufacturer data are missing, one should be supplied

The method was called with no advertising information to be configured. Either services or manufacturerData must be passed.

107 Pairing canceled by user

The ongoing pairing with a remote Bluetooth device has been canceled. The cancel is initiated by the client at the local device.

136 Device is not connected

The remote Bluetooth device is not connected to our Bluetooth adapter via the profile.

106 Device with supplied address is not available

The remote Bluetooth device with the supplied address is not available (in the discovered devices list) to continue the operation of this method.

 

8 Unknown device address

The remote Bluetooth device's address for performing the requested operation is not available in the list of found remote devices or is invalid.

13 Device is already paired

The remote device with which we are trying to pair is already paired to the local device adapter.

1 The operation failed for an unspecified or generic reason

The requested Bluetooth operation failed for an unspecified or generic reason in the Bluetooth stack.

4 The operation can not be performed at this time

The requested operation can not be performed by the adapter at this time since the adapter or SIL is busy with a different operation.

5 The requested operation is not supported by the stack or device

The requested operation is not supported by the Bluetooth stack or adapter.

127 Profile backend is not available

The SIL module used doesn't provide any implementation for the profile.

177 Invalid GATT Service

The supplied GATT service is not available or is not configured. 

165 Invalid value input for GATT characteristic

The supplied value for GATT characteristics is invalid.

101 Bluetooth adapter is not available

The underlying Bluetooth daemon is not running or isn't attached to the hardware. Use "start bluetooth-setup" which will then create the communication channel to the chip and make it known to the Bluetooth stack (bluez).

180 Required 'address' parameter is not supplied

The address parameter is mandatory, but was not supplied by the caller of the method.

247 Failed to get Socket Path

The Path parameter is mandatory, but was not supplied by the caller of the method.


Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.