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