diff --git a/docs/Common/Enums/index.md b/docs/Common/Enums/index.md index deaf31c0e..74bf5b352 100644 --- a/docs/Common/Enums/index.md +++ b/docs/Common/Enums/index.md @@ -9,6 +9,8 @@ |ENTRY_VOICE|2|| |ENTRY_CANCELLED|3|| |ENTRY_ABORTED|4|| +|INPUT_KEY_MASK_ENABLED|5|| +|INPUT_KEY_MASK_DISABLED|6|| ### FuelCutoffStatus @@ -188,6 +190,7 @@ |QWERTY|0|| |QWERTZ|1|| |AZERTY|2|| +|NUMERIC|3|| ### MenuLayout @@ -1356,3 +1359,10 @@ |LOCKED|1|The status is selected if a door is closed and locked| |AJAR|2|The status is selected if a door is open| |REMOVED|3|The status is selected if a door is physically removed| + +### KeyboardInputMask +|Name|Value|Description| +|:---|:----|:----------| +|ENABLE_INPUT_KEY_MASK|0|| +|DISABLE_INPUT_KEY_MASK|1|| +|USER_CHOICE_INPUT_KEY_MASK|2|| diff --git a/docs/Common/Structs/index.md b/docs/Common/Structs/index.md index 6c84de13c..f33a184b0 100644 --- a/docs/Common/Structs/index.md +++ b/docs/Common/Structs/index.md @@ -175,6 +175,8 @@ |keypressMode|[Common.KeypressMode](../enums/#keypressmode)|false||| |limitedCharacterList|String|false|array: true
minsize: 1
maxsize: 100
maxlength: 1|| |autoCompleteList|String|false|array: true
minsize: 0
maxsize: 100
maxlength: 1000|| +|maskInputCharacters|[Common.KeyboardInputMask](../enums/#keyboardinputmask)|false||Allows an app to mask entered characters on HMI| +|customKeys|String|false|maxlength: 1
minsize: 1
maxsize: 10
array: true|Array of special characters to show in customizable Keys.
If omitted, keyboard will show default special characters.| ### Choice @@ -1107,6 +1109,7 @@ There are no defined parameters for this struct |softButtonCapabilities|Common.SoftButtonCapabilities|false|array: true
minsize: 1
maxsize: 100|The number of soft buttons available on-window and the capabilities for each button.| |menuLayoutsAvailable|[Common.MenuLayout](../enums/#menulayout)|false|array: true
minsize: 1
maxsize: 1000|An array of available menu layouts. If this parameter is not provided, only the `LIST` layout is assumed to be available| |dynamicUpdateCapabilities|Common.DynamicUpdateCapabilities|false||Contains the head unit's capabilities for dynamic updating features declaring if the module will send dynamic update RPCs| +|keyboardCapabilities|[Common.KeyboardCapabilities](../structs/#keyboardcapabilities)|false||See KeyboardCapabilities| ### ModuleInfo @@ -1234,3 +1237,17 @@ There are no defined parameters for this struct |externalTemperature|Common.Temperature|false||The external temperature in degrees celsius| |cabinTemperature|Common.Temperature|false||Internal ambient cabin temperature in degrees celsius| |atmosphericPressure|float|false|minvalue: 0
maxvalue: 2000|Current atmospheric pressure in mBar| + +### KeyboardCapabilities + +|Name|Type|Mandatory|Additional|Description| +|:---|:---|:--------|:---------|:----------| +|maskInputCharactersSupported|Boolean|false||Availability of capability to mask input characters using keyboard.
True: Available, False: Not Available.| +|supportedKeyboards|Common.KeyboardLayoutCapability|false|minsize: 1
maxsize: 1000
array: true|Capabilities of supported keyboard layouts by HMI.| + +### KeyboardLayoutCapability + +|Name|Type|Mandatory|Additional|Description| +|:---|:---|:--------|:---------|:----------| +|keyboardLayout|[Common.KeyboardLayout](../enums/#keyboardlayout)|true||| +|numConfigurableKeys|Integer|true|minvalue: 0
maxvalue: 10|Number of keys available for special characters, App can customize as per their needs.| diff --git a/docs/UI/OnKeyboardInput/assets/KeyboardEventInputKeyMask.png b/docs/UI/OnKeyboardInput/assets/KeyboardEventInputKeyMask.png new file mode 100644 index 000000000..ddf83b994 Binary files /dev/null and b/docs/UI/OnKeyboardInput/assets/KeyboardEventInputKeyMask.png differ diff --git a/docs/UI/OnKeyboardInput/assets/KeyboardEventInputKeyMask.txt b/docs/UI/OnKeyboardInput/assets/KeyboardEventInputKeyMask.txt new file mode 100644 index 000000000..e7d7bc983 --- /dev/null +++ b/docs/UI/OnKeyboardInput/assets/KeyboardEventInputKeyMask.txt @@ -0,0 +1,56 @@ +participant App +participant SDL +participant HMI + +note over App,HMI: **//Pre-conditions://**\n**1.** appID application is successfully registered and active on HMI\n**2.** HMI supports masking input characters + +HMI->>SDL: BC.OnSystemCapabilityUpdated(**maskInputCharactersSupported=true**) +SDL->>App: OnSystemCapabilityUpdated(maskInputCharactersSupported=true) +opt App sends the request to mask keyboard input characters +App->SDL:SetGlobalProperties(appID,\n **maskInputCharacters=ENABLE_INPUT_KEY_MASK**) +SDL->HMI:UI.SetGlobalProperties(appID,\n **maskInputCharacters=ENABLE_INPUT_KEY_MASK**) + +note over HMI:Stores the request data\nassociating it with appID +HMI->>SDL:UI.OnKeyboardInput () +SDL->>App:OnKeyboardInput () +HMI-->SDL:UI.SetGlobalProperties (code:0) +SDL-->App:SetGlobalProperties (SUCCESS) +note over HMI:The User presses **"1"** key +HMI->>SDL:UI.OnKeyboardInput ("1", ) +SDL->>App:OnKeyboardInput ("1", ) +note over HMI:User input is shown **masked** +end + +opt App sends the request to UNmask keyboard input characters +App->SDL:SetGlobalProperties(appID,\n **maskInputCharacters=DISABLE_INPUT_KEY_MASK** +SDL->HMI:UI.SetGlobalProperties(appID,\n**maskInputCharacters=DISABLE_INPUT_KEY_MASK** +note over HMI:Stores the request data\nassociating it with appID +HMI->>SDL:UI.OnKeyboardInput () +SDL->>App:OnKeyboardInput () +HMI-->SDL:UI.SetGlobalProperties (code:0) +SDL-->App:SetGlobalProperties (SUCCESS) +note over HMI:The User presses **"1"** key +HMI->>SDL:UI.OnKeyboardInput ("1", ) +SDL->>App:OnKeyboardInput ("1", ) +note over HMI:User input is shown **NOT masked** +end + +opt App sends the request to unmask keyboard input characters per User choice +App->SDL: SetGlobalProperties (appID,\n **maskInputCharacters=USER_CHOICE_INPUT_KEY_MASK**) +SDL->HMI: UI.SetGlobalProperties (appID,\n **maskInputCharacters=USER_CHOICE_INPUT_KEY_MASK**) +note over HMI:Stores the request data\nassociating it with appID +HMI->>SDL:UI.OnKeyboardInput () +SDL->>App:OnKeyboardInput () +HMI-->SDL:UI.SetGlobalProperties (code:0) +SDL-->App:SetGlobalProperties (SUCCESS) +note over HMI:A key to mask/unmask\ninput characters is shown +note over HMI:The User presses **"1"** key +HMI->>SDL:UI.OnKeyboardInput ("1", ) +SDL->>App:OnKeyboardInput ("1", ) +note over HMI:User input is shown **masked** +note over HMI:The User presses the key\n to unmask input characters +HMI->>SDL:UI.OnKeyboardInput () +SDL->>App:OnKeyboardInput () +note over HMI:Keyboard input characters\nare **NOT masked**\non the screen + +end diff --git a/docs/UI/OnKeyboardInput/index.md b/docs/UI/OnKeyboardInput/index.md index b9aadfe15..cf9e7c0d1 100644 --- a/docs/UI/OnKeyboardInput/index.md +++ b/docs/UI/OnKeyboardInput/index.md @@ -11,6 +11,19 @@ Purpose ### Notification +!!! MUST + +Notify SDL whether keyboard input characters are displayed as masked or not masked on HMI screen. + +!!! + +!!! NOTE + +1. By default keyboard input characters are not masked. +2. When `maskInputCharacters` value is set to "USER_CHOICE_INPUT_KEY_MASK", HMI masks input characters **and** provides a toggle button allowing the user to unmask them if needed. + +!!! + #### Parameters |Name|Type|Mandatory|Additional| @@ -45,6 +58,11 @@ OnKeyboardInput ENTRY_VOICE mode ![OnKeyboardInput](./assets/OnKeyboardInputVoice.png) ||| +||| +KeyboardEvent InputKeyMask +![OnKeyboardInput](./assets/KeyboardEventInputKeyMask.png) +||| + ### JSON Message Examples #### Example Notification diff --git a/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesCustomKeys.png b/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesCustomKeys.png new file mode 100644 index 000000000..81fbf2a35 Binary files /dev/null and b/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesCustomKeys.png differ diff --git a/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesCustomKeys.txt b/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesCustomKeys.txt new file mode 100644 index 000000000..26c87e7ba --- /dev/null +++ b/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesCustomKeys.txt @@ -0,0 +1,42 @@ +participant App +participant SDL +participant HMI + +note over App,HMI: **//Pre-conditions://**\n**1.** appID application is successfuly registered and active\n + +opt App sends a request to change customizable keys special characters - Happy Path +note over HMI:Keyboard layout\ncustomizable keys are:\n**" # "** - default value\n**" - "** - default value +App->SDL:SetGlobalProperties (appID, ) +SDL->HMI:UI.SetGlobalProperties (appID, ) +HMI->HMI:Update\ncustomizable\nkeys +HMI-->SDL:UI.SetGlobalProperties (SUCCESS) +SDL-->App:SetGlobalProperties (SUCCESS) +note over HMI:Keyboard layout\ncustomizable keys are:\n**" ¥ "** - customized value\n** " $ "** - customized value +end + +opt App sends a request with a special character already available on keyboard +note over HMI:Keyboard layout\ncustomizable keys are:\n**" $ "** and **" + "** +App->SDL:SetGlobalProperties (appID, ) +SDL->HMI:UI.SetGlobalProperties (appID, ) +note over HMI:**" + "** is already\navailable on keyboard +HMI->HMI:Use only\n**" @ "** value\nto update\ncustomizable\nkeys +HMI-->SDL:UI.SetGlobalProperties (SUCCESS) +SDL-->App:SetGlobalProperties (SUCCESS) +note over HMI:Keyboard layout\ncustomizable keys are:\n**" @ "** - customized value\n**" + "** - remains unchanged +end + +opt App sends a request with too many special characters +App->SDL:SetGlobalProperties (appID, ) +note over SDL: array\nhas more values than\ncustomizable keys allowed +SDL-->App:SetGlobalProperties\n(INVALID_DATA: "CustomKeys exceeds the number of customizable keys in this Layout") +note over HMI:Customizable keys' values\nare not changed +end + +opt App sends a request with not supported special characters +App->SDL:SetGlobalProperties (appID, ) +SDL->HMI:UI.SetGlobalProperties (appID, ) +note over HMI: array\nhas unsupported values +HMI-->SDL:UI.SetGlobalProperties\n(WARNINGS: "Some symbols might not be supported by system") +SDL-->App:SetGlobalProperties\n(WARNINGS: "Some symbols might not be supported by system") +note over HMI:Customizable keys' values\nare not changed +end \ No newline at end of file diff --git a/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesResumptionKeyboardProperties.png b/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesResumptionKeyboardProperties.png new file mode 100644 index 000000000..72cb69ddb Binary files /dev/null and b/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesResumptionKeyboardProperties.png differ diff --git a/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesResumptionKeyboardProperties.txt b/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesResumptionKeyboardProperties.txt new file mode 100644 index 000000000..76b10e92f --- /dev/null +++ b/docs/UI/SetGlobalProperties/assets/SetGlobalPropertiesResumptionKeyboardProperties.txt @@ -0,0 +1,28 @@ +participant App +participant SDL +participant HMI + +note over App,HMI:**//Pre-conditions://**\n**1.** appID application is successfuly registered, activated\n**2.** App set non-default values for 'KeyboardProperties' via SetGlobalProperties request\n keyboardLayout=AZERTY; maskInputCharacters=USER_CHOICE_INPUT_KEY_MASK; customKeys = "#", "$" + +note over App,HMI: Unexpected disconnect and reconnect are performed + +App->SDL: RegisterAppInterface(hashID, params) + + +note over SDL: is valid\nStart data resumption for the App + +SDL->>HMI: BC.OnAppRegistered(appName; appID) +SDL->HMI:UI.SetGlobalProperties\n (**keyboardLayout=AZERTY;\nmaskInputCharacters=USER_CHOICE_INPUT_KEY_MASK;\ncustomKeys = #, $**) + +HMI-->SDL: UI.SetGlobalProperties (code:0) + + +SDL-->App: RegisterAppInterface (SUCCESS) + +SDL->>App: OnHMIStatus() + +SDL->HMI: BC.ActivateApp() +HMI-->SDL: BC.ActivateApp (code:0) + +HMI->>SDL: UI.OnKeyboardInput(INPUT_KEY_MASK_ENABLED) +SDL->>App:OnKeyboardInput(INPUT_KEY_MASK_ENABLED) \ No newline at end of file diff --git a/docs/UI/SetGlobalProperties/index.md b/docs/UI/SetGlobalProperties/index.md index 465c5bac0..dfa9bfb25 100644 --- a/docs/UI/SetGlobalProperties/index.md +++ b/docs/UI/SetGlobalProperties/index.md @@ -11,54 +11,54 @@ Purpose ### Description -SDL requests to set-up the data for VR help layout, the name and icon for in-application menu and the properties of the touchscreen keyboard. +SDL requests to set-up the data for VR help layout, the name and icon for in-application menu and the properties of the touchscreen keyboard (such as providing custom special characters to display at the root level of the keyboard layout). -The request may arrive for the application whether being active or in background on HMI (depends on Policy Table permissions applicable to mobile application request, by default allowed to operate in all HMI levels except of NONE). +### Request + +The request may arrive for the application whether being active or in background on HMI (depends on the Policy Table permissions applicable to mobile application request, by default allowed to operate in all HMI levels except `NONE`). -The `vrHelp` parameter of the `SetGlobalProperties` RPC is used by the system to display the help items on the screen and the `helpPrompt` parameter is used by the system for playing out the associated TTS help prompt. +The `vrHelp` parameter of the `SetGlobalProperties` RPC is used by the system to display the help items on the screen, and the `helpPrompt` parameter is used by the system for playing out the associated TTS help prompt. -SDL sends SetGlobalProperties request with specific `` and `` values to HMI in next cases: +SDL Core sends `SetGlobalProperties` request with specific `vrHelp` and `vrHelpTitle` values to HMI in the following cases: -1. If at any point in time, the application sends `SetGlobalProperties` RPC with the `vrHelp` **and** `helpPrompt` parameters, then SDL Core shall continue with the existing behavior of forwarding such requests to HMI and SDL Core shall delete its internal list and stop sending `SetGlobalProperties` RPC to HMI after each AddCommand/DeleteCommand request received from mobile. +1. If at any point in time, the application sends `SetGlobalProperties` RPC with the `vrHelp` **and** `helpPrompt` parameters, then SDL Core shall continue with the existing behavior of forwarding such requests to HMI and SDL Core shall delete its internal list and stop sending `SetGlobalProperties` RPC to HMI after each `AddCommand`/`DeleteCommand` request received from mobile. 2. If at any point in time, the application sends `SetGlobalProperties` RPC with **either** of `vrHelp` **or** `helpPrompt` parameters, then SDL Core shall continue with the existing behavior of forwarding such requests to HMI and SDL Core shall not delete its internal list and shall continue to update the parameter which was not provided by the application. -3. In case mobile app sends `AddCommand` with `CommandType = Command`, SDL must send update values of `vrHelp` via `SetGlobalProperties` to HMI. _(Note: AddCommand requests related to choice set must NOT trigger the update of "vrHelp")_ -4. In case mobile app sends _SetGlobalProperties_request_ to SDL: - - _SDL must_ omit the `autoCompleteText` parameter when forwarding to the HMI - - if `autoCompleteText` is present and `autoCompleteList` is omitted, SDL will forward `autoCompleteList` with a single value, taken from `autoCompleteText`. - +3. In case mobile application sends `AddCommand` with `CommandType = Command`, SDL Core must send updated values of `vrHelp` via `SetGlobalProperties` to HMI. _(Note: `AddCommand` requests related to choice set must NOT trigger the update of `vrHelp`)_ +4. In case mobile application sends _SetGlobalProperties request_ to SDL Core: + * SDL Core must omit the `autoCompleteText` parameter when forwarding to the HMI + * if `autoCompleteText` is present and `autoCompleteList` is omitted, SDL Core forwards `autoCompleteList` with a single value, taken from `autoCompleteText`. + +!!! MUST + +1. Store the information and associate it with `appID`. + * _Note:_ Initially, the appID together with other application-related information is provided by SDL within UpdateAppList or OnAppRegistered RPCs. +2. When the system receives a new list of strings in `autoCompleteList` for a particular application, the system must delete the previous list and replace it with the new list for that application. +3. Whenever the User activates VR or sets up the requested values for VR help layout, HMI must display the list of commands available for voice recognition. SDL Core provides the title for this list (`vrHelpTitle` parameter) and the list of commands itself (`vrHelp` parameter which is an array of `VrHelpItem`). + * _**Important Note:**_ If HMI-defined VR commands are accessible together with those provided by SDL Core via VR.AddCommand, HMI must: + * add the corresponding VR HMI-defined commands to the list of VR help items provided by SDL via UI.SetGlobalProperties + * display the complete list of available VR commands (SDL-defined and HMI-defined ones) when the User activates VR. +4. HMI displays the in-application menu for every active application upon the User's request. It must contain SDL-requested commands (UI.AddCommand) and sub-menus (UI.AddSubMenu). SDL provides the values for the name (`menuTitle` parameter) and for the icon (`menuIcon` parameter) of this in-application menu. The values for in-application menu and touchscreen keyboard are allowed by SDL Core for navigation type of application only. +5. In case SDL sends request with some values in `customKeys` array, HMI must: + * use these values to change the special characters shown in customizable keys + * keep default values in the remaining keys, if the array is less than or equal to customizable keys amount + +_Note: HMI should not duplicate special characters on keyboard._ + +!!! + !!! NOTE By default `vrHelpTitle` value is set to application name. _**Notes for HMI expected behavior:**_ -1. The system shall have the ability to receive and store multiple strings from `autoCompleteList` per app. -2. When the system receives a new list of strings in `autoCompleteList` for a particular app, the system shall delete the previous list and replace it with the new list for that app. -3. When any of the keyboard layouts are being used, the system shall reference the `autoCompleteList` strings for that app. -4. As the user enters data on the keyboard, the system shall display values from `autoCompleteList` which match the entry. -5. The number of matching `autoCompleteList` strings displayed shall only be limited by the character length constraints of the HMI. -6. The system shall provide the user the ability to select one of the displayed matching `autoCompleteList` strings without having to enter the entire string. -7. When the user selects one of the displayed matching `autoCompleteList` strings, the system shall submit that entry and not require further user input for submission. - -!!! - -### Request - -#### Behavior - -!!! MUST - -1. Store the information and associate it with appID. - * Note: _Initially, the appID together with other application-related information is provided by SDL within UpdateAppList or OnAppRegistered RPCs._ -2. Whenever the User activates VR, set up the requested values for VR help layout, the name and icon for in-application menu and the properties of the touchscreen keyboard (if supported): - * display the list of commands available for voice recognition. SDL provides the title for this list (_vrHelpTitle_ parameter) and the list of commands itself (vrHelp parameter which is an array of VrHelpItem‘s). - * display the in-application menu for every active application on User’s request. It must contain SDL-requested commands (UI.AddCommand) and sub menus (UI.AddSubMenu). SDL provides the values for the name (_menuTitle_ parameter) and for the icon (menuIcon parameter) of this in-application menu. The values for in-application menu and touchscreen keyboard are allowed by SDL for navigation type of application only. - * display the onscreen keyboard upon User\`s request within the following condition: all keyboardProperties supported by HMI must be embodied in HMI_capabilities.json file. In this case SDL are able to compare keyboardProperties requested by mobile device with actual supported keyboardProperties and send to HMI only that are supported. - * use default keyboardProperties – parameter in case SDL transfers UI.SetGlobalProperties request with omitted or empty keyboardProperties param to HMI. - * _**Important Note:**_ _If HMI-defined VR commands are accessible together with those provided by SDL via VR.AddCommand, HMI must:_ - * _add the corresponding VR HMI-defined commands to the list of VR help items provided by SDL via UI.SetGlobalProperties_ - * _display the complete list of available VR commands (SDL-defined and HMI-defined ones) when the User activates VR._ -3. Respond to the request. +1. The system shall have the ability to receive and store multiple strings from `autoCompleteList` per application. +2. When any of the keyboard layouts are being used, the system shall reference the `autoCompleteList` strings for that application. +3. As the User enters data on the keyboard, the system shall display values from `autoCompleteList` which match the entry. +4. The number of matching `autoCompleteList` strings displayed shall only be limited by the character length constraints of the HMI. +5. The system shall provide the User with the ability to select one of the displayed matching `autoCompleteList` strings without having to enter the entire string. +6. When the User selects one of the displayed matching `autoCompleteList` strings, the system shall submit that entry and not require further User input for submission. +7. The system shall allow applications to customize the special characters in each keyboard layout depending on the [KeyboardCapabilities](../../common/structs/#keyboardcapabilities) it provides. !!! @@ -76,22 +76,15 @@ _**Notes for HMI expected behavior:**_ ### Response -|Result |Description |Message type WebSocket|Message type D-Bus|Message Params| -|:------|:-----------|:---------------------|:-----------------|:-------------| -|Success|SUCCESS: HMI has set the requested properties.|JSON response|Method return|code: 0| -|Failure|INVALID_ID:appID is not valid (e.g.does not exist)|JSON response|Method return|code: 13| -|Failure|INVALID_DATA: The data sent is invalid (invalid JSON syntax or parameters out of bounds or of wrong type)|JSON response|Method return|code: 11| -|Failure|GENERIC_ERROR: The unknown issue occurred or other codes are not applicable.|JSON response|Method return|code: 22| - !!! NOTE -In case HMI does not respond SDL's request during SDL-default timeout (10 sec), SDL will return GENERIC_ERROR result code to the corresponding mobile app's request. Please see [Result Enumeration] for all SDL-supported codes. -!!! -[Result Enumeration]: ../../common/enums/#result +In case HMI does not respond to SDL Core request during SDL-default timeout (10 sec), SDL Core returns **"GENERIC_ERROR"** result code to the corresponding mobile application request. + +!!! #### Parameters -This RPC has no additional parameter requirements +This RPC has no additional parameter requirements. ### Sequence Diagrams @@ -101,10 +94,20 @@ SetGlobalProperties for active app on HMI with V ||| ||| -SetGlobalProperties for active app with TTS.SetGlobalProperties_request, UI.SetGlobalProperties_request, VR.Started, VR.Stopped. +SetGlobalProperties for active app with TTS.SetGlobalProperties_request, UI.SetGlobalProperties_request, VR.Started, VR.Stopped ![SetGlobalProperties](./assets/SetGlobalProperties_TTS_UI_VR.png) ||| +||| +SetGlobalProperties Custom Keys +![SetGlobalProperties](./assets/SetGlobalPropertiesCustomKeys.png) +||| + +||| +SetGlobalProperties Resumption of non-default KeyboardProperties +![SetGlobalProperties](./assets/SetGlobalPropertiesResumptionKeyboardProperties.png) +||| + ### JSON Message Examples #### Example Request