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 - [agl-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::init (const int port, const std::string &token)
 186 ```
 187     port [in] : This argument should be specified to the port number to be used for websocket
 188     token [in] : This argument should be specified to the token to be used for websocket
 189
 190     Create connection to homescreen-service by port and token which provided by
 191     application framework. This API must be called before calling other api.
 192 ```
 193 - LibHomeScreen::tapShortcut(const char *application_id)
 194 ```
 195     application_id [in] : Tapped application id (label)
 196
 197     This api is deprecated, recommend using showWindow.
 198 ```
 199 - LibHomeScreen::onScreenMessage(const char *display_message)
 200 ```
 201     display_message [in] : message for display
 202
 203     This api is deprecated, recommend using showWindow/hideWindow to call onscreenapp.
 204 ```
 205 - LibHomeScreen::onScreenReply(const char *reply_message)
 206 ```
 207     reply_message [in] : message for reply
 208
 209     This api is deprecated, recommend using replyShowWindow.
 210 ```
 211 - LibHomeScreen::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)
 212 ```
 213     event_cb [in] : This argument should be specified to the callback for subscribed event
 214     reply_cb [in] : This argument should be specified to the reply callback for call function
 215     hangup_cb [in] : This argument should be specified to the hangup callback for call function
 216
 217     This api is deprecated, recommend using set_event_handler.
 218 ```
 219 - LibHomeScreen::set_event_handler(enum EventType et, handler_func f)
 220 ```
 221     et [in] : event name
 222     f [in] : event handler
 223
 224     Setting event handler for Homescreen-Service Event.
 225 ```
 226 - LibHomeScreen::call(const string& verb, struct json_object* arg)
 227 - LibHomeScreen::call(const char* verb, struct json_object* arg)
 228 ```
 229     verb [in] : This argument should be specified to the API name (e.g. "tap_shortcut")
 230     arg [in] : This argument should be specified to the argument of API.
 231     And this argument expects JSON object
 232
 233     Call homescreen-service verb.
 234 ```
 235 - LibHomeScreen::subscribe(const string& event_name)
 236 ```
 237     event_name [in] : This argument should be specified to the event name
 238
 239     Subscribe homescreen-service event. Deprecated, recommend using set_event_handler.
 240 ```
 241 - LibHomeScreen::unsubscribe(const string& event_name)
 242 ```
 243     event_name [in] : This argument should be specified to the event name
 244
 245     Unsubscribe homescreen-service event. Deprecated, recommend using set_event_handler.
 246 ```
 247 - LibHomeScreen::showWindow(const char* application_id, json_object* json)
 248 ```
 249     application_id [in] : This argument should be specified to the application's id
 250     json [in] : This argument should be specified to the json parameters
 251
 252     Request to show the window of application_id, and set display area in json liked
 253     {"area":"normal.full"}.
 254 ```
 255 - LibHomeScreen::hideWindow(const char* application_id)
 256 ```
 257     application_id [in] : This argument should be specified to the application's id
 258
 259     Request to hide the window of application_id.
 260 ```
 261 - LibHomeScreen::replyShowWindow(const char* application_id, json_object* json)
 262 ```
 263     application_id [in] : This argument should be specified to the onscreen reply to applilcation id
 264     json [in] : This argument should be specified to the json parameters
 265
 266     Post reply information to who called showWindow.
 267 ```
 268 - LibHomeScreen::showNotification(json_object* json)
 269 ```
 270     json [in] : This argument should be specified to the json parameters.
 271
 272     Post Notification to Homescreen which will display at top area of Homescreen.
 273 ```
 274 - LibHomeScreen::showInformation(json_object* json)
 275 ```
 276     json [in] : This argument should be specified to the json parameters.
 277
 278     Post Information to Homescreen which will display at bottom area of Homescreen.
 279 ```
 280
 281 * * *
 282
 283 ## Sequence
 284
 285 ### Initialize Sequence
 286 ![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
 287
 288 ### Tap Shortcut Sequence
 289 ![tap_shortcut.svg](parts/tap_shortcut.svg)
 290
 291 ### ShowWindow Sequence
 292 ![showWindow.svg](parts/showWindow.svg)
 293
 294 ### On Screen Message / Reply Sequence
 295 ![on_screen_message.svg](parts/on_screen_message.svg)
 296
 297 ### ShowOnScreen Sequence
 298 ![showOnScreen.svg](parts/showOnScreen.svg)
 299
 300 ### ShowNotification Sequence
 301 ![showNotification.svg](parts/showNotification.svg)
 302
 303 ### ShowInformation Sequence
 304 ![showInformation.svg](parts/showInformation.svg)
 305
 306 * * *
 307
 308 ## Sample code
 309 You can find sample implementation of HomeScreen as below.
 310
 311 * `libhomescreen/sample/simple-egl`
 312
 313 * `libhomescreen/sample/template`
 314
 315 * * *
 316
 317 ## Limitation
 318 None.
 319
 320 * * *
 321
 322 ## Next Plan
 323 None.
 324
 325 * * *
 326
 327 ## Appendix
 328
 329 ```
 330 @startuml
 331
 332 title Application initialization phase
 333
 334 entity App
 335 entity HomeScreenBinder
 336 entity HomeScreenGUI
 337
 338 App->HomeScreenBinder: init(port, token)
 339 App->HomeScreenBinder: set_event_handler()
 340
 341 note over HomeScreenBinder
 342     setup event handler the App wishes to receive
 343     ・LibHomeScreen::Event_ShowWindow
 344     ・LibHomeScreen::Event_HideWindow
 345     ・LibHomeScreen::Event_ReplyShowWindow
 346 end note
 347
 348 @enduml
 349 ```
 350
 351 ```
 352 @startuml
 353 title Application Callback Event TapShortcut phase
 354 entity App
 355 entity HomeScreenBinder
 356 entity HomeScreenGUI
 357 App->HomeScreenBinder: set_event_handler()
 358
 359 note over App
 360     LibHomeScreen::Event_TapShortcut
 361 end note
 362
 363 HomeScreenGUI->HomeScreenBinder: tapShortcut(application_id)
 364 HomeScreenBinder->App: event_handler(application_id)
 365 @enduml
 366 ```
 367
 368 ```
 369 @startuml
 370
 371 title Application callback event showWindow phase
 372
 373 actor user
 374 entity "homescreen-service" as hss
 375 entity launcher
 376 entity App
 377 entity windowmanager as wm
 378
 379 user-->launcher: tap app's icon
 380 launcher->hss: showWindow()
 381 note over hss,App
 382 {"application_id":"tapped application id", "parameter":{"area":"display area", ...}}
 383 end note
 384 hss->App: push showWindow event
 385 App->wm: activateWindow("application_name","display area")
 386 wm-->App: push syncDraw event
 387 App->App: display
 388
 389 @enduml
 390 ```
 391
 392 ```
 393 @startuml
 394 title Application Callback Event On Screen Message / Reply phase
 395 entity App
 396 entity HomeScreenBinder
 397 entity HomeScreenGUI
 398
 399 HomeScreenGUI->HomeScreenBinder: set_event_handler()
 400
 401 note over HomeScreenGUI
 402     LibHomeScreen::Event_OnScreenMessage
 403 end note
 404
 405
 406 App->HomeScreenBinder: set_event_handler()
 407
 408 note over App
 409     LibHomeScreen::Event_OnScreenReply
 410 end note
 411
 412 App->HomeScreenBinder: onScreenMessage(display_message)
 413 HomeScreenBinder->HomeScreenGUI: event_handler(display_message)
 414 HomeScreenGUI->HomeScreenBinder: onScreenReply(reply_message)
 415 HomeScreenBinder->App: event_handler(reply_message)
 416 @enduml
 417 ```
 418
 419 ```
 420 @startuml
 421
 422 title show/hide onscreen phase
 423
 424 actor user
 425 entity "homescreen-service" as hss
 426 entity App
 427 entity onscreenapp
 428 entity windowmanager as wm
 429
 430 == show onscreen ==
 431 user->App: the operation request onscreen
 432 App->hss: showWindow()
 433 note over App,hss
 434 {"application_id":"onscreenapp",
 435 "parameter":{"area":"display area", "file":"qml file path",
 436 "data":{"the datas to onscreen qml"}}}
 437 end note
 438
 439 hss->onscreenapp: push showWindow event
 440 note over hss,onscreenapp
 441 {"application_id":"onscreenapp",
 442 "parameter":{"area":"display area", "file":"qml file path",
 443 "data":{"the datas to onscreen qml"},
 444 <font color=red >"replyto":"caller application id"
 445 }}
 446 end note
 447
 448 onscreenapp->onscreenapp: get and save parameters
 449 onscreenapp->wm: activateWindow("onscreeapp", "display area")
 450 alt can show
 451 wm-->onscreenapp: push syncDraw event
 452 onscreenapp->wm: endDraw("onscreeapp")
 453 onscreenapp->onscreenapp: load and display qml file
 454 else can't show
 455 note over onscreenapp,wm
 456 do nothing
 457 end note
 458 end
 459
 460 == hide onscreen ==
 461
 462 user->onscreenapp: tap onscreen's button
 463 onscreenapp->hss: replyShowWindow()
 464 note over onscreenapp,hss
 465 {"application_id":"the application id who called onscreenapp",
 466 "parameter": {"buttonName": "VOLUME_UP", "buttonPressMode": "shortPress", "buttonPressState": "release"}}
 467 end note
 468 hss->App: push replyShowWindow event
 469 App->App: call reply function
 470 App->hss: hideWindow("onscreenapp")
 471 hss->onscreenapp: push hideWindow event
 472 note over hss,onscreenapp
 473 {"application_id":"request hideWindow application id"}
 474 end note
 475 onscreenapp->wm: deactivateWindow("onscreenapp");
 476 onscreenapp->onscreenapp: hide window
 477
 478 @enduml
 479 ```
 480
 481 ```
 482 @startuml
 483
 484 title show notification on HomeScreen top area
 485
 486 entity "homescreen-service" as hss
 487 entity homescreen
 488 entity App
 489
 490 App->hss: showNotification()
 491 note over App,hss
 492 {"icon":"display icon", "text":"display text"}
 493 end note
 494 hss-> homescreen: push showNotification event
 495 note over hss,homescreen
 496 {"application_id":"request application id",
 497 "parameter":{"icon":"display icon", "text":"display text"}}
 498 end note
 499
 500 homescreen->homescreen: display notification message 3s
 501
 502 @enduml
 503 ```
 504
 505 ```
 506 @startuml
 507
 508 title show information on HomeScreen bottom area
 509
 510 entity "homescreen-service" as hss
 511 entity homescreen
 512 entity App
 513
 514 App->hss: showInformation()
 515 note over hss
 516 {"info":"display information"}
 517 end note
 518 hss-> homescreen: push showInformation event
 519
 520 homescreen->homescreen: display information message 3s
 521
 522 @enduml
 523 ```