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 - [On Screen Message / Reply Sequence](#on-screen-message-/-reply-sequence)
25 - [Sample code](#sample-code)
26 - [Limitation](#limitation)
27 - [Next Plan](#next-plan)
28 - [Appendix](#appendix)
32 ## Target reader of this document
33 Application developer whose software uses HomeScreen.
38 HomeScreen is built with a GUI application created with Qt(referred as HomeScreenGUI), and a service running on afb-daemon (referred as HomeScreenBinder).
39 HomeScreen can start/switch applications run in AGL, also displays information such as onscreen messages.
41 You can find these projects in AGL gerrit.
43 - [homescreen-2017(HomeScreenGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/staging/homescreen-2017)
44 - [agl-service-homescreen-2017(HomeScreenBinder's binding library)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen-2017)
45 - [libhomescreen(library for application to communication with HomeScreenBinder)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen)
47 Also HomeScreenGUI is using libwindowmanager.
53 ### Supported environment
55 | Item | Description |
56 |:------------|:----------------------------------|
57 | AGL version | Funky Flounder |
58 | Hardware | Renesas R-Car Starter Kit Pro(M3) |
68 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
73 Then you can find the following recipes.
75 * `meta-agl-devel/meta-hmi-framework/homescreen-2017`
77 * `meta-agl-devel/meta-hmi-framework/agl-service-homescreen-2017`
79 * `meta-agl-demo/recipes-demo-hmi/libhomescreen`
85 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
86 $ bitbake agl-demo-platform
90 To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application.
93 <feature name="urn:AGL:widget:required-api">
94 <param name="homescreen" value="ws" />
98 ### How to call HomeScreen APIs from your Application?
99 HomeScreen provides a library which is called "libhomescreen".
100 This library treats "json format" as API calling.
101 For example, if an application wants to call "tap_shortcut()" API, the you should implement as below.
103 At first the application should create the instance of libhomescreen.
106 LibHomeScreen* libhs;
107 libhs = new LibHomeScreen();
108 libhs->init(port, token);
111 The port and token is provided by Application Framework
113 Execute the "tapShortcut()" function.
116 libhs->tapShortcut("application_name");
119 Regarding the detail of tap_shortcut() API, please refer [this](#HomeScreen\ API) section.
120 The first parameter is the name of API, so in this case "tap_shortcut" is proper string.
121 And the second parameter corresponds to arguments of "connect()" API.
123 See also our [Sample code](#sample-code).
128 1. HomeScreenGUI sending ShortCut Icon tapped event to applications
129 - Applications using libhomescreen to subscribe the tapShortcut event,
130 HomeScreenGUI will send ShortCut Icon tapped event to applications.
131 2. Display OnScreen messages
132 - Applications sending OnScreen messages to homescreen-service, and OnScreenAPP
133 will get these message and display.
134 3. Get OnSreen Reply event
135 - When OnScreen messages is displaying, OnScreenAPP will send a reply event to applications.
139 ## Software Architecture
140 The architecture of HomeScreen is shown below.
141 HomeScreen is the service designed to be used by multiple applications.
142 Therefore HomeScreen framework consists on two binder layers. Please refer the following figure.
143 The upper binder is for application side security context for applications. The lower binder is for servide side security context.
144 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.
145 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).
147 The communication protocols between libhomescreen and upper binder, upper binder and lower binder, lower binder (homescreen-binding) are WebSocket.
149 ![software-stack.png](parts/software-stack.png)
154 "libhomescreen" and "agl-service-homescreen-2017" provides several kinds of APIs.
156 ### HomeScreen Specific API
158 - LibHomeScreen::init (const int port, const std::string &token)
160 port [in] : This argument should be specified to the port number to be used for websocket
161 token [in] : This argument should be specified to the token to be used for websocket
163 Create connection to homescreen-service by port and token which provided by
164 application framework. This API must be called before calling other api.
166 - LibHomeScreen::tapShortcut(const char *application_name)
168 application_name [in] : Tapped application name (label)
170 Request to show the window of application_name.
172 - LibHomeScreen::onScreenMessage(const char *display_message)
174 display_message [in] : message for display
176 Request to display message in onscreen.
178 - LibHomeScreen::onScreenReply(const char *reply_message)
180 reply_message [in] : message for reply
182 Post reply message to application.
184 - 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)
186 event_cb [in] : This argument should be specified to the callback for subscribed event
187 reply_cb [in] : This argument should be specified to the reply callback for call function
188 hangup_cb [in] : This argument should be specified to the hangup callback for call function
190 This api is deprecated, recommend using set_event_handler.
192 - LibHomeScreen::set_event_handler(enum EventType et, handler_func f)
195 f [in] : event handler
197 Setting event handler for Homescreen-Service Event.
199 - LibHomeScreen::call(const string& verb, struct json_object* arg)
200 - LibHomeScreen::call(const char* verb, struct json_object* arg)
202 verb [in] : This argument should be specified to the API name (e.g. "tap_shortcut")
203 arg [in] : This argument should be specified to the argument of API.
204 And this argument expects JSON object
206 Call homescreen-service verb.
208 - LibHomeScreen::subscribe(const string& event_name)
210 event_name [in] : This argument should be specified to the event name
212 Subscribe homescreen-service event. Deprecated, recommend using set_event_handler.
214 - LibHomeScreen::unsubscribe(const string& event_name)
216 event_name [in] : This argument should be specified to the event name
218 Unsubscribe homescreen-service event. Deprecated, recommend using set_event_handler.
225 ### Initialize Sequence
226 ![initialize-registercallback.svg](parts/initialize-registercallback.svg) * deprecated
227 ![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
229 ### Tap Shortcut Sequence
230 ![tap_shortcut.svg](parts/tap_shortcut.svg)
232 ### On Screen Message / Reply Sequence
233 ![on_screen_message.svg](parts/on_screen_message.svg)
236 You can find sample implementation of HomeScreen as below.
238 * `libhomescreen/sample/simple-egl`
240 * `libhomescreen/sample/template`
258 title Application initialization phase (ex. registerCallback)
260 entity HomeScreenBinder
262 App->HomeScreenBinder: init(port, token)
263 App->HomeScreenBinder: subscribe()
265 note over HomeScreenBinder
266 Register the event the App wishes to receive
272 App->HomeScreenBinder: registerCallback()
279 title Application initialization phase (ex. set_event_handler)
281 entity HomeScreenBinder
283 App->HomeScreenBinder: init(port, token)
284 App->HomeScreenBinder: set_event_handler()
286 note over HomeScreenBinder
287 setup event handler the App wishes to receive
288 ・LibHomeScreen::Event_TapShortcut
289 ・LibHomeScreen::Event_OnScreenMessage
290 ・LibHomeScreen::Event_OnScreenReply
298 title Application Callback Event TapShortcut phase
300 entity HomeScreenBinder
302 App->HomeScreenBinder: set_event_handler()
305 LibHomeScreen::Event_TapShortcut
308 HomeScreenGUI->HomeScreenBinder: tapShortcut(application_name)
309 HomeScreenBinder->App: event_handler(application_name)
315 title Application Callback Event On Screen Message / Reply phase
317 entity HomeScreenBinder
320 HomeScreenGUI->HomeScreenBinder: set_event_handler()
322 note over HomeScreenGUI
323 LibHomeScreen::Event_OnScreenMessage
327 App->HomeScreenBinder: set_event_handler()
330 LibHomeScreen::Event_OnScreenReply
333 App->HomeScreenBinder: onScreenMessage(display_message)
334 HomeScreenBinder->HomeScreenGUI: event_handler(display_message)
335 HomeScreenGUI->HomeScreenBinder: onScreenReply(reply_message)
336 HomeScreenBinder->App: event_handler(reply_message)