Bluetooth Service
Summary
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.
Name: org.rdk.bluetoothSettings_3
This is updated version of Bluetooth API. It provides events to support Bluetooth auto-connect notification for the last connected bluetooth device, in which the connection can be Accepted or Rejected
based on user interest. This API is extension of existing org.rdk.bluetoothSettings_2 api.
Event:
Name | Payload | Description |
---|---|---|
deviceFound | HashMap {
deviceID:uint64 name:String deviceType:String lastConnectedState:bool } | 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 lastConnectedState – true or false. Only the last connected device has the true status.
|
deviceLost | HashMap {
deviceID:uint64 name:String deviceType:String lastConnectedState:bool } | 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 lastConnectedState – true or false. Only the last connected device has the true status. Status is true in this case. |
Name: org.rdk.bluetoothSettings_2
This is updated version of Bluetooth API. It provides methods to support Bluetooth-In feature, allowing external source device to play audio through set top box.
This API is extension of existing org.rdk.bluetoothSettings_1 api.
Methods:
Name | Parameters | Return Value | Description |
---|---|---|---|
getAudioInfo | deviceID:uint64
| HashMap { album: string trackNumber: uint32 genre: string duration: unit32 numberOfTracks:uint32 title: string artist: string } | 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 | deviceID:uint64 audioCtrlCmd:String | none | This method provides control over connected source. Request can have one of the following values: PLAY, PAUSE, STOP, SKIP_NEXT, RESTART, SKIP_PREVIOUS 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 | deviceID:uint64 eventType: string respValue: string | none | 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 |
Event
Name | Payload | Description |
---|---|---|
streamingStatusChanged | newStatus:String | Returns the status change for Bluetooth In streaming functionality. “PLAYBACK_STARTED” – playback was started “PLAYBACK_STOPPED” – remote source stopped playback “PLAYBACK_PAUSED” – remote source paused current playback “PLAYBACK_ENDED” – remote source stopped playback and requested disconnect. |
connectionRequest | HashMap { deviceID:uint64 name:String deviceType:String supportedProfle:String manufacturer:String MAC:String } | 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 supportedProfle – list of profiles that are supported by device manufacturer – device manufacturer MAC – device MAC ID |
playbackRequest | HashMap { deviceID:uint64 name:String deviceType:String supportedProfle:String manufacturer:String MAC:String } | 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 supportedProfle – list of profiles that are supported by device manufacturer – device manufacturer MAC – device MAC ID |
Name: org.rdk.bluetoothSettings_1
This is initial version of Bluetooth API. It provides methods to discover Bluetooth devices, retrieve list of paired and currently connected devices.
It also provides functions to initiate pairing and connecting.
Service Manager will send event in case external Bluetooth adapter is inserted or removed, when device connects or is disconnects, or if it requests to pair for input.
Existence of this API indicates that software support for Bluetooth in RDK stack exists.
Methods:
Name | Parameters | Return Value | Description |
---|---|---|---|
getStatusSupport | none | status:String | 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. |
startDeviceDiscovery | timeout:int | status:String | Initiates device discovery. Passes timeout in seconds. If call is made with timeout of 0 seconds, settop will immediately stop discovery. 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 | none | none | Stops Bluetooth device discovery immediately. |
getDiscoveredDevices | none | HashMap { deviceID:uint64 name:String deviceType:String connectedState:bool paired:bool } | 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) connectedState – true or false paired – true or false |
getPairedDevices | none | HashMap { deviceID:uint64 name:String deviceType:String connectedState:bool } | 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) connectedState – true or false |
getConnectedDevices | none | HashMap { deviceID:uint64 name:String deviceType:String activeState:enum } | 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. |
setDeviceConnection | deviceID:uint64 enable:String | none | 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 |
setAudioStream | deviceID:uint64 audionStreamName:String | none | 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 | deviceID:uint64 pair:boolean | none | Passes the device ID to pairt. Device ID is obtained by calling getDiscoveredDevices. pair: true – request to pair false – request to remove pairing |
setBluetoothEnabled | enabled:String | none | Application enables or disables Bluetooth feature. 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 |
setSinkDiscovery | enabled:String | none | 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. |
getDeviceInfo | deviceID:uint64 | HashMap { deviceID:uint64 name: String deviceType:String supportedProfle:String manufacturer:uint64 MAC:String rssi:int signalStrength:float } | 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 supportedProfle – list of profiles that are supported by device manufacturer – device manufacturer ID MAC – device MAC ID rssi– received signal strength indicator signalStrength – signal level in dBm received from connected device |
Events:
Name | Payload | Description |
---|---|---|
statusChanged | newStatus:String | Returns the status change for Bluetooth functionality. “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 should obtain updated list of paired devices by calling getPairedDevices. “CONNECTION_CHANGE” – one or more Bluetooth connections changed status. App should 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 callinggetDiscoveredDevices. |
pairingRequest | HashMap { deviceID:uint64 name:String deviceType:String supportedProfle:String manufacturer:String MAC:String pinRequired:String pinValue:String } | 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 supportedProfle – 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 | pinValue:String | PIN is required for pairing in progress. XRE needs to update pairing screen with PIN info. |
requestFailed | errorID:String MAC:String | Indicates that previous request to pair or connect failed. In absence of failure XRE would receive statusChanged when pairing or connecting succeeds. errorID – error identifier “PAIRING_FAILED”, “CONNECTING_FAILED”. MAC – MAC ID for failed request. |