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