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     17th/June/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     - [On Screen Message / Reply Sequence](#on-screen-message-/-reply-sequence)
  25 - [Sample code](#sample-code)
  26 - [Limitation](#limitation)
  27 - [Next Plan](#next-plan)
  28 - [Appendix](#appendix)
  29
  30 * * *
  31
  32 ## Target reader of this document
  33 Application developer whose software uses HomeScreen.
  34
  35 * * *
  36
  37 ## Overview
  38 HomeScreen is built with a GUI application created with Qt(referred as HomeScreenGUI), and a service running on afb-daemon (referred as HomeScreenBinder).
  39 HomeScreen can start/switch applications run in AGL, also displays information such as onscreen messages.
  40
  41 You can find these projects in AGL gerrit.
  42
  43 - [homescreen-2017(HomeScreenGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/staging/homescreen-2017)
  44 - [agl-service-homescreen-2017(HomeScreenBinder's binding library)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen-2017)
  45 - [libhomescreen(library for application to communication with HomeScreenBinder)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen)
  46
  47 Also HomeScreenGUI is using libwindowmanager.
  48
  49 * * *
  50
  51 ## Getting Start
  52
  53 ### Supported environment
  54
  55 | Item        | Description                       |
  56 |:------------|:----------------------------------|
  57 | AGL version | Funky Flounder                      |
  58 | Hardware    | Renesas R-Car Starter Kit Pro(M3) |
  59
  60
  61 ### Build
  62
  63 **Download recipe**
  64
  65 ```
  66 $ mkdir WORK
  67 $ cd WORK
  68 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
  69 $ repo sync
  70
  71 ```
  72
  73 Then you can find the following recipes.
  74
  75 * `meta-agl-devel/meta-hmi-framework/homescreen-2017`
  76
  77 * `meta-agl-devel/meta-hmi-framework/agl-service-homescreen-2017`
  78
  79 * `meta-agl-demo/recipes-demo-hmi/libhomescreen`
  80
  81
  82 **Bitbake**
  83
  84 ```
  85 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
  86 $ bitbake agl-demo-platform
  87 ```
  88
  89 ### Configuring
  90 To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application.
  91
  92 ```
  93 <feature name="urn:AGL:widget:required-api">
  94         <param name="homescreen" value="ws" />
  95 </feature>
  96 ```
  97
  98 ### How to call HomeScreen APIs from your Application?
  99 HomeScreen provides a library which is called "libhomescreen".
 100 This library treats "json format" as API calling.
 101 For example, if an application wants to call "tap_shortcut()" API, the you should implement as below.
 102
 103 At first the application should create the instance of libhomescreen.
 104
 105 ```
 106 LibHomeScreen* libhs;
 107 libhs = new LibHomeScreen();
 108 libhs->init(port, token);
 109 ```
 110
 111 The port and token is provided by Application Framework
 112
 113 Execute the "tapShortcut()" function.
 114
 115 ```
 116 libhs->tapShortcut("application_name");
 117 ```
 118
 119 Regarding the detail of tap_shortcut() API, please refer [this](#HomeScreen\ API) section.
 120 The first parameter is the name of API, so in this case "tap_shortcut" is proper string.
 121 And the second parameter corresponds to arguments of "connect()" API.
 122
 123 See also our [Sample code](#sample-code).
 124
 125 * * *
 126
 127 ## Supported usecase
 128 1. HomeScreenGUI sending ShortCut Icon tapped event to applications
 129         - Applications using libhomescreen to subscribe the tapShortcut event,
 130         HomeScreenGUI will send ShortCut Icon tapped event to applications.
 131 2. Display OnScreen messages
 132         - Applications sending OnScreen messages to homescreen-service, and OnScreenAPP
 133         will get these message and display.
 134 3. Get OnSreen Reply event
 135         - When OnScreen messages is displaying, OnScreenAPP will send a reply event to applications.
 136
 137 * * *
 138
 139 ## Software Architecture
 140 The architecture of HomeScreen is shown below.
 141 HomeScreen is the service designed to be used by multiple applications.
 142 Therefore HomeScreen framework consists on two binder layers. Please refer the following figure.
 143 The upper binder is for application side security context for applications. The lower binder is for servide side security context.
 144 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.
 145 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).
 146
 147 The communication protocols between libhomescreen and upper binder, upper binder and lower binder, lower binder (homescreen-binding) are WebSocket.
 148
 149 ![software-stack.png](parts/software-stack.png)
 150
 151 * * *
 152
 153 ## API reference
 154 "libhomescreen" and "agl-service-homescreen-2017" provides several kinds of APIs.
 155
 156 ### HomeScreen Specific API
 157
 158 - LibHomeScreen::init (const int port, const std::string &token)
 159 ```
 160     port [in] : This argument should be specified to the port number to be used for websocket
 161     token [in] : This argument should be specified to the token to be used for websocket
 162
 163     Create connection to homescreen-service by port and token which provided by
 164     application framework. This API must be called before calling other api.
 165 ```
 166 - LibHomeScreen::tapShortcut(const char *application_name)
 167 ```
 168     application_name [in] : Tapped application name (label)
 169
 170     Request to show the window of application_name.
 171 ```
 172 - LibHomeScreen::onScreenMessage(const char *display_message)
 173 ```
 174     display_message [in] : message for display
 175
 176     Request to display message in onscreen.
 177 ```
 178 - LibHomeScreen::onScreenReply(const char *reply_message)
 179 ```
 180     reply_message [in] : message for reply
 181
 182     Post reply message to application.
 183 ```
 184 - 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)
 185 ```
 186     event_cb [in] : This argument should be specified to the callback for subscribed event
 187     reply_cb [in] : This argument should be specified to the reply callback for call function
 188     hangup_cb [in] : This argument should be specified to the hangup callback for call function
 189
 190     This api is deprecated, recommend using set_event_handler.
 191 ```
 192 - LibHomeScreen::set_event_handler(enum EventType et, handler_func f)
 193 ```
 194     et [in] : event name
 195     f [in] : event handler
 196
 197     Setting event handler for Homescreen-Service Event.
 198 ```
 199 - LibHomeScreen::call(const string& verb, struct json_object* arg)
 200 - LibHomeScreen::call(const char* verb, struct json_object* arg)
 201 ```
 202     verb [in] : This argument should be specified to the API name (e.g. "tap_shortcut")
 203     arg [in] : This argument should be specified to the argument of API.
 204     And this argument expects JSON object
 205
 206     Call homescreen-service verb.
 207 ```
 208 - LibHomeScreen::subscribe(const string& event_name)
 209 ```
 210     event_name [in] : This argument should be specified to the event name
 211
 212     Subscribe homescreen-service event. Deprecated, recommend using set_event_handler.
 213 ```
 214 - LibHomeScreen::unsubscribe(const string& event_name)
 215 ```
 216     event_name [in] : This argument should be specified to the event name
 217
 218     Unsubscribe homescreen-service event. Deprecated, recommend using set_event_handler.
 219 ```
 220
 221 * * *
 222
 223 ## Sequence
 224
 225 ### Initialize Sequence
 226 ![initialize-registercallback.svg](parts/initialize-registercallback.svg) * deprecated
 227 ![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
 228
 229 ### Tap Shortcut Sequence
 230 ![tap_shortcut.svg](parts/tap_shortcut.svg)
 231
 232 ### On Screen Message / Reply Sequence
 233 ![on_screen_message.svg](parts/on_screen_message.svg)
 234
 235 ## Sample code
 236 You can find sample implementation of HomeScreen as below.
 237
 238 * `libhomescreen/sample/simple-egl`
 239
 240 * `libhomescreen/sample/template`
 241
 242 * * *
 243
 244 ## Limitation
 245 None.
 246
 247 * * *
 248
 249 ## Next Plan
 250 None.
 251
 252 * * *
 253
 254 ## Appendix
 255
 256 ```
 257 @startuml
 258 title Application initialization phase (ex. registerCallback)
 259 entity App
 260 entity HomeScreenBinder
 261 entity HomeScreenGUI
 262 App->HomeScreenBinder: init(port, token)
 263 App->HomeScreenBinder: subscribe()
 264
 265 note over HomeScreenBinder
 266     Register the event the App wishes to receive
 267     ・tap_shortcut
 268     ・on_screen_message
 269     ・on_screen_reply
 270 end note
 271
 272 App->HomeScreenBinder: registerCallback()
 273
 274 @enduml
 275 ```
 276
 277 ```
 278 @startuml
 279 title Application initialization phase (ex. set_event_handler)
 280 entity App
 281 entity HomeScreenBinder
 282 entity HomeScreenGUI
 283 App->HomeScreenBinder: init(port, token)
 284 App->HomeScreenBinder: set_event_handler()
 285
 286 note over HomeScreenBinder
 287     setup event handler the App wishes to receive
 288     ・LibHomeScreen::Event_TapShortcut
 289     ・LibHomeScreen::Event_OnScreenMessage
 290     ・LibHomeScreen::Event_OnScreenReply
 291 end note
 292
 293 @enduml
 294 ```
 295
 296 ```
 297 @startuml
 298 title Application Callback Event TapShortcut phase
 299 entity App
 300 entity HomeScreenBinder
 301 entity HomeScreenGUI
 302 App->HomeScreenBinder: set_event_handler()
 303
 304 note over App
 305     LibHomeScreen::Event_TapShortcut
 306 end note
 307
 308 HomeScreenGUI->HomeScreenBinder: tapShortcut(application_name)
 309 HomeScreenBinder->App: event_handler(application_name)
 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 ```