FAQ

Bluetooth – ServiceManager

API
Published: March 26, 2020
Edited: March 26, 2020

org.rdk.bluetoothSettings_5

Description

This API provides methods and events to support Bluetooth discovery, pairing and connecting. It also provides method to select appropriate audio sink and to chose audio stream to be streamed to device.

Methods

getStatusSupport

Parameters:  none

Return Value:  status:String

Description:  Returns the current status of Bluetooth subsystem. Valid responses are:
"NO_BLUETOOTH_HARDWARE" - Bluetooth is supported in RDK software, but no Bluetooth hardware found.
"SOFTWARE_DISABLED" - Bluetooth is currently disabled in software. Bluetooth needs to be enabled by calling setBluetoothEnabled.
"AVAILABLE" - Bluetooth stack is initialized, not software disabled and hardware is running.

getBluetoothProperties

Parameters:  property:String

Return Value:  HashMap { name:String power:String }

Description:  This method called with specific property. Like name or power. limited to 2 property at this point; will be extended in future.
The input string cannot be empty. The response will be a HashMap with property as the key and the value as the value.
It returns Bluetooth Properties of the Box as follows.
name - Name of the Bluetooth Adapter of the Box that was configured/persisted
power - Current Power status; ie Power ON or Power OFF
The response will be only the requested; will not contain both name & power. ie If the name is requested,
HashMap {
name:String
}
If the power is requested,
HashMap {
power:String
}

setBluetoothProperties

Parameters:  HashMap { name:String power:String }

Return Value:  None

Description:  Sets the given property to the Bluetooth Adapter of the Box. Method will be called either with name or power but not both in one go.
If the name is requested,
HashMap {
name:String
}
If the power is requested,
HashMap {
power:String
}

setBluetoothEnabled

Parameters:  enabled:String

Return Value:  none

Description:  Application enables or disables Bluetooth feature. This will be obsolete. The setBluetoothProperties() must be used with power as input.
enabled:
"BLUETOOTH_DISABLED" - Software disabled
"BLUETOOTH_ENABLED" - Software enables settop as a source device
"BLUETOOTH_INPUT_ENABLED" - Software enables settop as a source and sink device

setBluetoothDiscoverable

Parameters:  enabled:String

Return Value:  none

Description:  This method enables settop discovery by other Bluetooth devices.
enabled:
"true" Settop broadcasts Bluetooth sink discovery signal
"false" Settop stops broadcasting Bluetooth sink discovery signal.

startDeviceDiscovery

Parameters:  timeout:int profile:String

Return Value:  status:String

Description:  Initiates discovery of devices of specific service support. If the 2nd parameter is empty, this new overloaded method should behave exactly same as calling bluetoothsettings_4 ::startDeviceDiscovery() only with timeout (ie the above function).
timeout: Discovery timeout in seconds; If call is made with timeout of 0 seconds, settop will immediately stop discovery.
profile: Comma separated profile as strings and this cannot be empty.
ex: For Audio-Out : {"LOUDSPEAKER", "HEADPHONES", "WEARABLE HEADSET", "HIFI AUDIO DEVICE"}
For Audio-In : {"SMARTPHONE", "TABLET"}
For HID : {"KEYBOARD", "MOUSE", "JOYSTICK"}
For HandsFree : {"HANDSFREE"}
For LE/Tile : {"LE", "LE TILE"}
For All The : {"DEFAULT"}
Call returns status:
"NO_BLUETOOTH_HARDWARE" - Bluetooth is supported in RDK software, but no Bluetooth hardware found
"AVAILABLE" - Bluetooth stack is initialized, not software disabled and hardware is running.

stopDeviceDiscovery

Parameters:  none

Return Value:  none

Description:  Stops Bluetooth device discovery immediately.

getDiscoveredDevices

Parameters:  none

Return Value:  HashMap { deviceID:uint64 name:String deviceType:String connected:bool paired:bool supportedProfiles:String }

Description:  Returns the list of discovered devices:
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
Example: MAC 6C:A0:17:B6:00:24 will be represented with 64 bit ID whose hex representation will look like 0 x 00 00 6C A0 17 B6 00 24
Example multiple Bluetooth speakers/headphones in the same room.
name - device name as specified by manufacturer
deviceType - device class (examples "headset", "speakers", etc)
connected - true or false
paired - true or false
supportedProfiles - list of profiles that are supported by device

getPairedDevices

Parameters:  none

Return Value:  HashMap { deviceID:uint64 name:String deviceType:String connected:bool supportedProfiles:String }

Description:  Returns list of all paired device:
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
name - device name as specified by manufacturer
deviceType - device class (examples "headset", "speakers", etc)
connected - true or false
supportedProfiles - list of profiles that are supported by device

getConnectedDevices

Parameters:  none

Return Value:  HashMap { deviceID:uint64 name:String deviceType:String activeState:enum connectedProfile :String }

Description:  Returns list of all connected devices. Multiple connections are supported.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
name - device name as specified by manufacturer
deviceType - device class (examples "headset", "speakers", etc)
activeState - for devices that support low power mode this parameter will indicate if device is in "STANDBY" mode ( value 0), "LOW_POWER" (1), or "ACTIVE" (2) mode.
connectedProfile : The profile that is used to connect to this device.

setDeviceConnection

Parameters:  deviceID:uint64 enable:String deviceType:String connectProfile:String

Return Value:  none

Description:  This method requests RDK to connect to Bluetooth device.
deviceIndex- Passes the MAC address of device to connect.
enable: "CONNECT" - request to connect "DISCONNECT" - request to end connection
deviceType - device class (examples "headset", "speakers", etc)
connectProfile - The profile to be used for connecting with external bluetooth device When the connectProfile string is empty, it should work as the previous version.. ie bluetoothsettings_4::setDeviceConnection().
The connectProfile could be either of the supportedProfiles that was reported.. For Audio-Out Profiles, it could be one of the following.
"LOUDSPEAKER" or "HEADPHONES" or "WEARABLE HEADSET" or "HIFI AUDIO DEVICE"..
The possible list of profiles for services are,
For Audio-Out : {"LOUDSPEAKER", "HEADPHONES", "WEARABLE HEADSET", "HIFI AUDIO DEVICE"}
For Audio-In : {"SMARTPHONE", "TABLET"}
For HID : {"KEYBOARD", "MOUSE", "JOYSTICK"}
For HandsFree : {"HANDSFREE"}
For LE/Tile : {"LE", "LE TILE"}
For All The : {"DEFAULT"}

setAudioStream

Parameters:  deviceID:uint64 audionStreamName:String

Return Value:  none

Description:  Passes the MAC address of device to connect.
Passes the parameter weather choose "PRIMARY" or "AUXILIARY" audio stream to be sent to audio sink.

setDevicePairing

Parameters:  deviceID:uint64 pair:boolean

Return Value:  none

Description:  Passes the device ID to pair. Device ID is obtained by calling getDiscoveredDevices.
pair: true - request to pair
false - request to remove pairing

getDeviceInfo

Parameters:  deviceID:uint64

Return Value:  HashMap { deviceID:uint64 name: String deviceType:String supportedProfile:String manufacturer:uint64 MAC:String rssi:int signalStrength:float }

Description:  device details device:
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
name - Device name as specified by manufacturer
deviceType - Device class
supportedProfile - list of profiles that are supported by device
manufacturer - device manufacturer ID
MAC - device MAC ID
rssi- received signal strength indicatorsignal
Strength - signal level in dBm received from connected device

getAudioInfo

Parameters:  deviceID:uint64

Return Value:  HashMap { album: string genre: string title: string artist: string ui32Duration: unit32 ui32TrackNumber: uint32 ui32NumberOfTracks:uint32 }

Description:  This method provides info on currently playing song/audio from external source. The returned info from Bluetooth-In device provides information that could be displayed on Tv screen.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes

setPlayback

Parameters:  deviceID:uint64 audioCtrlCmd:String

Return Value:  none

Description:  This method provides control over connected source. Request can have one of the following values:
PLAY, PAUSE, STOP, SKIP_NEXT, RESTART, SKIP_PREVIOUS, VOLUME_DOWN, VOLUME_UP & AUDIO_MUTE
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes
audioCtrlCmd - Audio control request to be set to the playback.

respondToEvent

Parameters:  deviceID:uint64 eventType: string respValue: string

Return Value:  none

Description:  Responds to a bluetooth event. For example, can respond to a pairing or connection event and indicate the proper response, such as is the connection request accepted.
Details is in object that defines the following keys:
eventType - CONNECTION, PAIRING, PLAYBACK
responseValue - ACCEPTED, REJECTED
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes

Events

statusChanged

Payload: newStatus:String
deviceID:uint64
name:String
deviceType:String

rawDeviceType:uint32
lastConnectedState:bool
paired:bool
connected:bool

Description: Returns the status change for Bluetooth functionality.
newStatus: The status.
"HARDWARE_AVAILABLE" - adapter inserted for external adapter, or onboard Bluetooth initialized and available
"HARDWARE_DISABLED" - adapter removed for external adapter, or onboard Bluetooth no longer available
"SOFTWARE_ENABLED" - Bluetooth functionality is enabled through software API
"SOFTWARE_INPUT_ENABLED" - Bluetooth input functionality is enabled through software API
"SOFTWARE_DISABLED" - Bluetooth functionality is disabled through software API
"PAIRING_CHANGE" - Pairing status changed. App will get the device which got paired/unpaired as part of this message. But its upto the App to obtain updated list of paired devices by calling getPairedDevices.
"CONNECTION_CHANGE" - one or more Bluetooth connections changed status. App will get the device which got connected/disconnected as part of this message. But its upto the App to obtain updated list of connected devices by calling getConnectedDevices.
"DISCOVERY_COMPLETED" - Bluetooth device discovery is completed, at least one device is available. Application should obtain updated list of discovered devices by calling getDiscoveredDevices. This information is newly added to bluetoothsettings_5 and future.. Old instances will send only the newStatus. This variable is associated with PAIRING_CHANGE & CONNECTION_CHANGE status events only. For other status events, it will be empty.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
name - device name as specified by manufacturer
deviceType - device class
rawDeviceType - Bluetooth device class hex code.
lastConnectedState - true or false. Only the last connected device has the true status.
paired - when the PAIRING_CHANGE status is sent, if it is paired, it will be sent as TRUE. If it is unpaired, it will be sent as false
connected - when the CONNECTION_CHANGE status is sent, if it is connected, it will be sent as TRUE. If it is disconnected, it will be sent as false

pairingRequest

Payload:HashMap {
deviceID:uint64
name:String
deviceType:String
supportedProfile:String
manufacturer:String
MAC:String
pinRequired:String
pinValue:String
}

Description: Pairing is requested by third party device that supports A2DP profile. Prerequisite is that settop is enabled as A2DP Sink device:
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
name - device name as specified by manufacturer
deviceType - device class
supportedProfile - list of profiles that are supported by device
manufacturer - device manufacturer
MAC - device MAC ID
pinRequired - Boolean "true" or "false". If true, XRE needs to display PIN on TV screen. Connecting device needs to enter PIN to complete pairing.
pinValue - PIN value

pinRequest

Payload: pinValue:String

Description:PIN is required for pairing in progress. XRE needs to update pairing screen with PIN info.

requestFailed

Payload:newStatus:String
deviceID:uint64
name:String
deviceType:String
rawDeviceType:uint32
lastConnectedState:bool
paired:bool
connected:bool

Description:Indicates that previous request to pair or connect failed. In absence of failure XRE would receive statusChanged when pairing or connecting succeeds.
newStatus - error identifier "PAIRING_FAILED", "CONNECTION_FAILED".
This information is newly added to bluetoothsettings_5 and future.. Old instances will send only the newStatus. This variable is associated with PAIRING_FAILED & CONNECTION_FAILED status events only. For other status events, it will be empty.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
name - device name as specified by manufacturer
deviceType - device class
rawDeviceType - Bluetooth device class hex code.
lastConnectedState - true or false. Only the last connected device has the true status.
paired - when the PAIRING_CHANGE status is sent, if it is paired, it will be sent as TRUE. If it is unpaired, it will be sent as false
connected - when the CONNECTION_CHANGE status is sent, if it is connected, it will be sent as TRUE. If it is disconnected, it will be sent as false

connectionRequest

Payload:HashMap {
deviceID:uint64
name:String
deviceType:String
supportedProfile:String
manufacturer:String
MAC:String
}

Description:A connection is requested by third party device that has already been paired to the set top box.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
name - device name as specified by manufacturer
deviceType - device class
supportedProfile - list of profiles that are supported by device
manufacturer - device manufacturer
MAC - device MAC ID

playbackRequest

Payload:HashMap {
deviceID:uint64
name:String
deviceType:String
supportedProfile:String
manufacturer:String
MAC:String
}

Description:A connection is requested by third party device that has already been paired to the set top box.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
name - device name as specified by manufacturer
deviceType - device class
supportedProfile - list of profiles that are supported by device
manufacturer - device manufacturer
MAC - device MAC ID

playbackStarted

Payload:HashMap { deviceID:uint64
position: uint32
Duration: uint32
}

Description:Will be emitted whenever the user plays a new track or when the Music player selects next track automatically from its playlist.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
position - Current track's position in milliseconds.
Duration - Current track's duration in milliseconds.

playbackPaused

Payload:HashMap {
deviceID:uint64
position: uint32
Duration: uint32
}

Description:Will be emitted whenever the user does a pause on the playback.
position - Current track's position in milliseconds.
Duration - Current track's duration in milliseconds.

playbackResumed

Payload:HashMap {
deviceID:uint64
position: uint32
Duration: uint32
}

Description:Will be emitted whenever the user does a resume on the playback.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
position - Current track's position in milliseconds.
Duration - Current track's duration in milliseconds.

playbackStopped

Payload:HashMap {
deviceID:uint64
position: uint32
Duration: uint32
}

Description:Will be emitted whenever the user does a stop on the playback.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
position - Current track's position in milliseconds.
Duration - Current track's duration in milliseconds.

playbackPosition

Payload:HashMap {
deviceID:uint64
position: uint32
Duration: uint32
}

Description:Will be emitted with one second interval as long as the status of the playback is playing.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
position - Current track's position in milliseconds.
Duration - Current track's duration in milliseconds.

playbackNewTrack

Payload:HashMap {
deviceID:uint64
album: string
genre: string
title: string
artist: string
ui32Duration: unit32
ui32TrackNumber: uint32
ui32NumberOfTracks:uint32
}

Description:Will be emitted whenever the user plays a new track or when the Music player selects next track automatically from its playlist.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.

playbackEnded

Payload:HashMap {
deviceID:uint64
}

Description:Will be emitted whenever the user exits the music app.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.

deviceFound

Payload:HashMap {
deviceID:uint64
name:String
deviceType:String
rawDeviceType:number
lastConnectedState:bool
}

Description:One or more of third party devices, that have already been paired to the set top box, will send this event when they come inside the set top box range or gets powered Up within the range.
Separate notification is sent for each device that comes up, provided the device is already paired with the set top box.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
name - device name as specified by manufacturer
deviceType - device class
rawDeviceType : Bluetooth device class hex code
lastConnectedState - true or false. Only the last connected device has the true status.

deviceLost

Payload:HashMap {
deviceID:uint64
name:String
deviceType:String
rawDeviceType:number
lastConnectedState:bool
}

Description:A third party device that is currently connected to the set top was lost(poweredOff) or went out of range. Separate notification is sent for the lost device
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
name - device name as specified by manufacturer
deviceType - device class
rawDeviceType : Bluetooth device class hex code
lastConnectedState - true or false. Only the last connected device has the true status. Status is true in this case.

onDiscoveredDevice

Payload:HashMap {
deviceID:uint64
discoveryType:String
name:String
deviceType:String
rawDeviceType:uint32
lastConnectedState:bool
paired:bool
}

Description:Fired during device discovery when a new device is discovered or a discovered device has been lost in real time.
deviceID - ID derived from Bluetooth MAC address. 6 byte MAC value is packed into 8 byte with leading zeros for first 2 bytes.
discoveryType - "DISCOVERED" or "LOST"
name - device name as specified by manufacturer
deviceType - device class
rawDeviceType: Bluetooth device class hex code
lastConnectedState - true or false.
paired - has this device been previously paired

PHP Code Snippets Powered By : XYZScripts.com