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 - [GetRunnables](###GetRunnables\ Sequence)
32 - [Sample code](#Sample\ code)
33 - [Limitation](#Limitation)
34 - [Next Plan](#Next\ Plan)
35 - [Appendix](#Appendix)
39 <div id="Target\ reader\ of\ this\ document"></div>
41 ## Target reader of this document
42 Application developer whose software uses HomeScreen.
46 <div id="Overview"></div>
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.
52 You can find these projects in AGL gerrit.
54 homescreen(HomeScreenGUI):
55 https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/homescreen
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
65 Also HomeScreenGUI is using libwindowmanager.
67 <div id="Getting\ Start"></div>
71 <div id="Supported\ environment"></div>
73 ### Supported environment
75 | Item | Description |
76 |:------------|:----------------------------------|
77 | AGL version | Electric Eel |
78 | Hardware | Renesas R-Car Starter Kit Pro(M3) |
81 <div id="Build"></div>
90 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
95 Then you can find the following recipes.
97 * `meta-agl-demo/recipes-demo-hmi/homescreen`
99 * `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/launcher`
101 * `meta-agl-demo/recipes-demo-hmi/agl-service-homescreen`
103 * `meta-agl-demo/recipes-demo-hmi/libhomescreen`
105 * `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/qlibhomescreen`
111 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
112 $ bitbake agl-demo-platform
118 <div id="Configuring"></div>
121 To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application.
124 <feature name="urn:AGL:widget:required-api">
125 <param name="homescreen" value="ws" />
126 <param name="windowmanager" value="ws" />
132 <div id="How\ to\ call\ HomeScreen\ APIs\ from\ your\ Application?"></div>
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.
139 At first the application should create the instance of libhomescreen.
142 LibHomeScreen* libhs;
143 libhs = new LibHomeScreen();
144 libhs->init(port, token);
147 The port and token is provided by Application Framework
149 Execute the "showWindow()" function.
152 libhs->showWindow("application_id", "display_area");
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.
160 See also our [Sample code](#Sample\ code).
167 <div id="Supported\ usecase"></div>
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
184 6. Send OnScreen Reply by replyShowWindow
185 - When user touch the button of OnScreen, OnScreenApp can call "relplyShowWindow" to send reply information
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.
198 <div id="Software\ Architecture"></div>
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).
208 The communication protocols between libhomescreen and upper binder, upper binder and lower binder, lower binder (homescreen-binding) are WebSocket.
210 ![software-stack.png](parts/software-stack.png)
214 <div id="API%20reference"></div>
217 "libhomescreen" and "agl-service-homescreen" provides several kinds of APIs.
219 <div id="Home\ Screen\ Specific\ API"></div>
221 ### HomeScreen Specific API
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)
243 <div id="Sequence"></div>
247 <div id="InitializeSequence"></div>
249 ### Initialize Sequence
250 ![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
252 <div id="TapShortcutSequence"></div>
254 ### Tap Shortcut Sequence
255 ![tap_shortcut.svg](parts/tap_shortcut.svg)
257 <div id="ShowWindowSequence"></div>
259 ### ShowWindow Sequence
260 ![showWindow.svg](parts/showWindow.svg)
262 <div id="OnScreenMessageSequence"></div>
264 ### On Screen Message / Reply Sequence
265 ![on_screen_message.svg](parts/on_screen_message.svg)
267 <div id="ShowOnscreenSequence"></div>
269 ### ShowOnScreen Sequence
270 ![showOnScreen.svg](parts/showOnScreen.svg)
272 <div id="ShowNotificationSequence"></div>
274 ### ShowNotification Sequence
275 ![showNotification.svg](parts/showNotification.svg)
277 <div id="ShowInformationSequence"></div>
279 ### ShowInformation Sequence
280 ![showInformation.svg](parts/showInformation.svg)
282 <div id="GetRunnablesSequence"></div>
284 ### GetRunnables Sequence
285 ![getRunnables.svg](parts/getRunnables.svg)
287 <div id="Sample\ code"></div>
290 You can find sample implementation of HomeScreen as below.
292 * `libhomescreen/sample/simple-egl`
294 * `libhomescreen/sample/template`
297 Now OnScreenApp is developing,approximately it will finished at GG.
307 title Application initialization phase
310 entity HomeScreenBinder
313 App->HomeScreenBinder: init(port, token)
314 App->HomeScreenBinder: set_event_handler()
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
328 title Application Callback Event TapShortcut phase
330 entity HomeScreenBinder
332 App->HomeScreenBinder: set_event_handler()
335 LibHomeScreen::Event_TapShortcut
338 HomeScreenGUI->HomeScreenBinder: tapShortcut(application_id)
339 HomeScreenBinder->App: event_handler(application_id)
346 title Application callback event showWindow phase
349 entity "homescreen-service" as hss
352 entity windowmanager as wm
354 user-->launcher: tap app's icon
355 launcher->hss: showWindow()
357 {"application_id":"tapped application id", "parameter":{"area":"display area", ...}}
359 hss->App: push showWindow event
360 App->wm: activateWindow("application_name","display area")
361 wm-->App: push syncDraw event
369 title Application Callback Event On Screen Message / Reply phase
371 entity HomeScreenBinder
374 HomeScreenGUI->HomeScreenBinder: set_event_handler()
376 note over HomeScreenGUI
377 LibHomeScreen::Event_OnScreenMessage
381 App->HomeScreenBinder: set_event_handler()
384 LibHomeScreen::Event_OnScreenReply
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)
397 title show/hide onscreen phase
400 entity "homescreen-service" as hss
403 entity windowmanager as wm
406 user->App: the operation request onscreen
407 App->hss: showWindow()
409 {"application_id":"onscreenapp",
410 "parameter":{"area":"display area", "file":"qml file path",
411 "data":{"the datas to onscreen qml"}}}
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"
423 onscreenapp->onscreenapp: get and save parameters
424 onscreenapp->wm: activateWindow("onscreeapp", "display area")
426 wm-->onscreenapp: push syncDraw event
427 onscreenapp->wm: endDraw("onscreeapp")
428 onscreenapp->onscreenapp: load and display qml file
430 note over onscreenapp,wm
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"}}
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"}
450 onscreenapp->wm: deactivateWindow("onscreenapp");
451 onscreenapp->onscreenapp: hide window
459 title show notification on HomeScreen top area
461 entity "homescreen-service" as hss
465 App->hss: showNotification()
467 {"icon":"display icon", "text":"display text"}
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"}}
475 homescreen->homescreen: display notification message 3s
483 title show information on HomeScreen bottom area
485 entity "homescreen-service" as hss
489 App->hss: showInformation()
491 {"info":"display information"}
493 hss-> homescreen: push showInformation event
495 homescreen->homescreen: display information message 3s