SDL Core and HMI Communication

Connecting HMI to SDL

WebSocket is the primary means of communicating with the SDL Core component from the vehicle. In a basic example, an HTML5 HMI would use a native WebSocket library to communicate with SDL Core.

The HMI Adapter must:

Must

• Be installed on the same vehicle HU OS where SDL is installed, or the HMI must be able to be networked to SDL and address it via a static IP address.
• Create and initialize components which are defined in the HMI_API specification for the version of SDL which is running on the vehicle HU. (For example: BasicCommunication, UI, Buttons, VR, TTS, Navigation, VehicleInfo, RC, AppService)
• Establish a separate WebSocket connection with SDL for each of components defined in the HMI_API specification.
• Use the appropriate corresponding connection when sending responses and notifications to any connected component.

Handshake

For opening a WebSocket connection, a handshake must be performed.

Note

1. Client/Server relationship
   • SDL Core is the Server
   • The HMI is the Client
2. Host
   • SDL Core is listening on 127.0.0.1:8087 by default
   • The IP and port are configurable in SDL Core's smartDeviceLink.ini file
3. WebSocket Protocol Version 13 is used by SDL Core

Example: Connecting to SDL Core with Javascript

connectToSDL() {
  this.socket = new WebSocket("ws://localhost:8087")
  this.socket.onopen = this.onopen.bind(this)
  this.socket.onclose = this.onclose.bind(this)
  this.socket.onmessage = this.onmessage.bind(this)
}

Note

SDL Core accepts multiple WebSocket clients and the HMI can choose to connect each interface to SDL Core via individual WebSocket connections.

Component Registration

Request

The HMI must register each component which can communicate with SDL Core using the following RPC format.

Example Request:

{
  "jsonrpc": "2.0",
  "id": 100,
  "method": "MB.registerComponent",
  "params": {
    "componentName": "BasicCommunication"
  }
}

The possible componentNames are:

• BasicCommunication - Generic interface responsible for a collection of information and user actions. Includes UpdateAppList and OnAppRegistered.
• UI - Interface responsible for RPC events and information made visible to the user. Includes Show and Alert.
• Buttons - Interface responsible for RPC events and information related to hard and soft buttons in the vehicle. Includes OnButtonPress and OnButtonEvent.
• VR - Interface responsible for RPC events and information related to voice recognition. Contains RPC voice recognition counterparts to the UI component RPCs.
• TTS - Interface responsible for RPC events and information related to text to speech capabilities. Includes RPC Speak.
• Navigation- Interface responsible for RPC events and information related to navigation. Includes StartStream and GetWayPoints.
• VehicleInfo- Interface responsible for RPC events and information related to vehicle data. Includes GetVehicleData and SubscribeVehicleData.
• RC - Interface responsible for RPC events and information related to the Remote Control Feature.
• AppService - Interface responsible for RPC events and information related to the App Services Feature.

Response

SDL provides a JSON Response

Example Response:

{
  "id": 100,
  "jsonrpc": "2.0",
  "result": 1000
}

Component Readiness Requests

Once the components are registered, the HMI must notify SDL Core that it is ready to begin further communication using the BasicCommunication.OnReady notification.

Upon receipt of the OnReady notification, SDL Core will begin checking the availability of the different HMI components via a chain of requests:

• UI.IsReady - The display availability
• VR.IsReady - The voice recognition module availability
• TTS.IsReady - The text to speech module availability
• Navigation.IsReady - Navigation engine availability
• VehicleInfo.IsReady - Indicates whether vehicle information can be collected and provided
• RC.IsReady - Indicates whether vehicle RC modules are present and ready to communicate with SDL Core

Note

In the case of a WebSocket connection, RPCs to each of the components are sent within a separate WebSocket connection.

Note

If the response to any of the component IsReady requests contains {"available": false}, SDL Core will no longer communicate with that component.

Registering for Notifications

The HMI must also register for notifications individually using the following RPC format.

{
  "jsonrpc": "2.0",
  "id": -1,
  "method": "MB.subscribeTo",
  "params": {
    "propertyName": notificationName
  }
}

"propertyName" is the name of the notification the HMI will receive from Core. Some examples include:

• Buttons.OnButtonSubscription
• BasicCommunication.OnAppRegistered
• BasicCommunication.OnAppUnregistered
• Navigation.OnVideoDataStreaming
• SDL.OnStatusUpdate

Core's MessageBroker will not route notifications to the HMI unless the notifications are subscribed to.

Must

The HMI must:
* Register its components
* Send the OnReady notification
* Respond to each of the IsReady RPCs
* Register for the notifications it would like to receive

The above steps should only occur once per life cycle of SDL Core

Communicating with SDL Core

This section describes the message structure for communication between your HMI and SDL Core.

From this point forward the actors for exchanging messages will be considered:
- Client - can send requests and notifications
- Server - can provide responses to requests from a Client and send notifications

Request

An RPC call is represented by sending a Request object to a Server. The Request object has the following properties

Example Requests

Request with no Parameters

{
  "id": 125,
  "jsonrpc": "2.0",
  "method": "Buttons.GetCapabilities"
}

Request with Parameters

{
  "id": 92,
  "jsonrpc": "2.0",
  "method": "UI.Alert",
  "params": {
    "alertStrings": [
      {
        "fieldName": "alertText1",
        "fieldText": "WARNING"
      },
      {
        "fieldName": "alertText2",
        "fieldText": "Adverse Weather Conditions Ahead"
      }
    ],
    "duration": 4000,
    "softButtons": [
      {
        "type": "TEXT",
        "text": "OK",
        "softButtonID": 697,
        "systemAction": "STEAL_FOCUS"
      }
    ],
    "appID": 8218
  }
}

Notification

A notification is a Request object without an id property. For all the other properties, see the Request section above.

The receiver should not reply to a notification, i.e. no response object needs to be returned to the client upon receipt of a notification.

Example Notifications

Notification with no Parameters

{
  "jsonrpc": "2.0",
  "method": "UI.OnReady"
}

Notifications with Parameters

{
  "jsonrpc": "2.0",
  "method": "BasicCommunication.OnAppActivated",
  "params": {
    "appID": 6578
  }
}

{
  "jsonrpc": "2.0",
  "method": "Buttons.OnButtonPress",
  "params": {
    "mode": "SHORT",
    "name": "OK"
  }
}

Response

On receipt of a request message, the server must reply with a Response. The Response is expressed as a single JSON Object with the following properties.

Example Responses

Response with no Parameters

{
  "id": 167,
  "jsonrpc": "2.0",
  "result": {
    "code": 0,
    "method": "UI.Alert"
  }
}

Response with Parameters

{
  "id": 125,
  "jsonrpc": "2.0",
  "result": {
    "capabilities" : [
      {
        "longPressAvailable" : true,
        "name" : "PRESET_0",
        "shortPressAvailable" : true,
        "upDownAvailable" : true
      },
      {
        "longPressAvailable" : true,
        "name" : "TUNEDOWN",
        "shortPressAvailable" : true,
        "upDownAvailable" : true
      }
    ],
    "presetBankCapabilities": {
      "onScreenPresetsAvailable" : true
    },
    "code" : 0,
    "method" : "Buttons.GetCapabilities"
  }
}

Error Response

Must

When an RPC encounters an error, the response object must contain the error property instead of the result property.

The error object has the following members:

Examples

Response with Error

{
  "id": 103,
  "jsonrpc": "2.0",
  "error": {
    "code": 13,
    "message": "One of the provided IDs is not valid",
    "data": {
      "method": "VehicleInfo.GetDTCs"
    }
  }
}