2 AGL Application Framework: A Quick Tutorial
3 ===========================================
7 This document proposes a quick tutorial to demonstrate the major functionnalities of the AGL Application Framework. For more complete information, please refer to the inline documentation available in the main git repository:
9 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main]
10 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder]
13 For more information on AGL, please visit:
14 [https://www.automotivelinux.org/]
20 4 sample applications (.wgt files) are prebuilt and available at the following address:
21 [https://github.com/iotbzh/afm-widget-examples]
23 You can get them by cloning this git repository on your desktop (will be useful later in this tutorial):
26 $ git clone https://github.com/iotbzh/afm-widget-examples
33 Connect your AGL target board to the network and copy some sample widgets on it through SSH (set BOARDIP with your board IP address) :
36 $ cd afm-widget-examples
38 $ scp *.wgt root@$BOARDIP:~/
41 Connect through SSH on the target board and check for Application Framework daemons:
44 root@porter:~# ps -ef|grep bin/afm
45 afm 409 1 0 13:00 ? 00:00:00 /usr/bin/afm-system-daemon
46 root 505 499 0 13:01 ? 00:00:00 /usr/bin/afm-user-daemon
47 root 596 550 0 13:22 pts/0 00:00:00 grep afm
49 We can see that there are two daemons running:
50 * **afm-system-daemon** runs with a system user 'afm' and is responsible for installing/uninstalling packages
51 * **afm-user-daemon** runs as a user daemon (currently as root because it's the only real user on the target board) and is responsible for the whole lifecycle of the applications running inside the user session.
53 The application framework has a tool running on the Command Line Interface (CLI). Using the **afm-util** command, you can install, uninstall, list, run, pause ... applications.
55 To begin, run '**afm-util help**' to get a quick help on commands:
57 root@porter:~# afm-util help
58 usage: afm-util command [arg]
63 runnables list the runnable widgets installed
66 install wgt install the wgt file
69 uninstall id remove the installed widget of id
72 detail id print detail about the installed widget of id
75 runners list the running instance
78 start id start an instance of the widget of id
81 terminate rid terminate the running instance rid
84 pause rid pause the running instance rid
87 continue rid resume the previously rid
90 state rid get status of the running instance rid
92 ### Install an application
94 You can then install your first application:
96 root@porter:~# afm-util install /home/root/annex.wgt
97 { "added": "webapps-annex@0.0" }
99 Let's install a second application:
101 root@porter:~# afm-util install /home/root/memory-match.wgt
102 { "added": "webapps-memory-match@1.1" }
104 Note that usually, **afm-util** will return a **JSON result**, which is the common format for messages returned by the Application Framework daemons.
106 ### List installed applications
107 You can then list all installed applications:
109 root@porter:~# afm-util list
110 [ { "id": "webapps-annex@0.0", "version": "0.0.10", "width": 0, "height": 0, "name": "Annex", "description": "Reversi\/Othello", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" },
111 { "id": "webapps-memory-match@1.1", "version": "1.1.7", "width": 0, "height": 0, "name": "MemoryMatch", "description": "Memory match", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" } ]
113 Here, we can see the two previously installed applications.
115 ### Get information about an application
116 Let's get some details about the first application:
118 root@porter:~# afm-util info webapps-annex@0.0
119 { "id": "webapps-annex@0.0", "version": "0.0.10", "width": 0, "height": 0, "name": "Annex", "description": "Reversi\/Othello", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" }
121 Note that AGL applications are mostly handled by afm-util through their IDs. In our example, the application ID is 'webapps-annex@0.0'.
123 ### Start application
124 Let's start the first application Annex:
126 root@porter:~# afm-util start webapps-annex@0.0
129 As the application is a HTML5 game, you should then get a webview running with QML on the board display.
132 The application has been started in the user session, with a dedicated security context, enforced by SMACK. To illustrate this, we can take a look at the running processes and their respective SMACK labels:
134 root@porter:~# ps -efZ |grep webapps-annex | grep -v grep
135 User::App::webapps-annex root 716 491 0 13:19 ? 00:00:00 /usr/bin/afb-daemon --mode=local --readyfd=8 --alias=/icons /usr/share/afm/icons --port=12348 --rootdir=/usr/share/afm/applications/webapps-annex/0.0 --token=7D6D2F16 --sessiondir=/home/root/app-data/webapps-annex/.afb-daemon
136 User::App::webapps-annex root 717 491 0 13:19 ? 00:00:00 /usr/bin/qt5/qmlscene http://localhost:12348/index.html?token=7D6D2F16 /usr/bin/web-runtime-webkit.qml
138 In the previous result, we see that the application is composed of two processes:
139 * the application binder (afb-daemon)
140 * the application UI (qmlscene ...)
142 While most system processes run with the label 'System', we see that the application runs with a specific SMACK label 'User::App::webapps-annex': this label is used to force the application to follow a Mandatory Access Control (MAC) scheme. This means that those processes run in their own security context, isolated from the rest of the system (and other applications). Global security rules can then be applied to restrict access to all other user or system resources.
144 ### Check running applications
145 To check for running applications, just run:
147 root@porter:~# afm-util ps
148 [ { "runid": 1, "state": "running", "id": "webapps-annex@0.0" } ]
150 The 'runid' is the application instance ID and is used as an argument for the subcommands controlling the application runtime state (kill/pause/resume/status)
152 ### Pause application
153 To pause the application that was just started (the one with RUNID 1), just run the pause command:
155 root@porter:~# afm-util terminate 1
158 The application is now paused, as confirmed by a list of running apps:
160 root@porter:~# afm-util ps
164 ### Uninstall application
165 To uninstall an application, simply use its ID:
167 root@porter:~# afm-util uninstall webapps-annex@0.0
170 Then list the installed apps to confirm the removal:
172 root@porter:~# afm-util list
173 [ { "id": "webapps-memory-match@1.1", "version": "1.1.7", "width": 0, "height": 0, "name": "MemoryMatch", "description": "Memory match", "shortname": "", "author": "Todd Brandt <todd.e.brandt@intel.com>" } ]
175 afm-client: a sample HTML5 'Homescreen'
176 ---------------------------------------
178 **afm-client** is a HTML5 UI that allows to install/uninstall applications as well as starting/pausing them as already demonstrated with afm-util.
180 The HTML5 UI is accessible remotely through this URL:
181 http://[board_ip]:1234/opa?token=132456789
183 ### Installing an application
185 By clicking on the '**Upload**' button on the right, you can send an application package (WGT file) and install it. Select for example the file '**rabbit.wgt**' that was cloned initially from the git repository afm-widget-examples.
187 Then a popup requester ask for a confirmation: 'Upload Application rabbit.wgt ?'. Click on the '**Install**' button.
189 You should then see some changes in the toolbar: a new icon appeared, representing the freshly installed application.
191 ### Running an application
192 In the toolbar, click on the button representing the Rabbit application. You'll get a popup asking to:
193 * start the application
194 * or get some info about it
197 Click on the 'start' item: the application starts and should be visible as a webview on the target board display. Note that at this point, we could also run the application remotely, that is in the same browser as the Homescreen app. By default, the application framework is configured to run applications 'locally' on the board display.
199 ### Pausing an application
201 In the Homescreen application, click again on the Rabbit application button, then select 'pause': the application then pauses.
203 ### Uninstalling an application
205 From the same popup menu, you can select 'uninstall' to remove the application from the system. As a consequence, the application icon should disappear from the toolbar.
207 afb-client: a template for Angular Applications
208 -----------------------------------------------
210 Another package '**afb-client**' is also available for testing.
211 This is a sample HTML5 application demonstrating various basic capabilities of the Binder daemon. It can be used by developers as a template to start writing real AGL Applications.
213 This application is not available as WGT file yet and it should be started manually without any specific security context:
215 root@porter:~# /usr/bin/afb-daemon --mode=remote --port=1235 --token='' --sessiondir=/home/root/.afm-daemon --rootdir=/usr/share/agl/afb-client --alias=/icons:/usr/share/afm/icons
217 Then you can access it from a browser:
218 http://[board_ip]:1235/opa/?token=132456789
220 afb-client is a simple application to demonstrate the built-in capabilities of the binder daemon (handling sessions and security tokens, testing POSTs uploads...) and was used during the application framework development to validate the proposed features.
222 [https://github.com/iotbzh/afm-widget-examples]: https://github.com/iotbzh/afm-widget-examples (afm-widget-examples)
223 [https://www.automotivelinux.org/]: https://www.automotivelinux.org/ (AGL)
224 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder (app-framework-binder)
225 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main (app-framework-main)