1 **HomeScreen GUI Application / HomeScreen Service Guide**
4 TOYOTA MOTOR CORPORATION
5 Advanced Driver Information Technology
11 - [Target reader of this document](#target-reader-of-this-document)
12 - [Overview](#overview)
13 - [Getting Start](#getting-start)
14 - [Supported environment](#supported-environment)
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 - [ShowWindow](#showwindow-sequence)
25 - [On Screen Message / Reply Sequence(deprecated)](#on-screen-message-reply-sequence)
26 - [ShowOnscreen](#showonscreen-sequence)
27 - [ShowNotification](#shownotification-sequence)
28 - [ShowInformation](#showinformation-sequence)
29 - [Sample code](#sample-code)
30 - [Limitation](#limitation)
31 - [Next Plan](#next-plan)
32 - [Appendix](#appendix)
36 ## Target reader of this document
37 Application developer whose software uses HomeScreen.
42 HomeScreen is built with a GUI application created with Qt(referred as HomeScreenGUI), and a service running on afb-daemon (referred as HomeScreenBinder).
43 HomeScreen can start/switch applications run in AGL, also displays information such as onscreen messages.
45 You can find these projects in AGL gerrit.
47 - [homescreen(HomeScreenGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/homescreen)
48 - [launcher(LauncherGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/launcher)
49 - [agl-service-homescreen(HomeScreenBinder's binding library)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen)
50 - [libhomescreen(library for application to communication with HomeScreenBinder]( https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen)
51 - [libqthomescreen(library for qt application to communication with HomeScreenBinder based on libhomescreen)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libqthomescreen)
53 Also HomeScreenGUI is using libwindowmanager.
59 ### Supported environment
61 | Item | Description |
62 |:------------|:----------------------------------|
63 | AGL version | Grumpy Guppy |
64 | Hardware | Renesas R-Car Starter Kit Pro(M3) |
74 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
79 Then you can find the following recipes.
81 * `meta-agl-demo/recipes-demo-hmi/homescreen`
83 * `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/launcher`
85 * `meta-agl-demo/recipes-demo-hmi/agl-service-homescreen`
87 * `meta-agl-demo/recipes-demo-hmi/libhomescreen`
89 * `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/qlibhomescreen`
95 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
96 $ bitbake agl-demo-platform
100 To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application.
103 <feature name="urn:AGL:widget:required-api">
104 <param name="homescreen" value="ws" />
105 <param name="windowmanager" value="ws" />
109 ### How to call HomeScreen APIs from your Application?
110 HomeScreen provides a library which is called "libhomescreen".
111 This library treats "json format" as API calling.
112 For example, if an application wants to call "showWIndow()" API, the you should implement as below.
114 At first the application should create the instance of libhomescreen.
117 LibHomeScreen* libhs;
118 libhs = new LibHomeScreen();
119 libhs->init(port, token);
122 The port and token is provided by Application Framework
124 Execute the "showWindow()" function.
127 libhs->showWindow("application_id", "display_area");
130 Regarding the detail of showWindow() API, please refer [this](#homescreen-specific-api) section.
131 The first parameter is the appid of application which want to display,liked "dashboard".
132 And the second parameter corresponds to display_area which defined by windowmanager,usually "normal",
133 so in this case "showWindow" the two parameters are proper string.
135 See also our [Sample code](#sample-code).
140 1. HomeScreenGUI sending showWindow event to applications
141 - Applications using libhomescreen to subscribe the showWindow event,
142 HomeScreenGUI will send showWindow event to applications.
143 2. Display OnScreen messages(deprecated)
144 - Applications sending OnScreen messages to homescreen-service, and OnScreenAPP
145 will get these message and display.
146 3. Get OnSreen Reply event(deprecated)
147 - When OnScreen messages is displaying, OnScreenAPP will send a reply event to applications.
148 4. Display OnScreen by showWindow
149 - When application who want to show OnScreen,it can call "showWindow",then OnScreenApp will
150 display request OnScreen.
151 5. Hide OnScreen by hideWindow
152 - When application who want to hide OnScreen which is displaying,it can call "hideWindow",then OnScreenApp
154 6. Send OnScreen Reply by replyShowWindow
155 - When user touch the button of OnScreen, OnScreenApp can call "relplyShowWindow" to send reply information
157 7. Show Notification on HomeScreenGUI
158 - When application who want to display a notification,it can call "showNotification",then HomeScreenGUI will
159 display the notification contents on the screen top area.
160 8. Show Information on HomeScreenGUI
161 - When application who want to display a information,it can call "showInformation",then HomeScreenGUI will
162 display the information contents on the screen bottom area.
166 ## Software Architecture
167 The architecture of HomeScreen is shown below.
168 HomeScreen is the service designed to be used by multiple applications.
169 Therefore HomeScreen framework consists on two binder layers. Please refer the following figure.
170 The upper binder is for application side security context for applications. The lower binder is for servide side security context.
171 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.
172 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).
174 The communication protocols between libhomescreen and upper binder, upper binder and lower binder, lower binder (homescreen-binding) are WebSocket.
176 ![software-stack.png](parts/software-stack.png)
181 "libhomescreen" and "agl-service-homescreen" provides several kinds of APIs.
183 ### HomeScreen Specific API
185 - LibHomeScreen::init (const int port, const std::string &token)
187 port [in] : This argument should be specified to the port number to be used for websocket
188 token [in] : This argument should be specified to the token to be used for websocket
190 Create connection to homescreen-service by port and token which provided by
191 application framework. This API must be called before calling other api.
193 - LibHomeScreen::tapShortcut(const char *application_id)
195 application_id [in] : Tapped application id (label)
197 This api is deprecated, recommend using showWindow.
199 - LibHomeScreen::onScreenMessage(const char *display_message)
201 display_message [in] : message for display
203 This api is deprecated, recommend using showWindow/hideWindow to call onscreenapp.
205 - LibHomeScreen::onScreenReply(const char *reply_message)
207 reply_message [in] : message for reply
209 This api is deprecated, recommend using replyShowWindow.
211 - 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)
213 event_cb [in] : This argument should be specified to the callback for subscribed event
214 reply_cb [in] : This argument should be specified to the reply callback for call function
215 hangup_cb [in] : This argument should be specified to the hangup callback for call function
217 This api is deprecated, recommend using set_event_handler.
219 - LibHomeScreen::set_event_handler(enum EventType et, handler_func f)
222 f [in] : event handler
224 Setting event handler for Homescreen-Service Event.
226 - LibHomeScreen::call(const string& verb, struct json_object* arg)
227 - LibHomeScreen::call(const char* verb, struct json_object* arg)
229 verb [in] : This argument should be specified to the API name (e.g. "tap_shortcut")
230 arg [in] : This argument should be specified to the argument of API.
231 And this argument expects JSON object
233 Call homescreen-service verb.
235 - LibHomeScreen::subscribe(const string& event_name)
237 event_name [in] : This argument should be specified to the event name
239 Subscribe homescreen-service event. Deprecated, recommend using set_event_handler.
241 - LibHomeScreen::unsubscribe(const string& event_name)
243 event_name [in] : This argument should be specified to the event name
245 Unsubscribe homescreen-service event. Deprecated, recommend using set_event_handler.
247 - LibHomeScreen::showWindow(const char* application_id, json_object* json)
249 application_id [in] : This argument should be specified to the application's id
250 json [in] : This argument should be specified to the json parameters
252 Request to show the window of application_id, and set display area in json liked
253 {"area":"normal.full"}.
255 - LibHomeScreen::hideWindow(const char* application_id)
257 application_id [in] : This argument should be specified to the application's id
259 Request to hide the window of application_id.
261 - LibHomeScreen::replyShowWindow(const char* application_id, json_object* json)
263 application_id [in] : This argument should be specified to the onscreen reply to applilcation id
264 json [in] : This argument should be specified to the json parameters
266 Post reply information to who called showWindow.
268 - LibHomeScreen::showNotification(json_object* json)
270 json [in] : This argument should be specified to the json parameters.
272 Post Notification to Homescreen which will display at top area of Homescreen.
274 - LibHomeScreen::showInformation(json_object* json)
276 json [in] : This argument should be specified to the json parameters.
278 Post Information to Homescreen which will display at bottom area of Homescreen.
285 ### Initialize Sequence
286 ![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
288 ### Tap Shortcut Sequence
289 ![tap_shortcut.svg](parts/tap_shortcut.svg)
291 ### ShowWindow Sequence
292 ![showWindow.svg](parts/showWindow.svg)
294 ### On Screen Message / Reply Sequence
295 ![on_screen_message.svg](parts/on_screen_message.svg)
297 ### ShowOnScreen Sequence
298 ![showOnScreen.svg](parts/showOnScreen.svg)
300 ### ShowNotification Sequence
301 ![showNotification.svg](parts/showNotification.svg)
303 ### ShowInformation Sequence
304 ![showInformation.svg](parts/showInformation.svg)
309 You can find sample implementation of HomeScreen as below.
311 * `libhomescreen/sample/simple-egl`
313 * `libhomescreen/sample/template`
332 title Application initialization phase
335 entity HomeScreenBinder
338 App->HomeScreenBinder: init(port, token)
339 App->HomeScreenBinder: set_event_handler()
341 note over HomeScreenBinder
342 setup event handler the App wishes to receive
343 ・LibHomeScreen::Event_ShowWindow
344 ・LibHomeScreen::Event_HideWindow
345 ・LibHomeScreen::Event_ReplyShowWindow
353 title Application Callback Event TapShortcut phase
355 entity HomeScreenBinder
357 App->HomeScreenBinder: set_event_handler()
360 LibHomeScreen::Event_TapShortcut
363 HomeScreenGUI->HomeScreenBinder: tapShortcut(application_id)
364 HomeScreenBinder->App: event_handler(application_id)
371 title Application callback event showWindow phase
374 entity "homescreen-service" as hss
377 entity windowmanager as wm
379 user-->launcher: tap app's icon
380 launcher->hss: showWindow()
382 {"application_id":"tapped application id", "parameter":{"area":"display area", ...}}
384 hss->App: push showWindow event
385 App->wm: activateWindow("application_name","display area")
386 wm-->App: push syncDraw event
394 title Application Callback Event On Screen Message / Reply phase
396 entity HomeScreenBinder
399 HomeScreenGUI->HomeScreenBinder: set_event_handler()
401 note over HomeScreenGUI
402 LibHomeScreen::Event_OnScreenMessage
406 App->HomeScreenBinder: set_event_handler()
409 LibHomeScreen::Event_OnScreenReply
412 App->HomeScreenBinder: onScreenMessage(display_message)
413 HomeScreenBinder->HomeScreenGUI: event_handler(display_message)
414 HomeScreenGUI->HomeScreenBinder: onScreenReply(reply_message)
415 HomeScreenBinder->App: event_handler(reply_message)
422 title show/hide onscreen phase
425 entity "homescreen-service" as hss
428 entity windowmanager as wm
431 user->App: the operation request onscreen
432 App->hss: showWindow()
434 {"application_id":"onscreenapp",
435 "parameter":{"area":"display area", "file":"qml file path",
436 "data":{"the datas to onscreen qml"}}}
439 hss->onscreenapp: push showWindow event
440 note over hss,onscreenapp
441 {"application_id":"onscreenapp",
442 "parameter":{"area":"display area", "file":"qml file path",
443 "data":{"the datas to onscreen qml"},
444 <font color=red >"replyto":"caller application id"
448 onscreenapp->onscreenapp: get and save parameters
449 onscreenapp->wm: activateWindow("onscreeapp", "display area")
451 wm-->onscreenapp: push syncDraw event
452 onscreenapp->wm: endDraw("onscreeapp")
453 onscreenapp->onscreenapp: load and display qml file
455 note over onscreenapp,wm
462 user->onscreenapp: tap onscreen's button
463 onscreenapp->hss: replyShowWindow()
464 note over onscreenapp,hss
465 {"application_id":"the application id who called onscreenapp",
466 "parameter": {"buttonName": "VOLUME_UP", "buttonPressMode": "shortPress", "buttonPressState": "release"}}
468 hss->App: push replyShowWindow event
469 App->App: call reply function
470 App->hss: hideWindow("onscreenapp")
471 hss->onscreenapp: push hideWindow event
472 note over hss,onscreenapp
473 {"application_id":"request hideWindow application id"}
475 onscreenapp->wm: deactivateWindow("onscreenapp");
476 onscreenapp->onscreenapp: hide window
484 title show notification on HomeScreen top area
486 entity "homescreen-service" as hss
490 App->hss: showNotification()
492 {"icon":"display icon", "text":"display text"}
494 hss-> homescreen: push showNotification event
495 note over hss,homescreen
496 {"application_id":"request application id",
497 "parameter":{"icon":"display icon", "text":"display text"}}
500 homescreen->homescreen: display notification message 3s
508 title show information on HomeScreen bottom area
510 entity "homescreen-service" as hss
514 App->hss: showInformation()
516 {"info":"display information"}
518 hss-> homescreen: push showInformation event
520 homescreen->homescreen: display information message 3s