dd3f1f0ee4adc3b51add2356e06a5a2360179b9f
[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">26th/Sep/2017</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](#InitializeSequence)
25         - [Tap Shortcut](#TapShortcutSequence)
26         - [On Screen Message / Reply Sequence](#OnScreenMessageSequence)
27 - [Sample code](#Sample\ code)
28 - [Limitation](#Limitation)
29 - [Next Plan](#Next\ Plan)
30
31 * * *
32
33 <div id="Target\ reader\ of\ this\ document"></div>
34
35 ## Target reader of this document
36 Application developer whose software uses HomeScreen.
37
38 * * *
39
40 <div id="Overview"></div>
41
42 ## Overview
43 HomeScreen is built with a GUI application created with Qt(referred as HomeScreenGUI), and a service running on afb-daemon (referred as HomeScreenBinder).
44 HomeScreen can start/switch applications run in AGL, also displays information such as onscreen messages.
45
46 You can find these projects in AGL gerrit.
47
48 homescreen-2017(HomeScreenGUI):
49     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/staging/homescreen-2017
50 agl-service-homescreen-2017(HomeScreenBinder's binding library):
51     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen-2017
52 libhomescreen(library for application to communication with HomeScreenBinder):
53     https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen
54
55 Also HomeScreenGUI is using libwindowmanager.
56
57 <div id="Getting\ Start"></div>
58
59 ## Getting Start
60
61 <div id="Supported\ environment"></div>
62
63 ### Supported environment
64
65 | Item        | Description                       |
66 |:------------|:----------------------------------|
67 | AGL version | Electric Eel                      |
68 | Hardware    | Renesas R-Car Starter Kit Pro(M3) |
69
70
71 <div id="Build"></div>
72
73 ### Build
74
75 **Download recipe**
76
77 ```
78 $ mkdir WORK
79 $ cd WORK
80 $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
81 $ repo sync
82
83 ```
84
85 Then you can find the following recipes.
86
87 * `meta-agl-devel/meta-hmi-framework/homescreen-2017`
88
89 * `meta-agl-devel/meta-hmi-framework/agl-service-homescreen-2017`
90
91 * `meta-agl-demo/recipes-demo-hmi/libhomescreen`
92
93
94 **Bitbake**
95
96 ```
97 $ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework
98 $ bitbake agl-demo-platform
99 ```
100
101
102 * * *
103
104 <div id="Configuring"></div>
105
106 ### Configuring
107 To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application.
108
109 ```
110 <feature name="urn:AGL:widget:required-api">
111         <param name="homescreen" value="ws" />
112 </feature>
113 ```
114
115 * * *
116
117 <div id="How\ to\ call\ HomeScreen\ APIs\ from\ your\ Application?"></div>
118
119 ### How to call HomeScreen APIs from your Application?
120 HomeScreen provides a library which is called "libhomescreen".
121 This library treats "json format" as API calling.
122 For example, if an application wants to call "tap_shortcut()" API, the you should implement as below.
123
124 At first the application should create the instance of libhomescreen.
125
126 ```
127 LibHomeScreen* libhs;
128 libhs = new LibHomeScreen();
129 libhs->init(port, token);
130 ```
131
132 The port and token is provided by Application Framework
133
134 Execute the "tapShortcut()" function.
135
136 ```
137 libhs->tapShortcut("application_id");
138 ```
139
140 Regarding the detail of tap_shortcut() API, please refer [this](#HomeScreen\ API) section.
141 The first parameter is the name of API, so in this case "tap_shortcut" is proper string.
142 And the second parameter corresponds to arguments of "connect()" API.
143
144
145 See also our [Sample code](#Sample\ code).
146
147
148 <br />
149
150 * * *
151
152 <div id="Supported\ usecase"></div>
153
154 ## Supported usecase
155 1. HomeScreenGUI sending ShortCut Icon tapped event to applications
156         - Applications using libhomescreen to subscribe the tapShortcut event,
157         HomeScreenGUI will send ShortCut Icon tapped event to applications.
158 2. Display OnScreen messages
159         - Applications sending OnScreen messages to homescreen-service, and OnScreenAPP
160         will get these message and display.
161 3. Get OnSreen Reply event
162         - When OnScreen messages is displaying, OnScreenAPP will send a reply event to applications.
163
164 * * *
165
166 <div id="Software\ Architecture"></div>
167
168 ## Software Architecture
169 The architecture of HomeScreen is shown below.
170 HomeScreen is the service designed to be used by multiple applications.
171 Therefore HomeScreen framework consists on two binder layers. Please refer the following figure.
172 The upper binder is for application side security context for applications. The lower binder is for servide side security context.
173 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.
174 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).
175
176 The communication protocols between libhomescreen and upper binder, upper binder and lower binder, lower binder (homescreen-binding) are WebSocket.
177
178 ![software-stack.png](parts/software-stack.png)
179
180 * * *
181
182 <div id="API%20reference"></div>
183
184 ## API reference
185 "libhomescreen" and "agl-service-homescreen-2017" provides several kinds of APIs.
186
187 <div id="Home\ Screen\ Specific\ API"></div>
188
189 ### HomeScreen Specific API
190
191 - [LibHomeScreen ()](api-ref/html/de/dd0/class_lib_home_screen.html#a724bd949c4154fad041f96a15ef0f5dc)
192 - [init (const int port, const std::string &token)](api-ref/html/de/dd0/class_lib_home_screen.html#a6a57b573cc767725762ba9beab032220)
193 - [tapShortcut(const char *application_id)](api-ref/html/de/dd0/class_lib_home_screen.html#afb571c9577087b47065eb23e7fdbc903)
194 - [onScreenMessage(const char *display_message)](api-ref/html/de/dd0/class_lib_home_screen.html#ac336482036a72b51a822725f1929523c)
195 - [onScreenReply(const char *reply_message)](api-ref/html/de/dd0/class_lib_home_screen.html#a6c065f41f2c5d1f58d2763bfb4da9c37)
196 - [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)
197 - [set\_event\_handler(enum EventType et, handler_func f)](api-ref/html/de/dd0/class_lib_home_screen.html#ab1b0e08bf35415de9064afed899e9f85)
198 - [call (const string& verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#a527b49dcfe581be6275d0eb2236ba37f)
199 - [call (const char* verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#ab5e8e8ab7d53e0f114e9e907fcbb7643)
200 - [subscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aa4c189807b75d070f567967f0d690738)
201 - [unsubscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aac03a45cbd453ba69ddb00c1016930a6)
202
203 * * *
204
205 <div id="Sequence"></div>
206
207 ## Sequence
208
209 <div id="InitializeSequence"></div>
210
211 ### Initialize Sequence
212 ![initialize-registercallback.svg](parts/initialize-registercallback.svg) * deprecated
213 ![initialize-set-event-handler](parts/initialize-set-event-handler.svg)
214
215 <div id="TapShortcutSequence"></div>
216
217 ### Tap Shortcut Sequence
218 ![tap_shortcut.svg](parts/tap_shortcut.svg)
219
220 <div id="OnScreenMessageSequence"></div>
221
222 ### On Screen Message / Reply Sequence
223 ![on_screen_message.svg](parts/on_screen_message.svg)
224
225
226 <div id="Sample\ code"></div>
227
228 # Sample code
229 You can find sample implementation of HomeScreen as below.
230
231 * `libhomescreen/sample/simple-egl`
232
233 * `libhomescreen/sample/template`
234
235 ### Appendix
236
237 ```
238 @startuml
239 title Application initialization phase (ex. registerCallback)
240 entity App
241 entity HomeScreenBinder
242 entity HomeScreenGUI
243 App->HomeScreenBinder: init(port, token)
244 App->HomeScreenBinder: subscribe()
245
246 note over HomeScreenBinder
247     Register the event the App wishes to receive
248     ・tap_shortcut
249     ・on_screen_message
250     ・on_screen_reply
251 end note
252
253 App->HomeScreenBinder: registerCallback()
254
255 @enduml
256 ```
257
258 ```
259 @startuml
260 title Application initialization phase (ex. set_event_handler)
261 entity App
262 entity HomeScreenBinder
263 entity HomeScreenGUI
264 App->HomeScreenBinder: init(port, token)
265 App->HomeScreenBinder: set_event_handler()
266
267 note over HomeScreenBinder
268     setup event handler the App wishes to receive
269     ・LibHomeScreen::Event_TapShortcut
270     ・LibHomeScreen::Event_OnScreenMessage
271     ・LibHomeScreen::Event_OnScreenReply
272 end note
273
274 @enduml
275 ```
276
277 ```
278 @startuml
279 title Application Callback Event TapShortcut phase
280 entity App
281 entity HomeScreenBinder
282 entity HomeScreenGUI
283 App->HomeScreenBinder: set_event_handler()
284
285 note over App
286     LibHomeScreen::Event_TapShortcut
287 end note
288
289 HomeScreenGUI->HomeScreenBinder: tapShortcut(application_id)
290 HomeScreenBinder->App: event_handler(application_id)
291 @enduml
292 ```
293
294 ```
295 @startuml
296 title Application Callback Event On Screen Message / Reply phase
297 entity App
298 entity HomeScreenBinder
299 entity HomeScreenGUI
300
301 HomeScreenGUI->HomeScreenBinder: set_event_handler()
302
303 note over HomeScreenGUI
304     LibHomeScreen::Event_OnScreenMessage
305 end note
306
307
308 App->HomeScreenBinder: set_event_handler()
309
310 note over App
311     LibHomeScreen::Event_OnScreenReply
312 end note
313
314 App->HomeScreenBinder: onScreenMessage(display_message)
315 HomeScreenBinder->HomeScreenGUI: event_handler(display_message)
316 HomeScreenGUI->HomeScreenBinder: onScreenReply(reply_message)
317 HomeScreenBinder->App: event_handler(reply_message)
318 @enduml
319 ```