- Proposal: SDL-0280
- Author: Shohei Kawano, Kazuki Sugimoto, Akihiro Miyazaki (Nexty)
- Status: Accepted with Revisions
- Impacted Platforms: [ Core / iOS / Java Suite / JavaScript Suite / RPC / Protocol / HMI ]
In this proposal, by adding the requiresAudioSupport
in RegisterAppInterface
and the bluetooothDeviceAddress
in DeviceInfo
, when the device is connected via only USB, head unit (HU) will connect to the SDL device's Bluetooth (BT) automatically or prompt the user requesting BT connection.
Since Android recommends not supporting AOA2.0, Android will no longer be able to play audio using only USB, and it will be necessary to use BT A2DP to play audio.
In the current SDL Java Suite library, if requiresAudioSupport
is TRUE and BT A2DP is not connected, SDL activation will be cancelled. Users aren't notified why the SDL App doesn't start, so the UX needs to be improved.
To solve this problem, add bluetoothDeviceAddress
and requiresAudioSupport
so that a new SDL device can be specified in RegisterAppInterface
, and prompt the user to connect the device via BT, or the HU will connect the device via BT automatically when connected via USB.
The current SDL Java Suite library cancels the transport connection if the requiresAudioSupport
setting is TRUE and BT A2DP is not connected.
However, with this proposal, by adding a new parameter, the SDL app always establishes the transport connection and is registered without depending on the connection status of BT A2DP. If BT A2DP is not connected, the HU will automatically connect BT using bluetoothDeviceAddress
or request connection from the user.
Note: In the case of other platforms (such as iOS and JavaScript Suite), the system can output the audio via USB. Therefore, iOS and JavaScript Suite can omit the requiresAudioSupport
parameter.
In order for the app to be always registered, the changes in SDL session establishment to app registration flow are shown below. This flow is only for Android devices. If the SDL app or HU cannot use this function, it will perform the same operation as before.
-
The developer will set their
requiresAudioSupport
to true. -
The library will send a
StartService
for the RPC service with a new param in the payload,requiresAudioSupport
. -
Core will receive the
StartService
for the RPC service:- Core will check its current audio connects (BT A2DP), if it has a supported audio connect it will continue in flow.
- If there is no audio support, Core will check if it supports the auto connect BT feature. If it does, it will continue in flow.
- If there is no supported audio methods and Core does not support the auto connect BT feature, it will send a
StartServiceNAK
with the reasonNo audio support available
.
-
If Core has continued, it will send a
StartServiceACK
with a new paramautoBTCapability
set to true. -
The app receives the response to its
StartService
for the RPC service:- If the response was a
StartServiceNAK
the app will shut down. - If the response was a
StartServiceACK
,requiresAudioSupport
was set to true, but the protocol version of the ACK is less than the major version of this feature, the app will check if audio support is available using theMediaStreamingStatus
class. If it is available it will continue, if not it will shut down. - If the response was a
StartServiceACK
,requiresAudioSupport
was set to true, the protocol version of the ACK is equal to or greater than the major version of this feature, and theautoBTCapability
flag is set to false, the app will check if audio support is available using theMediaStreamingStatus
class. If it is available it will continue, if not it will shut down. - If the response was a
StartServiceACK
,requiresAudioSupport
was set to true, the protocol version of the ACK is equal to or greater than the major version of this feature, and theautoBTCapability
flag is set to true, the app will continue.
- If the response was a
-
The app will send its
RegisterAppInterface
which will include thehmiTypes
andisMediaApplication
flag. -
Core will receive the
RegisterAppInterface
:- If the
requiresAudioSupport
flag was not included in theStartService
,isMediaApplication
is set to true in theRegisterAppInterface
and the protocol version for the session is less than the major version of the version that included this feature, it will send aRegisterAppInterface
response withsuccess=false
and deny the app's registration. - If the
requiresAudioSupport
flag was not included in theStartService
,isMediaApplication
is set to true in theRegisterAppInterface
and the protocol version for the session is equal to or greater than the major version of the version that included this feature, it will send aRegisterAppInterface
response withsuccess=true
but not move forward with this proposal's feature. - If the
requiresAudioSupport
flag was set to true in theStartService
,isMediaApplication
is set to true in theRegisterAppInterface
and the protocol version for the session is equal to or greater than the major version of the version that included this feature, it will send aRegisterAppInterface
response withsuccess=true
and move forward with this proposal's feature.
- If the
The protocol version will need to be incremented for a major change. Using the current library apps will not register at all without audio support. So it is assumed in this flow the app will only be using a compatible library.
- StartService
requiresAudioSupport
is added to the payload of StartService
.
Similar to the default in the existing Java Suite library, requiresAudioSupport
is set to true for media apps and false for other types of apps. However, app developers can change these settings if needed.
Core considers requireAudioSupport
to be false if StartService
is the protocol version that does not support this function, or if it supports this function but requireAudioSupport
is not set.
- StartServiceACK
autoBTCapability
is added to the payload of StartServiceACK
.
Additionally, a new parameter autoBTConnection
, which indicates whether the HU has the BT automatic connection function, is added to HMICapabilities
. SDL Core sets autoBTCapability
to true if it has a supported audio connect or if it supports the auto connect BT feature.
The app considers autoBTCapability
to be false if StartServiceACK
is the protocol version that does not support this function, or if it supports this function but autoBTCapability
is not set.
HMI API:
<struct name="HMICapabilities">
<param name="navigation" type="Boolean" mandatory="false">
<description>Availability of build in Nav. True: Available, False: Not Available</description>
</param>
<param name="phoneCall" type="Boolean" mandatory="false">
<description>Availability of build in phone. True: Available, False: Not Available</description>
</param>
<param name="videoStreaming" type="Boolean" mandatory="false">
<description>Availability of built-in video streaming. True: Available, False: Not Available</description>
</param>
+ <param name="autoBTConnection" type="Boolean" mandatory="false">
+ <description>Indicates whether the HU has BT automatic connection function. True: Available, False: Not Available</description>
+ </param>
</struct>
- RegisterAppInterface
- OnAppRegistered
Add bluetoothDeviceAddress
toDeviceInfo
. Add requiresAudioSupport
toHMIApplication
. Add BluetoothInfo
toOnDeviceStateChanged
.
Mobile API:
<struct name="DeviceInfo" since="3.0">
<description>Various information about connecting device.</description>
<param name="hardware" type="String" minlength="0" maxlength="500" mandatory="false">
<description>Device model</description>
</param>
<param name="firmwareRev" type="String" minlength="0" maxlength="500" mandatory="false">
<description>Device firmware revision</description>
</param>
<param name="os" type="String" minlength="0" maxlength="500" mandatory="false">
<description>Device OS</description>
</param>
<param name="osVersion" type="String" minlength="0" maxlength="500" mandatory="false">
<description>Device OS version</description>
</param>
<param name="carrier" type="String" minlength="0" maxlength="500" mandatory="false">
<description>Device mobile carrier (if applicable)</description>
</param>
<param name="maxNumberRFCOMMPorts" type="Integer" minvalue="0" maxvalue="100" mandatory="false">
<description>Omitted if connected not via BT.</description>
</param>
+ <param name="bluetoothDeviceAddress" type="String" minlength="0" maxlength="500" mandatory="false">
+ <description>Device BT Address</description>
+ </param>
</struct>
HMI API:
<function name="OnDeviceStateChanged" messagetype="notification" scope="internal">
<param name="deviceState" type="Common.DeviceState" mandatory="true" />
<param name="deviceInternalId" type="String" mandatory="true" minlength="0" maxlength="500" />
<param name="deviceId" type="Common.DeviceInfo" mandatory="false"/>
+ <param name="bluetoothInfo" type="Common.BluetoothInfo" mandatory="false"/>
</function>
...
<struct name="DeviceInfo">
<param name="name" type="String" mandatory="true">
<description>The name of the device connected.</description>
</param>
<param name="id" type="String" mandatory="true">
<description>The ID of the device connectedi: either hash of device's USB serial number(in case of USB connection) or has of device's MAC address(in case of BlueTooth or WIFI connection</description>
</param>
<param name="transportType" type="Common.TransportType" mandatory="false">
<description>The transport type the named-app's-device is connected over HU(BlueTooth, USB or WiFi). It must be provided in OnAppRegistered and in UpdateDeviceList</description>
</param>
<param name="isSDLAllowed" type="Boolean" mandatory="false">
<description>Sent by SDL in UpdateDeviceList. 'true' - if device is allowed for PolicyTable Exchange; 'false' - if device is NOT allowed for PolicyTable Exchange </description>
</param>
+ <param name="bluetoothDeviceAddress" type="String" mandatory="false">
+ <description>Device BT Address</description>
+ </param>
</struct>
...
<struct name="HMIApplication">
...
<param name="deviceInfo" type="Common.DeviceInfo" mandatory="true">
<description>The ID, serial number, and transport type by which the named app's device is connected to HU.</description>
</param>
...
<param name="cloudConnectionStatus" type="Common.CloudConnectionStatus" mandatory="false"></param>
+ <param name="requiresAudioSupport" type="Boolean" mandatory="false">
+ <description>Set whether or not this app requires the use of an audio streaming output device.</description>
+ </param>
</struct>
...
+ <struct name="BluetoothInfo">
+ <param name="bluetoothDeviceAddress" type="String" mandatory="false">
+ <description>Device BT Address</description>
+ </param>
+ <param name="a2dpConnectionState" type="Boolean" mandatory="false">
+ <description>Notify the state of A2DP connection. 'true' - Connected at BT A2DP; 'false' - Connected at BT</description>
+ </param>
+ </struct>
...
<enum name="DeviceState">
<element name="UNKNOWN"/>
<element name="UNPAIRED"/>
+ <element name="PAIRED"/>
</enum>
If the Java Suite library supports the newer version of the protocol specification, but the IVI system is using a lower version, the app will still need to use the MediaStreamingStatus
class before attempting to register.
By using the value of isAudioOutputAvailable()
method, which is one of the methods of the MediaStreamingStatus
class that actually checks for multiple Audio Output options, the Java Suite library can make a decision whether BT A2DP is connected like below:
- True : BT A2DP is connected.
- False : BT A2DP is NOT connected.
With the changes of the flow, it is necessary to do refactoring of the Java Suite library to move the logic of the MediaStreamingStatus
class to the post-processing of StartService ACK or NAK.
By using this function, the HU is able to perform BT automatic connection based on the bluetoothDeviceAddress
which is notified when the app that requests audio (requiresAudioSupport
is set to true) is launched.
It can also display a message that prompts BT connection to the user.
Note: The HMI will be responsible for preventing app activation while the HMI is in the process of connecting to the mobile device's BT for an app that has requiresAudioSupport=true
. For example, the HMI could show a loading icon for that app, or display an error message to the user upon activation.
Due to the complexity of the flow, the developer must do the implementation carefully.
This proposal requires a major version change. Since new parameters are added, Core, iOS, Java Suite, JavaScript Suite, RPC, Protocol, and HMI are affected. Since there are not any public code changes listed in this proposal, the SDLC Project Maintainer will have discretion over implementation details, including changes to classes that are not accessible to developers, especially given changes to Java Suite library in 5.0 release.
While this alternative was considered, the Steering Committee determined this flow does not account for previous versions of the protocol, and therefore is not viable as the primary solution.
-
The developer will set their
requiresAudioSupport
to true. -
The library will send a
StartService
for the RPC service with a new param in the payload,requiresAudioSupport
. -
Core will receive the
StartService
for the RPC service:- If
requiresAudioSupport
was set to false or not set, it will continue in flow. - Core will check its current audio connects (BT A2DP), if it has a supported audio connect it will continue in flow.
- If there is no audio support, Core will check if it supports the auto connect BT function. If it does, it will continue in flow.
- If
requiresAudioSupport
is true and there is no supported audio methods and Core does not support the auto connect BT function, it will send aStartServiceNAK
with the reasonNo audio support available
.
- If
-
If it supports the auto connect BT function, a new param in the payload of
StartServiceACK
,autoBTCapability
is set to true, otherwise set to false. Then if Core has continued, it will send aStartServiceACK
. -
The app receives the response to its
StartService
for the RPC service:- If the response was a
StartServiceNAK
, the app will shut down. - If the response was a
StartServiceACK
, it will continue in flow. - If
requiresAudioSupport
was set to false or not set, it will continue in flow. - The library checks its current audio connects (BT A2DP), if it has a supported audio connect, it will continue in flow.
- If
autoBTCapability
was set to true, it will continue in flow. - If the response was a
StartServiceACK
andrequiresAudioSupport
was set to true andautoBTCapability
was set to false, the app will shut down.
- If the response was a
-
The app will send its
RegisterAppInterface
which will includerequiresAudioSupport
andbluetoothDeviceAddress
indeviceInfo
. -
When Core receives
RegisterAppInterface
, it sends response. Then it will sendOnAppRegistered
includingdeviceInfo
to HMI.
As demonstrated in the flow, the following conditions are required to use this function. If the SDL app or HU cannot use this function, it will perform the same operation as before.
conditions | details |
---|---|
The app/HMI must have the version that supports this function | App side: requiresAudioSupport of RegisterAppInterface must be set to true in order to use this function.HMI side: autoBTCapability of StartServiceACK must be set to true in order to use this function. |
App must request audio | In case of media app, requestAudioSupport is set to true as default. However, developers can set requiresAudioSupport to true regardless of default settings. |
HU must have BT automatic connection function | autoBTConnect of HMICapabilities must be set to true. |
Only the differences from the Proposed solution
section are shown below.
- StartServiceACK
Additionally, a new parameter
autoBTConnection
, which indicates whether the HU has the BT automatic connection function, is added toHMICapabilities
. SDL Core setsautoBTCapability
to true, ifautoBTConnection
is true.