docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.1_Home_Screen_Developer_Guide.md

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