To gain access to the JCenter repository, make sure your app's build.gradle file includes the following:

Transcription

1 Guides Android Documentation Document current as of 06/28/ :37 PM. Installation Introduction Each SDL Android library release is published to JCenter. By adding a few lines in their app's gradle script, developers can compile with the latest SDL Android release. To gain access to the JCenter repository, make sure your app's build.gradle file includes the following: repositories { jcenter() Gradle Build To compile with the a release of SDL Android, include the following line in your app's build.gradle file,

2 dependencies { implementation 'com.smartdevicelink:sdl_android:{version' and replace {version with the desired release version in format of x.x.x. The list of releases can be found here. Examples To compile release 4.6.0, use the following line: dependencies { implementation 'com.smartdevicelink:sdl_android:4.6.0' To compile the latest minor release of major version 4, use: dependencies { implementation 'com.smartdevicelink:sdl_android:4.+'

3 Integration Basics Getting Started on Android In this guide, we exclusively use Android Studio. We are going to set-up a barebones application so you get started using SDL. O T E The SDL Mobile library for supports Android 2.2.x (API Level 8) or higher. Required System Permissions In the AndroidManifest for our sample project we need to ensure we have the following system permissions: Internet - Used by the mobile library to communicate with a SDL Server Bluetooth - Primary transport for SDL communication between the device and the vehicle's head-unit Access etwork State - Required to check if WiFi is enabled on the device

4 <manifest xmlns:android=" android" package="com.company.mysdlapplication">... <uses-permission android:name="android.permission.iteret" /> <uses-permission android:name="android.permission.bluetooth"/ > <uses-permission android:name= "android.permission.access_etwork_state" />... </manifest> k Service A k Android Service should be created to manage the lifecycle of an SDL Proxy. The SDL Service enables auto-start by creating the SDL Proxy, which then waits for a connection from SDL. This file also sends and receives messages to and from SDL after connected. Create a new service and name it appropriately, for this guide we are going to call it SdlService. This service must implement the IProxyListenerALM interface: public class SdlService extends Service implements IProxyListenerALM { // Inherited methods from IProxyListenerALM

5 The IProxyListenerALM interface has most of the callbacks you will receive during the SDL proxy's lifecycle. This includes callbacks for RPC responses. If you created the service using the Android Studio template then the service should have been added to your AndroidManifest.xml otherwise the service needs to be defined in the manifest: <manifest xmlns:android=" android" package="com.company.mysdlapplication"> <application>... <service android:name=".sdlservice" android:enabled="true"/> </application>... </manifest> Entering the Foreground Because of Android Oreo's requirements, it is mandatory that services enter the foreground for long running tasks. The first bit of integration is ensuring that happens in the oncreate method of the SdlService or similar. Within the service that implements the SDL lifecycle you will need to add a call to start the service in the foreground. This will include creating a notification to sit in the status bar tray. This information and icons should be relevant for what the service is doing/going to do. If you already start your service in the foreground, you can ignore this section.

6 public void oncreate() { super.oncreate();... if(build.versio.sdk_it >= Build.VERSIO_CODES.O) { otificationmanager notificationmanager = (otificationmanager) getsystemservice(context.otificatio_service); notificationmanager.createotificationchannel(...); otification serviceotification = new otification.builder(this, * otification Channel*).setContentTitle(...).setSmallIcon(...).setLargeIcon(...).setContentText(...).setChannelId(channel.getId()).build(); startforeground(id, serviceotification); O T E The sample code checks if the OS is of Android Oreo or newer to start a foreground service. It is up to the app developer if they wish to start the notification in previous versions. Exiting the Foreground It's important that you don't leave you notification in the notification tray as it is very confusing to users. So in the ondestroy method in your service, simply call the stopforeground method.

7 @Override public void ondestroy(){ //... if(build.versio.sdk_it>=build.versio_codes.o){ otificationmanager notificationmanager = (otificationmanager) getsystemservice(context.otificatio_service); if(notificationmanager!=null){ //If this is the only notification on your channel notificationmanager.deleteotificationchannel(* otification Channel*); stopforeground(true); Implementing SDL Proxy Lifecycle In order to correctly use a proxy developers need to implement methods for the proper creation and disposing of an SDL Proxy in our SDLService. O T E An instance of SdlProxy cannot be reused after it is closed and properly disposed of. Instead, a new instance must be created. Only one instance of SdlProxy should be in use at any given time.

8 public class SdlService extends Service implements IProxyListenerALM { //The proxy handles communication between the application and SDL private SdlProxyALM proxy = null; public int onstartcommand(intent intent, int flags, int startid) { boolean forceconnect = intent!=null && intent.getbooleanextra( TransportConstants.FORCE_TRASPORT_COECTED, false); if (proxy == null) { try { //Create a new proxy using Bluetooth transport //The listener, app name, //whether or not it is a media app and the applicationid are supplied. proxy = new SdlProxyALM(this.getBaseContext(),this, "Hello SDL App", true, " "); catch (SdlException e) { //There was an error creating the proxy if (proxy == null) { //Stop the SdlService stopself(); else if(forceconnect){ proxy.forceonconnected(); //use START_STICKY because we want the SDLService to be explicitly started and stopped as needed. return public void ondestroy() { //Dispose of the proxy if (proxy!= null) { try { proxy.dispose(); catch (SdlException e) { e.printstacktrace(); finally { proxy = null;

9 public void onproxyclosed(string info, Exception e, SdlDisconnectedReason reason) { //Stop the service stopself(); //... onproxyclosed() is called whenever the proxy detects some disconnect in the connection, whether initiated by the app, by SDL, or by the device s bluetooth connection. As long as the exception does not equal Sdl_PROXY_CYCLED or BLUETOOTH_DISABLED, the proxy would be reset for the exception SDL_PROXY_DISPOSED. O T E We must properly dispose of our proxy in the ondestroy() method because SDL will issue an error that it lost connection with the app if the connection fails before calling proxy.dispose(). Implementing IProxyListenerALM Methods OOHMISTATUS() In our SdlService, the ononhmistatus() method is where you should control your application with SDL various HMI Statuses. When you receive the first

10 HMI_FULL, you should initialize your app on SDL by subscribing to buttons, registering addcommands, sending an initial show or speak command, public void ononhmistatus(onhmistatus notification) { switch(notification.gethmilevel()) { case HMI_FULL: //send welcome message, addcommands, subscribe to buttons ect break; case HMI_LIMITED: break; case HMI_BACKGROUD: break; case HMI_OE: break; default: return; k Router Service The SdlRouterService will listen for a bluetooth connection with an SDL enabled module. When a connection happens, it will alert all SDL enabled apps that a connection has been established and they should start their SDL services. We must implement a local copy of the SdlRouterService into our project. The class doesn't need any modification, it's just important that we include it. We will extend the com.smartdevicelink.transport.sdlrouterservice in our class named SdlRouterService :

11 O T E Do not include an import for com.smartdevicelink.transport.sdlrou terservice. Otherwise, we will get an error for 'SdlRouterService' is already defined in this compilation unit. public class SdlRouterService extends com.smartdevicelink.transport. SdlRouterService { //othing to do here M U S T The local extension of the com.smartdevicelink.transport.sdlrouter Service must be named SdlRouterService. M U S T Make sure this local class (SdlRouterService.java) is in the same package of SdlReceiver.java (described below) If you created the service using the Android Studio template then the service should have been added to your AndroidManifest.xml otherwise the service

12 needs to be added in the manifest. Because we want our service to be seen by other SDL enabled apps, we need to set android:exported="true". The system may issue a lint warning because of this, so we can suppress that using tools:i gnore="exportedservice". Once added, it should be defined like below: <manifest xmlns:android=" android" package="com.company.mysdlapplication"> <application>... <service android:name= "com.company.mysdlapplication.sdlrouterservice" android:exported="true" android:process="com.smartdevicelink.router" tools:ignore="exportedservice"> <intent-filter> <action android:name="com.smartdevicelink.router.service"/ > </intent-filter> <meta-data android:name="@string/ sdl_router_service_version_name" android:value="@integer/ sdl_router_service_version_value" /> </service> </application>... </manifest> M U S T The SdlRouterService must be placed in a separate process with the name com.smartdevicelink.router. If it is not in that process during it's start up it will stop itself.

13 O T E Setting android:name sdl_router_service_version_name for the router service metadata may cause issues with some app packaging and analyzing tools like aapt. You can avoid that by hardcoding the string value instead of using a string reference. <meta-data android:name="sdl_router_version" android:value= "@integer/sdl_router_service_version_value" /> Intent Filter <intent-filter> <action android:name="com.smartdevicelink.router.service"/> </intent-filter> The new versions of the SDL Android library rely on the com.smartdevicelink.ro uter.service action to query SDL enabled apps that host router services. This allows the library to determine which router service to start. M U S T This intent-filter MUST be included.

14 Metadata ROUTER SERVICE VERSIO <meta-data /> Adding the sdl_router_service_version metadata allows the library to know the version of the router service that the app is using. This makes it simpler for the library to choose the newest router service when multiple router services are available. CUSTOM ROUTER SERVICE <meta-data sdl_router_service_is_custom_name" android:value="false" /> O T E This is only for specific OEM applications, therefore normal developers do not need to worry about this.

15 Some OEMs choose to implement custom router services. Setting the sdl_route r_service_is_custom_name metadata value to true means that the app is using something custom over the default router service that is included in the SDL Android library. Do not include this meta-data entry unless you know what you are doing. k Broadcast Receiver The Android implementation of the SdlProxy relies heavily on the OS's bluetooth intents. When the phone is connected to SDL, the app needs to create a SdlProxy, which publishes an SDP record for SDL to connect to. As mentioned previously, a SdlProxy cannot be re-used. When a disconnect between the app and SDL occurs, the current proxy must be disposed of and a new one created. The SDL Android library has a custom broadcast receiver named SdlBroadcast Receiver that should be used as the base for your BroadcastReceiver. It is a child class of Android's BroadcastReceiver so all normal flow and attributes will be available. Two abstract methods will be automatically populate the class, we will fill them out soon. Create a new SdlBroadcastReceiver and name it appropriately, for this guide we are going to call it SdlReceiver : public class SdlReceiver extends SdlBroadcastReceiver public void onsdlenabled(context context, Intent intent) { public Class<? extends SdlRouterService> definelocalsdlrouterclass () { //...

16 M U S T SdlBroadcastReceiver must call super if onreceive is public void onreceive(context context, Intent intent) { super.onreceive(context, intent); //your code here If you created the BroadcastReceiver using the Android Studio template then the service should have been added to your AndroidManifest.xml otherwise the receiver needs to be defined in the manifest. Regardless, the manifest needs to be edited so that the SdlBroadcastReceiver needs to respond to the following intents: android.bluetooth.device.action.acl_coected sdl.router.startservice

17 <manifest xmlns:android=" android" package="com.company.mysdlapplication"> <application>... <receiver android:name=".sdlreceiver" android:exported="true" android:enabled="true"> <intent-filter> <action android:name= "android.bluetooth.device.action.acl_coected" /> <action android:name="sdl.router.startservice" /> </intent-filter>... </receiver> </application> </manifest> O T E The intent sdl.router.startservice is a custom intent that will come from the SdlRouterService to tell us that we have just connected to an SDL enabled piece of hardware.

18 M U S T SdlBroadcastReceiver has to be exported, or it will not work correctly ext, we want to make sure we supply our instance of the SdlBroadcastService with our local copy of the SdlRouterService. We do this by simply returning the class object in the method definelocalsdlrouterclass: public class SdlReceiver extends SdlBroadcastReceiver public void onsdlenabled(context context, Intent intent) { public Class<? extends SdlRouterService> definelocalsdlrouterclass () { //Return a local copy of the SdlRouterService located in your project return com.company.mysdlapplication.sdlrouterservice.class; We want to start the SDL Proxy when an SDL connection is made via the SdlRo uterservice. We do this by taking action in the onsdlenabled method: M U S T Apps must start their service in the foreground as of Android Oreo (API 26).

19 public class SdlReceiver extends SdlBroadcastReceiver public void onsdlenabled(context context, Intent intent) { //Use the provided intent but set the class to the SdlService intent.setclass(context, SdlService.class); if(build.versio.sdk_it < Build.VERSIO_CODES.O) { context.startservice(intent); else{ public Class<? extends SdlRouterService> definelocalsdlrouterclass () { //Return a local copy of the SdlRouterService located in your project return com.company.mysdlapplication.sdlrouterservice.class; O T E The onsdlenabled method will be the main start point for our SDL connection session. We define exactly what we want to happen when we find out we are connected to SDL enabled hardware. Main Activity ow that the basic connection infrastructure is in place, we should add methods to start the SdlService when our application starts. In oncreate() in your main activity, you need to call a method that will check to see if there is currently an SDL connection made. If there is one, the onsdlenabled method

20 will be called and we will follow the flow we already set up. In our MainActivity.j ava we need to check for an SDL connection: public class MainActivity extends Activity protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.activity_main); //If we are connected to a module we want to start our SdlService SdlReceiver.queryForConnectedService(this); Using Android Open Accessory Protocol Incorporating AOA into an SDL-enabled app allows it to communicate to a module over USB. This guide will assume the SDL library is already integrated into the app. This guide also requires you to have implement a local SdlBroadc astreceiver as outlined in the Bluetooth Multiplexing documentation. Prerequisites: SdlReceiver We will add or make changes to: Android Manifest (of your app) Accessory Filter (new)

21 SdlService Prerequisites If you have already implemented the Multiplexing guidelines in your project, feel free to skip this section. SdlReceiver Create your own SdlReceiver that extends SdlBroadcastReceiver and implement the following: public class SdlReceiver extends com.smartdevicelink. SdlBroadcastReceiver public void onsdlenabled(context context, Intent intent) { //Use the provided intent but set the class to your SdlService intent.setclass(context, SdlService.class); public Class<? extends SdlRouterService> definelocalsdlrouterclass () { return null; //Since we use AOA, we will not be using public void onreceive(context context, Intent intent){ super.onreceive(context, intent); //Your code and add the Receiver to your app's Android Manifest with the following intent filters:

22 <receiver android:name="com.company.mysdlapplication.sdlreceiver" android:exported="true" android:enabled="true" > <intent-filter> <action android:name="sdl.router.startservice" /> </intent-filter> </receiver> Android Manifest To use the AOA protocol, you must specify so in your app's Manifest with: <uses-feature android:name="android.hardware.usb.accessory"/> M U S T This feature will not work without including this line! The SDL Android library houses a USBAccessoryAttachmentActivity that you need to add between your Manifest's <application> </application> tags:

23 <activity android:name= "com.smartdevicelink.transport.usbaccessoryattachmentactivity" android:launchmode="singletop"> <intent-filter> <action android:name= "android.hardware.usb.action.usb_accessory_attached" /> </intent-filter> <meta-data android:name= "android.hardware.usb.action.usb_accessory_attached" /> </activity> For AOA, your project's local SdlReceiver needs an intent filter for com.smartde vicelink.usb_accessory_attached. <receiver android:name="com.company.mysdlapplication.sdlreceiver" android:exported="true" android:enabled="true" > <intent-filter> <action android:name= "com.smartdevicelink.usb_accessory_attached"/> <!--For AOA --> <action android:name="sdl.router.startservice" /> </intent-filter> </receiver> Accessory Filter (ew) For security purposes, an accessory filter will limit accessory connections to those included in the filter. Add the directory /res/xml to your project and create a new XML file accessory_filter.xml inside of it. Add in the following to accessory_filter.xml :

24 <?xml version="1.0" encoding="utf-8"?> <resource> <usb-accessory manufacturer="sdl" model="core" version="1.0"/> </resource> k Service When using AOA, the USB Transport instantiation is dependent on an accessory device actually being connected. The following changes need to be made in the onstartcommand() function of your SdlService. AOA is only supported on devices with API level 12 or higher. You can check for this with: if(android.os.build.versio.sdk_it > android.os.build. VERSIO_CODES.HOEYCOMB){ // create USB transport else{ Log.e("SdlService", "Unable to start proxy. Android OS version is too low"); // optional O T E It's recommended to either check for an API level 12 or higher here or specify an API level 12 or higher in your app's Manifest.

25 You also need to check that the intent that started your service has an Extra equal to UsbManager.EXTRA_ACCESSORY : if(android.os.build.versio.sdk_it > android.os.build. VERSIO_CODES.HOEYCOMB){ if(intent!=null && intent.hasextra(usbmanager.extra_accessory)) { // create USB transport else{ Log.e("SdlService", "Unable to start proxy. Android OS version is too low"); // optional Finally, we can create a new USBTransport with: transport = new USBTransportConfig(getBaseContext(), (UsbAccessory) intent.getparcelableextra(usbmanager.extra_accessory), false, false ); And our final result is:

26 public int onstartcommand(intent intent, int flags, int startid) { boolean forceconnect = intent!=null && intent.getbooleanextra( TransportConstants.FORCE_TRASPORT_COECTED, false); if (proxy == null) { try { BaseTransportConfig transport = null; if(android.os.build.versio.sdk_it > android.os.build. VERSIO_CODES.HOEYCOMB){ if(intent!=null && intent.hasextra(usbmanager. EXTRA_ACCESSORY)) { transport = new USBTransportConfig(getBaseContext(), (UsbAccessory) intent.getparcelableextra(usbmanager. EXTRA_ACCESSORY), false, false); // create USB transport else{ Log.e("SdlService", "Unable to start proxy. Android OS version is too low"); // optional if(transport!= null){ proxy = new SdlProxyALM(this, APP_AME, true, APP_ID, transport); catch (SdlException e) { //There was an error creating the proxy if (proxy == null) { //Stop the SdlService stopself(); else if(forceconnect){ proxy.forceonconnected(); //use START_STICKY because we want the SDLService to be explicitly started and stopped as needed. return START_STICKY;

27 Sending Multiple RPCs Batch Sending RPCs There are two ways to send multiple requests to the head unit: concurrently and sequentially. Which method you should use depends on the type of RPCs being sent. Concurrently sent requests might finish in a random order and should only be used when none of the requests in the group depend on the response of another, such as when uploading a group of artworks. Sequentially sent requests only send the next request in the group when a response has been received for the previously sent RPC. Requests should be sent sequentially when you need to know the result of a previous request before sending the next, like when sending the several different requests needed to create a menu. Both methods have optional listeners that are specific to them, the OnMultiple RequestListener. This listener will provide additional information than the normal OnRPCResponseListener. Its use is shown below. Send Requests sendrequests allows you to easily send an ArrayList of RPCRequests easily to the head unit. When you send multiple RPCs concurrently there is no guarantee of the order in which the RPCs will be sent or in which order Core will return responses. The method also comes with its own listener, OnMultipleReq uestlistener that will provide you with updates as the sending progresses, errors that may arise, and let you know when the sending is finished. Below is a sample call:

28 List<RPCRequest> rpcs = new ArrayList<>(); // rpc 1 Show show = new Show(); show.setmainfield1("hey friends"); show.setmainfield2(""); show.setmainfield3(""); show.setmainfield4(""); rpcs.add(show); // rpc 2 Image image = new Image(); image.setimagetype(imagetype.dyamic); image.setvalue("appimage.jpeg"); // a previously uploaded filename using PutFile RPC Show show2 = new Show(); show2.setgraphic(image); rpcs.add(show2); try { proxy.sendrequests(rpcs, new OnMultipleRequestListener() public void onupdate(int remainingrequests) public void onfinished() public void onresponse(int correlationid, RPCResponse response) public void onerror(int correlationid, RPCResponse response) { ); catch (SdlException e) { e.printstacktrace();

29 Send Sequential Requests As you may have guessed, this method is called similarly to sendrequests but sends the requests synchronously, guaranteeing order. It is important to note that you want to build your array with the items that you want to send first, first. This is particularly useful for RPCs that are dependent upon other ones, such as a performinteraction needing a createinteractionchoiceset 's id. This method call is exactly the same as above, except for the method name being sendsequentialrequests. For your convinience, the listener is also the same and performs similarly.

30 List<RPCRequest> rpcs = new ArrayList<>(); // rpc 1 Show show = new Show(); show.setmainfield1("hey friends"); show.setmainfield2(""); show.setmainfield3(""); show.setmainfield4(""); rpcs.add(show); // rpc 2 Image image = new Image(); image.setimagetype(imagetype.dyamic); image.setvalue("appimage.jpeg"); // a previously uploaded filename using PutFile RPC Show show2 = new Show(); show2.setgraphic(image); rpcs.add(show2); try { proxy.sendsequentialrequests(rpcs, new OnMultipleRequestListener() public void onupdate(int remainingrequests) public void onfinished() public void onresponse(int correlationid, RPCResponse response) { info) public void onerror(int correlationid, Result resultcode, String ); catch (SdlException e) { e.printstacktrace();

31 Hello SDL Android Introduction In this guide we take you through the steps to get our sample project, Hello Sdl Android, running and connected to Sdl Core as well as showing up on the generic HMI. First, make sure you download or clone the latest release from GitHub. Open the project in Android Studio. We will exclusively use Android Studio as it is the current supported platform for Android development. O T E The SDL Android Library is set up to use sdl_android with Gradle. When you clone the repository, perform a Gradle sync. Getting Started If you are not using a Ford TDK for development, we will assume that you have SDL Core (We recommend Ubuntu 16.04) and an HMI set up prior to this point. Most people getting started with this tutorial will not have a Ford TDK, so sample outputs will be using Sdl Core and our Generic HMI. If you don't want to set up a virtual machine for testing, we offer Manticore, which is a free service that allows you to test your apps via TCP/IP in the cloud.

32 O T E Sdl Core and an HMI or Manticore are needed to run Hello Sdl Android and to ensure that it connects BUILD FL AVORS Hello Sdl Android has been built with different build flavors. To access the Build Variant menu to choose your flavor, click on the menu Buil d then Select Build Variant. A small window will appear on the bottom left of your IDE window that allows you to choose a flavor. There are many flavors to choose from and for now we will only be concerned with the debug versions. Versions Include: lbt - Legacy Bluetooth mbt - Multiplexing Bluetooth tcp - Transmission Control Protocol usb - Universal Serial Bus We will mainly be dealing with mbt (if using a TDK) or tcp (if connecting to SDL Core via a virtual machine or your localhost)

33 Transports COFIGURE FOR TCP If you aren't using a TDK or head unit, you can connect to SDL core via a virtual machine or to your localhost. To do this we will use the flavor tcpdebug. For TCP to work, you will have to know the IP address of your machine that is running Sdl Core. If you don't know what it is, running ifconfig in a linux terminal will usually let you see it for the interface you are connected with to your network. We have to modify the IP address in Hello Sdl Android to let it know where your instance of Sdl Core is running. In the main Java folder of Hello Sdl Android, open up SdlService.java In the top of this file, locate the variable declaration for DEV_MACHIE_IP_ADD RESS. Change it to your Sdl Core's IP. Leave the TCP_PORT set to // TCP/IP transport config private static final int TCP_PORT = 12345; private static final String DEV_MACHIE_IP_ADDRESS = " "; // change to your IP O T E if you do not change the target IP address, the application will not connect to Sdl Core or show up on the HMI

34 COFIGURE FOR BLUETOOTH Right out of the box, all you need to do to run bluetooth is to select the mbt_of fdebug (Multiplexing Bluetooth) build flavor. COFIGURE FOR USB (AOA) To connect to an SDL Core instance or TDK via USB transport, select the usbde bug build flavor. There is more information for USB transport under Getting Started - Using AOA Protocol. Building the Project For TCP, you may use the built-in Android emulator or an Android phone on the same network as Sdl Core. For Bluetooth, you will need an Android phone that is paired to a TDK or head unit via Bluetooth. M U S T Make sure Sdl Core and the HMI are running prior to running Hello Sdl Android Run the project in Android Studio, targeting the device you want Hello Sdl Android installed on. Hello Sdl Android should compile and launch on your device of choosing:

35 Following this, you should see an application appear on the TDK or HMI. In the case of the Generic HMI (using TCP), you will see the following: Click on the Hello Sdl icon in the HMI.

36 This is the main screen of the Hello Sdl App. If you get to this point, the project is working. On the device you are running the app on, a lock screen should now appear once the app is opened on the HMI:

37 O T E Lock Screens are an important part of Sdl enabled applications. The goal is to keep the driver's eyes forward and off of the device At this point Hello Sdl Android has been compiled and is running properly! Continue reading through our guides to learn about all of the RPCs (Remote Procedure Calls) that can be made with the library. Troubleshooting Sometimes things don't always go as planned, and so this section exists. If your app compiles and does OT show up on the HMI, there are a few things to check out. TCP 1. Make sure that you have changed the IP in SdlService.java to match the machine running Sdl Core. Being on the same network is also important. 2. If you are sure that the IP is correct and it is still not showing up, make sure the Build Flavor that is running is tcpdebug. 3. If the two above dont work, make sure there is no firewall blocking the incoming port on the machine or VM running SDL Core. In the same breath, make sure your firewall allows that outgoing port.

38 4. There are different network configurations needed for different virtualization software (virtualbox, vmware, etc). Make sure yours is set up correctly. Or use Manticore. BLUETOOTH 1. Make sure the build flavor mbt_offdebug is selected. 2. Ensure your phone is properly paired with the TDK 3. Make sure Bluetooth is turned on - on Both the TDK and your phone 4. Make sure apps are enabled on the TDK (in settings) Adding the Lock Screen In order for your SDL application to be certified with most OEMs you will be required to implement a lock screen on the mobile device. The lock screen will disable user interactions with the application while they are using the head-unit to control application functionality. The URL for the lock screen image to display is send by the head-unit. O T E This guide assumes that you have an SDL Service implemented as defined in the Getting Started guide. Lock Screen Activity First, we need to create a new activity that will host our lock screen. In the activity we add a simple BroadcastReceiver that listens for CLOSE_LOCK_SCRE

39 E_ACTIO intents. In the broadcast receiver we will then call finish() in order to shutdown the activity. We also check for a Bitmap extra, LOCKSCREE_BITM AP_EXTRA, in the intent that started the activity: public class LockScreenActivity extends Activity { public static final String LOCKSCREE_BITMAP_EXTRA = "LOCKSCREE_BITMAP_EXTRA"; public static final String CLOSE_LOCK_SCREE_ACTIO = "CLOSE_LOCK_SCREE"; private final BroadcastReceiver closelockscreenbroadcastreceiver = new BroadcastReceiver() public void onreceive(context context, Intent intent) { finish(); protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); registerreceiver(closelockscreenbroadcastreceiver, new IntentFilter(CLOSE_LOCK_SCREE_ACTIO)); setcontentview(r.layout.activity_lock_screen); Intent intent = getintent(); ImageView imageview = (ImageView) findviewbyid(r.id. lockscreen); if(intent.hasextra(lockscree_bitmap_extra)){ Bitmap lockscreen = (Bitmap) intent.getparcelableextra( LOCKSCREE_BITMAP_EXTRA); if(lockscreen!= null){ protected void ondestroy() { unregisterreceiver(closelockscreenbroadcastreceiver); super.ondestroy();

40 When the activity is created it will generate a layout file to use. We updated this layout to display a default sample image from res/drawable in the middle of the screen: <?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android=" android" android:orientation="vertical" android:layout_width="match_parent" android:layout_height="match_parent" android:gravity="center"> <ImageView android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_gravity="center" android:src="@drawable/sample_lock" <!-- Replace with your own default image --> android:id="@+id/lockscreen"/> </LinearLayout> In our AndroidManifest we need to define the style and launch mode for our lock screen activity. The theme is set Theme.Black.oTitleBar.Fullscreen and the launch mode is set to singleinstance:

41 <?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android=" android" package="com.livio.hellosdl"> <application android:allowbackup="true" android:supportsrtl="true" <activity android:name=".lockscreenactivity" Theme.Black.oTitleBar.Fullscreen" android:launchmode="singleinstance"/> </application> </manifest> Updating SDL Service To fully implement a lock screen, you'll want to add a LockScreenManager as a member of your Service. public class SdlService extends Service implements IProxyListenerALM{ //... private LockScreenManager lockscreenmanager = new LockScreenManager(); //...

42 The LockScreenManager can download and hold a lock screen Bitmap given a URL and a class that implements its callbacks. You can create a class similar to this: private class LockScreenDownloadedListener implements public void onlockscreenicondownloaded(bitmap icon) { Log.i(TAG, "Lock screen icon downloaded public void onlockscreenicondownloaderror(exception e) { Log.e(TAG, "Couldn't download lock screen icon, resorting to default."); You should prepare to accept and download the lock screen image from the URL sent by the head-unit in the ononsystemrequest callback. public void ononsystemrequest(onsystemrequest notification) { if(notification.getrequesttype().equals(requesttype. LOCK_SCREE_ICO_URL)){ if(notification.geturl()!= null && lockscreenmanager. getlockscreenicon() == null){ lockscreenmanager.downloadlockscreenicon(notification. geturl(), new LockScreenDownloadedListener()); ow that our lock screen activity and manager are setup, all we have to do is handle starting and stopping the activity. In the ononlockscreenotification we need to trigger the lock screen to be displayed with the HMI Level is set to FULL and when the lock screen status is required. If available, we also need to

43 pass along the Bitmap for the lock screen image. To finish, we need to close the lock screen when the the lock screen status is public void ononlockscreenotification(onlockscreenstatus notification) { if(notification.gethmilevel() == HMILevel.HMI_FULL && notification.getshowlockscreen() == LockScreenStatus.REQUIRED) { Intent showlockscreenintent = new Intent(this, LockScreenActivity.class); showlockscreenintent.addflags(intent. FLAG_ACTIVITY_EW_TASK); if(lockscreenmanager.getlockscreenicon()!= null){ showlockscreenintent.putextra(lockscreenactivity. LOCKSCREE_BITMAP_EXTRA, lockscreenmanager.getlockscreenicon ()); startactivity(showlockscreenintent); else if(notification.getshowlockscreen() == LockScreenStatus. OFF){ sendbroadcast(new Intent(LockScreenActivity. CLOSE_LOCK_SCREE_ACTIO)); We also need to close the lock screen when a disconnect happens. We do that by sending another broadcast in the SdlService.onDestroy public void ondestroy() {... sendbroadcast(new Intent(LockScreenActivity. CLOSE_LOCK_SCREE_ACTIO));... ow when the HMI fully displays the application, the mobile device will display the lock screen with an image provided by the head-unit.

44 Designing a User Interface Designing for Different User Interfaces Each car manufacturer has different user interface style guidelines, so the number of lines of text, buttons, and images supported will vary between different types of head units. After your app creates an SdlProxyALM object (which sends a RegisterAppInterface RPC) and connects to Core, the object automatically holds information from the RegisterAppInterface Response. You can use this information to determine how to layout the user interface. SdlProxyALM Object The RegisterAppInterface response contains information about the display type, the type of images supported, the number of text fields supported, the HMI display language, and a lot of other useful properties. This information is stored in the SdlProxyALM object. The table below has a list of all possible properties available in the SdlProxyALM object. Each property is optional, so you may not get information for all the parameters in the table.

45 PA R A M E T E R S D E S C R I P T I O O T E S SdlMsgVersion sdllanguage hmidisplaylanguage displaycapabilities buttoncapabilities softbuttoncapabilities presetbankcapabilities hmizonecapabilities speechcapabilities prerecordedspeech vrcapabilities Specifies the version number of the SDL V4 interface. This is used by both the application and SDL to declare what interface version each is using. The currently active voicerecognition and text-tospeech language on the head unit. The currently active display language on the head unit. Information about the head unit display. This includes information about available templates, whether or not graphics are supported, and a list of all text fields and the max number of characters allowed in each text field. A list of available buttons and whether the buttons support long, short and up-down presses. A list of available soft buttons and whether the button support images. Also information about whether the button supports long, short and up-down presses. If returned, the platform supports custom onscreen presets. Specifies HMI Zones in the vehicle. There may be a HMI available for back seat passengers as well as front seat passengers. Contains information about TTS capabilities on the SDL platform. Platforms may support text, SAPI phonemes, LH PLUS phonemes, prerecorded speech, and silence. A list of pre-recorded sounds you can use in your app. Sounds may include a help, initial, listen, positive, or a negative jingle. The voice-recognition capabilities of the connected SDL platform. The platform may be able to recognize spoken text in the current language. Check SdlMsgVersion.java for more information Check Language.java for more information Check Language.java for more information Check DisplayCapabilities.java for more information Check ButtonCapabilities.java for more information Check SoftButtonCapabilities.ja va for more information Check PresetBankCapabilities.j ava for more information Check HmiZoneCapabilities.jav a for more information Check SpeechCapabilities.java for more information Check PrerecordedSpeech.java for more information Check VrCapabilities.java for more information

46 PA R A M E T E R S D E S C R I P T I O O T E S audiopassthrucapabiliti es vehicletype supporteddiagmodes hmicapabilities systemsoftwareversion Describes the sampling rate, bits per sample, and audio types available. The make, model, year, and the trim of the vehicle. Specifies the white-list of supported diagnostic modes (0x00-0xFF) capable for DiagnosticMessage requests. If a mode outside this list is requested, it will be rejected. Returns whether or not the app can support builtin navigation and phone calls. The software version of the system that implements the k core Check AudioPassThruCapabiliti es.java for more information Check VehicleType.java for more information List Check HMICapabilities.java for more information String Templates Each car manufacturer supports a set of templates for the user interface. These templates determine the position and size of the text, images, and buttons on the screen. A list of supported templates is sent with RegisterAppInterface response and stored in the SdlProxyALM objects. To change a template at any time, send a SetDisplayLayout RPC to the SDL Core. If you want to ensure that the new template is used, wait for a response from the SDL Core before sending any more user interface RPCs.

47 SetDisplayLayout setdisplaylayoutrequest = new SetDisplayLayout(); setdisplaylayoutrequest.setdisplaylayout("graphic_with_text"); setdisplaylayoutrequest.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if(((setdisplaylayoutresponse) response).getsuccess()){ Log.i("SdlService", "Display layout set successfully."); // Proceed with more user interface RPCs else{ Log.i("SdlService", "Display layout request rejected."); ); try{ proxy.sendrpcrequest(setdisplaylayoutrequest); catch (SdlException e){ e.printstacktrace(); Available Templates There are fifteen standard templates to choose from, however some head units may only support a subset of these templates. Please check the DisplayCapabi lities object returned by SdlProxyALM.getDisplayCapabilities() for the supported templates. The following examples show how templates will appear on the generic head unit. O T E You will automatically be assigned the media template if you set your configuration app type as MEDIA.

48 1. MEDIA - WITH AD WITHOUT PROGRESS BAR F O R D H M I 2. O-MEDIA - WITH AD WITHOUT SOFT BUTTOS

49 F O R D H M I 3. GRAPHIC_WITH_TEXT

50 F O R D H M I 4. TEXT_WITH_GRAPHIC F O R D H M I 5. TILES_OLY

51 F O R D H M I 6. GRAPHIC_WITH_TILES F O R D H M I 7. TILES_WITH_GRAPHIC

52 F O R D H M I 8. GRAPHIC_WITH_TEXT_AD_SOFTBUTTOS F O R D H M I 9. TEXT_AD_SOFTBUTTOS_WITH_GRAPHIC

53 F O R D H M I 10. GRAPHIC_WITH_TEXTBUTTOS F O R D H M I 11. DOUBLE_GRAPHIC_SOFTBUTTOS

54 F O R D H M I 12. TEXTBUTTOS_WITH_GRAPHIC F O R D H M I 13. TEXTBUTTOS_OLY

55 F O R D H M I 14. L ARGE_GRAPHIC_WITH_SOFTBUTTOS F O R D H M I 15. L ARGE_GRAPHIC_OLY

56 F O R D H M I Text, Images, and Buttons All text, images, and buttons on the HMI screen must be sent as part of a Show RPC. Subscribe buttons are sent as part of a SubscribeButton RPC. Text A maximum of four lines of text can be set in Show RPC, however, some templates may only support 1, 2, or 3 lines of text. If all four lines of text are set in the Show RPC, but the template only supports three lines of text, then the fourth line will simply be ignored.

57 Show show = new Show(); show.setmainfield1("hello, this is MainField1."); show.setmainfield2("hello, this is MainField2."); show.setmainfield3("hello, this is MainField3."); show.setmainfield4("hello, this is MainField4."); show.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if (((ShowResponse) response).getsuccess()) { Log.i("SdlService", "Successfully showed."); else { Log.i("SdlService", "Show request was rejected."); ); proxy.sendrpcrequest(show); Images The position and size of images on the screen is determined by the currently set template. All images must first be uploaded to the remote system using the PutFile RPC before being used in a Show RPC. Once the image has been successfully uploaded, the app will be notified in the upload method's completion handler. For information relating to how to upload images, go to the Uploading Files and Graphics section. O T E Some head units you may be connected to may not support images at all. Please consult the getgraphicsupported() method in the Di splaycapabilities property available from the SdlProxyALM object.

58 SHOW THE IMAGE O A HEAD UIT Once the image has been uploaded to the head unit, you can show the image on the user interface. To send the image, create an Image (com.smartdevicelink.rpc.image) object, and send it using the Show RPC. The Value property should be set to the same value used in the filename property when it was previously uploaded. Since you have uploaded your own image, the ImageType property should be set to ImageType.DYAMIC. Image image = new Image(); image.setimagetype(imagetype.dyamic); image.setvalue("appimage.jpeg"); // a previously uploaded filename using PutFile RPC Show show = new Show(); show.setgraphic(image); show.setcorrelationid(correlationidgenerator.generateid()); show.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if (((ShowResponse) response).getsuccess()) { Log.i("SdlService", "Successfully showed."); else { Log.i("SdlService", "Show request was rejected."); ); proxy.sendrpcrequest(show); Soft & Subscribe Buttons Buttons on the HMI screen are referred to as soft buttons to distinguish them from hard buttons, which are physical buttons on the head unit. Don t confuse soft buttons with subscribe buttons, which are buttons that can detect user selection on hard buttons (or built-in soft buttons).

59 SOFT BUTTOS Soft buttons can be created with text, images or both text and images. The location, size, and number of soft buttons visible on the screen depends on the template. If the button has an image, remember to upload the image first to the head unit before setting the image in the SoftButton instance. O T E If a button type is set to SBT_IMAGE or SBT_BOTH but no image is stored on the head unit, the button might not show up on the HMI screen.

60 Image cancelimage = new Image(); cancelimage.setimagetype(imagetype.dyamic); cancelimage.setvalue("cancel.jpeg"); List<SoftButton> softbuttons = new ArrayList<>(); SoftButton yesbutton = new SoftButton(); yesbutton.settype(softbuttontype.sbt_text); yesbutton.settext("yes"); yesbutton.setsoftbuttonid(0); SoftButton cancelbutton = new SoftButton(); cancelbutton.settype(softbuttontype.sbt_image); cancelbutton.setimage(cancelimage); cancelbutton.setsoftbuttonid(1); softbuttons.add(yesbutton); softbuttons.add(cancelbutton); Show show = new Show(); show.setsoftbuttons(softbuttons); show.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if (((ShowResponse) response).getsuccess()) { Log.i("SdlService", "Successfully showed."); else { Log.i("SdlService", "Show request was rejected."); ); proxy.sendrpcrequest(show); SUBSCRIBE BUTTOS Subscribe buttons are used to detect changes to hard buttons. You can subscribe to the following hard buttons:

61 B U T T O T E M P L AT E B U T T O T Y P E Ok (play/pause) media template only soft button and hard button Seek left media template only soft button and hard button Seek right media template only soft button and hard button Tune up media template only hard button Tune down media template only hard button Preset 0-9 any template hard button Search any template hard button Custom any template hard button Audio buttons like the OK (i.e. the play/pause button), seek left, seek right, tune up, and tune down buttons can only be used with a media template. The OK, seek left, and seek right buttons will also show up on the screen in a predefined location dictated by the media template on touchscreens. The app will be notified when the user selects the subscribe button on the screen or when the user manipulates the corresponding hard button. You can subscribe to buttons using the SubscribeButton RPC. SubscribeButton subscribebuttonrequest = new SubscribeButton(); subscribebuttonrequest.setbuttoname(buttoname.seekright); proxy.sendrpcrequest(subscribebuttonrequest);

62 O T E It is not required to manually subscribe to soft buttons. When soft buttons are added, your app will automatically be subscribed for their events RECEIVIG BUTTOS EVETS Once you have successfully subscribed to buttons and/or added soft buttons you will likely want to know when events happen to those buttons. These events come through two callbacks from the IProxyListenerALM interface, on OnButtonEvent and ononbuttonpress. Depending which type of event you're looking for you can use that type of callback. The Buttoname enum refers to which button the event happened to. SoftButton events will have the Button ame of CUSTOM_BUTTO.

63 @Override public void ononbuttonevent(onbuttonevent notification) { switch(notification.getbuttoname()){ case CUSTOM_BUTTO: //Custom buttons are the soft buttons previously added. int ID = notification.getcustombuttonid(); Log.d("SdlService", "Button event received for button " + ID); break; case OK: break; case SEEKLEFT: break; case SEEKRIGHT: break; case TUEUP: break; case TUEDOW: break; default: public void ononbuttonpress(onbuttonpress notification) { switch(notification.getbuttoname()){ case CUSTOM_BUTTO: //Custom buttons are the soft buttons previously added. int ID = notification.getcustombuttoname(); Log.d("SdlService", "Button press received for button " + ID); break; case OK: break; case SEEKLEFT: break; case SEEKRIGHT: break; case TUEUP: break; case TUEDOW: break; default: break;

64 Menus You have two different options when creating menus. One is to simply add items to the default menu available in every template. The other is to create a custom menu that pops up when needed. Default Menu F O R D H M I Every template has a default menu button. The position of this button varies between templates, and can not be removed from the template. The default menu is initially empty except for an "Exit Your App ame" button. Items can be

65 added to the menu at the root level or to a submenu. It is important to note that a submenu can only be one level deep. Menu Structure ADD MEU ITEMS The AddCommand RPC can be used to add items to the root menu or to a submenu. Each AddCommand RPC must be sent with a unique id, a voicerecognition command, and a set of menu parameters. The menu parameters include the menu name, the position of the item in the menu, and the id of the menu item s parent. If the menu item is being added to the root menu, then the

66 parent id is 0. If it is being added to a submenu, then the parent id is the submenu s id. // Create the menu parameters // The parent id is 0 if adding to the root menu // If adding to a submenu, the parent id is the submenu's id MenuParams menuparams = new MenuParams(); menuparams.setparentid(0); menuparams.setposition(0); menuparams.setmenuame("options"); AddCommand addcommand = new AddCommand(); addcommand.setcmdid(0); // Ensure this is unique addcommand.setmenuparams(menuparams); // Set the menu parameters proxy.sendrpcrequest(addcommand); ADD A SUBMEU To create a submenu, first send an AddSubMenu RPC. When a response is received from the SDL Core, check if the submenu was added successfully. If it was, send an AddCommand RPC for each item in the submenu.

67 int unique_id = 313; AddSubMenu addsubmenu = new AddSubMenu(); addsubmenu.setposition(0); addsubmenu.setmenuid(unique_id); addsubmenu.setmenuame("submenu"); addsubmenu.setonrpcresponselistener(new OnRPCResponseListener () public void onresponse(int correlationid, RPCResponse response) { if(((addsubmenuresponse) response).getsuccess()){ // The submenu was created successfully, start adding the submenu items // Use unique_id else{ Log.i("SdlService", "AddSubMenu request rejected."); ); DELETE MEU ITEMS Use the cmdid of the menu item to tell the SDL Core which item to delete using the DeleteCommand RPC. int cmdid_to_delete = 1; DeleteCommand deletecommand = new DeleteCommand(); deletecommand.setcmdid(cmdid_to_delete); proxy.sendrpcrequest(deletecommand);

68 DELETE SUBMEUS Use the menuid to tell the SDLCore which item to delete using the DeleteSubM enu RPC. DeleteSubMenu deletesubmenu = new DeleteSubMenu(); deletesubmenu.setmenuid(submenuid_to_delete); // Replace with submenu ID to delete Custom Menus Custom menus, called perform interactions, are one level deep, however, you can create submenus by triggering another perform interaction when the user selects a row in a menu. Perform interactions can be set up to recognize speech, so a user can select an item in the menu by speaking their preference rather than physically selecting the item.

69 Perform interactions are created by sending two different RPCs. First a CreateIn teractionchoiceset RPC must be sent. This RPC sends a list of items that will show up in the menu. When the request has been registered successfully, then a PerformInteraction RPC is sent. The PerformInteraction RPC sends the formatting requirements, the voice-recognition commands, and a timeout command. CREATE A SET OF CUSTOM MEU ITEMS Each menu item choice defined in Choice should be assigned a unique id. The choice set in CreateInteractionChoiceSet should also have its own unique id. CreateInteractionChoiceSet choiceset = new CreateInteractionChoiceSet(); Choice choice = new Choice(); choice.setchoiceid(uniquechoiceid); choice.setmenuame("choicea"); choice.setvrcommands(arrays.aslist("choicea")); List<Choice> choicelist = new ArrayList<>(); choicelist.add(choice); choiceset.setchoiceset(choicelist); choiceset.setinteractionchoicesetid(uniqueintchoicesetid); choiceset.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if(((createinteractionchoicesetresponse) response).getsuccess()){ // The request was successful, now send the SDLPerformInteraction RPC else{ // The request was unsuccessful ); proxy.sendrpcrequest(choiceset);

70 FORMAT THE SET OF CUSTOM MEU ITEMS Once the set of menu items has been sent to SDL Core, send a PerformInteract ion RPC to get the items to show up on the HMI screen. List<Integer> interactionchoicesetidlist = new ArrayList<>(); interactionchoicesetidlist.add(uniqueintchoicesetid); PerformInteraction performinteraction = new PerformInteraction(); performinteraction.setinitialtext("initial text."); performinteraction.setinteractionchoicesetidlist( interactionchoicesetidlist); ITERACTIO MODE The interaction mode specifies the way the user is prompted to make a section and the way in which the user s selection is recorded. I T E R A C T I O M O D E D E S C R I P T I O Manual only Interactions occur only through the display VR only Interactions occur only through text-tospeech and voice recognition Both Interactions can occur both manually or through VR

71 performinteraction.setinteractionmode(interactionmode.maual_oly ); VR ITERACTIO MODE F O R D H M I MAUAL ITERACTIO MODE

72 F O R D H M I ITERACTIO L AYOUT The items in the perform interaction can be shown as a grid of buttons (with optional images) or as a list of choices. L AY O U T M O D E F O R M AT T I G D E S C R I P T I O Icon only A grid of buttons with images Icon with search A grid of buttons with images along with a search field in the HMI List only A vertical list of text List with search A vertical list of text with a search field in the HMI Keyboard A keyboard shows up immediately in the HMI

73 O T E Keyboard is currently only supported for the navigation app type. performinteraction.setinteractionlayout(layoutmode.list_oly); ICO OLY ITERACTIO L AYOUT F O R D H M I LIST OLY ITERACTIO L AYOUT

74 F O R D H M I LIST WITH SEARCH ITERACTIO L AYOUT F O R D H M I

75 TEXT-TO -SPEECH (TTS) A text-to-speech chunk is a text phrase or prerecorded sound that will be spoken by the head unit. The text parameter specifies the text to be spoken or the name of the pre-recorded sound. Use the type parameter to define the type of information in the text parameter. The PerformInteraction request can have a initial, timeout, and a help prompt. performinteraction.setinitialprompt( TTSChunkFactory.createSimpleTTSChunks("Hello, welcome.")); TIMEOUT The timeout parameter defines the amount of time the menu will appear on the screen before the menu is dismissed automatically by the HMI. performinteraction.settimeout(30000); // 30 seconds

76 SED THE REQUEST performinteraction.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { PerformInteractionResponse piresponse = ( PerformInteractionResponse) response; if(piresponse.getsuccess()){ // Successful request if(piresponse.getresultcode().equals(result.timed_out)){ // Interaction timed out without user input else if(piresponse.getresultcode().equals(result.success)){ Integer userchoice = piresponse.getchoiceid(); else{ // Unsuccessful request ); proxy.sendrpcrequest(performinteraction); DELETE THE CUSTOM MEU If the information in the menu is dynamic, then the old interaction choice set needs to be deleted with a DeleteInteractionChoiceSet RPC before the new information can be added to the menu. Use the interaction choice set id to delete the menu.

77 DeleteInteractionChoiceSet deleteinteractionchoiceset = new DeleteInteractionChoiceSet(); deleteinteractionchoiceset.setinteractionchoicesetid( interactionchoicesetid_to_delete); // Replace with interaction choice set to delete proxy.sendrpcrequest(deleteinteractionchoiceset); Alerts An alert is a pop-up window with some lines of text and optional soft buttons. When an alert is activated, it will abort any SDL operation that is in-progress, except the already-in-progress alert. If an alert is issued while another alert is still in progress, the newest alert will simply be ignored. Alert UI Depending the platform, an alert can have up to three lines of text, a progress indicator (e.g. a spinning wheel or hourglass), and up to four soft buttons. ALERT WITHOUT SOFT BUTTOS

78 F O R D H M I ALERT WITH SOFT BUTTOS F O R D H M I Alert TTS The alert can also be formatted to speak a prompt when the alert appears on the screen. Do this by setting the ttschunks parameter. To play the alert tone before the text-to-speech is spoken, set playtone to true.

79 Example Alert alert = new Alert(); alert.setalerttext1("alert Text 1"); alert.setalerttext2("alert Text 2"); alert.setalerttext3("alert Text 3"); // Maximum time alert appears before being dismissed // Timeouts are must be between 3-10 seconds // Timeouts may not work when soft buttons are also used in the alert alert.setduration(5000); // A progress indicator (e.g. spinning wheel or hourglass) // ot all head units support the progress indicator alert.setprogressindicator(true); //Text to speech alert.setttschunks(tts_list); // TTS_list populated elsewhere // Special tone played before the tts is spoken alert.setplaytone(true); // Soft buttons alert.setsoftbuttons(softbuttons); // softbuttons populated elsewhere // Send alert proxy.sendrpcrequest(alert); Dismissing the Alert The alert will persist on the screen until the timeout has elapsed, or the user dismisses the alert by selecting a button. There is no way to dismiss the alert programmatically other than to set the timeout length.

80 Uploading Files and Graphics Graphics allow for you to better customize what you would like to have your users see and provide a better User Interface. When developing an application using k, two things must always be remembered when using graphics: 1. You may be connected to a head unit that does not display graphics. 2. You must upload them from your mobile device to Core before using them. Detecting if Graphics are Supported Being able to know if graphics are supported is a very important feature of your application, as this avoids you uploading unneccessary images to the head unit. In order to see if graphics are supported, use the getcapability() method of a valid SdlProxyALM to find out the display capabilities of the head unit. if (proxy.iscapabilitysupported(systemcapabilitytype.display)){ // Since the module does support this capability we can query it for more information proxy.getcapability(systemcapabilitytype.display, new public void oncapabilityretrieved(object capability){ DisplayCapabilities dispcapability = (DisplayCapabilities) capability; // ow it is possible to get details on how this capability // is supported using the dispcapability public void onerror(string info){ Log.i(TAG, "Capability could not be retrieved: "+ info); );

81 Uploading a File using PutFile To upload a file to Core, use the PutFile RPC. You can use the RPC response callback to perform certain actions upon a successful or unsuccessful upload. Here's an example that attempts to upload an image to Core and set's the app's HMI icon upon a successful upload. PutFile putfilerequest = new PutFile(); putfilerequest.setsdlfileame("appicon.jpeg"); putfilerequest.setfiletype(filetype.graphic_jpeg); putfilerequest.setpersistentfile(true); putfilerequest.setfiledata(file_data); // can create file_data using helper method below putfilerequest.setcorrelationid(correlationidgenerator.generateid()); putfilerequest.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { setlistenertype(update_listeer_type_put_file); // necessary for PutFile requests if(response.getsuccess()){ try { proxy.setappicon("appicon.jpeg", CorrelationIdGenerator. generateid()); catch (SdlException e) { e.printstacktrace(); else{ Log.i("SdlService", "Unsuccessful app icon upload."); ); try { proxy.sendrpcrequest(putfilerequest); catch (SdlException e) { e.printstacktrace(); App icons and other images might be hardcoded into the app and getting their raw data will be important. The following method will help get that data:

82 /** * Helper method to take resource files and turn them into byte arrays resource Resource file id. Resulting byte array. */ private byte[] contentsofresource(int resource) { InputStream is = null; try { is = getresources().openrawresource(resource); ByteArrayOutputStream os = new ByteArrayOutputStream(is. available()); final int buffersize = 4096; final byte[] buffer = new byte[buffersize]; int available; while ((available = is.read(buffer)) >= 0) { os.write(buffer, 0, available); return os.tobytearray(); catch (IOException e) { Log.w(TAG, "Can't read icon file", e); return null; finally { if (is!= null) { try { is.close(); catch (IOException e) { e.printstacktrace(); File aming The file name can only consist of letters (a-z) and numbers (0-9), otherwise the SDL Core may fail to find the uploaded file (even if it was uploaded successfully).

83 File Persistance PutFile supports uploading persistant images, i.e. images that do not become deleted when your application disconnects. Persistance should be used for images relating to your UI, and not for dynamic aspects, such as Album Artwork. This relates to the following line in the above example: putfilerequest.setpersistentfile(true); O T E Be aware that persistance will not work if space on the head unit is limited. Overwrite Stored Files If a file being uploaded has the same name as an already uploaded file, the new file will overwrite the previous file. Check if a File Has Already Been Uploaded You can use the ListFiles RPC to check for the names of uploaded files to avoid overwriting a file.

84 ListFiles listfiles = new ListFiles(); listfiles.setcorrelationid(correlationidgenerator.generateid()); listfiles.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if(response.getsuccess()){ List<String> filenames = ((ListFilesResponse) response). getfilenames(); if(filenames.contains("appicon.jpeg")){ Log.i("SdlService", "App icon is already uploaded."); else{ Log.i("SdlService", "App icon has not been uploaded."); else{ Log.i("SdlService", "Failed to request list of uploaded files."); ); try{ proxy.sendrpcrequest(listfiles); catch (SdlException e) { e.printstacktrace(); Check the Amount of File Storage To find the amount of file storage left on the head unit, use the the ListFiles RPC in a similar fashion.

85 ListFiles listfiles = new ListFiles(); listfiles.setcorrelationid(correlationidgenerator.generateid()); listfiles.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if(response.getsuccess()){ Integer spaceavailable = ((ListFilesResponse) response). getspaceavailable(); Log.i("SdlService", "Space available on Core = " + spaceavailable); else{ Log.i("SdlService", "Failed to request list of uploaded files."); ); try{ proxy.sendrpcrequest(listfiles); catch (SdlException e) { e.printstacktrace(); Delete Stored Files Use the DeleteFile RPC to delete a file associated with a file name.

86 DeleteFile deletefilerequest = new DeleteFile(); deletefilerequest.setsdlfileame("appicon.jpeg"); deletefilerequest.setcorrelationid(correlationidgenerator.generateid ()); deletefilerequest.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if(response.getsuccess()){ Log.i("SdlService", "App icon deleted."); else{ Log.i("SdlService", "Unable to delete app icon."); ); try{ proxy.sendrpcrequest(deletefilerequest); catch (SdlException e) { e.printstacktrace(); Image Specifics Image File Type Images may be formatted as PG, JPEG, or BMP. Check the DisplayCapabilities object provided by your SdlProxyALM to find out what image formats the head unit supports. Image Sizes If an image is uploaded that is larger than the supported size, that image will be scaled down to accomodate.

87 IMAGE SPECIFICATIOS I M A G E A M E U S E D I R P C D E TA I L S H E I G H T W I D T H T Y P E softbutt onimag e choicei mage choices econdar yimage vrhelpit em menuic on cmdico n appicon graphic Show CreateInt eractionc hoiceset CreateInt eractionc hoiceset SetGlobal Propertie s SetGlobal Propertie s AddCom mand SetAppIc on Show Will be shown on softbutto ns on the base screen Will be shown in the manual part of an performin teraction either big (ICO_O LY) or small (LIST_OL Y) Will be shown on the right side of an entry in (LIST_OL Y) performin teraction Will be shown during voice interactio n Will be shown on the More button Will be shown for command s in the "More " menu Will be shown as Icon in the "Mobile Apps" menu Will be shown on the basescre en as cover art 70px 70px 35px 35px 35px 35px 70px 185px 70px 70px 35px 35px 35px 35px 70px 185px png, jpg, bmp png, jpg, bmp png, jpg, bmp png, jpg, bmp png, jpg, bmp png, jpg, bmp png, jpg, bmp png, jpg, bmp

88 Get Vehicle Data Use the GetVehicleData RPC request to get vehicle data. The HMI level must be FULL, LIMITED, or BACKGROUD in order to get data. Each vehicle manufacturer decides which data it will expose. Please check the OnPermissionsChange RPC notification to find out which data you will have access to in your head unit. O T E You may only ask for vehicle data that is available to your appame & appid combination. These will be specified by each OEM separately.

89 V E H I C L E D ATA PA R A M E T E R A M E D E S C R I P T I O GPS gps Longitude and latitude, current time in UTC, degree of precision, altitude, heading, speed, satellite data vs dead reckoning, and supported dimensions of the GPS Speed speed Speed in KPH RPM Fuel level Fuel level state Instant fuel consumption External temperature VI PRDL Tire pressure rpm fuellevel fuellevel_state instantfuelconsumption externaltemperature vin prndl tirepressure The number of revolutions per minute of the engine The fuel level in the tank (percentage) The fuel level state: unknown, normal, low, fault, alert, or not supported The instantaneous fuel consumption in microlitres The external temperature in degrees celsius The Vehicle Identification umber The selected gear the car is in: park, reverse, neutral, drive, sport, low gear, first, second, third, fourth, fifth, sixth, seventh or eighth gear, unknown, or fault Tire status of each wheel in the vehicle: normal, low, fault, alert, or not supported. Warning light status for the tire pressure: off, on, flash, or not used Odometer odometer Odometer reading in km Belt status Body information beltstatus bodyinformation The status of each of the seat belts: no, yes, not supported, fault, or no event Door ajar status for each door. The Ignition status. The ignition stable status. The park brake active status.

90 V E H I C L E D ATA PA R A M E T E R A M E D E S C R I P T I O Device status Driver braking Wiper status Head lamp status Engine torque Acceleration pedal position Steering wheel angle E-Call infomation Airbag status devicestatus driverbraking wiperstatus headlampstatus enginetorque accpedalposition steeringwheelangle ecallinfo airbagstatus Contains information about the smartphone device. Is voice recognition on or off, has a bluetooth connection been established, is a call active, is the phone in roaming mode, is a text message available, the battery level, the status of the mono and stereo output channels, the signal level, the primary audio source, whether or not an emergency call is currently taking place The status of the brake pedal: yes, no, no event, fault, not supported The status of the wipers: off, automatic off, off moving, manual interaction off, manual interaction on, manual low, manual high, manual flick, wash, automatic low, automatic high, courtesy wipe, automatic adjust, stalled, no data exists Status of the head lamps: whether or not the low and high beams are on or off. The ambient light sensor status: night, twilight 1, twilight 2, twilight 3, twilight 4, day, unknown, invalid Torque value for engine (in m) on non-diesel variants Accelerator pedal position (percentage depressed) Current angle of the steering wheel (in degrees) Information about the status of an emergency call Status of each of the airbags in the vehicle: yes, no, no event, not supported, fault

91 V E H I C L E D ATA PA R A M E T E R A M E D E S C R I P T I O Emergency event Cluster mode status My key emergencyevent clustermodestatus mykey The type of emergency: frontal, side, rear, rollover, no event, not supported, fault. Fuel cutoff status: normal operation, fuel is cut off, fault. The roll over status: yes, no, no event, not supported, fault. The maximum change in velocity. Whether or not multiple emergency events have occurred Whether or not the power mode is active. The power mode qualification status: power mode undefined, power mode evaluation in progress, not defined, power mode ok. The car mode status: normal, factory, transport, or crash. The power mode status: key out, key recently out, key approved, post accessory, accessory, post ignition, ignition on, running, crank Information about whether or not the emergency 911 override has been activated Single Time Vehicle Data Retrieval Using GetVehicleData, we can ask for vehicle data a single time, if needed.

92 GetVehicleData vdrequest = new GetVehicleData(); vdrequest.setprndl(true); vdrequest.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if(response.getsuccess()){ PRDL prndl = ((GetVehicleDataResponse) response).getprndl(); Log.i("SdlService", "PRDL status: " + prndl.tostring()); else{ Log.i("SdlService", "GetVehicleData was rejected."); ); try { proxy.sendrpcrequest(vdrequest); catch (SdlException e) { e.printstacktrace(); Subscribing to Vehicle Data Subscribing to vehicle data allows you to get notified whenever we have new data available. This data should not be relied upon being received in a consistent manner. ew vehicle data is available roughly every second. First, send the Subscribe Vehicle Data Request

93 SubscribeVehicleData subscriberequest = new SubscribeVehicleData(); subscriberequest.setprndl(true); subscriberequest.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if(response.getsuccess()){ Log.i("SdlService", "Successfully subscribed to vehicle data."); else{ Log.i("SdlService", "Request to subscribe to vehicle data was rejected."); ); try { proxy.sendrpcrequest(subscriberequest); catch (SdlException e) { e.printstacktrace(); Then, you'll be able to observe the new data in the OnVehicleData public void ononvehicledata(onvehicledata notification) { PRDL prndl = notification.getprndl(); Log.i("SdlService", "PRDL status was updated to: " prndl.tostring()); Unsubscribing from Vehicle Data Sometimes you may not always need all of the vehicle data you are listening to. We suggest that you only are subscribing when the vehicle data is needed. To stop listening to specific vehicle data items, utilize UnsubscribeVehicleData.

94 UnsubscribeVehicleData unsubscriberequest = new UnsubscribeVehicleData(); unsubscriberequest.setprndl(true); // unsubscribe to PRDL data unsubscriberequest.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { if(response.getsuccess()){ Log.i("SdlService", "Successfully unsubscribed to vehicle data." ); else{ Log.i("SdlService", "Request to unsubscribe to vehicle data was rejected."); ); try { proxy.sendrpcrequest(unsubscriberequest); catch (SdlException e) { e.printstacktrace(); Knowing the In-Car UI Status Once your app is connected to Core, most of the interaction you will be doing requires knowledge of the current In-Car UI, or HMI, Status. The HMI Status informs you of where the user is within the head unit in a general sense. Refer to the table below of all possible HMI States:

95 H M I S TAT E W H AT D O E S T H I S M E A? OE BACKGROUD LIMITED FULL The user has not been opened your app, or it has been Exited via the "Menu" button. The user has opened your app, but is currently in another part of the Head Unit. If you have a Media app, this means that another Media app has been selected. For Media apps, this means that a user has opened your app, but is in another part of the Head Unit. Your app is currently in focus on the screen. Monitoring HMI Status Monitoring HMI Status is possible through an OnHMIStatus notification in the ononhmistatus() callback in your app's SDL Service. It will give you information relating to the previous and new HMI levels your app is progressing through. public void ononhmistatus(onhmistatus notification) { // Check notification for various HMI info More Detailed HMI Information When an interaction occurs relating to your application, there is some additional pieces of information that can be observed that help figure out a more descriptive picture of what is going on with the Head Unit.

96 AUDIO STREAMIG STATE From the documentation, Audio Streaming State informs your app whether any currently streaming audio is audible to user (AUDIBLE) or not (OT_AUDIBLE). A value of OT_AUDIBLE means that either the application's audio will not be audible to the user, or that the application's audio should not be audible to the user (i.e. some other application on the mobile device may be streaming audio and the application's audio would be blended with that other audio). You will see this come in for things such as Alert, PerformAudioPassThru, Speaks, etc. A U D I O S T R E A M I G S TAT E W H AT D O E S T H I S M E A? AUDIBLE ATTEUATED OT_AUDIBLE Any audio you are streaming will be audible to the user. Some kind of audio mixing is occuring between what you are streaming, if anything, and some system level sound. This can be visible is displaying an Alert with playtone set to true. Your streaming audio is not audible. This could occur during a VRSESSSIO System Context. SYSTEM COTEXT System Context informs your app if there is potentially a blocking HMI component while your app is still visible. An example of this would be if your application is open, and you display an Alert. Your app will receive a System Context of ALERT while it is presented on the screen, followed by MAI when it is dismissed.

97 S Y S T E M C O T E X T S TAT E W H AT D O E S T H I S M E A? MAI o user interaction is in progress that could be blocking your app's visibility. VRSESSIO Voice Recognition is currently in progress. MEU HMI_OBSCURED ALERT A menu interaction is currently inprogress. The app's display HMI is being blocked by either a system or other app's overlay (another app's Alert, for instance). An alert that you have sent is currently visible (Other apps will not receive this). Monitoring Audio Streaming State and System Context Monitoring these two properties is quite easy using the OnHMIStatus notification. public void ononhmistatus(onhmistatus notification) { AudioStreamingState streamingstate = notification. getaudiostreamingstate(); SystemContext systemcontext = notification.getsystemcontext(); Setting the avigation Destination Setting a avigation Destination allows you to send a GPS location that you would like to prompt that user to navigate to using their embedded navigation.

98 When using the SendLocation RPC, you will not receive a callback about how the user interacted with this location, only if it was successfully sent to Core and received. It will be handled by Core from that point on using the embedded navigation system. O T E This currently is only supported for Embedded avigation. This does not work with Mobile avigation Apps at this time. O T E SendLocation is an RPC that is usually restricted by OEMs. As a result, the OEM you are connecting to may limit app functionality if not approved for usage. Determining the Result of SendLocation SendLocation has 3 possible results that you should expect: 1. SUCCESS - SendLocation was successfully sent. 2. IVALID_DATA - The request you sent contains invalid data and was rejected. 3. DISALLOWED - Your app does not have permission to use SendLocation. Detecting if SendLocation is Available SendLocation is a newer RPC, so there is a possibility that not all head units will support it, especially if you are connected to a head unit that does not have an embedded navigation. To see if SendLocation is supported, you may look

99 at your SdlProxyALM object's gethmicapabilities method after the successfully creating the proxy. if(proxy.gethmicapabilities().isavigationavailable()){ // SendLocation supported else{ // SendLocation is not supported Using SendLocation To use SendLocation, you must at least include the Longitude and Latitude of the location. You can also include an address, name, description, phone number, and image.

100 SendLocation sendlocation = new SendLocation(); sendlocation.setlatitudedegrees( ); sendlocation.setlongitudedegrees( ); sendlocation.setlocationame("the Center"); sendlocation.setlocationdescription("center of the United States"); // Create Address OasisAddress address = new OasisAddress(); address.setsubthoroughfare("900"); address.setthoroughfare("whiting Dr"); address.setlocality("yankton"); address.setadministrativearea("sd"); address.setpostalcode("57078"); address.setcountrycode("us-sd"); address.setcountryame("united States"); sendlocation.setaddress(address); // Monitor response sendlocation.setonrpcresponselistener(new OnRPCResponseListener () public void onresponse(int correlationid, RPCResponse response) { Result result = response.getresultcode(); if(result.equals(result.success)){ // SendLocation was successfully sent. else if(result.equals(result.ivalid_data)){ // The request you sent contains invalid data and was rejected. else if(result.equals(result.disallowed)){ // Your app does not have permission to use SendLocation. ); proxy.sendrpcrequest(sendlocation);

101 Calling a Phone umber Dialing a Phone umber allows you to send a phone number to dial on the user's phone. Regardless of platform, you must be sure that a device is connected via Bluetooth for this RPC to work. If it is not connected, you will receive a REJECTED Result. O T E Dialumber is an RPC that is usually restricted by OEMs. As a result, the OEM you are connecting to may limit app functionality if not approved for usage. Determining the Result of Dialumber Dialumber has 3 possible results that you should expect: 1. SUCCESS - Dialumber was successfully sent, and a phone call was initiated by the user. 2. REJECTED - Dialumber was sent, and a phone call was cancelled by the user. Also, this could mean that there is no phone connected via Bluetooth. 3. DISALLOWED - Your app does not have permission to use Dialumber. Detecting if Dialumber is Available Dialumber is a newer RPC, so there is a possibility that not all head units will support it. To see if Dialumber is supported, you may look at your SdlProxyALM object's gethmicapabilities method after the successfully creating the proxy.

102 if(proxy.gethmicapabilities().isphonecallavailable()){ // Dialumber supported else{ // Dialumber is not supported How to Use O T E For Dialumber, all characters are stripped except for 0-9, *, #,,, ;, and + Dialumber dialumber = new Dialumber(); dialumber.setumber(" "); dialumber.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { Result result = response.getresultcode(); if(result.equals(result.success)){ // `Dialumber` was successfully sent, and a phone call was initiated by the user. else if(result.equals(result.rejected)){ // `Dialumber` was sent, and a phone call was cancelled by the user. Also, this could mean that there is no phone connected via Bluetooth. else if(result.equals(result.disallowed)){ // Your app does not have permission to use Dialumber. ); proxy.sendrpcrequest(dialumber);

103 Getting In-Car Audio Capturing in-car audio allows developers to interact with users via raw audio data provided to them from the car's microphones. In order to gather the raw audio from the vehicle, we must leverage the PerformAudioPassThru RPC. O T E PerformAudioPassThru does not support automatic speech cancellation detection, so if this feature is desired, it is up to the developer to implement. Starting Audio Capture To initiate audio capture, we must construct a PerformAudioPassThru object. The properties we will set in this object's constructor relate to how we wish to gather the audio data from the vehicle we are connected to.

104 PerformAudioPassThru performapt = new PerformAudioPassThru(); performapt.setaudiopassthrudisplaytext1("ask me \"What's the weather?\""); performapt.setaudiopassthrudisplaytext2("or \"What's 1 + 2?\""); performapt.setinitialprompt(ttschunkfactory.createsimplettschunks("ask me What's the weather? or What's 1 plus 2?")); performapt.setsamplingrate(samplingrate._22khz); performapt.setmaxduration(7000); performapt.setbitspersample(bitspersample._16_bit); performapt.setaudiotype(audiotype.pcm); performapt.setmuteaudio(false); proxy.sendrpcrequest(performapt); FORD HMI In order to know the currently supported audio capture capabilities of the connected head unit, please refer to the SdlProxyALM object created when your SDL Service starts. It contains a method getaudiopassthrucapabilities that returns a list of AudioPassThruCapabilities that the head unit supports.

105 O T E Currently, Ford's SYC 3 vehicles only support a sampling rates of 16 khz and a bit rate of 16. Gathering Audio Data SDL provides audio data as fast as it can gather it, and sends it to the developer in chunks. In order to retrieve this audio data, observe the OnAudioP assthru notification in the ononaudiopassthru callback of your Sdl public void ononaudiopassthru(onaudiopassthru notification) { byte[] datarcvd; datarcvd = notification.getaptdata(); processaptdata(datarcvd); // Do something with audio data O T E This audio data is only the current audio data, so the developer must be in charge of managing previously retrieved audio data.

106 Ending Audio Capture AudioPassThru is a request that works in a different way when compared to other RPCs. For most RPCs a request is followed by an immediate response that informs the developer whether or not that RPC was successful. This RPC, however, will only send out the response when the Perform Audio Pass Thru is ended. Audio Capture can be ended in 4 ways: 1. AudioPassThru has timed out. If the audio passthrough has proceeded longer than the requested timeout duration, Core will end this request and send a PerformAudioPassThruRes ponse with a Result of SUCCESS. You should expect to handle this audio passthrough as though it was successful. 2. AudioPassThru was closed due to user pressing "Cancel". If the audio passthrough was displayed, and the user pressed the "Cancel" button, you will receive a PerformAudioPassThruResponse with a Result of ABORTED. You should expect to ignore this audio pass through. 3. AudioPassThru was closed due to user pressing "Done". If the audio passthrough was displayed, and the user pressed the "Done" button, you will receive a PerformAudioPassThruResponse with a Result of SUCCESS. You should expect to handle this audio passthrough as though it was successful. 4. AudioPassThru was ended due to the developer ending the request. If the audio passthrough was displayed, but you have established on your own that you no longer need to capture audio data, you can send an End AudioPassThru RPC. EndAudioPassThru endapt = new EndAudioPassThru(); proxy.sendrpcrequest(endapt);

107 You will receive an EndAudioPassThruResponse and a PerformAudioPassThruR esponse with a Result of SUCCESS, and should expect to handle this audio passthrough as though it was successful. Handling the Response To process the response that we received from an ended audio capture, we monitor the PerformAudioPassThruResponse through the callback in the Sdl Service. If the response has a successful Result, all of the audio data for the passthrough has been received and is ready for public void onperformaudiopassthruresponse( PerformAudioPassThruResponse response) { Result result = response.getresultcode(); if(result.equals(result.success)){ // We can use the data else{ // Cancel any usage of the data Log.e("SdlService", "Audio pass thru attempt failed."); Mobile avigation Mobile avigation allows map partners to bring their applications into the car and display their maps and turn by turn easily for the user. This feature has a different behavior on the head unit than normal applications. The main differences are: avigation Apps don't use base screen templates. Their main view is the video stream sent from the device

108 avigation Apps can send audio via a binary stream. This will attenuate the current audio source and should be used for navigation commands avigation Apps can receive touch events from the video stream O T E In order to use SDL's Mobile avigation feature, the app must have a minimum requirement of Android 4.4 (SDK 19). This is due to using Android's provided video encoder. Connecting an app The basic connection is the similar for all apps. Please follow Getting Started > Integration Basics for more information. The first difference for a navigation app is the apphmitype of AVIGATIO that has to be set in the creation of the SdlProxyALM. avigation apps are also non-media apps. The second difference is a property called securitymanagers that needs to be set in the SdlProxyBuilder.Builder if connecting to a version of Core that requires secure video & audio streaming. This property requires an array of classes of Security Managers, which will extend the SdlSecurityBase class. These security libraries are provided by the OEMs themselves, and will only work for that OEM. There is not a general catch-all security library.

109 SdlProxyBuilder.Builder builder = new SdlProxyBuilder.Builder(this, APP_ID, APP_AME, false, getapplicationcontext()); Vector<AppHMIType> hmitypes = new Vector<AppHMIType>(); hmitypes.add(apphmitype.avigatio); builder.setvrapphmitypes(hmitypes); List<? extends SdlSecurityBase> securitymanagers = new ArrayList(); securitymanagers.add(oemsecuritymanager1.class); securitymanagers.add(oemsecuritymanager1.class); builder.setsdlsecurity(securitymanagers); BaseTransportConfig transport = new USBTransportConfig( getbasecontext(), (UsbAccessory) intent.getparcelableextra( UsbManager.EXTRA_ACCESSORY), false, false); builder.settransporttype(transport); proxy = builder.build(); O T E When compiling, you must make sure to include all possible OEM's security managers that you wish to support. After being registered, the app will start receiving callbacks. One important callback is ononhmistatus, which informs the app about the currently visible application on the head unit. Right after registering, the hmilevel will be O E or BACKGROUD. Streaming should commence once the hmilevel has been set to FULL by the head unit.

110 Video Streaming In order to stream video from an SDL app, we only need to manage a few things. For the most part, the library will handle the majority of logic needed to perform video streaming. SDLProxyALM It is important that we create our SDLProxyALM instance with the correct settings in order to stream video. This was already covered in the Mobile avigation > Introduction. SDL Remote Display The SdlRemoteDisplay base class provides the easiest way to start streaming using SDL. The SdlRemoteDisplay is extended from Android's Presentation class with modifications to work with other aspects of the SDL Android library. O T E It is recommended that you extend this as a local class within the service that you have the SDLProxyALM instance. Extending this class gives developers a familiar, native experience to handling layouts and events on screen.

111 public static class MyDisplay extends SdlRemoteDisplay{ public MyDisplay(Context context, Display display) { super(context, protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.sdl); final Button button1 = (Button) findviewbyid(r.id.button_1); button1.setontouchlistener(new View.OnTouchListener() public boolean ontouch(view v, MotionEvent event) { Log.d(TAG, "Received motion event for button1"); ); Managing the Stream The only thing left to do to start the stream is combine the SDLProxyALM instance and the extension of the SdlRemoteDisplay. This should happen when your app receives its first HMI_FULL status in the ononhmistatus (OnHMIStatus notification) callback. The method that needs to be called is sta rtremotedisplaystream(context context, final Class<? extends SdlRemoteDisplay> remotedisplay, final VideoStreamingParameters parameters, final boolean encrypted) from the SDLProxyALM.

112 @Override public void ononhmistatus(onhmistatus notification) { if(notification.gethmilevel().equals(hmilevel.hmi_full)){ if (notification.getfirstrun()) { proxy.startremotedisplaystream(getapplicationcontext(), MyDisplay.class, null, false); Ending the Stream When the HMIStatus is back to HMI_OE it is time to stop the stream. This is accomplished through a method stopremotedisplaystream() in the SDLPro xyalm. Audio Streaming avigation apps are allowed to stream raw audio to be played by the head unit. The audio received this way is played immediately, and the current audio source will be attenuated. The raw audio has to be played with the following parameters: Format: PCM Sample Rate: 16k umber of Channels: 1 Bits Per Second (BPS): 16 bits per sample / 2 bytes per sample

113 O T E For streaming consistent audio, such as music, use a normal A2DP stream and not this method. STREAMIG AUDIO To stream audio, we call proxy.startaudiostream() which will return an IAudio StreamListener object that we will use to send the audio. This should happen when your app is in HMI_FULL status in the ononhmistatus(onhmistatus notification) callback. For example:

114 private void startaudiostream(){ final InputStream is = getresources().openrawresource(r.raw. audio_resource); AudioStreamingParams audioparams = new AudioStreamingParams(44100, 1); IAudioStreamListener listener = proxy.startaudiostream(false, AudioStreamingCodec.LPCM, audioparams); if (listener!= null){ try { listener.sendaudio(readtobytebuffer(is), -1); catch (IOException e) { e.printstacktrace(); private static ByteBuffer readtobytebuffer(inputstream instream) throws IOException { byte[] buffer = new byte[8000]; ByteArrayOutputStream outstream = new ByteArrayOutputStream (8000); int read; while (true) { read = instream.read(buffer); if (read == -1) { break; outstream.write(buffer, 0, read); return ByteBuffer.wrap(outStream.toByteArray()); STOPPIG THE AUDIO STREAM When the stream is complete, or you receive HMI_OE, you should stop the stream by calling

115 private void stopaudiostream() { proxy.endaudiostream(); Supporting Haptic Input SDL now supports "haptic" input, input from something other than a touch screen. This could include trackpads, click-wheels, etc. These kinds of inputs work by knowing which areas on the screen are touchable and focusing on those areas when the user moves the trackpad or click wheel. When the user selects a rect, the center of that area will be "touched". O T E Currently, there are no RPCs for knowing which rect is highlighted, so your UI will have to remain static, without scrolling. You will also need to implement touch input support (Mobile avigation/touch Input) in order to receive touches of the rects. Using SDL Presentation SDL has support for automatically detecting focusable rects within your UI and sending that data to the head unit. You will still need to tell SDL when your UI changes so that it can re-scan and detect the rects to be sent. The easiest way

116 to use this is by taking advantage of SDL's Presentation class. This will automatically check if the capability is available and instantiate the manager for you. All you have to do is set your layout: public static class MyPresentation extends SdlRemoteDisplay{ public MyPresentation(Context context, Display display) { super(context, protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.haptic_layout); LinearLayout videoview = (LinearLayout) findviewbyid(r.id. cat_view); videoview.setontouchlistener(new View.OnTouchListener() public boolean ontouch(view v, MotionEvent event) { //...Update something on the ui MyPresentation.this.invalidate() ); This will go through your view that was passed in and then find and send the rects to the head unit for use. When your UI changes, call invalidate() from your class that extends SdlRemoteDisplay; Sending your own Rects It is also possible that you may want to create your own rects instead of using the automated methods in the Presentation class. It is important that if sending this data youself that you also use the SystemCapabilityManager to check if you are on a head unit that supports this feature. If the capability is available, it is easy to build the area you want to become selectable:

117 public void sendhapticdata() { Rectangle rectangle = new Rectangle(); rectangle.setx((float) 1.0); rectangle.sety((float) 1.0); rectangle.setwidth((float) 1.0); rectangle.setheight((float) 1.0); HapticRect hapticrect = new HapticRect(); hapticrect.setid(123); hapticrect.setrect(rec); (); ArrayList<HapticRect> hapticarray = new ArrayList<HapticRect> hapticarray.add(0,hr); SendHapticData sendhapticdata = new SendHapticData(); sendhapticdata.sethapticrectdata(hapticarray); try { proxy.sendrpcrequest(sendhapticdata); catch (SdlException e) { e.printstacktrace(); Each SendHapticData rpc should contain the entirety of all clickable areas to be accessed via haptic controls. Setting Security Level for Multiplexing When connecting to Core via Multiplex Bluetooth transport, your SDL app will use a Router Service housed within your app or another SDL enabled app. To help ensure the validility of the Router Service, you can select the security level explicity when you create your Multiplex Bluetooth transport in your app's SdlService:

118 int securitylevel = FLAG_MULTI_SECURITY_MED; BaseTransport transport = MultiplexTransportConfig(context, appid, securitylevel); If you create the transport without specifying the security level, it will be set to FLAG_MULTI_SECURITY_MED by default. Security Levels S E C U R I T Y F L A G M E A I G FLAG_MULTI_SECURITY_OFF FLAG_MULTI_SECURITY_LOW FLAG_MULTI_SECURITY_MED FLAG_MULTI_SECURITY_HIGH Multiplexing security turned off. All router services are trusted. Multiplexing security will be minimal. Only trusted router services will be used. Trusted router list will be obtained from server. List will be refreshed every 20 days or during next connection session if an SDL enabled app has been installed or uninstalled. Multiplexing security will be on at a normal level. Only trusted router services will be used. Trusted router list will be obtained from server. List will be refreshed every 7 days or during next connection session if an SDL enabled app has been installed or uninstalled. Multiplexing security will be very strict. Only trusted router services installed from trusted app stores will be used. Trusted router list will be obtained from server. List will be refreshed every 7 days or during next connection session if an SDL enabled app has been installed or uninstalled.

119 Applying to the Trusted Router Service List To get your app onto the Trusted Router Service List, please contact the SDL Android channel on Slack or We'll need to test and review your app before approving it for the trusted list. Handling a Language Change O T E This guide applies if your app uses the Multiplex Bluetooth transport When a user changes the language on a head unit, the onproxyclosed() callback will be called in your app's Sdl Service and your app will disconnect from Core. In order for your app to automatically reconnect to the head unit, there are a few changes to make in the following files: local Sdl Broadcast Receiver local Sdl Service O T E This guide assumes you have set your app up for Bluetooth Multiplexing using the Upgrading to Multiplexing guide

120 Sdl Broadcast Receiver When the Sdl Service's connection to core is closed, we want to tell our local Sdl Broadcast Receiver to restart the Sdl Service. To do this, first add a public String in your app's local Sdl Broadcast Receiver class that can be included as an extra in a broadcast intent. public static final String RECOECT_LAG_CHAGE = "RECOECT_LAG_CHAGE"; Then, override the onreceive() method of the local Sdl Broadcast Receiver to call onsdlenabled() when receiving that public void onreceive(context context, Intent intent) { super.onreceive(context, intent); // Required if overriding this method if (intent!= null) { String action = intent.getaction(); if (action!= null){ if(action.equalsignorecase(transportconstants. START_ROUTER_SERVICE_ACTIO)) { if (intent.getbooleanextra(recoect_lag_chage, false )) { onsdlenabled(context, intent);

121 M U S T Be sure to call super.onreceive(context, intent); at the start of the method! O T E This guide also assumes your local Sdl Broadcast Receiver implements the onsdlenabled() method as public void onsdlenabled(context context, Intent intent) { intent.setclass(context, SdlService.class); context.startservice(intent); Sdl Service Without accounting for a language change, your Sdl Service's onproxyclosed() method probably looked similar to public void onproxyclosed(string info, Exception e, SdlDisconnectedReason reason) { stopself();

122 We want to tell our local Sdl Broadcast Receiver to restart the service when the reason for closing is a language change. To do so, modify the method as public void onproxyclosed(string info, Exception e, SdlDisconnectedReason reason) { stopself(); if(reason.equals(sdldisconnectedreason.laguage_chage)){ Intent intent = new Intent(TransportConstants. START_ROUTER_SERVICE_ACTIO); intent.putextra(sdlreceiver.recoect_lag_chage, true); sendbroadcast(intent); System Capability Manager The System Capability Manager is a central location to obtain capabilities about the currently connected module. Specific capabilities will be returned for a number of given keys (e.g. AVIGATIO, VIDEO_STREAMIG ). It also alleviates the need to individually cache results that come from the RegisterAp pinterface response or from the new SystemCapabilityQuery. There are multiple capabilities that can be retrieved:

123 S U P P O R T E D C A PA B I L I T I E S AVIGATIO PHOE_CALL VIDEO_STREAMIG REMOTE_COTROL HMI DISPLAY AUDIO_PASSTHROUGH BUTTO HMI_ZOE PRESET_BAK SOFTBUTTO SPEECH VOICE_RECOGITIO Querying Capabilities Any point after receiving the first OnHMIStatus notification from the connected module, you can access the SystemCapability manager and its data. Your instance of SdlProxyALM will have convenience methods that tie into the SystemCapabilityManager.

124 O T E It is important to query capabilities before you use them. Your app may be used on a variety of head units across different manufacturers and software versions. ever assume that a capability exists. For example (obtaining the head unit's AVIGATIO capability): // First you can check to see if the capability is supported on the module if (proxy.iscapabilitysupported(systemcapabilitytype.avigatio)){ // Since the module does support this capability we can query it for more information proxy.getcapability(systemcapabilitytype.avigatio, new public void oncapabilityretrieved(object capability){ avigationcapability navcapability = (avigationcapability) capability; // ow it is possible to get details on how this capability // is supported using the navcapability public void onerror(string info){ Log.i(TAG, "Capability could not be retrieved: "+ info); ); The returned capability needs to be casted into the capability type you requested. From there you can determine whether or not the head unit that the app is connected to can utilize a feature or not.

125 Capability Lists These are the current responses that come back as Lists: - AUDIO_PASSTHROUGH - BUTTO - SOFTBUTTO - SPEECH - HMI_ZOE - VOICE_RECOGITIO We've created a method in the SystemCapabilityManager to help cast these lists. Below is an example of its usage: public void getcapabilities() { proxy.getcapability(systemcapabilitytype.butto, new public void oncapabilityretrieved(object capability){ List<ButtonCapabilities> buttoncapabilitylist = SystemCapabilityManager.convertToList(capability, ButtonCapabilities. public void onerror(string info){ Log.i(TAG, "Capability could not be retrieved: "+ info); ); This method prevents the developer from having to suppress a warning as well as creates a safe way to cast the object to a list.

126 Asynchronous vs Synchronous Queries Some capabilities will be instantly available after the first OnHMIStatus notification. These are parsed from the RegisterAppInterface response. However, some capabilities MUST be obtained asynchronously and therefore require a callback to be obtained. If a capability can be retrieved synchronously another method can be used via the SdlProxyALM object, proxy.getcapability (SystemCapabilityType).

127 C A PA B I L I T Y A S Y C R E Q U I R E D AVIGATIO Yes PHOE_CALL Yes VIDEO_STREAMIG Yes REMOTE_COTROL Yes HMI o DISPLAY o AUDIO_PASSTHROUGH o BUTTO o HMI_ZOE o PRESET_BAK o SOFTBUTTO o SPEECH o VOICE_RECOGITIO o Remote Control Remote Control provides a framework to allow apps to control certain safe modules within a vehicle.

128 O T E ot all vehicles have this functionality. Even if they support remote control, you will likely need to request permission from the vehicle manufacturer to use it. WHY IS THIS HELPFUL? Consider the following scenarios: A radio application wants to use the in-vehicle radio tuner. It needs the functionality to select the radio band (AM/FM/XM/HD/DAB), tune the radio frequency or change the radio station, as well as obtain general radio information for decision making. A climate control application needs to turn on the AC, control the air circulation mode, change the fan speed and set the desired cabin temperature. A user profile application wants to remember users' favorite settings and apply it later automatically when the users get into the same/another vehicle. Currently, the Remote Control feature supports these modules: S U P P O R T E D R C M O D U L E S Radio Climate

129 The following table lists what control items are in each control module.

130 R C M O D U L E C O T R O L I T E M V A L U E R A G E T Y P E C O M M E T S Radio Radio Enabled true,false Get/Set/ otification read only, all other radio control items need radio enabled to work Radio Band AM,FM,XM Get/Set/ otification Radio Frequency Get/Set/ otification value range depends on band Radio RDS Data Get/ otification read only Available HD Channel 1-3 Get/ otification read only Current HD Channel 1-3 Get/Set/ otification Radio Signal Strength Get/ otification read only Climate Signal Change Threshold Radio State Current Cabin Temperature Desired Cabin Temperature Acquiring, acquired, multicast, not_found Get/ otification Get/ otification Get/ otification Get/Set/ otification read only read only read only, value range depends on OEM value range depends on OEM AC Setting on, off Get/Set/ otification AC MAX Setting on, off Get/Set/ otification Air Recirculation Setting on, off Get/Set/ otification Auto AC Mode Setting on, off Get/Set/ otification Defrost Zone Setting front, rear, all, none Get/Set/ otification

131 R C M O D U L E C O T R O L I T E M V A L U E R A G E T Y P E C O M M E T S Dual Mode Setting on, off Get/Set/ otification Fan Speed Setting 0%-100% Get/Set/ otification Ventilation Mode Setting upper, lower, both, none Get/Set/ otification Remote Control can also allow mobile applications to send simulated button press events for the following common buttons in the vehicle. The system shall list all available buttons for Remote Control in the RemoteCon trolcapabilities. The capability object will have a List of ButtonCapabilities that can be obtained using getbuttoncapabilities().

132 R C M O D U L E C O T R O L B U T T O Climate AC AC MAX RECIRCULATE FA UP FA DOW TEMPERATURE UP TEMPERATURE DOW DEFROST DEFROST REAR DEFROST MAX UPPER VET LOWER VET Radio VOLUME UP VOLUME DOW EJECT SOURCE SHUFFLE REPEAT

133 Integration O T E For Remote Control to work, the head unit must support SDL Core Version 4.4 or newer SYSTEM CAPABILITY M U S T Prior to using any Remote Control RPCs, you must check that the head unit has the Remote Control capability. As you may encounter head units that do not support it, this check is important. To check for this capability, use the following call:

134 // First you can check to see if the capability is supported on the module if (proxy.iscapabilitysupported(systemcapabilitytype. REMOTE_COTROL)){ // Since the module does support this capability we can query it for more information proxy.getcapability(systemcapabilitytype.remote_cotrol, new public void oncapabilityretrieved(object capability){ RemoteControlCapabilities remotecontrolcapabilities = ( RemoteControlCapabilities) capability; // ow it is possible to get details on how this capability // is supported using the remotecontrolcapabilities public void onerror(string info){ Log.i(TAG, "Capability could not be retrieved: "+ info); ); GETTIG DATA It is possible to retrieve current data relating to these Remote Control modules. The data could be used to store the settings prior to setting them, saving user preferences, etc. Following the check on the system's capability to support Remote Control, we can actually retrieve the data. The following is an example of getting data about the RADIO module. It also subscribes to updates to radio data, which will be discussed later on in this guide.

135 GetInteriorVehicleData interiorvehicledata = new GetInteriorVehicleData(); interiorvehicledata.setmoduletype(moduletype.radio); interiorvehicledata.setsubscribe(true); interiorvehicledata.setonrpcresponselistener(new OnRPCResponseListener() public void onresponse(int correlationid, RPCResponse response) { GetInteriorVehicleData getresponse = (GetInteriorVehicleData) response; //This can now be used to retrieve data ); proxy.sendrpcrequest(interiorvehicledata); SETTIG DATA Of course, the ability to set these modules is the point of Remote Control. Setting data is similar to getting it. Below is an example of setting ClimateCont roldata.

136 Temperature temp = new Temperature(); temp.setunit(temperatureunit.fahreheit); temp.setvalue((float) 74.1); ClimateControlData climatecontroldata = new ClimateControlData(); climatecontroldata.setacenable(true); climatecontroldata.setacmaxenable(true); climatecontroldata.setautomodeenable(false); climatecontroldata.setcirculateairenable(true); climatecontroldata.setcurrenttemperature(temp); climatecontroldata.setdefrostzone(defrostzone.frot); climatecontroldata.setdualmodeenable(true); climatecontroldata.setfanspeed(2); climatecontroldata.setventilationmode(ventilationmode.both); climatecontroldata.setdesiredtemperature(temp); ModuleData moduledata = new ModuleData(); moduledata.setmoduletype(moduletype.climate); moduledata.setclimatecontroldata(climatecontroldata); SetInteriorVehicleData setinteriorvehicledata = new SetInteriorVehicleData(); setinteriorvehicledata.setmoduledata(moduledata); proxy.sendrpcrequest(setinteriorvehicledata); It is likely that you will not need to set all the data as it is in the example, so if there are settings you don't wish to modify, then you don't have to. BUTTO PRESSES Another unique feature of Remote Control is the ability to send simulated button presses to the associated modules, imitating a button press on the hardware itself. Simply specify the module, the button, and the type of press you would like:

137 ButtonPress buttonpress = new ButtonPress(); buttonpress.setmoduletype(moduletype.radio); buttonpress.setbuttoname(buttoname.eject); buttonpress.setbuttonpressmode(buttonpressmode.short); proxy.sendrpcrequest(buttonpress); SUBSCRIBIG TO CHAGES It is also possible to subscribe to changes in data associated with supported modules. To do so, during your GET request for data, simply add in setsubscribe (Boolean). To unsubscribe, send the request again with the boolean set to Fals e. A code sample for setting the subscription is in the GET example above. The response to a subscription will come in a form of a notification. You can receive this notification through the IProxyListenerALM that was supplied to the SdlProxyALM object; the method ononinteriorvehicledata will be called when the RPC is received. U S I G I P R OX Y L I S T E E RA L public void ononinteriorvehicledata(oninteriorvehicledata response) { //Perform action based on notification

138 S E T T I G O T I F I C AT I O L I S T E E R proxy.addonrpcotificationlistener(functionid. O_ITERIOR_VEHICLE_DATA, new OnRPCotificationListener() public void onotified(rpcotification notification) { OnInteriorVehicleData oninteriorvehicledata = ( OnInteriorVehicleData)notification; //Perform action based on notification ); Proguard Guidelines k and its dependent libraries are open source and not intended to be obfuscated. When using Proguard in an app that integrates k, it is necessary to follow these guidelines. Required Proguard Rules Apps that are code shrinking a release build with Proguard typically have a section resembling this snippet in their build.gradle : android { buildtypes { release { minifyenabled true proguardfiles getdefaultproguardfile('proguard-android.txt'), 'proguard-rules.pro'...

139 Developers using Proguard in this manner should be sure to include the following lines in their proguard-rules.pro file: -keep class com.smartdevicelink.** { *; -keep class com.livio.** { *; O T E Failure to include these Proguard rules may result in a failed build or cause issues during runtime. Updating to 4.4 (Upgrading To Multiplexing) This guide is to help developers get setup with the SDL Android library 4.4. Upgrading apps to utilize the multiplexing transport flow will require us to do a few steps. This guide will assume the SDL library is already integrated into the app. We will make changes to: SdlService SdlRouterService (new) SdlBroadcastReceiver MainActivity

140 k Service The k proxy object instantiation needs to change to the new constructor. We also need to check for a boolean extra supplied through the intent that started the service. The old instantiation should look similar to this: proxy = new SdlProxyALM(this, APP_AME, true, APP_ID); The new constructor should look like this

141 public class SdlService extends Service implements IProxyListenerALM { public int onstartcommand(intent intent, int flags, int startid) { boolean forceconnect = intent!=null && intent.getbooleanextra( TransportConstants.FORCE_TRASPORT_COECTED, false); if (proxy == null) { try { //Create a new proxy using Bluetooth transport //The listener, app name, //whether or not it is a media app and the applicationid are supplied. proxy = new SdlProxyALM(this.getBaseContext(),this, APP_AME, true, APP_ID); catch (SdlException e) { //There was an error creating the proxy if (proxy == null) { //Stop the SdlService stopself(); else if(forceconnect){ proxy.forceonconnected(); //use START_STICKY because we want the SDLService to be explicitly started and stopped as needed. return START_STICKY; otice we now gather the extra boolean from the intent and add to our if-else statement. If the proxy is not null, we need to check if the supplied boolean extra is true and if so, take action. if (proxy == null) { //... else if(forceconnect){ proxy.forceonconnected();

142 k Router Service (ew) The SdlRouterService will listen for a bluetooth connection with an SDL enabled module. When a connection happens, it will alert all SDL enabled apps that a connection has been established and they should start their SDL services. We must implement a local copy of the SdlRouterService into our project. The class doesn't need any modification, it's just important that we include it. We will extend the com.smartdevicelink.transport.sdlrouterservice in our class named SdlRouterService : O T E Do not include an import for com.smartdevicelink.transport.sdlrou terservice. Otherwise, we will get an error for 'SdlRouterService' is already defined in this compilation unit. public class SdlRouterService extends com.smartdevicelink.transport. SdlRouterService { //othing to do here M U S T The local extension of the com.smartdevicelink.transport.sdlrouter Service must be named SdlRouterService.

143 M U S T Make sure this local class (SdlRouterService.java) is in the same package of SdlReceiver.java (described below) If you created the service using the Android Studio template then the service should have been added to your AndroidManifest.xml otherwise the service needs to be added in the manifest. Because we want our service to be seen by other SDL enabled apps, we need to set android:exported="true". The system may issue a lint warning because of this, so we can suppress that using tools:i gnore="exportedservice". Once added, it should be defined like below: <manifest xmlns:android=" android" package="com.company.mysdlapplication"> <application>... <service android:name= "com.company.mysdlapplication.sdlrouterservice" android:exported="true" android:process="com.smartdevicelink.router" tools:ignore="exportedservice"> </service> </application>... </manifest>

144 M U S T The SdlRouterService must be placed in a separate process with the name com.smartdevicelink.router. If it is not in that process during it's start up it will stop itself. k Broadcast Receiver The k Android Library now includes a base BroadcastReceiver that needs to be used. It's called SdlBroadcastReceiver. Our old BroadcastReceiver will just need to extend this class instead of the Android BroadcastReceiver. Two abstract methods will be automatically populate the class, we will fill them out soon. public class SdlReceiver extends SdlBroadcastReceiver public void onsdlenabled(context context, Intent intent) public Class<? extends SdlRouterService> definelocalsdlrouterclass () {... ext, we want to make sure we supply our instance of the SdlBroadcastService with our local copy of the SdlRouterService. We do this by simply returning the class object in the method definelocalsdlrouterclass:

145 public Class<? extends SdlRouterService> definelocalsdlrouterclass () { //Return a local copy of the SdlRouterService located in your project return com.company.mysdlapplication.sdlrouterservice.class; We want to start the SDL Proxy when an SDL connection is made via the SdlRo uterservice. This is likely code included on the onreceive method call previously. We do this by taking action in the onsdlenabled method: O T E The actual package definition for the SdlRouterService might be different. Just make sure to return your local copy and not the class object from the library itself.

146 public class SdlReceiver extends SdlBroadcastReceiver public void onsdlenabled(context context, Intent intent) { //Use the provided intent but set the class to the SdlService intent.setclass(context, SdlService.class); public Class<? extends SdlRouterService> definelocalsdlrouterclass () { //Return a local copy of the SdlRouterService located in your project. return com.company.mysdlapplication.sdlrouterservice.class; O T E The onsdlenabled method will be the main start point for our SDL connection session. We define exactly what we want to happen when we find out we are connected to SDL enabled hardware. M U S T SdlBroadcastReceiver must call super if onreceive is overridden

147 @Override public void onreceive(context context, Intent intent) { super.onreceive(context, intent); //your code here ow we need to add two extra intent actions to or our intent filter for the SdlBroadcastReceiver: android.bluetooth.adapter.action.state_chaged sdl.router.startservice

148 <manifest xmlns:android=" android" package="com.company.mysdlapplication"> <application>... <receiver android:name=".sdlreceiver" android:exported="true" android:enabled="true"> <intent-filter> <action android:name= "android.bluetooth.device.action.acl_coected" /> <action android:name= "android.bluetooth.device.action.acl_discoected"/> <action android:name= "android.bluetooth.adapter.action.state_chaged"/> <action android:name= "android.media.audio_becomig_oisy" /> <action android:name="sdl.router.startservice" /> </intent-filter>... </receiver> </application> </manifest> M U S T SdlBroadcastReceiver has to be exported, or it will not work correctly

149 Main Activity Our previous MainActivity class probably looked similar to this: public class MainActivity extends Activity protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.activity_main); // Start the SDLService Intent sdlserviceintent = new Intent(this, SdlService.class); startservice(sdlserviceintent); However now instead of starting the service every time we launch the application we can do a query that will let us know if we are connected to SDL enabled hardware or not. If we are, the onsdlenabled method in our SdlBroadcastReceiver will be called and the proper flow should start. We do this by removing the intent creation and startservice call and instead replace them with a single call to SdlReceiver.queryForConnectedService(Context). public class MainActivity extends Activity protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.activity_main); //If we are connected to a module we want to start our SdlService SdlReceiver.queryForConnectedService(this);

150 Updating from 4.4 to 4.5 This guide is to help developers get setup with the SDL Android library 4.5. It is assumed that the developer is already updated to 4.4 of the library. There are a few very important changes that we need to make to the integration to keep things working well. The first is a few new additions to the AndroidManifest.xml and the SdlRouterService entry. ext, we have to prepare for Android Oreo's push towards foreground services. We will make changes to: AndroidManifest.xml SdlService SdlBroadcastReceiver AndroidManifest.xml Updates Assuming the manifest was up to date with version 4.4 requirements we need to add an intent-filter and a meta-data item. The entire entry should look as follows:

151 <manifest xmlns:android=" android" package="com.company.mysdlapplication"> <application>... <service android:name= "com.company.mysdlapplication.sdlrouterservice" android:exported="true" android:process="com.smartdevicelink.router" tools:ignore="exportedservice"> <intent-filter> <action android:name="com.smartdevicelink.router.service"/ > </intent-filter> <meta-data sdl_router_service_version_name" sdl_router_service_version_value" /> </service> </application>... </manifest> Intent Filter <intent-filter> <action android:name="com.smartdevicelink.router.service"/> </intent-filter> The new versions of the SDL Android library rely on the com.smartdevicelink.ro uter.service action to query SDL enabled apps that host router services. This allows the library to determine which router service to start.

152 M U S T This intent-filter MUST be included. Metadata ROUTER SERVICE VERSIO <meta-data android:name="@string/sdl_router_service_version_name" android:value="@integer/sdl_router_service_version_value" /> Adding the sdl_router_service_version metadata allows the library to know the version of the router service that the app is using. This makes it simpler for the library to choose the newest router service when multiple router services are available. CUSTOM ROUTER SERVICE <meta-data android:name="@string/ sdl_router_service_is_custom_name" android:value="false" />

153 O T E This is only for specific OEM applications, therefore normal developers do not need to worry about this. Some OEMs choose to implement custom router services. Setting the sdl_route r_service_is_custom_name metadata value to true means that the app is using something custom over the default router service that is included in the SDL Android library. Do not include this meta-data entry unless you know what you are doing. Android Oreo's Push To Foreground Services Previous versions of Android allowed our SDL app partners to start their SDL services in the background and attach themselves to the foregrounded SDL router service. Android Oreo (API 26) has changed that. Due to new OS limitations, apps must start their SDL service in the foreground. What do I need to do? There are a few changes to make, one in the SdlBroadcastReceiver and the other in the SdlService (or which service the proxy is implemented). SDLBROADCASTRECEIVER

154 P R E V I O U S V E R S I public void onsdlenabled(context context, Intent intent) { Log.d(TAG, "SDL Enabled"); intent.setclass(context, SdlService.class); context.startservice(intent); S A M P L E U P D AT public void onsdlenabled(context context, Intent intent) { Log.d(TAG, "SDL Enabled"); intent.setclass(context, SdlService.class); if(build.versio.sdk_it < Build.VERSIO_CODES.O) { context.startservice(intent); else{ context.startforegroundservice(intent); This means the app will start the SDL service in the background if we are on a device that uses Android or earlier. If the app is running on Android Oreo or newer, the service will make a promise to the OS that the service will move into

155 the foreground. If the service doesn't explicitly move into the foreground an exception will be thrown. SDLSERVICE (OR SIMIL AR) Within the SdlService class or similar you will need to add a call to start the service in the foreground. This will include creating a notification to sit in the status bar tray. This information and icons should be relevant for what the service is doing/going to do. If you already start your service in the foreground, you can ignore this section. public void oncreate() { super.oncreate();... otificationmanager notificationmanager = (otificationmanager) getsystemservice(context.otificatio_service); notificationmanager.createotificationchannel(...); otification serviceotification = new otification.builder(this, * otification Channel*).setContentTitle(...).setSmallIcon(...).setLargeIcon(...).setContentText(...).setChannelId(channel.getId()).build(); startforeground(id, serviceotification);

156 EXITIG THE FOREGROUD It's important that you don't leave you notification in the notification tray as it is very confusing to users. So in the ondestroy method in your service, simply call the stopforeground public void ondestroy(){ //... if(build.versio.sdk_it>=build.versio_codes.o){ otificationmanager notificationmanager = (otificationmanager) getsystemservice(context.otificatio_service); if(notificationmanager!=null){ //If this is the only notification on your channel notificationmanager.deleteotificationchannel(* otification Channel*); stopforeground(true); otification Suggestions We realize that pushing a notification to the notification tray is not ideal for any apps, but with Android's push for more transparency to users it's important that we don't try to workaround that. Android is getting stricter with their guidelines

157 and could potentially prevent apps from being released if they are found to be not adhering to these rules. THE CORRECT WAY The right way to handle the new foreground service requirement is to simply push a full fledged notification to the notification tray. H o w t o d o i public void oncreate() { super.oncreate();... if(build.versio.sdk_it >= Build.VERSIO_CODES.O) { otificationmanager notificationmanager = (otificationmanager ) getsystemservice(context.otificatio_service); otificationchannel channel = new otificationchannel( "MyApp", "SdlService", otificationmanager.importace_default); notificationmanager.createotificationchannel(channel); otification serviceotification = new otification.builder(this, channel.getid()).setcontenttitle("myapp is connected through SDL").setSmallIcon(R.drawable.ic_launcher_foreground).build(); startforeground(id, serviceotification); THE OT SO CORRECT WAY Currently Android Oreo allows a notification to be used that has not declared a notification channel. This results in the notification icon not actually appearing on its own. Instead it is grouped together into the notification channel that

158 reads "# apps are using battery" from the Android System. This is likely to prevent breaking changes from apps that have not updated their integration to Android Oreo, however, we fully anticipate this to be changed in the future so it is not recommended. H o w t o d o i public void oncreate() { super.oncreate();... if(build.versio.sdk_it >= Build.VERSIO_CODES.O) { otification serviceotification = new otification.builder(this, "ochannel").setcontenttitle("myapp is connected through SDL").setSmallIcon(R.drawable.ic_launcher_foreground).build(); startforeground(id, serviceotification);

159 H o w i t l o o k s THE ABSOLUTELY OT CORRECT WAY It is possible to create a somewhat invisible notification. This will appear to just be blank space in the notification tray. With adding minimal content to the notification when the user pulls down the tray it will have a very small footprint on the screen. However, this is completely disingenuous to the user and should

160 not be considered a solution. Android will most likely see this as bad behavior and could prevent you from releasing your app or even remove your app from the play store with a ban included. Don't do this. H o w t o d o i public void oncreate() { super.oncreate();... if(build.versio.sdk_it >= Build.VERSIO_CODES.O) { otificationmanager notificationmanager = (otificationmanager ) getsystemservice(context.otificatio_service); otificationchannel channel = new otificationchannel( "MyApp", "SdlService", otificationmanager.importace_default); notificationmanager.createotificationchannel(channel); otification serviceotification = new otification.builder(this, channel.getid()).setsmallicon(r.drawable.sdl_tray_invis).build(); startforeground(id, serviceotification);

161 H o w i t l o o k s Updating from 4.5 to 4.6 This guide is to help developers get setup with the SDL Android library 4.6. It is assumed that the developer is already updated to 4.5 of the library. There are a few important changes that we need to make to the integration to keep things working well. The first is removing some of the BroadcastReceiver's intent filters in AndroidManifest.xml that are now unneccessary. Secondly, the gradle

162 integration of our library should now use implementation instead of compile. Lastly, the RPCRequestFactory class has been deprecated and constructors with mandatory parameters have been added for each RPC class. We will make changes to: AndroidManifest.xml build.gradle any usage of RPCRequestFactory AndroidManifest.xml Updates Assuming the manifest was up to date with version 4.5, we can now remove some of the intent-filters ( ACL_DISCOECTED, STATE_CHAGED, AUDIO_B ECOMIG_OISY ) for your app's BroadcastReceiver. The BroadcastReceiver section of the manifest should look as follows:

163 <manifest xmlns:android=" android" package="com.company.mysdlapplication"> <application>... <receiver android:name=".sdlreceiver" android:exported="true" android:enabled="true"> <intent-filter> <action android:name= "android.bluetooth.device.action.acl_coected" /> <action android:name="sdl.router.startservice" /> </intent-filter>... </receiver> </application> </manifest> Gradle Update The previous way of including the libary via compile should now use impleme ntation. The dependencies section of your app's build.gradle file should now appear as: dependencies { implementation 'com.smartdevicelink:sdl_android:4.+'

164 Deprecation of RPCRequestFactory The RPCRequestFactory has been deprecated in 4.6. To build RPC requests, developers should use the constructors in the desired RPC request class. For example, instead of using RPCRequestFactory.buildAddCommand(...) to build an AddCommand request, try the following: AddCommand addcommand = new AddCommand(100); addcommand.setmenuparams(new MenuParams("Skip")); proxy.sendrpcrequest(addcommand); AddCommand Adds a Command to the application's Command Menu. A Command will be added to the end of the list of elements in the Command Menu under the following conditions: When a Command is added with no MenuParams value provided When a MenuParams value is provided with a MenuParam.position value greater than or equal to the number of menu items currently defined in the menu specified by the MenuParam.parentID value The set of choices which the application builds using AddCommand can be a mixture of: Choices having only VR synonym definitions, but no MenuParams definitions Choices having only MenuParams definitions, but no VR synonym definitions

165 Choices having both MenuParams and VR synonym definitions When a user initiates an interaction, the user may choose from whatever choices are defined at that moment. It is up to the application to ensure that all appropriate choices are defined before the user initiates an interaction. ote: A consequence of this is that it is possible for the application to be in the middle of adding commands (or submenu items) when the user presses the PTT or Menu button and only the commands added up to that moment will be available for the user to choose from (either by VR or Menu). It is possible in this situation for the user to not have had all intended options available when they started the interaction. The application will receive an OnHMIStatus with a SystemContext value of VRSESSIO or MEU indicating that such a userinitiated interaction has begun. The application can make use of this notification to know that, if it is still building a Command Menu using AddCommand/AddSubMenu, the results of the interaction should be discarded. This approach is necessary because there is no way to "cancel" an interaction in progress (neither a user initiated interaction, nor an app-initiated interaction). ote: smartdevicelink batches together AddCommand and AddSubMenu requests before making them available for selection by the user via PTT or the menu. The end of a batch of successive AddCommand/AddSubMenu requests is defined as 500 milliseconds passing with no further AddCommand/AddSubMenu requests arriving at SDL. When the batch of requests has ended, SDL then prepares these commands for use by the user. A command should be available for use 1 second after the end of the batch in which that command was added (timing based batch size). ote: Commands should be grouped by using position id. If you are planning to create child commands of a parent command to keep the commands grouped together. Add the commands to the top level menu (basically the root); you can pass in a 0 for the parentid. If you would like to add the commands to a submenu, then the submenuid is passed in for the parentid. The position ID can be used to sort the commands in the menu. However, the logic isn't always straightforward. The position is relative to the commands that are currently in existence. However, once commands are added, they drop the Position parameter and the sync hardware just tracks their sequential order.

166 For example: send add: command1, Position 5 send add: command2, Position 10 send add: command3, Position 20 Results in on tdk: command1, command2, command3 If you then followed up with: send add: command4, Position 1 You get the following result on the TDK: command1, command4, command2, command3 There are a few other noteworthy consequences of MenuParams for a given command: - Commands that do not have vrcommands associated with them will not be accessible by voice commands (when the user hits push-to-talk). - Commands that do not have menuparams associated with them will not be accessible through the HMI application menu HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T Parameter List

167

168 Param ame cmdid menupa rams vrcom mands cmdico n Type Integer Buttona me String Image Descript ion unique ID of the command to add ame of the button to unsubscri be. An array of strings to be used as VR synonym s for this comman d. If this array is provided, it may not be empty. Image struct determini ng whether static or dynamic icon. If omitted on supporte d displays, no (or the default if applicabl e) icon shall be displaye d. Req. Y Y otes minvalue: 0 maxvalu e: minsize:1 maxsize: 100 Versio n Availab le k 1.0 k 1.0 k 1.0 k 1.0 R E S P O S E Indicates that the corresponding request has failed or succeeded, if the response returns with a SUCCESS result code, this means a command was added to the Command Menu successfully.

169 on-default Result Codes: SUCCESS IVALID_DATA OUT_OF_MEMORY TOO_MAY_PEDIG_REQUESTS APPLICATIO_OT_REGISTERED GEERIC_ERROR REJECTED IVALID_ID DUPLICATE_AME USUPPORTED_RESOURCE DISALLOWED Related Operations DeleteCommand AddSubMenu DeleteSubMenu Example Function Call AddCommand addcommand = new AddCommand(100); addcommand.setmenuparams(new MenuParams("Skip")); proxy.sendrpcrequest(addcommand); DeleteCommand Removes a command from the Command Menu

170 For a discussion of conflict with user-initiated interaction, see AddCommand. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T Parameter List ame Type Descript ion Reg. otes Versio n cmdid Integer Unique ID that identifies the Comman d to be deleted from Comman d Menu Y Min Value: 0 Max Value: k 1.0

171 R E S P O S E Indicates that the corresponding request either failed or succeeded. If the response returns with a SUCCESS result code, this means a command was removed from the Command Menu successfully. on-default Result Codes: SUCCESS IVALID_DATA OUT_OF_MEMORY TOO_MAY_PEDIG_REQUESTS APPLICATIO_OT_REGISTERED GEERIC_ERROR REJECTED IVALID_ID I_USE Related Operations AddCommand AddSubMenu DeleteSubMenu Example Function Call DeleteCommand deletecommand = new DeleteCommand(commandID ); proxy.sendrpcrequest(deletecommand);

172 AddSubMenu Adds a SubMenu to the Command Menu A SubMenu can only be added to the Top Level Menu (i.e. a SubMenu cannot be added to a SubMenu), and may only contain commands as children. For a discussion of conflict with user-initiated interaction, see AddCommand. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T Parameter List

173 Param ame menuid position menu ame Type Integer Integer String Descript ion Unique ID that identifies this sub menu. This value is used in AddCom mand to which SubMenu is the parent of the command being added. Position within the items of the top level Comman d Menu. 0 will insert at the front, 1 will insert after the first existing element, etc. Position of any submenu will always be located before the return and exit options. Text which is displayed represent ing this submenu item Req. Y Y otes Min Value: 0 Max Value: 1000 If position is greater or equal than the number of items on top level, the sub menu will be appended by the end. If this paramete r is omitted, the entry will be added at the end of the list. maxlengt h:500 Versio n Availab le k 1.0 k 1.0 k 1.0

174 R E S P O S E Indicates that the corresponding request either failed or succeeded. If the response returns with a SUCCESS result code, this means the SubMenu was added to the Command Menu successfully on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - IVALID_ID - DUPLICATE_AME Related Operations - DeleteSubMenu - AddCommand - DeleteCommand Example Function Call AddSubMenu addsubmenu = new AddSubMenu(menuID, menuame); proxy.sendrpcrequest(addsubmenu);

175 DeleteSubMenu Deletes a submenu from the Command Menu. For a discussion of conflict with user-initiated interaction, see AddCommand. When an app deletes a submenu that has child commands, those child commands are also deleted. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T Parameter List

176 ame Type Descript ion Reg. otes Versio n menuid Integer Unique ID that identifies the SubMenu to be delete Y Min Value: 0 Max Value: k 1.0 R E S P O S E on-default Result Codes: SUCCESS IVALID_DATA OUT_OF_MEMORY TOO_MAY_PEDIG_REQUESTS APPLICATIO_OT_REGISTERED GEERIC_ERROR REJECTED IVALID_ID I_USE Related Operations AddCommand AddSubMenu DeleteCommand Example Function Call DeleteSubMenu deletesubmenu = new DeleteSubMenu(menuID); proxy.sendrpcrequest(deletesubmenu);

177 Alert Provides information to the user using either TTS, the Display or both and can include a system-generated alert tone. The displayed portion of the Alert, if any, will persist until the specified timeout has elapsed, or the Alert is preempted. An Alert will preempt (abort) any smartdevicelink Operation that is inprogress, except an already-in-progress Alert. An Alert cannot be preempted by any smartdevicelink Operation. An Alert can be preempted by a user action (button push). An Alert will fail if it is issued while another Alert is in progress. Assuming it's coming from the same app, the current Alert gets ABORTED and the new Alert will get displayed/audible. Although each Alert parameter is optional, in fact each Alert request must supply at least one of the following parameters: alerttext1 alerttext2 alerttext3 ttschunks HMI Status Requirements HMILevel needs to be FULL or LIMITED. If the app has been granted function group otification the HMILevel can also be BACKGROUD R E Q U E S T

178

179

180 ame alerttex t1 alerttex t2 alerttex t3 ttschun ks Type String String String TTSChunk [] Descript ion Text to be displayed in the first field of the display during the Alert. Text to be displayed in the second field of the display during the Alert. Text to be displayed in the third field of the display during the Alert. Array of type TTSChunk which, taken together, specify what is to be spoken to the user. Req. otes Length is limited to what is indicated in RegisterA ppinterfa ce response. If omitted, top display line will be cleared. Text is always centered Only permitted if HMI supports a second display line. Length is limited to what is indicated in RegisterA ppinterfa ce response. If omitted, second display line will be cleared. Array must have a least one element. Array must have a least one element. Versio n Availab le k 1.0 k 1.0 k 1.0 k 1.0

181 duratio n playton e softbutt ons Integer Boolean SoftButto n[] The duration of the displayed portion of the alert, in millisecon ds. After this amount of time has passed, the display fields alerttext1 and alerttext2 will revert to what was displayed in those fields before the alert began. Specifies whether the alert tone should be played before the TTS (if any) is spoken. Specifies the softbutto ns, the apps wants to use in this alert. Min Value: 3000 Max Value: If omitted, the default is 5000 millisecon ds If omitted, default is true. If omitted on supporte d displays, the alert will not have any SoftButto n. ArrayMin: 0 ArrayMa x: 4 k 1.0 k 1.0 k 1.0

182 progres sindicat or Boolean If supporte d on the given platform, the alert GUI will include some sort of animation indicating that loading of a feature is progressi ng. e.g. a spinning wheel or hourglas s, etc. k 1.0 R E S P O S E If a resultcode of "SUCCESS" is returned, the request was accepted by SDL. By the time the corresponding response is received, the Alert will have completed. on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - ABORTED - DISALLOWED - USER_DISALLOWED - USUPPORTED_RESOURCE

183 ame tryagai ntime Type Integer Descript ion Amount of time (in seconds) that an app must wait before resending an alert. Req. otes If provided, another system event or overlay currently has a higher priority than this alert. An app must not send an alert without waiting at least the amount of time dictated. Versio n Availab le smartde vicelink 1.0 Related Operations Show Speak

184 Example Function Call Alert alert = new Alert(); alert.setalerttext1("alert1"); alert.setduration(10); alert.setplaytone(true); proxy.sendrpcrequest(alert); CreateInteractionChoiceSet Creates a Choice Set which can be used in subsequent PerformInteraction Operations. A Choice Set is a list of commands (menu or voice) that can be used in certain operations to gain input from the user. Multiple Choices with the same id can be added to SDL from one application. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T

185 ame Type Descript ion Reg. otes Versio n interact ionchoi cesetid choices et Integer Choice[] A unique ID that identifies the Choice Set Array of one or more elements. Y Y Min Value: 0 Max Value: Min Value: 1 Max Value: 100 k 1.0 k 1.0 ote: Second Utterance issue with CreateInteractionChoiceSet RPC. Before a perform interaction is sent you MUST wait for the success from the CreateInteractionChoiceSet RPC. If you do not wait the system may not recognize the first utterance from the user. Response Indicates that the corresponding request either failed or succeeded. If the response returns with a SUCCESS result code, this means the Choice Set was created. on-default Result Codes:

186 - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - IVALID_ID - DUPLICATE_AME - USUPPORTED_RESOURCE Related Operations - DeleteInteractionChoiceSet - PerformInteraction Example Function Call CreateInteractionChoiceSet choiceset = new CreateInteractionChoiceSet(choiceSetID, choicesetlist); proxy.sendrpcrequest(choiceset);

187 DeleteInteractionChoiceSet Deletes an existing Choice Set identified by the parameter interactionchoicesetid. If the specified interactionchoicesetid is currently in use by an active PerformInteraction, this call to delete the Choice Set will fail returning an I_USE resultcode. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T

188 ame Type Descript ion Reg. otes Versio n interact ionchoi cesetid Integer A unique ID that identifies the Choice Set (specified in a previous call to CreateInt eractionc hoiceset) Y Min Value: 0 Max Value: k 1.0 R E S P O S E If a resultcode of "SUCCESS" is returned, the requested choice set has been created and can now be referenced by the application using the value of interactionchoicesetid provided by the application. O-DEFAULT RESULT CODES: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - IVALID_ID - I_USE

189 Related Operations CreateInteractionChoiceSet PerformInteraction Example Function Call DeleteInteractionChoiceSet deletechoiceset = new DeleteInteractionChoiceSet(choiceSetId); proxy.sendrpcrequest(deletechoiceset); RegisterAppInterface Registers the application's interface with SDL, declaring properties of the registration, including the messaging interface version, the app name, etc. The mobile application must establish its interface registration with SDL before any other interaction with SDL can take place. The registration lasts until it is terminated either by the application calling the UnregisterAppInterface method, or by SDL sending an OnAppInterfaceUnregistered notification, or by loss of the underlying transport connection, or closing of the underlying message transmission protocol RPC session. Until the application receives its first OnHMIStatus otification, its HMI Status is assumed to be: HMILevel=OE, AudioStreamingState=OT_AUDIBLE, Sys temcontext=mai. All SDL resources which the application creates or uses (e.g. Choice Sets, Command Menu, etc.) are associated with the application's interface registration. Therefore, when the interface registration ends, the SDL resources

190 associated with the application are disposed of. As a result, even though the application itself may continue to run on its host platform (e.g. mobile device) after the interface registration terminates, the application will not be able to use the SDL HMI without first establishing a new interface registration and recreating its required SDL resources. That is, SDL resources created by (or on behalf of) an application do not persist beyond the life span of the interface registration. Resources and settings whose lifespan is tied to the duration of an application's interface registration: - Choice Sets - Command Menus (built by successive calls to AddCommand) - Media clock timer display value - Media track display value - Button subscriptions The autoactivateid is used to grant an application the HMILevel and AudioStreamingState it had when it last disconnected. ote: The autoactivateid parameter, and associated behavior, is currently ignored by SDL. When first calling this method (i.e. first time within life cycle of mobile app), an autoactivateid should not be included. After successfully registering an interface, an autoactivateid is returned to the mobile application for it to use in subsequent connections. If the connection between SDL and the mobile application is lost, such as the vehicle is turned off while the application is running, the autoactivateid can then be passed in another call to RegisterAppInterface to re-acquire HMILevel=FULL. If the application intends to stream audio it is important to indicate so via the ismediaapp parameter. When set to true, audio will reliably stream without any configuration required by the user. When not set, audio may stream, depending on what the user might have manually configured as a media source on SDL. There is no time limit for how long the autoactivateid is "valid" (i.e. would confer focus and opt-in)

191 HMI Status Requirements HMILevel is not defined before registering. R E Q U E S T

192

193

194 ame Type Descript ion Reg. otes Versio n

195 MsgVer sion MsgVersi on Declares what version of the SDL interface the applicatio n expects to use with SDL Y To be compatibl e, app msg major version number must be less than or equal to SDL major version number. If msg versions are incompati ble, app has 20 seconds to attempt successfu l RegisterA ppinterfa ce (w.r.t. msg version) on underlyin g protocol session, else will be terminate d. Major version number is a compatibi lity declaratio n. Minor version number indicates minor functional variations (e.g. features, capabiliti es, bug fixes) when sent from SDL to app (in RegisterA ppinterfa ce response ). However, the minor version number sent from the app to SDL (in RegisterA ppinterfa ce k 1.0

196 appa me ttsam e ngnmed iascree nappa me String TTSChunk String The mobile applicatio n's name. This name is displayed in the SDL Mobile Applicatio ns menu. It also serves as the unique identifier of the applicatio n for SDL. TTS string for VR recognitio n of the mobile applicatio n name. Meant to overcome any failing on speech engine in properly pronounci ng / understa nding app name. Provides an abbreviat ed version of the app name (if necessar y) that will be displayed on the G media screen. Y - Must be character s in length. - Must consist of following character s: - May not be the same (by case insensitiv e comparis on) as the name or any synonym of any currentlyregistere d applicatio n. - Size must be eeds to be unique over all applicatio ns - May not be empty. - May not start with a new line character. - Must be 1-5 character s - If not provided, value will be derived from appame truncated to 5 character s. k 1.0 k 2.0 k 1.0

197 vrsynon yms ismedia Applicat ion String Boolean An array of elements, each element containin g a voicerecognitio n synonym by which this app can be called when being addresse d in the mobile applicatio ns menu. Indicates that the applicatio n will be streamin g audio to SDL (via A2DP) that is audible outside of the BT media source. Y - Each vr synonym is limited to 40 character s, and there can be synonym s in array- May not be the same (by case insensitiv e comparis on) as the name or any synonym of any currentlyregistere d applicatio n. k 1.0 k 1.0

198 languag edesire d hmidisp laylang uagede sired apphmi Type Language Language AppHMITy pe An enumerat ion indicating what language the applicatio n intends to use for user interactio n (Display, TTS and VR). An enumerat ion indicating what language the applicatio n intends to use for user interactio n ( Display). List of all applicabl e app types stating which classificat ions to be given to the app.e.g. for platforms this will determin e which "corner (s)" the app can populate Y Y - If the language indicated does not match the active language on SDL, the interface registrati on will be rejected. - If the user changes the SDL language while this interface registrati on is active, the interface registrati on will be terminate d. Array Minsize: 1 Array Maxsize: 100 k 1.0 k 2.0 k 2.0

199 hashid devicei nfo appid String DeviceInf o String ID used to uniquely identify current state of all app data that can persist through connectio n cycles (e.g. ignition cycles). This registere d data (comman ds, submenu s, choice sets, etc.) can be reestablis hed without needing to explicitly reregister each piece. If omitted, then the previous state of an app's command s, etc. will not be restored. When sending hashid, all RegisterA ppinterfa ce paramete rs should still be provided (e.g. ttsame, etc.). Various informati on about connectin g device. ID used to validate app with policy table entries Y maxlengt h:100 Maxlengt h: 100 k k k 2.0

200 R E S P O S E The response message contains essential information about the SDL system that the request was sent to. This information can be used by an application to alter functionality depending on which type of SDL system it is running on. For instance, an application can use the displaycapabilities parameter to see whether the SDL HMI offers a touch screen, a two-line display, or a one-line display. The application could then use that information to make sure that the text written to the screen is readable for the given platform. If a resultcode other than SUCCESS is received, the application will have to send one or more RegisterAppInterface Requests until one has a result code of SUCCESS; otherwise, the application is not permitted to send any other Requests. on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - GEERIC_ERROR - DUPLICATE_AME - TOO_MAY_APPLICATIOS - APPLICATIO_REGISTERED_ALREADY - USUPPORTED_VERSIO - WROG_LAGUAGE - DISALLOWED Related Operations - UnregisterAppInterface - OnAppInterfaceUnregistered

201 Example Function Call RegisterAppInterface registerappinterface = new RegisterAppInterface( syncmsgversion, appame, ismediaapplication, languagedesired, hmidisplaylanguagedesired, appid); proxy.sendrpcrequest(registerappinterface); UnregisterAppInterface Terminates an application's interface registration. This causes SDL to dispose of all resources associated with the application's interface registration (e.g. Command Menu items, Choice Sets, button subscriptions, etc.). After the UnregisterAppInterface operation is performed, no other operations can be performed until a new app interface registration is established by calling RegisterAppInterface. This operation will fail if no interface registration is currently in effect (i.e. no RegisterAppInterface operation was performed prior to this call). HMI Status Requirements HMILevel can be FULL, LIMITED, BACKGROUD or OE. R E Q U E S T

202

203

204

205

206 ame gps speed rpm fuellev el fuellev el_state instantf uelcons umption external Temper ature prndl Type Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Descript ion GPS data. See GPSData for details The vehicle speed in kilometer s per hour The number of revolution s per minute of the engine The fuel level in the tank (percenta ge) The fuel level state The instantan eous fuel consumpt ion in microlitre s The external temperat ure in degrees celsius Currently selected gear. Reg. otes Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Smart Device Link Versio n k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 tirepres sure Boolean Tire pressure status Subscriba ble k 2.0 odomet er beltstat us bodyinf ormatio n Boolean Boolean Boolean Odomete r in km The status of the seat belts The body informati on including ignition status and internal temp Max Length: 500 Subscriba ble Subscriba ble k 2.0 k 2.0 k 2.0

207 devices tatus driverbr aking wiperst atus headla mpstat us enginet orque accpeda lpositio n steering WheelA ngle ecallinf o airbags tatus emerge ncyeve nt cluster ModeSt atus Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean The device status including signal and battery strength The status of the brake pedal The status of the wipers Status of the head lamps Torque value for engine (in m) on nondiesel variants Accelerat or pedal position (percenta ge depresse d) Current angle of the steering wheel (in deg) Emergen cy Call notificatio n and confirmat ion data. The status of the air bags. Informati on related to an emergenc y event (and if it occurred ). The status modes of the instrume nt panel cluster. Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0

208 mykey Boolean Informati on related to the MyKey feature. Subscriba ble k 2.0 R E S P O S E Once this response is received, no other Operations will be accepted by SDL and no otifications will be sent by SDL. O-DEFAULT RESULT CODES: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR Related Operations RegisterAppInterface OnAppInterfaceUnregistered Example Function Call UnregisterAppInterface unregisterappinterface = new UnregisterAppInterface(); proxy.sendrpcrequest(unregisterappinterface);

209 Speak Speaks a phrase over the vehicle s audio system using SDL's TTS (text-tospeech) engine. The provided text to be spoken can be simply a text phrase, or it can consist of phoneme specifications to direct SDL's TTS engine to speak a "speech-sculpted" phrase. Receipt of the Response indicates the completion of the Speak operation, regardless of how the Speak operation may have completed (i.e. successfully, interrupted, terminated, etc.). Requesting a new Speak operation while the application has another Speak operation already in progress (i.e. no corresponding Response for that inprogress Speak operation has been received yet) will terminate the in-progress Speak operation (causing its corresponding Response to be sent by SDL) and begin the requested Speak operation. Requesting a new Speak operation while the application has an Alert operation already in progress (i.e. no corresponding Response for that in-progress Alert operation has been received yet) will result in the Alert operation being canceled (indicated in the Response to the Request). Requesting a new Alert operation while the application has a Speak operation already in progress (i.e. no corresponding Response for that in-progress Speak operation has been received yet) will terminate the in-progress Speak operation (causing its corresponding Response to be sent by SDL) and begin the requested Alert operation. Requesting a new Speak operation while the application has a PerformInteraction operation already in progress (i.e. no corresponding Response for that in-progress PerformInteraction operation has been received yet) will result in the Speak operation request being rejected (indicated in the Response to the Request). Requesting a PerformInteraction operation while the application has a Speak operation already in progress (i.e. no corresponding Response for that inprogress Speak operation has been received yet) will terminate the in-progress

210 Speak operation (causing its corresponding Response to be sent by SDL) and begin the requested PerformInteraction operation. ote: Total character limit depends on platform. Chunks are limited to 500 characters; however, you can have multiple TTS chunks. This could vary according to the VCA. HMI Status Requirements HMILevel:FULL, Limited AudioStreamingState:Any SystemContext:MAI, MEU, VR ote: When Alert is issued with MEU in effect, Alert is queued and "played" when MEU interaction is completed (i.e. SystemContext reverts to MAI). When Alert is issued with VR in effect, Alert is queued and "played" when VR interaction is completed (i.e. SystemContext reverts to MAI). ote: When both Alert and Speak are queued during MEU or VR, they are "played" back in the order in which they were queued, with all existing rules for "collisions" still in effect. R E Q U E S T

211 ame ttschun ks Type String Descript ion An array of TTSChunk structs which, taken together, specify the phrase to be spoken. Reg. Y otes The array must have elements. The total length of the phrase compose d from the ttschunks provided must be less than 500 character s or the request will be rejected. Each chunk can be no more than 500 character s. Ver. Availab le k 1.0 R E S P O S E This Response notifies the application of the completion, interruption, or failure of a Speak Request. on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - DISALLOWED - ABORTED

212 Related Operations Alert Example Function Call Speak speak = new Speak(ttsChunks); proxy.sendrpcrequest(speak); ResetGlobalProperties Resets the passed global properties to their default values as defined by SDL The HELPPROMPT global property default value is generated by SDL consists of the first vrcommand of each Command Menu item defined at the moment PTT is pressed. The TIMEOUTPROMPT global property default value is the same as the HELPPROMPT global property default value. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T Parameter List

213 Param ame properti es Type GlobalPro perty Descript ion An array of one or more GlobalPro perty enumerat ion elements indicating which global propertie s to reset to their default value. Req. Y otes Array must have at least one element. minsize:1 maxsize: 100 Versio n Availab le k 1.0 R E S P O S E Indicates whether the Global Properties were successfully set to their default values. on-default Result Codes: SUCCESS IVALID_DATA OUT_OF_MEMORY TOO_MAY_PEDIG_REQUESTS

214 APPLICATIO_OT_REGISTERED GEERIC_ERROR REJECTED DISALLOWED Related Operations SetGlobalProperties Example Function Call ResetGlobalProperties req = new ResetGlobalProperties(); req.setcorrelationid(autoinccorrid++); Vector<GlobalProperty> properties = new Vector<GlobalProperty>(); properties.add(helpprompt): req.setproperties(properties); _sdlproxy.sendrpcrequest(req); SetGlobalProperties Sets value(s) for the specified global property(ies). HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD.

215 R E Q U E S T

216 Param ame helppro mpt timeout Prompt vrhelpti tle Type TTSChunk TTSChunk string Descript ion The help prompt. An array of text chunks of type TTSChun k. See TTSChun k.the array must have at least one item. Array of one or more TTSChunk elements specifyin g the help prompt used in an interactio n started by PTT. Text, which is shown as title of the VR help screen used in an interactio n started by PTT. Req. otes Array must have at least one element. Only optional it timeoutpr ompt has been specified. minsize:1 maxsize: 100 Array must have at least one element Only optional it helpprom pt has been specified minsize: 1 maxsize: 100 If omitted on supporte d displays, the default SDL help title will be used. If omitted and one or more vrhelp items are provided, the request will be rejected. maxlengt h: 500 Versio n Availab le k 1.0 k 1.0 k 1.0

217 vrhelp menutit le menuic on keyboar dproper ties VrHelep Image Keyboard Propertie s Items listed in the VR help screen used in an interactio n started by PTT. Optional text to label an app menu button (for certain touchscre en platforms ). Optional icon to draw on an app menu button (for certain touchscre en platforms ). Onscreen keybaord configura tion (if available ). If omitted on supporte d displays, the default SDL VR help / What Can I Say? screen will be used If the list of VR Help Items contains nonseque ntial positions (e.g. [1,2,4]), the RPC will be rejected. If omitted and a vrhelptitl e is provided, the request will be rejected. minsize:1 maxsize: 100 maxlengt h: 500 k 1.0 k 1.0 k 1.0 k 1.0

218 ote Your application shall send a SetGlobalProperties to establish an advanced help prompt before sending any voice commands. R E S P O S E Indicates whether the requested Global Properties were successfully set. on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - DISALLOWED Related Operations ResetGlobalProperties Example Function Call SetGlobalProperties setglobalproperties = new SetGlobalProperties(); setglobalproperties.sethelpprompt(helpprompt); setglobalproperties.settimeoutprompt(timeoutprompt); proxy.sendrpcrequest(setglobalproperties);

219 SetMediaClockTimer Sets the media clock/timer value and the update method (e.g. count-up, countdown, etc.). HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T

220

221 Param ame starttim e Type StartTime Descript ion StartTime struct specifyin g hour, minute, second values to which media clock timer is set. Req. otes Versio n Availab le k 1.0

222 endtim e StartTime EndTime can be provided for "COUTU P" and "COUTD OW"; to be used to calculate any visual progress bar (if not provided, this feature is ignored) If endtime is greater then starttime for COUTD OW or less than starttime for COUTU P, then the request will return an IVALID_ DATA. endtime will be ignored for "RESUME ", and "CLEAR" endtime can be sent for "PAUSE", in which case it will update the paused endtime Array must have at least one element Only optional it helpprom pt has been specified minsize: 1 maxsize: 100 k 1.0

223 update Mode UpdateM ode Specifies how the media clock/ timer is to be updated (COUTU P/ COUTD OW/ PAUSE/ RESUME), based at the starttim e. Y If "updatem ode" is COUTUP or COUTD OW, this paramete r must be provided. Will be ignored for PAUSE,RE SUME and CLEAR k 1.0 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - IGORED Example Function Calls SetMediaClockTimer setmediaclocktimer = new SetMediaClockTimer( updatemode); setmediaclocktimer.setstarttime(0); setmediaclocktimer.setendtime(30); proxy.sendrpcrequest(setmediaclocktimer);

224 Show Updates the application's display text area, regardless of whether or not this text area is visible to the user at the time of the request. The application's display text area remains unchanged until updated by subsequent calls to Show. The content of the application's display text area is visible to the user when the application's HMILevel is FULL or LIMITED, and the SystemContext=MAI and no Alert is in progress. The Show operation cannot be used to create an animated scrolling screen. To avoid distracting the driver, Show commands cannot be issued more than once every 4 seconds. Requests made more frequently than this will be rejected. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T

225

226

227 Param ame mainfie ld1 mainfie ld2 Type String String Descript ion Text to be displayed in a singleline display, or in the upper display line in a two-line display. Text to be displayed on the second display line of a two-line display. Req. otes If this paramete r is omitted, the text of mainfield 1 does not change. If this paramete r is an empty string, the field will be cleared. Maxlengt h = 500 If this paramete r is omitted, the text of mainfield 2 does not change. If this paramete r is an empty string, the field will be cleared. If provided and the display is a singleline display, the paramete r is ignored. Maxlengt h = 500 Versio n Availab le k 1.0 k 1.0

228 mainfie ld3 mainfie ld4 String String Text to be displayed on the first display line of the second page. Text to be displayed on the second display line of the second page. If this paramete r is omitted, the text of mainfield 3 does not change. f this paramete r is an empty string, the field will be cleared. If provided and the display is a singleline display, the paramete r is ignored. Maxlengt h = 500 If this paramete r is omitted, the text of mainfield 4 does not change. If this paramete r is an empty string, the field will be cleared. If provided and the display is a singleline display, the paramete r is ignored. Maxlengt h = 500 k 2.0 k 2.0

229 alignme nt statusb ar TextAlign ment String Specifies how mainfield 1 and mainfield 2 text should be aligned on display. The text is placed in the status bar area. Applies only to mainfield 1 and mainfield 2 provided on this call, not to what is already showing in display. If this paramete r is omitted, text in both mainfield 1 and mainfield 2 will be centered. Has no effect with navigatio n display ote: The status bar only exists on navigatio n displays If this paramete r is omitted, the status bar text will remain unchange d. If this paramete r is an empty string, the field will be cleared. If provided and the display has no status bar, this paramete r is ignored. Maxlengt h = 500 k 1.0 k 1.0

230 mediacl ock mediatr ack graphic String String Image Text value for MediaClo ck field. Has to be properly formatted by Mobile App according to SDL capabiliti es. If this text is set, any automati c media clock updates previousl y set with SetMedia ClockTim er will be stopped. Array of one or more TTSChunk elements specifyin g the help prompt used in an interactio n started by PTT. Image to be shown on supporte d displays. Must be properly formatted as described in the MediaClo ckformat enumerat ion. If a value of five spaces is provided, this will clear that field on the display (i.e. the media clock timer field will not display anything) Maxlengt h = 500 If paramete r is omitted, the track field remains unchange d. If an empty string is provided, the field will be cleared. This field is only valid for media applicatio ns on navigatio n displays. Maxlengt h = 500 If omitted on supporte d displays, the displayed graphic shall not change. k 1.0 k 1.0 k 2.0

231 second arygrap hic softbutt ons custom Presets Image SoftButto n String Image struct determini ng whether static or dynamic secondar y image to display in app. If omitted on supporte d displays, the displayed secondar y graphic shall not change. Soft buttons as defined by the App Custom presets as defined by the App. If omitted on supporte d displays, the currently displayed SoftButto n values will not change. Array Minsize: 0 Array Maxsize: 8 If omitted on supporte d displays, the presets will be shown as not defined. Minsize: 0 Maxsize: 6 k k 2.0 k 2.0

232 R E S P O S E O-DEFAULT RESULT CODES: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - DISALLOWED - USUPPORTED_RESOURCE - ABORTED Related Operations Alert SetMediaClockTimer Example Function Call Show show = new Show(); show.setmainfield1(mainfield1); show.setmainfield2(mainfield2); show.setalignment(alightment); proxy.sendrpcrequest(show);

233 SubscribeButton Establishes a subscription to button notifications for HMI buttons. Buttons are not necessarily physical buttons, but can also be "soft" buttons on a touch screen, depending on the display in the vehicle. Once subscribed to a particular button, an application will receive both OnButtonEvent and OnButtonPress notifications whenever that button is pressed. The application may also unsubscribe from notifications for a button by invoking the UnsubscribeButton operation. When a button is depressed, an OnButtonEvent notification is sent to the application with a ButtonEventMode of BUTTODOW. When that same button is released, an OnButtonEvent notification is sent to the application with a ButtonEventMode of BUTTOUP. When the duration of a button depression (that is, time between depression and release) is less than two seconds, an OnButtonPress notification is sent to the application (at the moment the button is released) with a ButtonPressMode of SHORT. When the duration is two or more seconds, an OnButtonPress notification is sent to the application (at the moment the two seconds have elapsed) with a ButtonPressMode of LOG. The purpose of OnButtonPress notifications is to allow for programmatic detection of long button presses similar to those used to store presets while listening to the radio, for example. When a button is depressed and released, the sequence in which notifications will be sent to the application is as follows: For short presses: OnButtonEvent (ButtonEventMode = BUTTODOW) OnButtonEvent (ButtonEventMode = BUTTOUP) * OnButtonPress (ButtonPressMode = SHORT) For long presses: OnButtonEvent (ButtonEventMode = BUTTODOW) OnButtonPress (ButtonPressMode = LOG) * OnButtonEvent (ButtonEventMode = BUTTOUP)

234 HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T ame Type Descript ion Reg. otes Versio n button ame Buttona me ame of the button to subscrib e. Y k 1.0 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - USUPPORTED_RESOURCE - IGORED - REJECTED Related Operations UnsubscribeButton

235 Example Function Call SubscribeButton subscribebutton = new SubscribeButton(Buttoname. OK); proxy.sendrpcrequest(subscribebutton); UnSubscribeButton Deletes a subscription to button notifications for the specified button. For more information about button subscriptions, see SubscribeButton. Application can unsubscribe from a button that is currently being pressed (i.e. has not yet been released), but app will not get button event. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T Param ame button ame Type Buttona me Descript ion ame of the button to unsubscri be. Req. Y otes Versio n Availab le k 1.0

236 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - USUPPORTED_RESOURCE - IGORED - REJECTED Related Operations SubscribeButton Example Function Call UnsubscribeButton unsubscribebutton = new UnsubscribeButton( Buttoname.OK); proxy.sendrpcrequest(unsubscribebutton);

237 PerformInteraction Performs an application-initiated interaction in which the user can select a Choice from among the specified Choice Sets. For instance, an application may use a PerformInteraction to ask a user to say the name of a song to play. The user's response is only valid if it appears in the specified Choice Sets and is recognized by SDL. HMI Status Requirements HMILevel needs to be FULL. R E Q U E S T

238

239 Param ame initialte xt initialpr ompt interact ionmod e Type String TTSChunk Interactio nmode Descript ion Displayed when the interactio n begins. This text may be overlaid by the "Listening " prompt during the interactio n. Text is displayed on first line of multiline display, and is centered. If text does not fit on line, it will be truncated An array of one or more TTSChunk s that, taken together, specify what is to be spoken to the user at the start of an interactio n. Indicates how user selects interactio n choice. User can choose either by voice (VR_OLY ), by visual selection from the menu (MAUAL _OLY), or by either mode (BOTH). Req. Y Y Y otes maxlengt h:500 minsize:1 maxsize: 100 Versio n Availab le k 1.0 k 1.0 k 1.0

240 interact ionchoi cesetid List helppro mpt Integer TTSChunk Array of one or more Choice Set IDs. User can select any choice from any of the specified Choice Sets. An array of TTSChunk s which, taken together, specify the help phrase to be spoken when the user says "help" during the VR session. If this paramete r is omitted, the help prompt will be construct ed by SDL from the first vrcomma nd of each choice of all the Choice Sets specified in the interactio nchoices etidlist paramete r. Y minsize:0 maxsize: 100 minvalue: 0 maxvalu e: minsize:1 maxsize: 100 The helppro mpt specifie d in SetGlob alprope rties is not used by Perform Interact ion. k 1.0 k 1.0

241 timeout Prompt TTSChunk An array of TTSChunk s which, taken together, specify the phrase to be spoken when the listen times out during the VR session. If this paramete r is omitted, the timeout prompt will be the same as the help prompt (see helpprom pt paramete r). The timeoutpr ompt specified in SetGlobal Propertie s is not used by PerformIn teraction. minsize:1 maxsize: 100 k 1.0

242 timeout Integer The amount of time, in millisecon ds, SDL will wait for the user to make a choice (VR or Menu). If this time elapses without the user making a choice, the timeoutpr ompt will be spoken. After this timeout value has been reached, the interactio n will stop and a subseque nt interactio n will take place after SDL speaks the timeout prompt. If that times out as well, the interactio n will end completel y. If omitted, the default is 10000ms. minvalue: 5000 maxvalu e: defvalue: k 1.0

243 vrhelp VrHelpIte m Ability to send suggeste d VR Help Items to display on-screen during Perform Interactio n If omitted on supporte d displays, the default SDL generate d list of suggeste d choices will be displaye d. Min = 1 Max = 100 k 2.0 interact ionlayo ut LayoutMo de See LayoutMo de k 3.0 R E S P O S E Indicates that interaction is complete, or was rejected. An interaction can complete when the user selects a choice, or when the interaction times out (no user selection was made), or when the interaction was interrupted by the user (pressing PTT or Menu button), or by system events (e.g. phone call), etc. This is sent to the mobile application after the user makes a choice from the PerformInteraction Request; or if the user fails to make a selection and the Request times out. Two additional parameters, cmdid and triggersource, are provided with this Response. The cmdid parameter represents the ID of the Choice in the InteractionChoices that was selected by the user. The

244 triggersource parameter indicates where said Choice selection came from (either Menu or VR). on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - IVALID_ID - DUPLICATE_AME - TIMED_OUT - ABORTED - USUPPORTED_RESOURCE - WARIGS Related Operations CreateInteractionChoiceSet DeleteInteractionChoiceSet Example Function Call PerformInteraction performinteraction = new PerformInteraction( initialtest, interactionmode, interactionchoicesetidlist); proxy.sendrpcrequest(performinteraction);

245 PerformAudioPassThru This will open an audio pass thru session. By doing so the app can receive audio data through the vehicle s microphone. HMI Status Requirements HMILevel needs to be FULL or LIMITED.

246 R E Q U E S T

247 ame Type Descript ion Reg. otes Versio n initialpr ompt audiopa ssthrud isplayte xt1 samplin grate maxdur ation bitspers ample audioty pe muteau dio TTSChunk [] String Sampling Rate Integer BitsPerSa mple AudioTyp e SDL will speak this prompt before opening the audio pass thru session. First line of text displayed during audio capture. This value shall is allowed to be 8 or 16 or 22 or 44 khz. The maximu m duration of audio recording in millisecon ds. Specifies the quality the audio is recorded - 8 bit or 16 bit. Specifies the type of audio data being requeste d. Boolean Y Y Y Y This is an array of text chunks of type TTSChun k. The array must have at least one item If omitted, then no initial prompt is spoken: Array Minsize: 1 Array Maxsize: 100 Maxlengt h = 500 Minvalue: 1 Maxvalu e: k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0

248 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - DISALLOWED - REJECTED - ABORTED - RETRY Related Operations EndAudioPassThru EndAudioPassThru When this request is invoked, the audio capture stops HMI Status Requirements HMILevel needs to be FULL or LIMITED.

249 R E Q U E S T o parameters. R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - DISALLOWED Related Operations PerformAudioPassThru SubscribeVehicleData Subscribes for specific published vehicle data items. The data will be only sent, if it has changed. The application will be notified by the onvehicledata notification whenever new data is available. The update rate is very much dependent on sensors, vehicle architecture and vehicle type. Be also prepared for the situation that a signal is

250 not available on a vehicle. To unsubscribe the notifications, use unsubscribe with the same subscriptiontype. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD.

251 R E Q U E S T

252 ame Type Descript ion gps Boolean GPS data. speed rpm fuellev el fuellev el_state instantf uelcons umption external Temper ature prndl tirepres sure odomet er beltstat us bodyinf ormatio n Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean The vehicle speed in kilometer s per hour The number of revolution s per minute of the engine The fuel level in the tank (percenta ge) The fuel level state The instantan eous fuel consumpt ion in microlitre s The external temperat ure in degrees celsius Currently selected gear. Tire pressure status Odomete r in km The status of the seat belts The body informati on including ignition status and internal temp Reg. otes Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Max Length: 500 Subscriba ble Subscriba ble Smart Device Link Versio n k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0

253 devices tatus driverbr aking wiperst atus headla mpstat us enginet orque accpeda lpositio n steering WheelA ngle ecallinf o airbags tatus emerge ncyeve nt cluster ModeSt atus Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean The device status including signal and battery strength The status of the brake pedal The status of the wipers Status of the head lamps Torque value for engine (in m) on nondiesel variants Accelerat or pedal position (percenta ge depresse d) Current angle of the steering wheel (in deg) Emergen cy Call notificatio n and confirmat ion data. The status of the air bags. Informati on related to an emergenc y event (and if it occurred ). The status modes of the instrume nt panel cluster. Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0

254 mykey Boolean Informati on related to the MyKey feature. Subscriba ble k 2.0 R E S P O S E on-default Result Codes: - SUCCESS - WARIGS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - IGORED - DISALLOWED - USER_DISALLOWED UnsubscribeVehicleData This function is used to unsubscribe the notifications from the subscribevehicledata function. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD.

255 R E Q U E S T

256 ame Type Descript ion Reg. otes Versio n gps speed rpm fuellev el fuellev el_state instantf uelcons umption external Temper ature prndl Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean GPS data. See {@linkpla in GPSdata for details The vehicle speed in kilometer s per hour The number of revolution s per minute of the engine The fuel level in the tank (percenta ge) The fuel level state The instantan eous fuel consumpt ion in microlitre s The external temperat ure in degrees celsius Currently selected gear. Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 tirepres sure Boolean Tire pressure status Subscriba ble k 2.0 odomet er beltstat us Boolean Boolean Odomete r in km The status of the seat belts Max Length: 500 Subscriba ble k 2.0 k 2.0

257 bodyinf ormatio n devices tatus driverbr aking wiperst atus headla mpstat us enginet orque accpeda lpositio n steering WheelA ngle ecallinf o airbags tatus emerge ncyeve nt Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean The body informati on including ignition status and internal temp The device status including signal and battery strength The status of the brake pedal The status of the wipers Status of the head lamps Torque value for engine (in m) on nondiesel variants Accelerat or pedal position (percenta ge depresse d) Current angle of the steering wheel (in deg) Emergen cy Call notificatio n and confirmat ion data. The status of the air bags. Informati on related to an emergenc y event (and if it occurred ). Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0

258 cluster ModeSt atus mykey Boolean Boolean The status modes of the instrume nt panel cluster. Informati on related to the MyKey feature. Subscriba ble Subscriba ble k 2.0 k 2.0 R E S P O S E on-default Result Codes: - SUCCESS - WARIGS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - IGORED - DISALLOWED Related Operations SubscribeVehicleData GetVehicleData GetVehicleData on-periodic vehicle data read request.

259 HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T

260

261

262

263 ame Type Descript ion Reg. otes Versio n gps speed rpm fuellev el fuellev el_state instantf uelcons umption external Temper ature vin prndl Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean GPS data. See {@linkpla in GPS data for details The vehicle speed in kilometer s per hour The number of revolution s per minute of the engine The fuel level in the tank (percenta ge) The fuel level state The instantan eous fuel consumpt ion in microlitre s The external temperat ure in degrees celsius Vehicle identificat ion number Currently selected gear. Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 tirepres sure Boolean Tire pressure status Subscriba ble k 2.0 odomet er beltstat us Boolean Boolean Odomete r in km The status of the seat belts Max Length: 500 Subscriba ble k 2.0 k 2.0

264 bodyinf ormatio n devices tatus driverbr aking wiperst atus headla mpstat us enginet orque accpeda lpositio n steering WheelA ngle Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean The body informati on including ignition status and internal temp The device status including signal and battery strength The status of the brake pedal The status of the wipers Status of the head lamps Torque value for engine (in m) on nondiesel variants Accelerat or pedal position (percenta ge depresse d) Current angle of the steering wheel (in deg) Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble Subscriba ble k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0

265 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - VEHICLE_DATA_OT_ALLOWED - VEHICLE_DATA_OT_AVAILABLE - USER_DISALLOWED ReadDID on-periodic vehicle data read request. This is an RPC to get diagnostics data from certain vehicle modules. DIDs of a certain module might differ from vehicle type to vehicle type. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD.

266 R E Q U E S T Param ame ecuam e didloca tion appid Type Integer Integer Integer Descript ion ame of ECU. Get raw data from vehicle data DID location (s). ID of the applicatio n that requeste d this RPC. Req. Y Y Y otes Minvalue: 0 Maxvalu e: Minvalue: 0 Maxvalu e: Versio n Availab le k 2.0 k 2.0 k 2.0 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - DISALLOWED - USER_DISALLOWED - TRUCATED_DATA

267 GetDTCs This RPC allows you to request diagnostic module trouble codes from a vehicle module. HMI Status Requirements HMILevel needs to be FULL, LIMITED, or BACKGROUD. R E Q U E S T

268 ame Type Descript ion Reg. otes Versio n ecuam e dtcmask Integer Integer ame of ECU. DTC Mask Byte to be sent in diagnosti c request to module. Y Min Value: 0 Max Value: Min Value: 0 Max Value: 255 k 2.0 k 2.0 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - DISALLOWED - USER_DISALLOWED - TRUCATED_DATA ScrollableMessage Creates a full screen overlay containing a large block of formatted text that can be scrolled with up to 8 SoftButtons defined.

269 HMI Status Requirements HMILevel needs to be FULL. R E Q U E S T

270 ame Type Descript ion Reg. otes Versio n scrollabl emessa gebody timeout softbutt ons String Integer SoftButto n Body of text that can include newlines and tabs. App defined timeout. Indicates how long of a timeout from the last action (i.e. scrolling message resets timeout). App defined SoftButto ns. If omitted on supporte d displays, only the system defined "Close" SoftButto n will be displaye d. Y minvalue =1000 maxvalue =65535 defvalue =30000 minsize= 0 maxsize= 8 evice Link 1.0 evice Link 1.0 evice Link 1.0

271 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - CHAR_LIMIT_EXCEEDED - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - DISALLOWED - USUPPORTED_RESOURCE - REJECTED - ABORTED Slider Creates a full screen or pop-up overlay (depending on platform) with a single user controlled slider. HMI Status Requirements HMILevel needs to be FULL.

272 R E Q U E S T TODO R E S P O S E on-default Result Codes: - SAVED - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - DISALLOWED - USUPPORTED_RESOURCE - REJECTED - ABORTED - TIMED_OUT ChangeRegistration If the app recognizes during the app registration that the SDL HMI language (voice/tts and/or display) does not match the app language, the app will be

273 able (but does not need) to change this registration with changeregistration prior to app being brought into focus. HMI Status Requirements HMILevel any. R E Q U E S T ame Langua ge hmidisp laylang uage appa me ttsam e ngnmed iascree nappa me vrsynon yms Type Language Language String TTSChunk String String Descript ion Requeste d SDL voice engine (VR+TTS) language registrati on. Request display language registrati on. Request new app name registrati on Request new ttsame registrati on Request new app short name registrati on Request new VR synonym s registrati on Req. Y Y otes Minvalue =0 Maxvalue = maxlengt h:100 minsize:1 maxsize: 100 maxlengt h: 100 maxlengt h: 40 minsize:1 maxsize: 100 Versio n Availab le k 2.0 k 2.0 k 2.0 k 2.0 k 2.0 k 2.0

274 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED - DISALLOWED Related Operations RegisterAppInterface GenericResponse Generic Response is sent, when the name of a received msg cannot be retrieved. Only used in case of an error. Currently, only resultcode IVALID_DATA is used.

275 Related Operations All functions. PutFile Used to push a binary data onto the SDL module from a mobile device, such as icons and album art. R E Q U E S T

276

277 ame Type Descript ion Req. otes Versio n Availab le Fileam e String File reference name. Y Maxlengt h=500 k 2.0 filetype FileType Selected file type. Y k 2.0 persiste ntfile Boolean Indicates if the file is meant to persist between sessions / ignition cycles. If set to TRUE,the n the system will aim to persist this file through session / cycles. While files with this designati on will have priority over others, they are subject to deletion by the system at any time. In the event of automati c deletion by the system, the app will receive a rejection and have to resend the file. If omitted, the value will be set to false. k 2.0

278 systemf ile offset length Boolean Float Float Indicates if the file is meant to be passed thru core to elsewher e on the system. If set to TRUE, then the system will instead pass the data thru as it arrives to a predeter mined area outside of core. If omitted, the value will be set to false. Optional offset in bytes for resuming partial data chunks Optional length in bytes for resuming partial data chunks. If offset is set to 0, then length is the total length of the file to be download ed Minvalue =0 Maxvalue = Minvalue =0 Maxvalue = k k k R E S P O S E Response is sent, when the file data was copied (success case). Or when an error occurred.

279 on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED Related Operations - DeleteFile - ListFiles DeleteFile Used to delete a file resident on the SDL module in the app's local cache. ot supported on first generation SDL vehicles. HMI Status Requirements R E Q U E S T

280 ame Type Descript ion Reg. otes Smart Device Link 2.0 SDLFile ame String File reference name. Y maxlengt h:500 k 2.0 R E S P O S E on-default Result Codes: SUCCESS IVALID_DATA OUT_OF_MEMORY TOO_MAY_PEDIG_REQUESTS APPLICATIO_OT_REGISTERED GEERIC_ERROR REJECTED Related Operations PutFile ListFiles

281 ListFiles Requests the current list of resident filenames for the registered app. R E Q U E S T o parameters. R E S P O S E Returns the current list of resident filenames for the registered app along with the current space available. on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED

282 SetAppIcon Used to set existing local file on SDL as the app's icon. ot supported on first generation SDL vehicles. R E Q U E S T Param ame Type Descript ion Req. otes Versio n Availab le SDLFile ame String File reference name. Y Maxlengt h=500 k 2.0 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED

283 SetDisplayLayout Used to set an alternate display layout. If not sent, default screen for given platform will be shown. R E Q U E S T Param ame displayl ayout Type string Descript ion Predefine d or dynamica lly created screen layout. Currently only predefine d screen layouts are defined. Predefine d layouts include: "OSCRE E_PRES ETS" Custom screen containin g appdefined onscreen presets. Req. Y otes maxlengt h: 500 Versio n Availab le k 2.0

284 R E S P O S E on-default Result Codes: - SUCCESS - IVALID_DATA - OUT_OF_MEMORY - TOO_MAY_PEDIG_REQUESTS - APPLICATIO_OT_REGISTERED - GEERIC_ERROR - REJECTED What is SDL? k (SDL) connects in-vehicle infotainment systems to smartphone apps. SDL allows automakers to provide highly integrated connected experiences and allows users to operate smartphone apps through the in-vehicle infotainment screen and, if equipped, voice recognition system. Why do you see SDL notifications? If you see a notification similar to the one in the screenshot below, that means you are using an app that has an SDL integration that allows it to push content to cars that support SDL. However, if your car doesn t support SDL, you can simply hide the notification.

285 How do you hide the notifications? If you would like to hide the notification, you can simply long click on the notification and disable it as shown in the following screenshot.

286