doc/ApplicationGuide.md

   1 **HomeScreen GUI Application / HomeScreen Service Guide**
   2 ====
   3     Revision: 0.1
   4     TOYOTA MOTOR CORPORATION
   5     Advanced Driver Information Technology
   6     13th/May/2019
   7
   8 * * *
   9
  10 ## Table of content
  11 - [Target reader of this document](#target-reader-of-this-document)
  12 - [Overview](#overview)
  13 - [Getting Start](#getting-start)
  14         - [Supported environment](#supported-environment)
  15         - [Build](#build)
  16         - [Configuring](#configuring)
  17         - [How to call HomeScreen APIs from your Application?](#how-to-call-homescreen-apis-from-your-application)
  18 - [Supported usecase](#supported-usecase)
  19 - [Software Architecture](#software-architecture)
  20 - [API reference](#api-reference)
  21 - [Sequence](#sequence)
  22         - [Initialize](#initialize-sequence)
  23         - [Tap Shortcut(deprecated)](#tap-shortcut-sequence)
  24     - [ShowWindow](#showwindow-sequence)
  25         - [On Screen Message / Reply Sequence(deprecated)](#on-screen-message-reply-sequence)
  26     - [ShowOnscreen](#showonscreen-sequence)
  27     - [ShowNotification](#shownotification-sequence)
  28     - [ShowInformation](#showinformation-sequence)
  29 - [Sample code](#sample-code)
  30 - [Limitation](#limitation)
  31 - [Next Plan](#next-plan)
  32 - [Appendix](#appendix)
  33
  34 * * *
  35
  36 ## Target reader of this document
  37 Application developer whose software uses HomeScreen.
  38
  39 * * *
  40
  41 ## Overview
  42 HomeScreen is built with a GUI application created with Qt(referred as HomeScreenGUI), and a service running on afb-daemon (referred as HomeScreenBinder).
  43 HomeScreen can start/switch applications run in AGL, also displays information such as onscreen messages.
  44
  45 You can find these projects in AGL gerrit.
  46
  47 - [homescreen(HomeScreenGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/homescreen)
  48 - [launcher(LauncherGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/launcher)
  49 - [gl-service-homescreen(HomeScreenBinder's binding library)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen)
  50 - [libhomescreen(library for application to communication with HomeScreenBinder](    https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen)
  51 - [libqthomescreen(library for qt application to communication with HomeScreenBinder based on libhomescreen)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libqthomescreen)
  52
  53 Also HomeScreenGUI is using libwindowmanager.
  54
  55 * * *
  56
  57 ## Getting Start
  58
  59 ### Supported environment
  60
  61 | Item        | Description                       |
  62 |:------------|:----------------------------------|
  63 | AGL version | Grumpy Guppy                      |
  64 | Hardware    | Renesas R-Car Starter Kit Pro(M3) |
  65
  66
  67 ### Build
  68
  69 **Download recipe**
  70
  71 ```
  72 $ mkdir WORK
  73 $ cd WORK
  74 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
  75 $ repo sync
  76
  77 ```
  78
  79 Then you can find the following recipes.
  80
  81 * `meta-agl-demo/recipes-demo-hmi/homescreen`
  82
  83 * `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/launcher`
  84
  85 * `meta-agl-demo/recipes-demo-hmi/agl-service-homescreen`
  86
  87 * `meta-agl-demo/recipes-demo-hmi/libhomescreen`
  88
  89 * `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/qlibhomescreen`
  90
  91
  92 **Bitbake**
  93
  94 ```
  95 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
  96 $ bitbake agl-demo-platform
  97 ```
  98
  99 ### Configuring
 100 To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application.
 101
 102 ```
 103 <feature name="urn:AGL:widget:required-api">
 104         <param name="homescreen" value="ws" />
 105     <param name="windowmanager" value="ws" />
 106 </feature>
 107 ```
 108
 109 ### How to call HomeScreen APIs from your Application?
 110 HomeScreen provides a library which is called "libhomescreen".
 111 This library treats "json format" as API calling.
 112 For example, if an application wants to call "showWIndow()" API, the you should implement as below.
 113
 114 At first the application should create the instance of libhomescreen.
 115
 116 ```
 117 LibHomeScreen* libhs;
 118 libhs = new LibHomeScreen();
 119 libhs->init(port, token);
 120 ```
 121
 122 The port and token is provided by Application Framework
 123
 124 Execute the "showWindow()" function.
 125
 126 ```
 127 libhs->showWindow("application_id", "display_area");
 128 ```
 129
 130 Regarding the detail of showWindow() API, please refer [this](#homescreen-specific-api) section.
 131 The first parameter is the appid of application which want to display,liked "dashboard".
 132 And the second parameter corresponds to display_area which defined by windowmanager,usually "normal",
 133 so in this case "showWindow" the two parameters are proper string.
 134
 135 See also our [Sample code](#sample-code).
 136
 137 * * *
 138
 139 ## Supported usecase
 140 1. HomeScreenGUI sending showWindow event to applications
 141         - Applications using libhomescreen to subscribe the showWindow event,
 142         HomeScreenGUI will send showWindow event to applications.
 143 2. Display OnScreen messages(deprecated)
 144         - Applications sending OnScreen messages to homescreen-service, and OnScreenAPP
 145         will get these message and display.
 146 3. Get OnSreen Reply event(deprecated)
 147         - When OnScreen messages is displaying, OnScreenAPP will send a reply event to applications.
 148 4. Display OnScreen by showWindow
 149     - When application who want to show OnScreen,it can call "showWindow",then OnScreenApp will
 150         display request OnScreen.
 151 5. Hide OnScreen by hideWindow
 152     - When application who want to hide OnScreen which is displaying,it can call "hideWindow",then OnScreenApp
 153         will hide OnScreen.
 154 6. Send OnScreen Reply by replyShowWindow
 155     - When user touch the button of OnScreen, OnScreenApp can call "relplyShowWindow" to send reply information
 156         back to application.
 157 7. Show Notification on HomeScreenGUI
 158     - When application who want to display a notification,it can call "showNotification",then HomeScreenGUI will
 159         display the notification contents on the screen top area.
 160 8. Show Information on HomeScreenGUI
 161     - When application who want to display a information,it can call "showInformation",then HomeScreenGUI will
 162         display the information contents on the screen bottom area.
 163
 164 * * *
 165
 166 ## Software Architecture
 167 The architecture of HomeScreen is shown below.
 168 HomeScreen is the service designed to be used by multiple applications.
 169 Therefore HomeScreen framework consists on two binder layers. Please refer the following figure.
 170 The upper binder is for application side security context for applications. The lower binder is for servide side security context.
 171 Usually application side binder has some business logic for each application, so the number of binders depend on the number of applications which use HomeScreen.
 172 On the other hand, regarding lower binder there is only one module in the system. This binder receives all messages from multiple applications (in detail, it comes from upper layer binder).
 173
 174 The communication protocols between libhomescreen and upper binder, upper binder and lower binder, lower binder (homescreen-binding) are WebSocket.
 175
 176 ![software-stack.png](parts/software-stack.png)
 177
 178 * * *
 179
 180 ## API reference
 181 "libhomescreen" and "agl-service-homescreen" provides several kinds of APIs.
 182
 183 ### HomeScreen Specific API
 184
 185 - [LibHomeScreen ()](api-ref/html/de/dd0/class_lib_home_screen.html#a724bd949c4154fad041f96a15ef0f5dc)
 186 - [init (const int port, const std::string &token)](api-ref/html/de/dd0/class_lib_home_screen.html#a6a57b573cc767725762ba9beab032220)
 187 - [tapShortcut(const char *application_id)](api-ref/html/de/dd0/class_lib_home_screen.html#a6ca8ff4a2aa019a735afaff713e0ef44)
 188 - [onScreenMessage(const char *display_message)](api-ref/html/de/dd0/class_lib_home_screen.html#ac336482036a72b51a822725f1929523c)
 189 - [onScreenReply(const char *reply_message)](api-ref/html/de/dd0/class_lib_home_screen.html#a6c065f41f2c5d1f58d2763bfb4da9c37)
 190 - [registerCallback (void(*event_cb)(const std::string &event, struct json_object *event_contents), void(*reply_cb)(struct json_object *reply_contents), void(*hangup_cb)(void)=nullptr)](api-ref/html/de/dd0/class_lib_home_screen.html#a2789e8a5372202cc36f48e71dbb9b7cf)
 191 - [set\_event\_handler(enum EventType et, handler_func f)](api-ref/html/de/dd0/class_lib_home_screen.html#ab1b0e08bf35415de9064afed899e9f85)
 192 - [call (const string& verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#a527b49dcfe581be6275d0eb2236ba37f)
 193 - [call (const char* verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#ab5e8e8ab7d53e0f114e9e907fcbb7643)
 194 - [subscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aa4c189807b75d070f567967f0d690738)
 195 - [unsubscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aac03a45cbd453ba69ddb00c1016930a6)
 196 - [showWindow (const char* application_id, json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a69fc770cb3f94d30a10c2c8c81eb892f)
 197 - [hideWindow (const char* application_id)](api-ref/html/de/dd0/class_lib_home_screen.html#a4dbaea6c7b310e8ce7207155ff11b32a)
 198 - [replyShowWindow (const char* application_id, json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a6310b129fc85ef0623e2e2063950cc4b)
 199 - [showNotification (json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a93ad567ed597a80a344ba82457c2bd7f)
 200 - [showInformation (json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#ada999aeb0444c964428bdf1ee236727f)
 201
 202 * * *
 203
 204 ## Sequence
 205
 206 ### Initialize Sequence
 207 ![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
 208
 209 ### Tap Shortcut Sequence
 210 ![tap_shortcut.svg](parts/tap_shortcut.svg)
 211
 212 ### ShowWindow Sequence
 213 ![showWindow.svg](parts/showWindow.svg)
 214
 215 ### On Screen Message / Reply Sequence
 216 ![on_screen_message.svg](parts/on_screen_message.svg)
 217
 218 ### ShowOnScreen Sequence
 219 ![showOnScreen.svg](parts/showOnScreen.svg)
 220
 221 ### ShowNotification Sequence
 222 ![showNotification.svg](parts/showNotification.svg)
 223
 224 ### ShowInformation Sequence
 225 ![showInformation.svg](parts/showInformation.svg)
 226
 227 * * *
 228
 229 ## Sample code
 230 You can find sample implementation of HomeScreen as below.
 231
 232 * `libhomescreen/sample/simple-egl`
 233
 234 * `libhomescreen/sample/template`
 235
 236 * * *
 237
 238 ## Limitation
 239 Now OnScreenApp is developing,approximately it will finished at GG.
 240
 241 * * *
 242
 243 ## Next Plan
 244 None.
 245
 246 * * *
 247
 248 ## Appendix
 249
 250 ```
 251 @startuml
 252
 253 title Application initialization phase
 254
 255 entity App
 256 entity HomeScreenBinder
 257 entity HomeScreenGUI
 258
 259 App->HomeScreenBinder: init(port, token)
 260 App->HomeScreenBinder: set_event_handler()
 261
 262 note over HomeScreenBinder
 263     setup event handler the App wishes to receive
 264     ・LibHomeScreen::Event_ShowWindow
 265     ・LibHomeScreen::Event_HideWindow
 266     ・LibHomeScreen::Event_ReplyShowWindow
 267 end note
 268
 269 @enduml
 270 ```
 271
 272 ```
 273 @startuml
 274 title Application Callback Event TapShortcut phase
 275 entity App
 276 entity HomeScreenBinder
 277 entity HomeScreenGUI
 278 App->HomeScreenBinder: set_event_handler()
 279
 280 note over App
 281     LibHomeScreen::Event_TapShortcut
 282 end note
 283
 284 HomeScreenGUI->HomeScreenBinder: tapShortcut(application_id)
 285 HomeScreenBinder->App: event_handler(application_id)
 286 @enduml
 287 ```
 288
 289 ```
 290 @startuml
 291
 292 title Application callback event showWindow phase
 293
 294 actor user
 295 entity "homescreen-service" as hss
 296 entity launcher
 297 entity App
 298 entity windowmanager as wm
 299
 300 user-->launcher: tap app's icon
 301 launcher->hss: showWindow()
 302 note over hss,App
 303 {"application_id":"tapped application id", "parameter":{"area":"display area", ...}}
 304 end note
 305 hss->App: push showWindow event
 306 App->wm: activateWindow("application_name","display area")
 307 wm-->App: push syncDraw event
 308 App->App: display
 309
 310 @enduml
 311 ```
 312
 313 ```
 314 @startuml
 315 title Application Callback Event On Screen Message / Reply phase
 316 entity App
 317 entity HomeScreenBinder
 318 entity HomeScreenGUI
 319
 320 HomeScreenGUI->HomeScreenBinder: set_event_handler()
 321
 322 note over HomeScreenGUI
 323     LibHomeScreen::Event_OnScreenMessage
 324 end note
 325
 326
 327 App->HomeScreenBinder: set_event_handler()
 328
 329 note over App
 330     LibHomeScreen::Event_OnScreenReply
 331 end note
 332
 333 App->HomeScreenBinder: onScreenMessage(display_message)
 334 HomeScreenBinder->HomeScreenGUI: event_handler(display_message)
 335 HomeScreenGUI->HomeScreenBinder: onScreenReply(reply_message)
 336 HomeScreenBinder->App: event_handler(reply_message)
 337 @enduml
 338 ```
 339
 340 ```
 341 @startuml
 342
 343 title show/hide onscreen phase
 344
 345 actor user
 346 entity "homescreen-service" as hss
 347 entity App
 348 entity onscreenapp
 349 entity windowmanager as wm
 350
 351 == show onscreen ==
 352 user->App: the operation request onscreen
 353 App->hss: showWindow()
 354 note over App,hss
 355 {"application_id":"onscreenapp",
 356 "parameter":{"area":"display area", "file":"qml file path",
 357 "data":{"the datas to onscreen qml"}}}
 358 end note
 359
 360 hss->onscreenapp: push showWindow event
 361 note over hss,onscreenapp
 362 {"application_id":"onscreenapp",
 363 "parameter":{"area":"display area", "file":"qml file path",
 364 "data":{"the datas to onscreen qml"},
 365 <font color=red >"replyto":"caller application id"
 366 }}
 367 end note
 368
 369 onscreenapp->onscreenapp: get and save parameters
 370 onscreenapp->wm: activateWindow("onscreeapp", "display area")
 371 alt can show
 372 wm-->onscreenapp: push syncDraw event
 373 onscreenapp->wm: endDraw("onscreeapp")
 374 onscreenapp->onscreenapp: load and display qml file
 375 else can't show
 376 note over onscreenapp,wm
 377 do nothing
 378 end note
 379 end
 380
 381 == hide onscreen ==
 382
 383 user->onscreenapp: tap onscreen's button
 384 onscreenapp->hss: replyShowWindow()
 385 note over onscreenapp,hss
 386 {"application_id":"the application id who called onscreenapp",
 387 "parameter": {"buttonName": "VOLUME_UP", "buttonPressMode": "shortPress", "buttonPressState": "release"}}
 388 end note
 389 hss->App: push replyShowWindow event
 390 App->App: call reply function
 391 App->hss: hideWindow("onscreenapp")
 392 hss->onscreenapp: push hideWindow event
 393 note over hss,onscreenapp
 394 {"application_id":"request hideWindow application id"}
 395 end note
 396 onscreenapp->wm: deactivateWindow("onscreenapp");
 397 onscreenapp->onscreenapp: hide window
 398
 399 @enduml
 400 ```
 401
 402 ```
 403 @startuml
 404
 405 title show notification on HomeScreen top area
 406
 407 entity "homescreen-service" as hss
 408 entity homescreen
 409 entity App
 410
 411 App->hss: showNotification()
 412 note over App,hss
 413 {"icon":"display icon", "text":"display text"}
 414 end note
 415 hss-> homescreen: push showNotification event
 416 note over hss,homescreen
 417 {"application_id":"request application id",
 418 "parameter":{"icon":"display icon", "text":"display text"}}
 419 end note
 420
 421 homescreen->homescreen: display notification message 3s
 422
 423 @enduml
 424 ```
 425
 426 ```
 427 @startuml
 428
 429 title show information on HomeScreen bottom area
 430
 431 entity "homescreen-service" as hss
 432 entity homescreen
 433 entity App
 434
 435 App->hss: showInformation()
 436 note over hss
 437 {"info":"display information"}
 438 end note
 439 hss-> homescreen: push showInformation event
 440
 441 homescreen->homescreen: display information message 3s
 442
 443 @enduml
 444 ```