smartdevicelink/sdl_hmi_integration_guidelines

Integration Guidelines for SDL Core into the vehicle HMI

sdl_hmi_integration_guidelines's Issues

Change ApplicationToNONEReason to ApplicationExitReason

Possibly an artifact of an older version, but ApplicationExitReason is the correct name for this enum. In addition, UNAUTHORIZED_TRANSPORT_REGISTRATION and UNSUPPORTED_HMI_RESOURCE are missing from this enum.

Missing Alert KEEP_CONTEXT Behavior

No diagrams or mentions of behavior for what an alert is to do when an alert KEEP_CONTEXT soft button is pressed.

[SDL 0274] Add preferred FPS to VideoStreamingCapability

Proposal: Add preferred FPS to VideoStreamingCapability

This proposal extends SDL video streaming feature by adding preferred FPS to VideoStreamingCapability, so that frame rate of video streaming can be adjusted per OEM.

Review: smartdevicelink/sdl_evolution#913

Steering Committee Decision:

The Steering Committee voted to accept this proposal with revisions. The revisions will include the items listed in this comment from the author.

The proposal .md file was updated to reflect these revisions on 2/10/2020.

Links in docs/UI/SetDisplayLayout/index.md are broken

In SetDisplayLayout index.md file, the link Common.DisplayCapabilities, Common.ButtonCapabilities, Common.SoftButtonCapabilities and Common.PresetBankCapabilities are all broken, because the link address should be "Common/Structs/index.md#" instead of "common/structs/#"

Add descriptions to Common/Enums and Common/Structs

None of the description fields are populated

Missing vrHelp parameter for PerformInteraction under VR section.

Missing vrHelp parameter for PerformInteraction here: https://smartdevicelink.com/en/docs/hmi/master/vr/performinteraction/.

The vrHelp parameter is included here (https://smartdevicelink.com/en/docs/hmi/master/ui/performinteraction/) just not under the VR section.

SetVideoConfig is in the incorrect interface

SetVideoConfig is included in the UI interface documentation, but it is part of the navigation interface

SDL 4.1 documentation is missing

With SDL 4.1 some new RPC's were introduced. The description of those RPC's is missing in the Integration Guidelines. The following RPC's are affected.

OnSystemInfoChanged
OnEventChanged
OnSystemError
AddStatisticsInfo

Issue moved from: smartdevicelink/sdl_core_guides#18

Describe 'Proprietary' flow of Policy Table Update

Impacted RPCs:

SDL.OnStatusUpdate
BC.PolicyUpdate
SDL.GetURLs
BC.OnSystemRequest
BC.SystemRequest
SDL.OnReceivedPolicyUpdate

Missing documentation for "BC.DecryptCertificate"

HMI Guideline Inconsistencies

See issue: smartdevicelink/sdl_core#541 (comment)

1. Press Mode is wrong.
   -> needs to be fixed in Guidelines
2. Alert timeout with soft buttons.
   -> SDL has a requirement to cancel the internal timeout for Alert with SBs.
   -> Per current requirements, if app -> SDL: Alert + SBs:
   and with "duration" -> SDL must transfer "duration" to HMI via UI.Alert
   and without "duration" -> SDL must omit "duration" in UI.Alert to HMI
   in both cases, HMI must apply the "default HMI timeout for alerts with SBs"
   -> So, in case of Alert with SBs it's completely HMI's responsibility to provide UI.Alert_response: SDL will keep waiting even without OnResetTimeout notification.
   ==> to sum up:
   a. it's SDL's defect to zero the "duration" in UI.Alert (while it's expected when SDL's internal timeout is zeroed)
   b. Guidelines needs to be updated for KEEP_CONTEXT behavior
3. Alert text fields.
   -> Per SDL requirements, in case mobile_API omits "minlength" descriptor of string param, SDL must use value of "minlength = 1" by default.
   -> returning INVALID_DATA to app's Alert that contains zeroed AlertTextStrings is an expected behavior.
   -> This above description is out of "SDL-HMI Guidelines" scope, since it impacts app-SDL relations only.
4. Alert - HMI defined "close" button behavior .
   -> the expected behavior is correct.
   -> please bring up as a separate issue, with logs if possible.
5. For 6.18.1.1, among the parameters of "BasicCommunication.OnSystemRequest", spec says that "appID" is an integer, but SDL Core expects it to be a string when testing.
   -> SDL behavior is fixed to expect integer "appID" in release_4.1.0
6. In 10.6.2.2, the description of parameter "ttsName" for "TTS.ChangeRegistration" is wrong. That is the description of parameter "vrSynonyms" for "VR.ChangeRegistration".
   -> Guidelines need to be fixed
7. In 7.29.3, it shows that when the response is SUCCESS for "UI.SetDisplayLayout", it can include four parameters "displayCapabilities", "buttonCapabilities", "softButtonCapabilities", and "presetBankCapabilities". But SDL Core logs will show "Incorrect parameter from HMI" when the response contains any of this four parameters.
   -> needs to be investigated (the above behavior is against the requirements). Please bring up as a separate issue.
8. In 10.2.3.1, it shows that the first parameter of "TTS.GetCapabilitites" is "capabilities". But I checked SDL Core code, and it expects "speechCapabilities".
   -> Guidelines need to be fixed

Parameter boundary do not align:

1. Such is inherited from mobile_API.
   The expected behavior is that when app sends AddCommand with ParentID=0 -> HMI needs to add it to the top-level menu (like "options" in html5_hmi)
2. Such is inherited from mobile_API.
3. Such is inherited from mobile_API.
4. Such is inherited from mobile_API.
5. That is expected SDL behavior (see also mobile_API description).
   The background is: what should HMI display if neither text nor image are provided for a softButton?
   If softButtons struct is included - it must contain reasonable values. If softButtons are not expected - the struct might be just omitted.

[SDL 0240] WebEngine support for SDL JavaScript

Proposal: WebEngine support for SDL JavaScript

This proposal is adding a new transport to the SDL JavaScript library to support (progressive) web apps to run on a WebEngine or a browser.

Review: smartdevicelink/sdl_evolution#767

Steering Committee Decision:

The Steering Committee voted to accept this proposal with the following revisions:

• When formatting locales in the manifest.json file, use standard (RFC 5646), and convert locale strings when necessary.
• Do not specify the location of the manifest's <script> tag placement within the proposal.
• All revisions included in this PR: https://github.com/smartdevicelink/sdl_evolution/pull/888/files

The proposal .md file was updated to reflect these revisions on 12/19/19.

Update License to 2020

License file should be updated from "Copyright (c) 2017 SmartDeviceLink Consortium, Inc." to "Copyright (c) 2017 - 2020 SmartDeviceLink Consortium, Inc."

Update Diagram: Revoked App Should Not Be Unregistered by SDL

If the app gets revoked by Policies update - SDL should notify HMI about the event, keep such app registered and in NONE level and disallow its activation.

The documentation defect (diagram 13.1.4.2) must be fixed to align with the above.

Raised by issue smartdevicelink/sdl_core#798

The message type for StartStream and StartAudioStream is incorrect

These messages are marked as Notification RPCs, but they are Request RPCs

OnEventChanged not documented

The message OnEventChanged is missing from the documentation and should be added.

[SDL 0274] Add preferred FPS to VideoStreamingCapability

Proposal: Add preferred FPS to VideoStreamingCapability

This proposal extends SDL video streaming feature by adding preferred FPS to VideoStreamingCapability, so that frame rate of video streaming can be adjusted per OEM.

Review: smartdevicelink/sdl_evolution#913

Steering Committee Decision:

The Steering Committee voted to accept this proposal with revisions. The revisions will include the items listed in this comment from the author.

The proposal .md file was updated to reflect these revisions on 2/10/2020.

Broken Links

There are a few broken links within the HMI Integration Guidelines.

Location: SDL/OnStatusUpdate - "BC.PolicyUpdate" link in Notification section.

• Current URL: https://smartdevicelink.com/en/docs/hmi/master/BasicCommunication/PolicyUpdate/index.md/#Request
• Expected URL: https://smartdevicelink.com/en/docs/hmi/master/basiccommunication/policyupdate/

Location: UI/AddCommand - "menuLength" link in first MUST section.

• Current URL: https://smartdevicelink.com/en/docs/hmi/master/common/struct/#driverdistractioncapability
• Expected URL: https://smartdevicelink.com/en/docs/hmi/master/common/structs/#driverdistractioncapability

Location: TTS/GetCapabilities - "Common.PrerecordedSpeech" link in first NOTE section.

• Current URL: https://smartdevicelink.com/en/docs/hmi/master/common/enums/index.md/#prerecordedspeech
• Expected URL: https://smartdevicelink.com/en/docs/hmi/master/common/enums/#prerecordedspeech

Location: BasicCommunication/ActivateApp - "VR.AddCommand" link in Behavior section.

• Current URL: https://smartdevicelink.com/en/docs/hmi/master/basiccommunication/VR/AddCommand/
• Expected URL: https://smartdevicelink.com/en/docs/hmi/master/vr/addcommand/

Location: Buttons/OnButtonPress - "Buttons.OnButtonSubscription" link in first paragraph.

• Current URL: https://smartdevicelink.com/en/docs/hmi/master/buttons/onbuttonsubscription/
• Expected URL: https://smartdevicelink.com/en/docs/hmi/master/buttons/subscribebutton/

Location: BasicCommunication/OnSystemCapabilityUpdated - "Create Window" link in Notification section.

• Current URL: https://smartdevicelink.com/en/docs/hmi/master/UI/CreateWindow/index.md/
• Expected URL: https://smartdevicelink.com/en/docs/hmi/master/ui/createwindow/

Describe unsupported interfaces ("IsReady: false" response)

Describe SDL behaviour in cases:

1. interface is not available: response IsReady(available: false)
2. interface availability is unknown: non-response
3. interface is available: response IsReady(available: true)

Impacted interfaces:

• UI
• TTS
• VR
• Navigation
• VehiclaeInfo

Add LICENSE file

Need to add a License file for sdl_hmi_integration_guidelines with the following content:

Copyright (c) 2017, SmartDeviceLink Consortium, Inc.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

Neither the name of 2017, SmartDeviceLink Consortium, Inc. nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Describe OnEventChanged notification

New OnEventChanged notification replaces OnEmergencyEvent, OnDeactivateHMI, OnPhoneCall + introduces new events AUDIO_SOURCE, EMBEDDED_NAVI.
The above needs to be properly described in Guidelines.

also discussed here: smartdevicelink/sdl_core/issues/831

[SDL 0248] HMI Policy Table Update using vehicle modem

Update documentation to reflect the new flow of the proposal described and linked below:

Proposal: HMI Policy Table Update using vehicle modem

This proposal describes an enhanced policy table update PTU sequence where the IVI system sends the policy table snapshots (PTS) directly to the policy server using the in-vehicle modem and returns a policy table update (PTU) back to SDL Core without using any SystemRequest RPC.

Review: smartdevicelink/sdl_evolution#813

Steering Committee Decision:

The Steering Committee voted to accept this proposal with the following revisions:

• Note SDL.GetURLs as deprecated, and add GetPolicyConfigurationData
• Include implementation details for HMI Integration Guidelines, SDL HMI, Generic HMI, and ATF/ATF Test Scripts, as outlined in this comment

The proposal .md file was updated to reflect these revisions on 9/3/19.

Describe the difference between BasicCommunication.OnAppActivated and SDL.ActivateApp

While Jack and I were working on an SDL HMI integration we found that there were two ways for an application to be activated by the HMI.

In the first, the HMI sends BasicCommunication.OnAppActivated to SDL, SDL sends BasicCommunication.ActivateApp to HMI and HMI returns with a success to SDL. In our testing, we found that activating applications using this flow only worked for some applications.

The other way to activate an application is to send a message called "SDL.ActivateApp" to SDL and get a response with information about the application that was activated. This approach seemed to work for all the applications that we tested.

The differences in these APIs should be documented. If the OnAppActivated API does not work for whatever reason, it should be removed so that it can't be used by future HMI integrations with SDL.

Incorrect sequence diagram for AddCommand Positions in HMI Docs

https://smartdevicelink.com/en/guides/hmi/ui/addcommand/
In the sequence diagram for "AddCommand positions"
It shows this:

However, if this is what the app sent thyen the menu would be
Test_3
Test_1
Test_2

I think you should ujst update the signal being sent from the app to say
UI.AddCommand {appID_1, cmdID_3, position: 1, menuName: "Test_3"}
This shows a good use of the position field

In the overview of Notifications add `MB.SubscribeTo` documentation

Remove `appId` from `GetVechicleData`, `SubscribeVehicleData`, and `UnsubscribeVehicleData`

This parameter was removed from these RPCs in smartdevicelink/sdl_core#152, the docs should be updated accordingly

Supported icons documentation

In the Ford developer portal, there is a static list of supported icons when using AddCommand and Show. These are missing from the HMI integration guidelines.

Reference: https://developer.ford.com/pages/supported-icons-for-developers-android

Links to Enums and Structs are broken

Currently, links from API description (example) to related Enums and Structs of Common Interface lead to "Page not found" by the reason:
-> current link: https://github.com/smartdevicelink/sdl_hmi_integration_guidelines/blob/master/docs/common/structs/index.md#image
-> should be: https://github.com/smartdevicelink/sdl_hmi_integration_guidelines/blob/master/docs/Common/Structs/index.md#image

The whole Guideline document is impacted.

Missing documentation

I havne't been able to find any documentation on the following:

OnDeactivateHMI
OnEventChanged (Understading issue #19 was raised)
ShowCustomForm

We need to include these ASAP.

Add information about stopping an embedded nav service

Embedded nav services should stop their route if they stop being the active nav service.

For more info: smartdevicelink/sdl_evolution#942

Missing Image for UI.SetGlobalProperties

Missing SetGlobalProperties_TTS_UI_VR.png

Grammatical errors and broken link updates

The following items need to be updated in the SDL HMI Integration Guidelines:

• from from in docs/BasicCommunication/DialNumber/index.md should be from
• distinguish distinguish in docs/BasicCommunication/OnAppUnregistered/index.md should be distinguish
• the link in docs/RC/GetInteriorVehicleDataConsent/index.md for Remote Control Consent should be https://smartdevicelink.com/en/guides/core/feature-documentation/remote-control/#consent
• the link in docs/UI/AddSubMenu/index.md for subMenuDepth should be ../../common/structs/#driverdistractioncapability
• the the in docs/UI/SetAppIcon/index.md should be the
• then in docs/UI/SetMediaClockTimer/index.md should be than
• the link in docs/BasicCommunication/GetSystemTime/index.md for <DefaultTimeout> should be https://smartdevicelink.com/en/guides/core/getting-started/ini-configuration/