Bluetooth Service

Created on June 21, 2022

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

streamingStatusChangednewStatus: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

getStatusSupportnonestatus: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.

startDeviceDiscoverytimeout:intstatus: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.

stopDeviceDiscoverynonenoneStops 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

setBluetoothEnabledenabled:Stringnone

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 

setSinkDiscoveryenabled:Stringnone

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

statusChangednewStatus: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

pinRequestpinValue:StringPIN 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.

 

Go To Top