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.