Bluetooth
The Bluetooth module exposes bluetooth manipulation APIs.
Scanning
In order to pair and connect to a bluetooth device, a scan operation has to be issued. To start a scanning operation, a call to startScan needs to be issued. Doing so populates the list of known devices. Keep in mind that this also sets the STB's bluetooth adapter to scanning state and will remain in that state until a call to stopScan is issued. When a new device is discovered, an onBluetoothEvent is emitted with the event property of the event data set to Platform.Bluetooth.BluetoothEvent.DEVICE_APPEARED. To retrieve a list of all known devices, call getDevices. Please note that the device list gets cleared 180 seconds after a scan is stopped, and only paired devices will be displayed after that period ends.
Pairing and connecting
To link a bluetooth device with the STB, a handshake known as pairing has to be made between the STB and the device. To pair a device, call pairDevice and pass as argument the MAC address of the desired device. This is an asynchronous operation. If pairing is successful, an onBluetoothEvent is emitted with the event property of the event data set to Platform.Bluetooth.BluetoothEvent.PAIR_SUCCESSFUL. If pairing fails, an onBluetoothEvent is emitted with the event property set to Platform.Bluetooth.BluetoothEvent.PAIR_FAILED and the error property of the event data is set to a value of the PairError enum. To initiate a connection with a bluetooth device, call connectDevice and pass as argument the MAC address of the desired device. This is an asynchronous operation. If the connection is successful, an onBluetoothEvent is emitted with the event property of the event data set to Platform.Bluetooth.BluetoothEvent.DEVICE_CONNECTED.
Standby
The Bluetooth module provides APIs to configure the bluetooth adapter with a device that will be able to wake up the STB when in standby state. To do so, call setStandbyDevice and pass as argument the MAC address of the desired device.
Members
BluetoothEvent
Enum for the bluetooth events.
Properties:
| Name | Type | Description |
|---|---|---|
PAIR_FAILED | ||
PAIR_SUCCESSFUL | ||
DEVICE_DISAPPEARED | ||
DEVICE_APPEARED | ||
DEVICE_CONNECTED | ||
DEVICE_DISCONNECTED |
onBluetoothEvent
Signal fired when some bluetooth event occurs with a device. The listener will be passed the following arguments:
- eventData: A EventData object containing event related data.
PairError
Enum for the pair errors.
Properties:
| Name | Type | Description |
|---|---|---|
UNKNOWN | ||
TIMEOUT | ||
FAILED | ||
ALREADY_EXISTS | ||
AUTHENTICATION_CANCELED | ||
AUTHENTICATION_FAILED | ||
AUTHENTICATION_REJECTED | ||
AUTHENTICATION_TIMEOUT | ||
CONNECTION_ATTEMPT_FAILED |
Methods
connectDevice(address)
Start connecting with a paired device. This is an asynchronous operation.
If the connection to the desired device is successful, an onBluetoothEvent is emitted with the event property set to Platform.Bluetooth.BluetoothEvent.DEVICE_CONNECTED.
Parameters:
| Name | Type | Description |
|---|---|---|
address | String | The MAC address of the device to connect to. |
Returns:
| Type | Description |
|---|---|
| A promise. | No arguments are passed to the completion handler. |
disconnectDevice(address)
Disconnect from a previously connected device. This is an asynchronous operation.
When disconnected successfully, an onBluetoothEvent is emitted with the event property set to Platform.Bluetooth.BluetoothEvent.DEVICE_DISCONNECTED.
Parameters:
| Name | Type | Description |
|---|---|---|
address | String | The MAC address of the device to disconnect from. |
Returns:
| Type | Description |
|---|---|
| A promise. | No arguments are passed to the completion handler. |
getAdapterInfo()
Retrieve information of the STB's bluetooth adapter.
Returns:
| Type | Description |
|---|---|
| A promise. | The completion handler will be passed the following arguments: - info: An AdapterInfo object containing the STB bluetooth adapter info. |
getDeviceInfo(address)
Retrieve information of a known Bluetooth device.
Parameters:
| Name | Type | Description |
|---|---|---|
address | String | The device MAC address to retrieve the information from. |
Returns:
| Type | Description |
|---|---|
| A promise. | The completion handler will be passed the following arguments: - device: A DeviceInfo object containing the device info. |
getDevices()
Retrieve a list with all known Bluetooth devices. Keep in mind that the list gets cleared 180 seconds after a scanning operation is stopped, and only paired devices will be returned until they are removed explicitly by calling removeDevice.
Returns:
| Type | Description |
|---|---|
| A promise. | The completion handler will be passed the following arguments: - devices: An Array of DeviceInfo objects containing the devices info. |
getStandbyDevice()
Retrieve the address of the registered bluetooth device which is able to wake up the system when in standby state.
Returns:
| Type | Description |
|---|---|
| A promise. | The completion handler will be passed the following arguments: - device: The MAC address of the registered standby device, or empty string if no device is registered. |
pairDevice(address)
Connect and start paring with a known bluetooth device from the device list. This is an asynchronous operation.
If pairing is successful, an onBluetoothEvent is emitted with the event property set to Platform.Bluetooth.BluetoothEvent.PAIR_SUCCESSFUL. If pairing fails, an onBluetoothEvent is emitted with the event property set to Platform.Bluetooth.BluetoothEvent.PAIR_FAILED and the error property is set to a value of the PairError enum.
Parameters:
| Name | Type | Description |
|---|---|---|
address | String | The MAC address of the device to pair with. |
Returns:
| Type | Description |
|---|---|
| A promise. | No arguments are passed to the completion handler. |
removeDevice(address)
Remove a device from the device list and remove pairing.
Parameters:
| Name | Type | Description |
|---|---|---|
address | String | The MAC address of the device to remove from the device list. |
Returns:
| Type | Description |
|---|---|
| A promise. | No arguments are passed to the completion handler. |
setAdapterPower(power)
Set the desired power state of the bluetooth adapter.
Parameters:
| Name | Type | Description |
|---|---|---|
power | Boolean | Set to true to turn the bluetooth adapter on, false to turn it off. |
Returns:
| Type | Description |
|---|---|
| A promise. | No arguments are passed to the completion handler. |
setStandbyDevice(address)
Set the device which can wakeup the system when in standby state or removes this configuration by passing an empty string or null.
Parameters:
| Name | Type | Description |
|---|---|---|
address | String | The MAC address of the desired standby device, or empty string to clear the setting. |
Returns:
| Type | Description |
|---|---|
| A promise. | No arguments are passed to the completion handler. |
startScan()
Initiate a bluetooth scanning operation. The adapter will remain in scanning state until a call to stopScan is issued.
During the scanning operation, when a device is discovered, an onBluetoothEvent is emitted with the event property set to Platform.Bluetooth.BluetoothEvent.DEVICE_APPEARED.
Returns:
| Type | Description |
|---|---|
| A promise. | No arguments are passed to the completion handler. |
stopScan()
Stop a previously started scanning operation.
Returns:
| Type | Description |
|---|---|
| A promise. | No arguments are passed to the completion handler. |
Type Definitions
AdapterInfo
A placeholder object for the bluetooth adapter information.
Properties:
| Name | Type | Description |
|---|---|---|
address | String | The MAC address of the bluetooth adapter. |
alias | String | The alias name of the bluetooth adapter. |
discoverable | Boolean | true if the bluetooth adapter is discoverable, false otherwise. |
pairable | Boolean | true if the bluetooth adapter is pairable, false otherwise. |
powered | Boolean | true if the bluetooth adapter is on, false otherwise. |
scanning | Boolean | true if the bluetooth adapter is in scanning state, false otherwise. |
DeviceInfo
A placeholder object for the bluetooth device information.
Properties:
| Name | Type | Description |
|---|---|---|
address | String | The MAC address of the bluetooth device. |
alias | String | The alias name of the bluetooth device. |
connected | Boolean | true if the bluetooth device is connected, false otherwise. |
paired | Boolean | true if the bluetooth device is paired, false otherwise. |
trusted | Boolean | true if the bluetooth device is trusted, false otherwise. |
rssi | Number | The signal strength in dbm. Only avaliable if the STB's bluetooth adapter is in scanning state, else 0. |
battery | Number | The Battery level in %. Only for supported & connected devices. |
EventData
A placeholder object for bluetooth events.
Properties:
| Name | Type | Description |
|---|---|---|
event | module:Platform.Bluetooth.BluetoothEvent | The emitted event identifier. device. |
address | String | The MAC address of the device that is related to the emitted event. |
error | module:Platform.Bluetooth.PairError | An error that may accompany the event. Usually, this property is undefined, except the case where the emitted event is PAIR_FAILED. |