doc/ApplicationGuide.md

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