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

Adaptive Interface Capabilities

Designing for Different Head Units

Since each car manufacturer has different user interface style guidelines, the number of lines of text, soft and hard buttons, and images supported will vary between different types of head units. When the app first connects to the SDL Core, a RegisterAppInterface response RPC will be sent by Core with the displayCapabilities, buttonCapabilities, speechCapabilities and other properties. You should use this information to create the user interface of your SDL app.

You may access these properties on the SdlManager.systemCapabilityManager instance as of library v.4.4.

System Capability Manager Properties

Parameters Description Notes
SystemCapabilityType.DISPLAY Information about the HMI 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. Check DisplayCapabilities.java for more information
SystemCapabilityType.BUTTON A list of available buttons and whether the buttons support long, short and up-down presses. Check ButtonCapabilities.java for more information
SystemCapabilityType.SOFTBUTTON 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. Check SoftButtonCapabilities.java for more information
SystemCapabilityType.PRESET_BANK If returned, the platform supports custom on-screen presets. Check PresetBankCapabilities.java for more information
SystemCapabilityType.HMI_ZONE Specifies HMI Zones in the vehicle. There may be a HMI available for back seat passengers as well as front seat passengers. Check HmiZoneCapabilities.java
SystemCapabilityType.SPEECH Contains information about TTS capabilities on the SDL platform. Platforms may support text, SAPI phonemes, LH PLUS phonemes, pre-recorded speech, and silence. Check SpeechCapabilities.java for more information
prerecordedSpeechCapabilities Currently only available in the SDL_iOS library currently only available in the SDL_iOS library
SystemCapabilityType.VOICE_RECOGNITION The voice-recognition capabilities of the connected SDL platform. The platform may be able to recognize spoken text in the current language. Check VrCapabilities.java for more information
SystemCapabilityType.AUDIO_PASSTHROUGH Describes the sampling rate, bits per sample, and audio types available. Check AudioPassThruCapabilities.java for more information
SystemCapabilityType.PCM_STREAMING Describes different audio type configurations for the audio PCM stream service, e.g. {8kHz,8-bit,PCM}. Check AudioPassThruCapabilities.java for more information
SystemCapabilityType.HMI Returns whether or not the app can support built-in navigation and phone calls. Check HMICapabilities.java for more information
SystemCapabilityType.APP_SERVICES Describes the capabilities of app services including what service types are supported and the current state of services. Check AppServicesCapabilities.java for more information
SystemCapabilityType.NAVIGATION Describes the built-in vehicle navigation system's APIs. Check NavigationCapability.java for more information
SystemCapabilityType.PHONE_CALL Describes the built-in phone calling capabilities of the IVI system. Check PhoneCapability.java for more information
SystemCapabilityType.VIDEO_STREAMING Describes the abilities of the head unit to video stream projection applications. Check VideoStreamingCapability.java for more information
SystemCapabilityType.REMOTE_CONTROL Describes the abilities of an app to control built-in aspects of the IVI system. Check RemoteControlCapabilities.java for more information

The Register App Interface Response (RAIR) RPC

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. The table below has a list of properties beyond those available on the system capability manager returned by the RegisterAppInterface response. Each property is optional, so you may not get data for all the parameters in the following table.

Parameters Description Notes
sdlMsgVersion Specifies the version number of the SmartDeviceLink protocol that is supported by the mobile application. Check SdlMsgVersion.java for more information
language The currently active VR+TTS language on the module. Check Language.java for more information
vehicleType The make, model, year, and the trim of the vehicle. Check VehicleType.java for more information
supportedDiagModes 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. Check DiagnosticMessage.java for more information
sdlVersion The SmartDeviceLink version. String
systemSoftwareVersion The software version of the system that implements the SmartDeviceLink core. String

Image Specifics

Image File Types

Images may be formatted as PNG, JPEG, or BMP. Each sdlManager.getRegisterAppInterfaceResponse().getDisplayCapabilities().getImageFields() property will have a list of imageTypeSupported.

Image Sizes

If an image is uploaded that is larger than the supported size, that image will be scaled down by Core. All image sizes are available from the sdlManager.getRegisterAppInterfaceResponse().getDisplayCapabilities().getImageFields() property once the manager has started successfully.

ImageName Used in RPC Details Height Width Type
softButtonImage Show Image shown on softbuttons on the base screen 70px 70px png, jpg, bmp
choiceImage CreateInteractionChoiceSet Image shown in the manual part of an performInteraction either big (ICON_ONLY) or small (LIST_ONLY) 70px 70px png, jpg, bmp
choiceSecondaryImage CreateInteractionChoiceSet Image shown on the right side of an entry in (LIST_ONLY) performInteraction 35px 35px png, jpg, bmp
vrHelpItem SetGlobalProperties Image shown during voice interaction 35px 35px png, jpg, bmp
menuIcon SetGlobalProperties Image shown on the “More…” button 35px 35px png, jpg, bmp
cmdIcon AddCommand Image shown for commands in the "More…" menu 35px 35px png, jpg, bmp
appIcon SetAppIcon Image shown as Icon in the "Mobile Apps" menu 70px 70px png, jpg, bmp
graphic Show Image shown on the basescreen as cover art 185px 185px png, jpg, bmp

Querying the RAIR Capabilities

An example of querying the Vr Capabilities:

sdlManager.getRegisterAppInterfaceResponse().getVrCapabilities();

System Capabilities

Most head units provide features that your app can use: making and receiving phone calls, an embedded navigation system, video and audio streaming, as well as supporting app services. To find out if the head unit supports a feature as well as more information about the feature, use the SystemCapabilityManager to query the head unit for the desired capability. Querying for capabilities is only available on head units supporting SDL Core v4.5 or greater; if connecting to older head units, the query will return null even if the head unit may support the capabilty.

Querying for System Capabilities

sdlManager.getSystemCapabilityManager().getCapability(SystemCapabilityType.APP_SERVICES, new OnSystemCapabilityListener() {
    @Override
    public void onCapabilityRetrieved(Object capability) {
        AppServicesCapabilities servicesCapabilities = (AppServicesCapabilities) capability;
    }

    @Override
    public void onError(String info) {
        <# Handle Error #>
    }
});

Subscribing to System Capability Updates

In addition getting the current system capabilities, it is also possible to register to get updates when the head unit capabilities change. Since this information must be queried from Core you must implement the OnSystemCapabilityListener. This feature is only available on head units supporting v.5.1 or greater.

Subscribe to a Capability

sdlManager.getSystemCapabilityManager().addOnSystemCapabilityListener(SystemCapabilityType.APP_SERVICES, new OnSystemCapabilityListener() {
    @Override
    public void onCapabilityRetrieved(Object capability) {
        AppServicesCapabilities servicesCapabilities = (AppServicesCapabilities) capability;
    }

    @Override
    public void onError(String info) {
        <# Handle Error #>
    }
});

GetSystemCapability getSystemCapability = new GetSystemCapability();
getSystemCapability.setSystemCapabilityType(SystemCapabilityType.APP_SERVICES);
getSystemCapability.setSubscribe(true);
sdlManager.sendRPC(getSystemCapability);
View on GitHub.com
Previous Section Next Section