LogicalLabs Bluetooth Module

API Docs for: 1.0.3
Show:

BluetoothModule Class

Module: Readme

Methods

cancelDiscovery

() Boolean

Available since 1.0.0

Cancels the current device discovery process.

Because discovery is a heavyweight procedure for the Bluetooth adapter, this method should always be called before attempting to connect to a remote device. Discovery is run as a system service, so an application should always call cancel discovery even if it did not directly request a discovery, just to be sure.

Returns:

Boolean:

If Bluetooth state is not STATE_ON, this function will return false.

checkBluetoothAddress

(
  • address
)
Boolean

Available since 1.0.0

Validates a Bluetooth address, such as "00:43:A8:23:10:F0". Returns true if the address is valid, false otherwise.

Alphabetic characters must be uppercase to be valid.

Parameters:

  • address String

    a string representing the address, such as "00:43:A8:23:10:F0".

Returns:

Boolean:

True if the address is valid, false otherwise.

createBluetoothSocket

(
  • params
)
BluetoothSocket deprecated

Deprecated: 1.0.1

Available since 1.0.0

This method is not needed as of Titanium 3.1.1.GA and is deprecated as of version 1.0.1 of the module. Please use the createSocket method instead.

Use this method to create a socket to a remote device until TIMOB-13097 is fixed in Titanium.

Parameters:

  • params Object

    An object with the following properties:

    • remoteDevice BluetoothDevice

      The device this socket will connect to.

    • uuid String

      UUID of the service this socket will connect to.

    • [secure=false] Boolean optional

      Defines whether the connection will be secure or insecure.

Returns:

createServerSocket

(
  • params
)
BluetoothServerSocket

Available since 1.0.0

Creates a server socket that listens for incoming connections.

Parameters:

  • params Object

    An object with the following properties:

    • name String

      Name of the service for SDP record.

    • uuid String

      The UUID of the service for SDP record.

    • [secure=false] Boolean optional

      Specifies whether the connection will be secured.

disable

() Boolean

Available since 1.0.0

Turns off Bluetooth functionality on the device. Android guidelines dictate that you only use this function in response to explicit user action to turn off Bluetooth.

This is an asynchronous call; it will return immediately. It returns true to indicate that shutdown of the Bluetooth adapter has begun, or false on immediate error. Listen for the stateChanged event to be notified of actual state changes.

See also the STATE_OFF, STATE_ON, STATE_TURNING_OFF, and STATE_TURNING_ON constants.

Returns:

Boolean:

Returns true to indicate that shutdown of the Bluetooth adapter has begun, or false on immediate error.

enable

() Boolean

Available since 1.0.0

Turns on Bluetooth functionality on the device. Android guidelines dictate that you only use this function in response to explicit user action to turn on Bluetooth.

This is an asynchronous call; it will return immediately. It returns true to indicate that startup of the Bluetooth adapter has begun, or false on immediate error. Listen for the stateChanged event to be notified of actual state changes.

See also the STATE_OFF, STATE_ON, STATE_TURNING_OFF, and STATE_TURNING_ON constants.

Returns:

Boolean:

Returns true to indicate that startup of the Bluetooth adapter has begun, or false on immediate error.

ensureDiscoverable

() Void

Available since 1.0.0

Displays a system activity that asks the user for permission to make the device discoverable by other devices, and to turn on Bluetooth if it is not currently enabled.

Returns:

Void:

getAddress

() String

Available since 1.0.0

Returns the hardware address of the local Bluetooth adapter as a string. For example, "00:11:22:AA:BB:CC".

Returns:

String:

The hardware address of the local Bluetooth adapter.

getName

() String

Available since 1.0.0

Returns the friendly Bluetooth name of the local Bluetooth adapter.

Returns:

String:

The friendly Bluetooth name of the local Bluetooth adapter. May return undefined if an error occurs.

getPairedDevices

() BluetoothDevice[]

Available since 1.0.0

Returns the BluetoothDevice objects that are paired to the local adapter.

Returns:

getRemoteDevice

(
  • address
)
BluetoothDevice

Available since 1.0.0

Returns a BluetoothDevice object for the given Bluetooth hardware address.

Parameters:

  • address String

Returns:

getScanMode

() Number final

Available since 1.0.0

Returns the current Bluetooth scan mode of the local Bluetooth adapter.

See also the SCAN_MODE_* constants.

Returns:

Number:

getState

() Number

Available since 1.0.0

Returns the current state of the local Bluetooth adapter.

See also the STATE_OFF, STATE_ON, STATE_TURNING_OFF, and STATE_TURNING_ON constants.

Returns:

Number:

isDiscovering

() Boolean

Available since 1.0.0

Returns true if the local Bluetooth adapter is currently in the device discovery process.

Device discovery is a heavyweight procedure. New connections to remote Bluetooth devices should not be attempted while discovery is in progress, and existing connections will experience limited bandwidth and high latency. Use cancelDiscovery() to cancel an ongoing discovery.

Returns:

Boolean:

true if the local Bluetooth adapter is currently in the device discovery process.

isEnabled

() Boolean

Available since 1.0.0

Determines whether the Bluetooth adapter is enabled and ready for use.

Returns:

Boolean:

Returns true if Bluetooth is currently enabled.

isSupported

() Boolean

Available since 1.0.0

Determines whether Bluetooth is supported on the device.

Returns:

Boolean:

Returns true if Bluetooth is supported on the device, false otherwise.

setName

(
  • name
)
Void

Available since 1.0.0

Sets the friendly Bluetooth name of the local Bluetooth adapter.

The Bluetooth adapter must be turned on before you can set the name. After turning on Bluetooth, wait for the adapter to reach STATE_ON state by listening to the stateChanged event.

Parameters:

  • name String

    A valid Bluetooth name. Valid Bluetooth names are a maximum of 248 bytes using UTF-8 encoding, although many remote devices can only display the first 40 characters, and some may be limited to just 20.

Returns:

Void:

startDiscovery

() Boolean

Available since 1.0.0

Starts the remote device discovery process.

The discovery process usually involves an inquiry scan of about 12 seconds, followed by a page scan of each new device to retrieve its Bluetooth name.

This is an asynchronous call; it will return immediately. It returns true to indicate success, or false on immediate error. Listen for the discoveryStarted, deviceFound, and BluetoothModule/discoverFinished:event events to be notified of the progress of the discovery process.

Returns:

Boolean:

Returns true to indicate success, or false on immediate error.

Properties

address

String read-only

Available since 1.0.0

The hardware address of this BluetoothDevice, for example "00:11:22:AA:BB:CC".

name

String

Available since 1.0.0

The friendly Bluetooth name of the local Bluetooth adapter.

pairedDevices

BluetoothDevice[] read-only

Available since 1.0.0

An array of the BluetoothDevice objects that are paired to the local adapter.

scanMode

Number

Available since 1.0.0

The current Bluetooth scan mode of the local Bluetooth adapter.

See also the SCAN_MODE_* constants.

state

Number read-only

Available since 1.0.0

The current state of the local Bluetooth adapter.

See also the STATE_OFF, STATE_ON, STATE_TURNING_OFF, and STATE_TURNING_ON constants.

Constants

DEVICE_BONDED

Number

Available since 1.0.0

The value returned by the getBondState method or bondState property when the device is bonded (paired) with the local Bluetooth adapter.

DEVICE_BONDING

Number

Available since 1.0.0

The value returned by the getBondState method or bondState property when bonding (pairing) between the device and the local Bluetooth adapter is in progress.

DEVICE_NOT_BONDED

Number

Available since 1.0.0

The value returned by the getBondState method or bondState property when the device is not bonded (paired) with the local Bluetooth adapter.

DEVICE_TYPE_CLASSIC

Number

Available since 1.0.1

One of the possible values returned by the getType method or the type property.

DEVICE_TYPE_DUAL

Number

Available since 1.0.1

One of the possible values returned by the getType method or the type property.

DEVICE_TYPE_LE

Number

Available since 1.0.1

One of the possible values returned by the getType method or the type property.

DEVICE_TYPE_UNKNOWN

Number

Available since 1.0.1

One of the possible values returned by the getType method or the type property.

SCAN_MODE_CONNECTABLE

Number

Available since 1.0.0

The value returned by the getScanMode method or scanMode property when inquiry scan is disabled but page scan is enabled on the local Bluetooth adapter. This means remote devices can connect to this device but cannot discover it.

SCAN_MODE_CONNECTABLE_DISCOVERABLE

Number

Available since 1.0.0

The value returned by the getScanMode method or scanMode property when both inquiry scan and page scan are enabled on the local Bluetooth adapter. This means remote devices can both discover and connect to this device.

SCAN_MODE_NONE

Number

Available since 1.0.0

The value returned by the getScanMode method or scanMode property when both inquiry scan and page scan are disabled on the local Bluetooth adapter. This means remote devices can neither discover nor connect to this device.

STATE_OFF

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is turned off.

STATE_ON

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is turned on.

STATE_TURNING_OFF

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is about to turn off.

STATE_TURNING_ON

Number

Available since 1.0.0

The value returned by the getState method or state property when the Bluetooth adapter is about to turn on.

Events

deviceFound

Available since 1.0.0

Fired when the local Bluetooth adapter discovers a device.

Event Payload:

  • device BluetoothDevice

    The discovered Bluetooth device.

  • RSSI Number

    The RSSI value at the time of device discovery. This field was added in version 1.0.1.

discoveryFinished

Available since 1.0.0

Fired when the local Bluetooth adapter finished discovery.

discoveryStarted

Available since 1.0.0

Fired when the local Bluetooth adapter started discovery.

fetchedUUIDs

Available since 1.0.1

Returns the results of service discovery started via the fetchUUIDs method.

Event Payload:

  • device BluetoothDevice

    The Bluetooth device in question.

  • UUIDs Array of Strings

    The service UUIDs of the device.

stateChanged

Available since 1.0.0

Fired when the state of the local Bluetooth adapter changes.