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