1 **HomeScreen GUI Application / HomeScreen Service Guide**
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>
10 <div id="Table\ of\ content"></div>
13 - [Target reader of this document](#Target\ reader\ of\ this\ document)
14 - [Overview](#Overview)
15 - [Getting Start](#Getting\ Start)
16 - [Supported environment](#Supported\ environment)
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 - [Sample code](#Sample\ code)
32 - [Limitation](#Limitation)
33 - [Next Plan](#Next\ Plan)
34 - [Appendix](#Appendix)
38 <div id="Target\ reader\ of\ this\ document"></div>
40 ## Target reader of this document
41 Application developer whose software uses HomeScreen.
45 <div id="Overview"></div>
48 HomeScreen is built with a GUI application created with Qt(referred as HomeScreenGUI), and a service running on afb-daemon (referred as HomeScreenBinder).
49 HomeScreen can start/switch applications run in AGL, also displays information such as onscreen messages.
51 You can find these projects in AGL gerrit.
53 homescreen(HomeScreenGUI):
54 https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/homescreen
56 https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/launcher
57 agl-service-homescreen(HomeScreenBinder's binding library):
58 https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen
59 libhomescreen(library for application to communication with HomeScreenBinder):
60 https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen
61 libqthomescreen(library for qt application to communication with HomeScreenBinder based on libhomescreen)
62 https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libqthomescreen
64 Also HomeScreenGUI is using libwindowmanager.
66 <div id="Getting\ Start"></div>
70 <div id="Supported\ environment"></div>
72 ### Supported environment
74 | Item | Description |
75 |:------------|:----------------------------------|
76 | AGL version | Electric Eel |
77 | Hardware | Renesas R-Car Starter Kit Pro(M3) |
80 <div id="Build"></div>
89 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
94 Then you can find the following recipes.
96 * `meta-agl-demo/recipes-demo-hmi/homescreen`
98 * `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/launcher`
100 * `meta-agl-demo/recipes-demo-hmi/agl-service-homescreen`
102 * `meta-agl-demo/recipes-demo-hmi/libhomescreen`
104 * `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/qlibhomescreen`
110 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
111 $ bitbake agl-demo-platform
117 <div id="Configuring"></div>
120 To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application.
123 <feature name="urn:AGL:widget:required-api">
124 <param name="homescreen" value="ws" />
125 <param name="windowmanager" value="ws" />
131 <div id="How\ to\ call\ HomeScreen\ APIs\ from\ your\ Application?"></div>
133 ### How to call HomeScreen APIs from your Application?
134 HomeScreen provides a library which is called "libhomescreen".
135 This library treats "json format" as API calling.
136 For example, if an application wants to call "showWIndow()" API, the you should implement as below.
138 At first the application should create the instance of libhomescreen.
141 LibHomeScreen* libhs;
142 libhs = new LibHomeScreen();
143 libhs->init(port, token);
146 The port and token is provided by Application Framework
148 Execute the "showWindow()" function.
151 libhs->showWindow("application_id", "display_area");
154 Regarding the detail of showWindow() API, please refer [this](#HomeScreen\ API) section.
155 The first parameter is the appid of application which want to display,liked "dashboard".
156 And the second parameter corresponds to display_area which defined by windowmanager,usually "normal",
157 so in this case "showWindow" the two parameters are proper string.
159 See also our [Sample code](#Sample\ code).
166 <div id="Supported\ usecase"></div>
169 1. HomeScreenGUI sending showWindow event to applications
170 - Applications using libhomescreen to subscribe the showWindow event,
171 HomeScreenGUI will send showWindow event to applications.
172 2. Display OnScreen messages(deprecated)
173 - Applications sending OnScreen messages to homescreen-service, and OnScreenAPP
174 will get these message and display.
175 3. Get OnSreen Reply event(deprecated)
176 - When OnScreen messages is displaying, OnScreenAPP will send a reply event to applications.
177 4. Display OnScreen by showWindow
178 - When application who want to show OnScreen,it can call "showWindow",then OnScreenApp will
179 display request OnScreen.
180 5. Hide OnScreen by hideWindow
181 - When application who want to hide OnScreen which is displaying,it can call "hideWindow",then OnScreenApp
183 6. Send OnScreen Reply by replyShowWindow
184 - When user touch the button of OnScreen, OnScreenApp can call "relplyShowWindow" to send reply information
186 7. Show Notification on HomeScreenGUI
187 - When application who want to display a notification,it can call "showNotification",then HomeScreenGUI will
188 display the notification contents on the screen top area.
189 8. Show Information on HomeScreenGUI
190 - When application who want to display a information,it can call "showInformation",then HomeScreenGUI will
191 display the information contents on the screen bottom area.
194 <div id="Software\ Architecture"></div>
196 ## Software Architecture
197 The architecture of HomeScreen is shown below.
198 HomeScreen is the service designed to be used by multiple applications.
199 Therefore HomeScreen framework consists on two binder layers. Please refer the following figure.
200 The upper binder is for application side security context for applications. The lower binder is for servide side security context.
201 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.
202 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).
204 The communication protocols between libhomescreen and upper binder, upper binder and lower binder, lower binder (homescreen-binding) are WebSocket.
206 ![software-stack.png](parts/software-stack.png)
210 <div id="API%20reference"></div>
213 "libhomescreen" and "agl-service-homescreen" provides several kinds of APIs.
215 <div id="Home\ Screen\ Specific\ API"></div>
217 ### HomeScreen Specific API
219 - [LibHomeScreen ()](api-ref/html/de/dd0/class_lib_home_screen.html#a724bd949c4154fad041f96a15ef0f5dc)
220 - [init (const int port, const std::string &token)](api-ref/html/de/dd0/class_lib_home_screen.html#a6a57b573cc767725762ba9beab032220)
221 - [tapShortcut(const char *application_id)](api-ref/html/de/dd0/class_lib_home_screen.html#a6ca8ff4a2aa019a735afaff713e0ef44)
222 - [onScreenMessage(const char *display_message)](api-ref/html/de/dd0/class_lib_home_screen.html#ac336482036a72b51a822725f1929523c)
223 - [onScreenReply(const char *reply_message)](api-ref/html/de/dd0/class_lib_home_screen.html#a6c065f41f2c5d1f58d2763bfb4da9c37)
224 - [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)
225 - [set\_event\_handler(enum EventType et, handler_func f)](api-ref/html/de/dd0/class_lib_home_screen.html#ab1b0e08bf35415de9064afed899e9f85)
226 - [call (const string& verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#a527b49dcfe581be6275d0eb2236ba37f)
227 - [call (const char* verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#ab5e8e8ab7d53e0f114e9e907fcbb7643)
228 - [subscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aa4c189807b75d070f567967f0d690738)
229 - [unsubscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aac03a45cbd453ba69ddb00c1016930a6)
230 - [showWindow (const char* application_id, json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a69fc770cb3f94d30a10c2c8c81eb892f)
231 - [hideWindow (const char* application_id)](api-ref/html/de/dd0/class_lib_home_screen.html#a4dbaea6c7b310e8ce7207155ff11b32a)
232 - [replyShowWindow (const char* application_id, json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a6310b129fc85ef0623e2e2063950cc4b)
233 - [showNotification (json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#a93ad567ed597a80a344ba82457c2bd7f)
234 - [showInformation (json_object* json)](api-ref/html/de/dd0/class_lib_home_screen.html#ada999aeb0444c964428bdf1ee236727f)
239 <div id="Sequence"></div>
243 <div id="InitializeSequence"></div>
245 ### Initialize Sequence
246 ![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
248 <div id="TapShortcutSequence"></div>
250 ### Tap Shortcut Sequence
251 ![tap_shortcut.svg](parts/tap_shortcut.svg)
253 <div id="ShowWindowSequence"></div>
255 ### ShowWindow Sequence
256 ![showWindow.svg](parts/showWindow.svg)
258 <div id="OnScreenMessageSequence"></div>
260 ### On Screen Message / Reply Sequence
261 ![on_screen_message.svg](parts/on_screen_message.svg)
263 <div id="ShowOnscreenSequence"></div>
265 ### ShowOnScreen Sequence
266 ![showOnScreen.svg](parts/showOnScreen.svg)
268 <div id="ShowNotificationSequence"></div>
270 ### ShowNotification Sequence
271 ![showNotification.svg](parts/showNotification.svg)
273 <div id="ShowInformationSequence"></div>
275 ### ShowInformation Sequence
276 ![showInformation.svg](parts/showInformation.svg)
279 <div id="Sample\ code"></div>
282 You can find sample implementation of HomeScreen as below.
284 * `libhomescreen/sample/simple-egl`
286 * `libhomescreen/sample/template`
289 Now OnScreenApp is developing,approximately it will finished at GG.
299 title Application initialization phase
302 entity HomeScreenBinder
305 App->HomeScreenBinder: init(port, token)
306 App->HomeScreenBinder: set_event_handler()
308 note over HomeScreenBinder
309 setup event handler the App wishes to receive
310 ・LibHomeScreen::Event_ShowWindow
311 ・LibHomeScreen::Event_HideWindow
312 ・LibHomeScreen::Event_ReplyShowWindow
320 title Application Callback Event TapShortcut phase
322 entity HomeScreenBinder
324 App->HomeScreenBinder: set_event_handler()
327 LibHomeScreen::Event_TapShortcut
330 HomeScreenGUI->HomeScreenBinder: tapShortcut(application_id)
331 HomeScreenBinder->App: event_handler(application_id)
338 title Application callback event showWindow phase
341 entity "homescreen-service" as hss
344 entity windowmanager as wm
346 user-->launcher: tap app's icon
347 launcher->hss: showWindow()
349 {"application_id":"tapped application id", "parameter":{"area":"display area", ...}}
351 hss->App: push showWindow event
352 App->wm: activateWindow("application_name","display area")
353 wm-->App: push syncDraw event
361 title Application Callback Event On Screen Message / Reply phase
363 entity HomeScreenBinder
366 HomeScreenGUI->HomeScreenBinder: set_event_handler()
368 note over HomeScreenGUI
369 LibHomeScreen::Event_OnScreenMessage
373 App->HomeScreenBinder: set_event_handler()
376 LibHomeScreen::Event_OnScreenReply
379 App->HomeScreenBinder: onScreenMessage(display_message)
380 HomeScreenBinder->HomeScreenGUI: event_handler(display_message)
381 HomeScreenGUI->HomeScreenBinder: onScreenReply(reply_message)
382 HomeScreenBinder->App: event_handler(reply_message)
389 title show/hide onscreen phase
392 entity "homescreen-service" as hss
395 entity windowmanager as wm
398 user->App: the operation request onscreen
399 App->hss: showWindow()
401 {"application_id":"onscreenapp",
402 "parameter":{"area":"display area", "file":"qml file path",
403 "data":{"the datas to onscreen qml"}}}
406 hss->onscreenapp: push showWindow event
407 note over hss,onscreenapp
408 {"application_id":"onscreenapp",
409 "parameter":{"area":"display area", "file":"qml file path",
410 "data":{"the datas to onscreen qml"},
411 <font color=red >"replyto":"caller application id"
415 onscreenapp->onscreenapp: get and save parameters
416 onscreenapp->wm: activateWindow("onscreeapp", "display area")
418 wm-->onscreenapp: push syncDraw event
419 onscreenapp->wm: endDraw("onscreeapp")
420 onscreenapp->onscreenapp: load and display qml file
422 note over onscreenapp,wm
429 user->onscreenapp: tap onscreen's button
430 onscreenapp->hss: replyShowWindow()
431 note over onscreenapp,hss
432 {"application_id":"the application id who called onscreenapp",
433 "parameter": {"buttonName": "VOLUME_UP", "buttonPressMode": "shortPress", "buttonPressState": "release"}}
435 hss->App: push replyShowWindow event
436 App->App: call reply function
437 App->hss: hideWindow("onscreenapp")
438 hss->onscreenapp: push hideWindow event
439 note over hss,onscreenapp
440 {"application_id":"request hideWindow application id"}
442 onscreenapp->wm: deactivateWindow("onscreenapp");
443 onscreenapp->onscreenapp: hide window
451 title show notification on HomeScreen top area
453 entity "homescreen-service" as hss
457 App->hss: showNotification()
459 {"icon":"display icon", "text":"display text"}
461 hss-> homescreen: push showNotification event
462 note over hss,homescreen
463 {"application_id":"request application id",
464 "parameter":{"icon":"display icon", "text":"display text"}}
467 homescreen->homescreen: display notification message 3s
475 title show information on HomeScreen bottom area
477 entity "homescreen-service" as hss
481 App->hss: showInformation()
483 {"info":"display information"}
485 hss-> homescreen: push showInformation event
487 homescreen->homescreen: display information message 3s