docs/quick-tutorial.md

   1
   2 AGL Application Framework: A Quick Tutorial
   3 ===========================================
   4
   5 Introduction
   6 ------------
   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:
   8 https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main
   9 https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder
  10
  11 For more information on AGL, please visit:
  12 https://www.automotivelinux.org/
  13
  14 ----------
  15
  16 Sample applications
  17 -------------------
  18 4 sample applications (.wgt files) are prebuilt and available at the following address:
  19 https://github.com/iotbzh/afm-widget-examples
  20
  21 You can get them by cloning this git repository on your desktop (will be useful later in this tutorial):
  22
  23 ```
  24 $ git clone https://github.com/iotbzh/afm-widget-examples
  25 ```
  26
  27 Using the CLI tool
  28 ------------------
  29
  30 ### Setup Environment
  31 Connect your AGL target board to the network and copy some sample widgets on it through SSH (set BOARDIP with your board IP address) :
  32
  33 ```
  34 $ cd afm-widget-examples
  35 $ BOARDIP=1.2.3.4
  36 $ scp *.wgt root@$BOARDIP:~/
  37 ```
  38
  39 Connect through SSH on the target board and check for Application Framework daemons:
  40
  41     $ ssh root@$BOARDIP
  42     root@porter:~# ps -ef|grep bin/afm
  43     afm        409     1  0 13:00 ?        00:00:00 /usr/bin/afm-system-daemon
  44     root       505   499  0 13:01 ?        00:00:00 /usr/bin/afm-user-daemon
  45     root       596   550  0 13:22 pts/0    00:00:00 grep afm
  46
  47 We can see that there are two daemons running:
  48 * **afm-system-daemon** runs with a system user 'afm' and is responsible for installing/uninstalling packages
  49 * **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.
  50
  51 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.
  52
  53 To begin, run '**afm-util help**' to get a quick help on commands:
  54
  55     root@porter:~# afm-util help
  56     usage: afm-util command [arg]
  57
  58     The commands are:
  59
  60       list
  61       runnables      list the runnable widgets installed
  62
  63       add wgt
  64       install wgt    install the wgt file
  65
  66       remove id
  67       uninstall id   remove the installed widget of id
  68
  69       info id
  70       detail id      print detail about the installed widget of id
  71
  72       ps
  73       runners        list the running instance
  74
  75       run id
  76       start id       start an instance of the widget of id
  77
  78       kill rid
  79       terminate rid  terminate the running instance rid
  80
  81       stop rid
  82       pause rid      pause the running instance rid
  83
  84       resume rid
  85       continue rid   resume the previously rid
  86
  87       status rid
  88       state rid      get status of the running instance rid
  89
  90 ### Install an application
  91
  92 You can then install your first application:
  93
  94     root@porter:~# afm-util install /home/root/annex.wgt
  95     { "added": "webapps-annex@0.0" }
  96
  97 Let's install a second application:
  98
  99     root@porter:~# afm-util install /home/root/memory-match.wgt
 100     { "added": "webapps-memory-match@1.1" }
 101
 102 Note that usually, **afm-util** will return a **JSON result**, which is the common format for messages returned by the Application Framework daemons.
 103
 104 ### List installed applications
 105 You can then list all installed applications:
 106
 107     root@porter:~# afm-util list
 108     [ { "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>" },
 109      { "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>" } ]
 110
 111 Here, we can see the two previously installed applications.
 112
 113 ### Get information about an application
 114 Let's get some details about the first application:
 115
 116     root@porter:~# afm-util info webapps-annex@0.0
 117     { "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>" }
 118
 119 Note that AGL applications are mostly handled by afm-util through their IDs. In our example, the application ID is 'webapps-annex@0.0'.
 120
 121 ### Start application
 122 Let's start the first application Annex:
 123
 124     root@porter:~# afm-util start webapps-annex@0.0
 125     1
 126
 127 As the application is a HTML5 game, you should then get a webview running with QML on the board display.
 128
 129 ### Security Context
 130 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:
 131
 132     root@porter:~# ps -efZ |grep webapps-annex | grep -v grep
 133     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
 134     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
 135
 136 In the previous result, we see that the application is composed of two processes:
 137 * the application binder (afb-daemon)
 138 * the application UI (qmlscene ...)
 139
 140 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.
 141
 142 ### Check running applications
 143 To check for running applications, just run:
 144
 145     root@porter:~# afm-util ps
 146     [ { "runid": 1, "state": "running", "id": "webapps-annex@0.0" } ]
 147
 148 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)
 149
 150 ### Pause application
 151 To pause the application that was just started (the one with RUNID 1), just run the pause command:
 152
 153     root@porter:~# afm-util terminate 1
 154     true
 155
 156 The application is now paused, as confirmed by a list of running apps:
 157
 158     root@porter:~# afm-util ps
 159     [ ]
 160
 161
 162 ### Uninstall application
 163 To uninstall an application, simply use its ID:
 164
 165     root@porter:~# afm-util uninstall webapps-annex@0.0
 166     true
 167
 168 Then list the installed apps to confirm the removal:
 169
 170     root@porter:~# afm-util list
 171     [ { "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>" } ]
 172
 173 afm-client: a sample HTML5 'Homescreen'
 174 ---------------------------------------
 175
 176 **afm-client** is a HTML5 UI that allows to install/uninstall applications as well as starting/pausing them as already demonstrated with afm-util.
 177
 178 The HTML5 UI is accessible remotely through this URL:
 179 http://[board_ip]:1234/opa?token=132456789
 180
 181 ### Installing an application
 182
 183 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.
 184
 185 Then a popup requester ask for a confirmation: 'Upload Application rabbit.wgt ?'. Click on the '**Install**' button.
 186
 187 You should then see some changes in the toolbar: a new icon appeared, representing the freshly installed application.
 188
 189 ### Running an application
 190 In the toolbar, click on the button representing the Rabbit application. You'll get a popup asking to:
 191 * start the application
 192 * or get some info about it
 193 * or uninstall it
 194
 195 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.
 196
 197 ### Pausing an application
 198
 199 In the Homescreen application, click again on the Rabbit application button, then select 'pause': the application then pauses.
 200
 201 ### Uninstalling an application
 202
 203 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.
 204
 205 afb-client: a template for Angular Applications
 206 -----------------------------------------------
 207
 208 Another package '**afb-client**' is also available for testing.
 209 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.
 210
 211 This application is not available as WGT file yet and it should be started manually without any specific security context:
 212
 213     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
 214
 215 Then you can access it from a browser:
 216 http://[board_ip]:1235/opa/?token=132456789
 217
 218 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.