docs/4_APIs_and_Services/4.2_Application_Framework/5_quick-tutorial.md

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