SmartDeviceLink - HMI Documentation

AddCommand

Type: Function
Sender: SDL
Purpose: Add a command to the specified application's menu or sub menu

UI.AddCommand represents a request from an application to add a command to the application's menu or sub-menu. This RPC can be sent to the HMI for an application that is registered and in any state (FULL, BACKGROUND, etc.)

Must

The commands sent for the application via AddCommand must be accessible from a Menu.
The user must be able to enter the Menu while the related application is in the FULL state.
Store the data provided in this RPC with the requesting application's appID.
Add the command to the application's menu at the position specified in the menuParams.
If driver distraction state is enabled, the number of shown items should be limited by the driver distraction system capability parameter menuLength.
Renew the timeout via sending BC.OnResetTimeout notification to SDL in case more time for processing UI.AddSubMenu request is needed.

Note

If SDL sends the HMI a UI.AddCommand and a VR.AddCommand, and receives a SUCCESS from one and a failure from the other, SDL will send a UI.DeleteCommand for the AddCommand which succeeded.
If the menuParams contains a parentID, the command is part of a sub menu. SDL adds new sub menus via the UI.AddSubMenu request.
If some command list items are hidden due to driver distraction, the HMI can note that some menu items are hidden for the drivers safety.
If the menuParams contains a parentID the command is part of a sub menu. SDL adds SubMenu Commands to the top level Menu via UI.AddSubMenu
During data resumption SDL sends UI.AddCommands to HMI by internal_consecutiveNumber in the same order as they were created by mobile app in previous ignition cycle.

As of Core 7.1, UI.AddCommand requests can contain all UI elements that were previously found in a Perform Interaction's Choice.

Request

Parameters

Name	Type	Mandatory	Additional
cmdID	Integer	true	minvalue: 0 maxvalue: 2000000000
menuParams	Common.MenuParams	false
cmdIcon	Common.Image	false
secondaryImage	Common.Image	false
appID	Integer	true

Response

Parameters

This RPC has no additional parameter requirements

Sequence Diagrams

Sequence Diagram

AddCommand Command Chosen By User

View Diagram

Sequence Diagram

AddCommand App Inactive

View Diagram

Sequence Diagram

AddCommand with sub menu

AddCommand positions

AddCommand Rejected Limit Reached

View Diagram

Sequence Diagram

AddCommand UI Succeeds, VR Fails

View Diagram

Sequence Diagram

AddCommand UI Succeeds, VR Unresponsive

View Diagram

Sequence Diagram

AddCommand UI Fails, VR Succeeds

View Diagram

Sequence Diagram

AddCommand UI No Response, VR Succeeds

View Diagram

Sequence Diagram

AddCommand for WebEngine App

View Diagram

Sequence Diagram

AddCommand restoring during data resumption

View Diagram

JSON Message Examples

Example Request

{
  "id" : 215,
  "jsonrpc" : "2.0",
  "method" : "UI.AddCommand",
  "params" :
  {
    "cmdID" : 2318,
    "menuParams" :
     {
         "parentID" : 6,
         "position" : 0,
         "menuName" : "Show weather for tomorrow",
         "secondaryText" : "Detroit, MI",
         "tertiaryText" : "0.8 miles"
     },
    "cmdIcon" :
     {
         "value" : "tmp/SDL/app/Gis_meteo/1245_28.jpeg",
         "imageType" : "DYNAMIC"
     },
    "secondaryImage" :
     {
         "value" : "tmp/SDL/app/Gis_meteo/5678.jpeg",
         "imageType" : "DYNAMIC"
     },
    "appID" : 65409
  }
}

Example Response

{
  "id" : 215,
  "jsonrpc" : "2.0",
  "result" :
  {
    "code" : 0,
    "method" : "UI.AddCommand"
  }
}

Example Error

{
  "id" : 215,
  "jsonrpc" : "2.0",
  "error" :
  {
    "code" : 13,
    "message" : "There’s no app with received appID registered",
    "data" :
    {
      "method" : "UI.AddCommand"
    }
  }
}

View on GitHub.com