# Bluetooth Serial Port Protocol (SPP)

webOS 2.0 exposes the Bluetooth SPP to applications needing to take advantage of certain bluetooth devices. At this time, only the SPP is exposed. The code samples contain an example Bluetooth project which opens a port to a Bluetooth GPS device and reads position data from it.

The general sequence is to get a list of paired devices from the Bluetooth service, then look for the device of interest within that list. If a device of interest is found, subscribe to Bluetooth notifications, then connect to the desired device. When a notification arrives from the connected device, call the `open` method on that instance, followed by the `read` method, which returns an object with the data.

To stop listening to the data, `close` the port followed by a `disconnect`.

## URI

Currently the Bluetooth SPP service exposes two URIs: one for general access profile (GAP) methods, and one for serial port access. The URI for GAP is:

>     com.palm.bluetooth/gap

The URI for serial port access is:

>     com.palm.bluetooth/spp

## Common Parameter Types

The following type descriptions are common to many of the methods used with Bluetooth SPP services.

Parameter | Format | Description
--- | --- | ---
BT Address | "address":"AA:BB:CC:DD:EE:FF" | Bluetooth device address where AA, BB, etc are hex digits for an IEEE standard MAC address
profile | "profile":"hfg|audio|pan|pbap|a2dp|opp" | profile names
state | "state":"off|on|disconnected|connecting|connected" | The state of the Bluetooth radio or profile.

## Method--GAP

This section describes the following method:

- gettrusteddevices

### gettrusteddevices

#### Parameters

`gettrusteddevices` does not take any parameters.

#### Returns

## Methods--SPP

This section describes the following methods:

- subscribenotifications
- connect
- selectservice
- open
- read
- close
- disconnect

### subscribenotifications

#### Parameters

Parameter | Type | Description
--- | --- | ---
subscribe | boolean | Subscribes or unsubscribes to Bluetooth SPP notifications. Set as "true" to subscribe and "false" to unsubscribe.

#### Returns

Returns an object with the following parameters:

- `returnValue`--boolean
- `trusteddevices`--array comprising the following items:
  - `address`--string containing the Bluetooth address, e.g., `"00:0d:b5:38:c0:3f"`
  - `name`--string containing the name of the device, e.g., `"BT-GPS-38C03F"`
  - `cod`--integer
  - `renamed`--boolean
  - `status`--string, either `connected` or `disconnected`

### connect

#### Parameters

Parameter | Type | Description
--- | --- | ---
address | BT Address | Address of the device.

#### Returns

Returns an object with the following parameters:

- `notification`--string. May be `notifnservicenames` if service names are being returned, `notifnconnected` if the device has connected, or `notifndisconnected` if the device has disconnected.
- `instanceId`--integer containing the context of the requested service.
- `services`--string, containing service names, if the response was a `notifnservicenames`.

### selectservice

#### Parameters

Parameter | Type | Description
--- | --- | ---
instanceId | integer | Context of the subscribed service.
servicename | string | Name of the service to be selected. Provided by the object returned from `subscribenotifications`.

#### Returns

`selectservice` does not return any parameters.

### open

#### Parameters

Parameter | Type | Description
--- | --- | ---
instanceId | integer | Context of the subscribed service.

#### Returns

`open` does not return any parameters.

### read

#### Parameters

Parameter | Type | Description
--- | --- | ---
instanceId | integer | Context of the subscribed service.
dataLength | integer | Size of the buffer to be returned.

#### Returns

On success, returns an object with the following parameters:

- `returnValue`--boolean
- `data`--string
- `dataLength`--integer

On failure, read returns:

- `returnValue`--boolean
- `errorText`--string

### close

#### Parameters

Parameter | Type | Description
--- | --- | ---
instanceId | integer | Context of the subscribed service.

#### Returns

On success, returns an object with a boolean `returnValue`.

On failure, returns an object with a boolean `returnValue`, and an integer `errorCode`.

### disconnect

#### Parameters

Parameter | Type | Description
--- | --- | ---
address | BT Address | Bluetooth device address.
instanceId | integer | Context of the subscribed service.

#### Returns

The `disconnect` method does not return any parameters in the returned object unless there is an error. In the event of an error, the property `errorCode` will be found in the returned object.