docs/4-quick-tutorial.md

   1 # AGL Application Framework: A Quick Tutorial
   2
   3 ## Introduction
   4
   5 This document proposes a quick tutorial to demonstrate the major
   6 functionalities of the AGL Application Framework.
   7 For more complete information, please refer to the inline documentation
   8 available in the main git repository:
   9
  10 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main]
  11 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder]
  12
  13 For more information on AGL, please visit:
  14 [https://www.automotivelinux.org/]
  15
  16 ----------
  17
  18 ## Sample applications
  19
  20 4 sample applications (.wgt files) are prebuilt and available at the following address:
  21 [https://github.com/iotbzh/afm-widget-examples]
  22
  23 You can get them by cloning this git repository on your desktop (will be useful later in this tutorial):
  24
  25 ```bash
  26 git clone https://github.com/iotbzh/afm-widget-examples
  27 ```
  28
  29 ## Using the CLI tool
  30
  31 ### Setup Environment
  32
  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) :
  34
  35 ```bash
  36 cd afm-widget-examples
  37 BOARDIP=1.2.3.4
  38 scp *.wgt root@$BOARDIP:~/
  39 ```
  40
  41 Connect through SSH on the target board and check for Application Framework daemons:
  42
  43 ```bash
  44 $ ssh root@$BOARDIP
  45 root@porter:~# ps -ef|grep bin/afm
  46 afm        409     1  0 13:00 ?        00:00:00 /usr/bin/afm-system-daemon
  47 root       505   499  0 13:01 ?        00:00:00 /usr/bin/afm-user-daemon
  48 root       596   550  0 13:22 pts/0    00:00:00 grep afm
  49 ```
  50
  51 We can see that there are two daemons running:
  52
  53 * **afm-system-daemon** runs with a system user 'afm' and is responsible for
  54   installing/uninstalling packages
  55 * **afm-user-daemon** runs as a user daemon (currently as root because it's the
  56   only real user on the target board) and is responsible for the whole life
  57   cycle of the applications running inside the user session.
  58
  59 The application framework has a tool running on the
  60 Command Line Interface (CLI).
  61 Using the **afm-util** command, you can install, uninstall, list, run, pause ... applications.
  62
  63 To begin, run '**afm-util help**' to get a quick help on commands:
  64
  65 ```bash
  66 root@porter:~# afm-util help
  67 usage: afm-util command [arg]
  68 ```
  69
  70 The commands are:
  71
  72 ```bash
  73 list
  74 runnables      list the runnable widgets installed
  75
  76 add wgt
  77 install wgt    install the wgt file
  78
  79 remove id
  80 uninstall id   remove the installed widget of id
  81
  82 info id
  83 detail id      print detail about the installed widget of id
  84
  85 ps
  86 runners        list the running instance
  87
  88 run id
  89 start id       start an instance of the widget of id
  90
  91 kill rid
  92 terminate rid  terminate the running instance rid
  93
  94 status rid
  95 state rid      get status of the running instance rid
  96 ```
  97
  98 ### Install an application
  99
 100 You can then install your first application:
 101
 102 ```bash
 103 root@porter:~# afm-util install /home/root/annex.wgt
 104 { "added": "webapps-annex@0.0" }
 105 ```
 106
 107 Let's install a second application:
 108
 109 ```bash
 110 root@porter:~# afm-util install /home/root/memory-match.wgt
 111 { "added": "webapps-memory-match@1.1" }
 112 ```
 113
 114 Note that usually, **afm-util** will return a **JSON result**, which is the common format for messages returned by the Application Framework daemons.
 115
 116 ### List installed applications
 117
 118 You can then list all installed applications:
 119
 120 ```bash
 121 root@porter:~# afm-util list
 122 [ { "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>" },
 123 { "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>" } ]
 124 ```
 125
 126 Here, we can see the two previously installed applications.
 127
 128 ### Get information about an application
 129
 130 Let's get some details about the first application:
 131
 132 ```bash
 133 root@porter:~# afm-util info webapps-annex@0.0
 134 { "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>" }
 135 ```
 136
 137 Note: that AGL applications are mostly handled by afm-util through their IDs.
 138 In our example, the application ID is 'webapps-annex@0.0'.
 139
 140 ### Start application
 141
 142 Let's start the first application Annex:
 143
 144 ```bash
 145 root@porter:~# afm-util start webapps-annex@0.0
 146 1
 147 ```
 148
 149 As the application is a HTML5 game, you should then get a webview running with QML on the board display.
 150
 151 ### Security Context
 152
 153 The application has been started in the user session, with a dedicated security context, enforced by SMACK.
 154 To illustrate this, we can take a look at the running processes and their respective SMACK labels:
 155
 156 ```bash
 157 root@porter:~# ps -efZ |grep webapps-annex | grep -v grep
 158 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
 159 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
 160 ```
 161
 162 In the previous result, we see that the application is composed of two processes:
 163
 164 * the application binder (afb-daemon)
 165 * the application UI (qmlscene ...)
 166
 167 While most system processes run with the label 'System', we see that the
 168 application runs with a specific SMACK label 'User::App::webapps-annex': this
 169 label is used to force the application to follow
 170 a Mandatory Access Control (MAC) scheme.
 171 This means that those processes run in their own security context,
 172 isolated from the rest of the system (and other applications).
 173 Global security rules can then be applied to restrict access
 174 to all other user or system resources.
 175
 176 ### Check running applications
 177
 178 To check for running applications, just run:
 179
 180 ```bash
 181 root@porter:~# afm-util ps
 182 [ { "runid": 1, "state": "running", "id": "webapps-annex@0.0" } ]
 183 ```
 184
 185 The 'runid' is the application instance ID and is used as an argument for the
 186 subcommands controlling the application runtime state (kill/pause/resume/status)
 187
 188 ### Uninstall application
 189
 190 To uninstall an application, simply use its ID:
 191
 192 ```bash
 193 root@porter:~# afm-util uninstall webapps-annex@0.0
 194 true
 195 ```
 196
 197 Then list the installed apps to confirm the removal:
 198
 199 ```bash
 200 root@porter:~# afm-util list
 201 [ { "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>" } ]
 202 ```
 203
 204 ## afm-client: a sample HTML5 'Homescreen'
 205
 206 **afm-client** is a HTML5 UI that allows to install/uninstall applications as well as starting/pausing them as already demonstrated with afm-util.
 207
 208 The HTML5 UI is accessible remotely through this URL:
 209 <http://[board_ip]:1234/opa?token=132456789>
 210
 211 ### Installing an application
 212
 213 By clicking on the '**Upload**' button on the right,
 214 you can send an application package (WGT file) and install it.
 215 Select for example the file '**rabbit.wgt**' that was cloned initially
 216  from the git repository afm-widget-examples.
 217
 218 Then a popup requester ask for a confirmation:
 219 'Upload Application rabbit.wgt ?'. Click on the '**Install**' button.
 220
 221 You should then see some changes in the toolbar:
 222 a new icon appeared, representing the freshly installed application.
 223
 224 ### Running an application
 225
 226 In the toolbar, click on the button representing the Rabbit application.
 227 You'll get a popup asking to:
 228
 229 * start the application
 230 * or get some info about it
 231 * or uninstall it
 232
 233 Click on the 'start' item: the application starts and should be visible
 234  as a webview on the target board display.
 235 Note that at this point, we could also run the application remotely,
 236 that is in the same browser as the Homescreen app.
 237 By default, the application framework is configured
 238 to run applications 'locally' on the board display.
 239
 240 ### Uninstalling an application
 241
 242 From the same popup menu, you can select 'uninstall'
 243 to remove the application from the system.
 244 As a consequence, the application icon should disappear from the toolbar.
 245
 246 ## afb-client: a template for Angular Applications
 247
 248 Another package '**afb-client**' is also available for testing.
 249 This is a sample HTML5 application demonstrating various basic
 250 capabilities of the Binder daemon.
 251 It can be used by developers as a template to start writing real AGL Applications.
 252
 253 This application is not available as WGT file yet and it should be started manually without any specific security context:
 254
 255 ```bash
 256 root@porter:~# /usr/bin/afb-daemon --port=1235 --token='' --sessiondir=/home/root/.afm-daemon --rootdir=/usr/share/agl/afb-client --alias=/icons:/usr/share/afm/icons
 257 ```
 258
 259 Then you can access it from a browser:
 260 <http://[board_ip]:1235/opa/?token=132456789>
 261
 262 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.
 263
 264 [https://github.com/iotbzh/afm-widget-examples]: https://github.com/iotbzh/afm-widget-examples
 265 [https://www.automotivelinux.org/]: https://www.automotivelinux.org/
 266 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder
 267 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main