Expand Minimize Picture-in-picture Power Device Status Voice Recognition Skip Back Skip Forward Minus Plus Play Search
Integration Basics

Integration Basics

How SDL Works

SmartDeviceLink works by sending remote procedure calls (RPCs) back and forth between a smartphone application and the SDL Core. These RPCs allow you to build the user interface, detect button presses, play audio, and get vehicle data, among other things. You will use the SDL library to build your app on the SDL Core.

In this guide, we exclusively use IntelliJ. We are going to set-up a bare-bones application so you get started using SDL.


The SDL Java library supports Java 7 and above.

A SmartDeviceLink Service should be created to manage the lifecycle of the SDL session. The SdlService should build and start an instance of the SdlManager which will automatically connect with a head unit when available. This SdlManager will handle sending and receiving messages to and from SDL after it is connected.

Create a new service and name it appropriately, for this guide we are going to call it SdlService.

public class SdlService {

Implementing SDL Manager

In order to correctly connect to an SDL enabled head unit developers need to implement methods for the proper creation and disposing of an SdlManager in our SdlService.


An instance of SdlManager cannot be reused after it is closed and properly disposed of. Instead, a new instance must be created. Only one instance of SdlManager should be in use at any given time.

public class SdlService {

    //The manager handles communication between the application and SDL
    private SdlManager sdlManager = null;

    public SdlService(BaseTransportConfig config){

    public void start() {
        if(sdlManager != null){

    public void stop() {
        if (sdlManager != null) {
            sdlManager = null;


    private void buildSdlManager(BaseTransportConfig transport) {

        if (sdlManager == null) {

            // The app type to be used
            Vector<AppHMIType> appType = new Vector<>();

            // The manager listener helps you know when certain events that pertain to the SDL Manager happen
            SdlManagerListener listener = new SdlManagerListener() {

                public void onStart(SdlManager sdlManager) {
                    // After this callback is triggered the SdlManager can be used to interact with the connected SDL session (updating the display, sending RPCs, etc)

                public void onDestroy(SdlManager sdlManager) {

                public void onError(SdlManager sdlManager, String info, Exception e) {

                public LifecycleConfigurationUpdate managerShouldUpdateLifecycle(Language language) {
                    return null;

            // Create App Icon, this is set in the SdlManager builder
            SdlArtwork appIcon = new SdlArtwork(ICON_FILENAME, FileType.GRAPHIC_PNG, ICON_PATH, true);

            // The manager builder sets options for your session
            SdlManager.Builder builder = new SdlManager.Builder(APP_ID, APP_NAME, listener);
            sdlManager = builder.build();


The sdlManager must be shutdown properly if this class is shutting down in the respective method using the method sdlManager.dispose().

Optional SdlManager Builder Parameters

App Icon

This is a custom icon for your application. Please refer to Adaptive Interface Capabilities for icon sizes.

App Type

The app type is used by car manufacturers to decide how to categorize your app. Each car manufacturer has a different categorization system. For example, if you set your app type as media, your app will also show up in the audio tab as well as the apps tab of Ford’s SYNC3 head unit. The app type options are: default, communication, media (i.e. music/podcasts/radio), messaging, navigation, projection, information, and social.

Vector<AppHMIType> appHMITypes = new Vector<>();

Short App Name

This is a shortened version of your app name that is substituted when the full app name will not be visible due to character count constraints. You will want to make this as short as possible.

Template Coloring

You can customize the color scheme of your initial template on head units that support this feature using the builder. For more information, see the Customizing the Template guide section.

Determining SDL Support

You have the ability to determine a minimum SDL protocol and a minimum SDL RPC version that your app supports. We recommend not setting these values until your app is ready for production. The OEMs you support will help you configure the correct minimumProtocolVersion and minimumRPCVersion during the application review process.

If a head unit is blocked by protocol version, your app icon will never appear on the head unit's screen. If you configure your app to block by RPC version, it will appear and then quickly disappear. So while blocking with minimumProtocolVersion is preferable, minimumRPCVersion allows you more granular control over which RPCs will be present.

builder.setMinimumProtocolVersion(new Version("3.0.0"));
builder.setMinimumRPCVersion(new Version("4.0.0"));

Some OEMs may want to encrypt messages passed between your SDL app and the head unit. If this is the case, when you submit your app to the OEM for review, they will ask you to add a security library to your SDL app. See the Encryption section.

File Manager Configuration

The file manager configuration allows you to configure retry behavior for uploading files and images. The default configuration attempts one re-upload, but will fail after that.

FileManagerConfig fileManagerConfig = new FileManagerConfig();


The desired language to be used on display/HMI of connected module can be set.

Listening for RPC notifications and events

You can listen for specific events using SdlManager's builder setRPCNotificationListeners. The following example shows how to listen for HMI Status notifications. Additional listeners can be added for specific RPCs by using their corresponding FunctionID in place of the ON_HMI_STATUS in the following example and casting the RPCNotification object to the correct type.

Map<FunctionID, OnRPCNotificationListener> onRPCNotificationListenerMap = new HashMap<>();
onRPCNotificationListenerMap.put(FunctionID.ON_HMI_STATUS, new OnRPCNotificationListener() {
    public void onNotified(RPCNotification notification) {
        OnHMIStatus onHMIStatus = (OnHMIStatus) notification;
        if (onHMIStatus.getHmiLevel() == HMILevel.HMI_FULL && onHMIStatus.getFirstRun()){
            // first time in HMI Full

Main Class

Now that the basic connection infrastructure is in place, we should add methods to start the SdlService when our application starts. In main(String[] args) in your main class, you will create and start an instance of the SdlService class.

You will also need to fill in what port the app should listen on for an incoming web socket connection.

public class Main {

    Thread thread;
    SdlService sdlService;

    public static void main(String[] args) {
        Main main = new Main();


private void startSdlService() {

        thread = new Thread(new Runnable() {

            public void run() {
                sdlService  = new SdlService(new WebSocketServerConfig(PORT, -1));

View on GitHub.com
Previous Section Next Section