Connecting to SDL

Requirements to HMI Adapter

WebSocket is the primary means of communicating with the SDL 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. (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 is the Server
   • The HMI is the Client
2. Host
   • SDL is listening on 127.0.0.1:8087
3. WebSocket Protocol Version 13 is used by SDL

HMI Component Registration

Once all the requested connections are opened, the HMI must send the JSON request for registering each component.

Request

Component Registration has the following unique request requirements

Response

SDL Provides a JSON Response

Component Registration Examples

Register Component JSON Messages

Request

{
  "id": 700,
  "jsonrpc": "2.0",
  "method": "MB.registerComponent",
  "params": {
    "componentName": "VehicleInfo"
  }
}

Response

{
  "id": 700,
  "jsonrpc": "2.0",
  "result": 7000
}

WebSocket Connection Diagram

HMI Adapter Initialization

JSON Message Format

This section describes the message structure for communication between your HMI and SDL. The JSON RPC 2.0 format is taken as a basis.

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

JSON Message Examples

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.

JSON Message Examples

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.

JSON Message Examples

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:

JSON Message 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"
    }
  }
}