docs/4-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 functionalities of the AGL Application Framework. For more complete information, please refer to the inline documentation available in the main git repository:
   8
   9 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main]
  10 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder]
  11
  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 ```
  26 $ git clone https://github.com/iotbzh/afm-widget-examples
  27 ```
  28
  29 Using the CLI tool
  30 ------------------
  31
  32 ### Setup Environment
  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 ```
  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     $ ssh root@$BOARDIP
  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
  48
  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 life cycle of the applications running inside the user session.
  52
  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.
  54
  55 To begin, run '**afm-util help**' to get a quick help on commands:
  56
  57     root@porter:~# afm-util help
  58     usage: afm-util command [arg]
  59
  60     The commands are:
  61
  62       list
  63       runnables      list the runnable widgets installed
  64
  65       add wgt
  66       install wgt    install the wgt file
  67
  68       remove id
  69       uninstall id   remove the installed widget of id
  70
  71       info id
  72       detail id      print detail about the installed widget of id
  73
  74       ps
  75       runners        list the running instance
  76
  77       run id
  78       start id       start an instance of the widget of id
  79
  80       kill rid
  81       terminate rid  terminate the running instance rid
  82
  83       status rid
  84       state rid      get status of the running instance rid
  85
  86 ### Install an application
  87
  88 You can then install your first application:
  89
  90     root@porter:~# afm-util install /home/root/annex.wgt
  91     { "added": "webapps-annex@0.0" }
  92
  93 Let's install a second application:
  94
  95     root@porter:~# afm-util install /home/root/memory-match.wgt
  96     { "added": "webapps-memory-match@1.1" }
  97
  98 Note that usually, **afm-util** will return a **JSON result**, which is the common format for messages returned by the Application Framework daemons.
  99
 100 ### List installed applications
 101 You can then list all installed applications:
 102
 103     root@porter:~# afm-util list
 104     [ { "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>" },
 105      { "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>" } ]
 106
 107 Here, we can see the two previously installed applications.
 108
 109 ### Get information about an application
 110 Let's get some details about the first application:
 111
 112     root@porter:~# afm-util info webapps-annex@0.0
 113     { "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>" }
 114
 115 Note that AGL applications are mostly handled by afm-util through their IDs. In our example, the application ID is 'webapps-annex@0.0'.
 116
 117 ### Start application
 118 Let's start the first application Annex:
 119
 120     root@porter:~# afm-util start webapps-annex@0.0
 121     1
 122
 123 As the application is a HTML5 game, you should then get a webview running with QML on the board display.
 124
 125 ### Security Context
 126 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:
 127
 128     root@porter:~# ps -efZ |grep webapps-annex | grep -v grep
 129     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
 130     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
 131
 132 In the previous result, we see that the application is composed of two processes:
 133 * the application binder (afb-daemon)
 134 * the application UI (qmlscene ...)
 135
 136 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.
 137
 138 ### Check running applications
 139 To check for running applications, just run:
 140
 141     root@porter:~# afm-util ps
 142     [ { "runid": 1, "state": "running", "id": "webapps-annex@0.0" } ]
 143
 144 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)
 145
 146 ### Uninstall application
 147 To uninstall an application, simply use its ID:
 148
 149     root@porter:~# afm-util uninstall webapps-annex@0.0
 150     true
 151
 152 Then list the installed apps to confirm the removal:
 153
 154     root@porter:~# afm-util list
 155     [ { "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>" } ]
 156
 157 afm-client: a sample HTML5 'Homescreen'
 158 ---------------------------------------
 159
 160 **afm-client** is a HTML5 UI that allows to install/uninstall applications as well as starting/pausing them as already demonstrated with afm-util.
 161
 162 The HTML5 UI is accessible remotely through this URL:
 163 http://[board_ip]:1234/opa?token=132456789
 164
 165 ### Installing an application
 166
 167 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.
 168
 169 Then a popup requester ask for a confirmation: 'Upload Application rabbit.wgt ?'. Click on the '**Install**' button.
 170
 171 You should then see some changes in the toolbar: a new icon appeared, representing the freshly installed application.
 172
 173 ### Running an application
 174 In the toolbar, click on the button representing the Rabbit application. You'll get a popup asking to:
 175 * start the application
 176 * or get some info about it
 177 * or uninstall it
 178
 179 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.
 180
 181 ### Uninstalling an application
 182
 183 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.
 184
 185 afb-client: a template for Angular Applications
 186 -----------------------------------------------
 187
 188 Another package '**afb-client**' is also available for testing.
 189 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.
 190
 191 This application is not available as WGT file yet and it should be started manually without any specific security context:
 192
 193     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
 194
 195 Then you can access it from a browser:
 196 http://[board_ip]:1235/opa/?token=132456789
 197
 198 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.
 199
 200 [https://github.com/iotbzh/afm-widget-examples]: https://github.com/iotbzh/afm-widget-examples
 201 [https://www.automotivelinux.org/]: https://www.automotivelinux.org/
 202 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder
 203 [https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main