From e0163d2b8daae98ced81f4bc737998c00858e771 Mon Sep 17 00:00:00 2001 From: zheng_wenlong Date: Fri, 29 Sep 2017 20:42:53 +0900 Subject: Add agl-service-homescreen-2017 Add a new binding agl-service-homescreen-2017 for homescreen-2017. There is a gles sample how to use this binding in sample/simple-egl. A image about this see JIRA SPEC-871. [PatchSets2] Use aglwgt make package. Change-Id: I9ae89188f9eb2de4c98ec8baa2f05fccca8b2372 Signed-off-by: zheng_wenlong --- doc/ApplicationGuide.md | 248 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 doc/ApplicationGuide.md (limited to 'doc/ApplicationGuide.md') diff --git a/doc/ApplicationGuide.md b/doc/ApplicationGuide.md new file mode 100644 index 0000000..85216df --- /dev/null +++ b/doc/ApplicationGuide.md @@ -0,0 +1,248 @@ +**HomeScreen GUI Application / HomeScreen Service Guide** +==== +
Revision: 0.1
+
TOYOTA MOTOR CORPORATION
+
Advanced Driver Information Technology
+
26th/Sep/2017
+ +* * * + +## **
Table of content
** +- [Target reader of this document](#Target\ reader\ of\ this\ document) +- [Overview](#Overview) +- [Getting Start](#Getting\ Start) + - [Supported environment](#Supported\ environment) + - [Build](#Build) + - [Configuring](#Configuring) + - [How to call HomeScreen APIs from your Application?](#How\ to\ call\ HomeScreen\ APIs\ from\ your\ Application?) +- [Supported usecase](#Supported\ usecase) +- [Software Architecture](#Software\ Architecture) +- [API reference](#API\ reference) +- [Sequence](#Sequence) + - [Initialize](#InitializeSequence) + - [Tap Shortcut](#TapShortcutSequence) + - [On Screen Message](#OnScreenMessageSequence) +- [Sample code](#Sample\ code) +- [Limitation](#Limitation) +- [Next Plan](#Next\ Plan) + +* * * + +## **
Target reader of this document
** +Application developer whose software uses HomeScreen. + +* * * + +## **
Overview
** +HomeScreenはQtで作成されたGUIアプリケーション(以下、HomeScreenGUI)と、afb-daemonで動作するサービス(以下HomeScreenBinder)で構築されます。HomeScreeはAGLにて動作するアプリケーションの起動、切り替え、およびオンスクリーンメッセージなどの情報表示を行います。 + +HomeScreenGUIはWindowManagerが提供するAPIを使用しています。 + +## **
Getting Start
** + +### **
Supported environment
** +| Item | Description | +|:------------|:----------------------------------| +| AGL version | Daring Dab | +| Hardware | Renesas R-Car Starter Kit Pro(M3) | + + +### **
Build
** + +You can make HomeScreen object files by the following two stage operations. + +**Download recipe** + +If repo is already done, please start with git clone + +``` +$ mkdir WORK +$ cd WORK +$ repo init -b dab -m dab_4.0.0_xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo +$ repo sync +$ git clone git clone https://gerrit.automotivelinux.org/gerrit/staging/meta-hmi-framework + +``` + +Then you can get the following recipe. + +* `meta-hmi-framework/homescreen-2017` + + +**Bitbake** + +``` +$ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack +$ bitbake homescreen-2017 +``` + + +* * * + +### **
Configuring
** +To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application. + +``` + + + +``` + +*) HomeScreenBindingはWindowManagerと同じport、tokenでのアクセスとなります。 + +* * * + +### **
How to call HomeScreen APIs from your Application?
** +HomeScreen provides a library which is called "libhomescreen". +This library treats "json format" as API calling. +For example, if an application wants to call "tap_shortcut()" API, the you should implement as below. + +At first the application should create the instance of libhomescreen. + +``` +LibHomeScreen* libhs; +libhs = new LibHomeScreen(); +libhs->init(port, token); +``` + +The port and token is provided by Application Framework + +Then assign the argument to JSON object + +``` +struct json_object* jobj = json_object_new_object(); + +json_object_object_add(jobj, "application_name", json_object_new_string("MediaPlayer")); + +``` + + +And finally execute the "cal()" function. + +``` +libhs->call("tap_shortcut", jobj); +``` + +Regarding the detail of tap_shortcut() API, please refer [this](#HomeScreen\ API) section. +The first parameter is the name of API, so in this case "tap_shortcut" is proper string. +And the second parameter corresponds to arguments of "connect()" API. + + +See also our [Sample code](#Sample\ code). + + +
+ +* * * + +## **
Supported usecase
** +1. HomeScreenGUIでショートカットアイコンがタップされたときに発行されるイベントを取得する + - 各アプリケーションは自身がアイコンタップにより起動（または表示）されたことを知るために、HomeScreenBinderに対してイベント登録を行い、そのイベントを取得することができます。 +2. オンスクリーンにメッセージを表示する + - T.B.D + +* * * + +## **
Software Architecture
** +The architecture of HomeScreen is shown below. +HomeScreen is the service designed to be used by multiple applications. +Therefore HomeScreen framework consists on two binder layers. Please refer the following figure. +The upper binder is for application side security context for applications. The lower binder is for servide side security context. +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. +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). + +The communication protocols between libhomescreen and upper binder, upper binder and lower binder, lower binder (homescreen-binding) are WebSocket. + +![software-stack.png](parts/software-stack.png) + +* * * + +## **
API reference
** +"libhomescreen" and "HomeScreenBinding" provides several kinds of APIs. + +### **
HomeScreen Specific API
** + +- [LibHomeScreen ()](api-ref/html/de/dd0/class_lib_home_screen.html#a724bd949c4154fad041f96a15ef0f5dc) +- [init (const int port, const std::string &token)](api-ref/html/de/dd0/class_lib_home_screen.html#a6a57b573cc767725762ba9beab032220) +- [tapShortcut(const char *application_name)](api-ref/html/de/dd0/class_lib_home_screen.html#afb571c9577087b47065eb23e7fdbc903) +- [onScreenMessage(const char *display_message)](api-ref/html/de/dd0/class_lib_home_screen.html#ac336482036a72b51a822725f1929523c) +- [set\_event\_handler(enum EventType et, handler_func f)](api-ref/html/de/dd0/class_lib_home_screen.html#ab1b0e08bf35415de9064afed899e9f85) +- [call (const string& verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#a527b49dcfe581be6275d0eb2236ba37f) +- [call (const char* verb, struct json_object* arg)](api-ref/html/de/dd0/class_lib_home_screen.html#ab5e8e8ab7d53e0f114e9e907fcbb7643) +- [subscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aa4c189807b75d070f567967f0d690738) +- [unsubscribe (const string& event_name)](api-ref/html/de/dd0/class_lib_home_screen.html#aac03a45cbd453ba69ddb00c1016930a6) + +* * * + +## **
Sequence
** + +### **
Initialize
** +![initialize.svg](parts/initialize.svg) + +### **
Tap Shortcut
** +![tap_shortcut.svg](parts/tap_shortcut.svg) + +### **
On Screen Message
** +![on_screen_message.svg](parts/on_screen_message.svg) + + +# **
Sample code
** +You can find sample implementation of HomeScreen as below. + +* `HomeScreenBinding/libhomescreen/test.cpp` + +### Appendix + +``` +@startuml +title Application initialization phase +entity App +entity HomeScreenBinder +entity HomeScreenGUI +App->HomeScreenBinder: init(port, token) +App->HomeScreenBinder: subscribe() + +note over HomeScreenBinder + Appが受信したいイベントを登録する + ・tap_shortcut +end note + +App->HomeScreenBinder: registerCallback() +App->HomeScreenBinder: set_event_handler() + +note over HomeScreenBinder + イベント受信のコールバック登録 + registerCallbackによる登録または + set_event_handlerによる登録どちらかでOK +end note + +@enduml +``` + +``` +@startuml +title Application Callback Event TapShortcut phase +entity App +entity HomeScreenBinder +entity HomeScreenGUI +note over App + Appは初期化時に + TapShortcutのイベントを受け取る設定をしていること +end note +HomeScreenGUI->HomeScreenBinder: tapShortcut(application_name) +HomeScreenBinder->App: eventCallback(application_name) +@enduml + +``` + +``` +@startuml +title Application Callback Event TapShortcut phase +entity App +entity HomeScreenBinder +entity HomeScreenGUI +App->HomeScreenBinder: onScreenMessage(display_message) +HomeScreenBinder->HomeScreenGUI: eventCallback(display_message) +@enduml + +``` \ No newline at end of file -- cgit 1.2.3-korg