change default lastmode pattern
[apps/agl-service-homescreen.git] / 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 ```