doc/quick-tutorial.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4 <meta charset="utf-8">
   5 <meta name="viewport" content="width=device-width, initial-scale=1.0">
   6 <title>quick-tutorial</title>
   7 <link rel="stylesheet" href="https://stackedit.io/res-min/themes/base.css" />
   8 <script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML"></script>
   9 </head>
  10 <body><div class="container"><h1 id="agl-application-framework-a-quick-tutorial">AGL Application Framework: A Quick Tutorial</h1>
  11
  12 <p><div class="toc">
  13 <ul>
  14 <li><a href="#agl-application-framework-a-quick-tutorial">AGL Application Framework: A Quick Tutorial</a><ul>
  15 <li><a href="#introduction">Introduction</a></li>
  16 <li><a href="#sample-applications">Sample applications</a></li>
  17 <li><a href="#using-the-cli-tool">Using the CLI tool</a><ul>
  18 <li><a href="#setup-environment">Setup Environment</a></li>
  19 <li><a href="#install-an-application">Install an application</a></li>
  20 <li><a href="#list-installed-applications">List installed applications</a></li>
  21 <li><a href="#get-information-about-an-application">Get information about an application</a></li>
  22 <li><a href="#start-application">Start application</a></li>
  23 <li><a href="#security-context">Security Context</a></li>
  24 <li><a href="#check-running-applications">Check running applications</a></li>
  25 <li><a href="#stop-application">Stop application</a></li>
  26 <li><a href="#uninstall-application">Uninstall application</a></li>
  27 </ul>
  28 </li>
  29 <li><a href="#afm-client-a-sample-html5-homescreen">afm-client: a sample HTML5 ‘Homescreen’</a><ul>
  30 <li><a href="#installing-an-application">Installing an application</a></li>
  31 <li><a href="#running-an-application">Running an application</a></li>
  32 <li><a href="#stopping-an-application">Stopping an application</a></li>
  33 <li><a href="#uninstalling-an-application">Uninstalling an application</a></li>
  34 </ul>
  35 </li>
  36 <li><a href="#afb-client-a-template-for-angular-applications">afb-client: a template for Angular Applications</a></li>
  37 </ul>
  38 </li>
  39 </ul>
  40 </div>
  41 </p>
  42
  43
  44
  45 <h2 id="introduction">Introduction</h2>
  46
  47 <p>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:  <br>
  48 <a href="https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main">https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main</a> <br>
  49 <a href="https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder">https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder</a></p>
  50
  51 <p>For more information on AGL, please visit: <br>
  52 <a href="https://www.automotivelinux.org/">https://www.automotivelinux.org/</a></p>
  53
  54 <hr>
  55
  56
  57
  58 <h2 id="sample-applications">Sample applications</h2>
  59
  60 <p>4 sample applications (.wgt files) are prebuilt and available at the following address: <br>
  61 <a href="https://github.com/iotbzh/afm-widget-examples">https://github.com/iotbzh/afm-widget-examples</a></p>
  62
  63 <p>You can get them by cloning this git repository on your desktop (will be useful later in this tutorial):</p>
  64
  65
  66
  67 <pre class="prettyprint"><code class=" hljs ruby"><span class="hljs-variable">$ </span>git clone <span class="hljs-symbol">https:</span>/<span class="hljs-regexp">/github.com/iotbzh</span><span class="hljs-regexp">/afm-widget-examples</span></code></pre>
  68
  69
  70
  71 <h2 id="using-the-cli-tool">Using the CLI tool</h2>
  72
  73
  74
  75 <h3 id="setup-environment">Setup Environment</h3>
  76
  77 <p>Connect your AGL target board to the network and copy some sample widgets on it through SSH (set BOARDIP with your board IP address) :</p>
  78
  79
  80
  81 <pre class="prettyprint"><code class=" hljs ruby"><span class="hljs-variable">$ </span>cd afm-widget-examples
  82 <span class="hljs-variable">$ </span><span class="hljs-constant">BOARDIP</span>=<span class="hljs-number">1.2</span>.<span class="hljs-number">3.4</span>
  83 <span class="hljs-variable">$ </span>scp *.wgt root@<span class="hljs-variable">$BOARDIP</span><span class="hljs-symbol">:~/</span></code></pre>
  84
  85 <p>Connect through SSH on the target board and check for Application Framework daemons:</p>
  86
  87 <pre><code>$ ssh root@$BOARDIP
  88 root@porter:~# ps -ef|grep bin/afm
  89 afm        409     1  0 13:00 ?        00:00:00 /usr/bin/afm-system-daemon
  90 root       505   499  0 13:01 ?        00:00:00 /usr/bin/afm-user-daemon
  91 root       596   550  0 13:22 pts/0    00:00:00 grep afm
  92 </code></pre>
  93
  94 <p>We can see that there are two daemons running: <br>
  95 * <strong>afm-system-daemon</strong> runs with a system user ‘afm’ and is responsible for installing/uninstalling packages <br>
  96 * <strong>afm-user-daemon</strong> 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.</p>
  97
  98 <p>The application framework has a tool running on the Command Line Interface (CLI). Using the <strong>afm-util</strong> command, you can install, uninstall, list, run, stop … applications. </p>
  99
 100 <p>To begin, run ‘<strong>afm-util help</strong>’ to get a quick help on commands:</p>
 101
 102 <pre><code>root@porter:~# afm-util help
 103 usage: afm-util command [arg]
 104
 105 The commands are:
 106
 107   list
 108   runnables      list the runnable widgets installed
 109
 110   add wgt
 111   install wgt    install the wgt file
 112
 113   remove id
 114   uninstall id   remove the installed widget of id
 115
 116   info id
 117   detail id      print detail about the installed widget of id
 118
 119   ps
 120   runners        list the running instance
 121
 122   run id
 123   start id       start an instance of the widget of id
 124
 125   kill rid
 126   terminate rid       terminate the running instance rid
 127
 128   stop rid
 129   pause rid      stop the running instance rid
 130
 131   resume rid
 132   continue rid   continue the previously rid
 133
 134   status rid
 135   state rid     get status of the running instance rid
 136 </code></pre>
 137
 138
 139
 140 <h3 id="install-an-application">Install an application</h3>
 141
 142 <p>You can then install your first application:</p>
 143
 144 <pre><code>root@porter:~# afm-util install /home/root/annex.wgt
 145 { "added": "webapps-annex@0.0" }
 146 </code></pre>
 147
 148 <p>Let’s install a second application:</p>
 149
 150 <pre><code>root@porter:~# afm-util install /home/root/memory-match.wgt
 151 { "added": "webapps-memory-match@1.1" }
 152 </code></pre>
 153
 154 <p>Note that usually, <strong>afm-util</strong> will return a <strong>JSON result</strong>, which is the common format for messages returned by the Application Framework daemons.</p>
 155
 156
 157
 158 <h3 id="list-installed-applications">List installed applications</h3>
 159
 160 <p>You can then list all installed applications:</p>
 161
 162 <pre><code>root@porter:~# afm-util list
 163 [ { "id": "webapps-annex@0.0", "version": "0.0.10", "width": 0, "height": 0, "name": "Annex", "description": "Reversi\/Othello", "shortname": "", "author": "Todd Brandt &lt;todd.e.brandt@intel.com&gt;" },
 164  { "id": "webapps-memory-match@1.1", "version": "1.1.7", "width": 0, "height": 0, "name": "MemoryMatch", "description": "Memory match", "shortname": "", "author": "Todd Brandt &lt;todd.e.brandt@intel.com&gt;" } ]
 165 </code></pre>
 166
 167 <p>Here, we can see the two previously installed applications.</p>
 168
 169
 170
 171 <h3 id="get-information-about-an-application">Get information about an application</h3>
 172
 173 <p>Let’s get some details about the first application:</p>
 174
 175 <pre><code>root@porter:~# afm-util info webapps-annex@0.0
 176 { "id": "webapps-annex@0.0", "version": "0.0.10", "width": 0, "height": 0, "name": "Annex", "description": "Reversi\/Othello", "shortname": "", "author": "Todd Brandt &lt;todd.e.brandt@intel.com&gt;" }
 177 </code></pre>
 178
 179 <p>Note that AGL applications are mostly handled by afm-util through their IDs. In our example, the application ID is ‘webapps-annex@0.0’.</p>
 180
 181
 182
 183 <h3 id="start-application">Start application</h3>
 184
 185 <p>Let’s start the first application Annex:</p>
 186
 187 <pre><code>root@porter:~# afm-util start webapps-annex@0.0
 188 1
 189 </code></pre>
 190
 191 <p>As the application is a HTML5 game, you should then get a webview running with QML on the board display.</p>
 192
 193
 194
 195 <h3 id="security-context">Security Context</h3>
 196
 197 <p>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:</p>
 198
 199 <pre><code>root@porter:~# ps -efZ |grep webapps-annex | grep -v grep
 200 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
 201 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
 202 </code></pre>
 203
 204 <p>In the previous result, we see that the application is composed of two processes: <br>
 205 * the application binder (afb-daemon) <br>
 206 * the application UI (qmlscene …)</p>
 207
 208 <p>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.</p>
 209
 210
 211
 212 <h3 id="check-running-applications">Check running applications</h3>
 213
 214 <p>To check for running applications, just run:</p>
 215
 216 <pre><code>root@porter:~# afm-util ps
 217 [ { "runid": 1, "state": "running", "id": "webapps-annex@0.0" } ]
 218 </code></pre>
 219
 220 <p>The ‘runid’ is the application instance ID and is used as an argument for the subcommands controlling the application runtime state (kill/stop/resume/status)</p>
 221
 222
 223
 224 <h3 id="stop-application">Stop application</h3>
 225
 226 <p>To stop the application that was just started (the one with RUNID 1), just run the stop command:</p>
 227
 228 <pre><code>root@porter:~# afm-util terminate 1
 229 true
 230 </code></pre>
 231
 232 <p>The application is now stopped, as confirmed by a list of running apps:</p>
 233
 234 <pre><code>root@porter:~# afm-util ps
 235 [ ]
 236 </code></pre>
 237
 238
 239
 240 <h3 id="uninstall-application">Uninstall application</h3>
 241
 242 <p>To uninstall an application, simply use its ID:</p>
 243
 244 <pre><code>root@porter:~# afm-util uninstall webapps-annex@0.0
 245 true
 246 </code></pre>
 247
 248 <p>Then list the installed apps to confirm the removal:</p>
 249
 250 <pre><code>root@porter:~# afm-util list
 251 [ { "id": "webapps-memory-match@1.1", "version": "1.1.7", "width": 0, "height": 0, "name": "MemoryMatch", "description": "Memory match", "shortname": "", "author": "Todd Brandt &lt;todd.e.brandt@intel.com&gt;" } ]
 252 </code></pre>
 253
 254
 255
 256 <h2 id="afm-client-a-sample-html5-homescreen">afm-client: a sample HTML5 ‘Homescreen’</h2>
 257
 258 <p><strong>afm-client</strong> is a HTML5 UI that allows to install/uninstall applications as well as starting/stopping them as already demonstrated with afm-util.</p>
 259
 260 <p>The HTML5 UI is accessible remotely through this URL:  <br>
 261 <a href="http://[board_ip]:1234/opa?token=132456789">http://[board_ip]:1234/opa?token=132456789</a></p>
 262
 263
 264
 265 <h3 id="installing-an-application">Installing an application</h3>
 266
 267 <p>By clicking on the ‘<strong>Upload</strong>’ button on the right, you can send an application package (WGT file) and install it. Select for example the file ‘<strong>rabbit.wgt</strong>’ that was cloned initially from the git repository afm-widget-examples.</p>
 268
 269 <p>Then a popup requester ask for a confirmation: ‘Upload Application rabbit.wgt ?’. Click on the ‘<strong>Install</strong>’ button.</p>
 270
 271 <p>You should then see some changes in the toolbar: a new icon appeared, representing the freshly installed application.</p>
 272
 273
 274
 275 <h3 id="running-an-application">Running an application</h3>
 276
 277 <p>In the toolbar, click on the button representing the Rabbit application. You’ll get a popup asking to: <br>
 278 * start the application <br>
 279 * or get some info about it <br>
 280 * or uninstall it</p>
 281
 282 <p>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.</p>
 283
 284
 285
 286 <h3 id="stopping-an-application">Stopping an application</h3>
 287
 288 <p>In the Homescreen application, click again on the Rabbit application button, then select ‘stop’: the application then stops.</p>
 289
 290
 291
 292 <h3 id="uninstalling-an-application">Uninstalling an application</h3>
 293
 294 <p>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.</p>
 295
 296
 297
 298 <h2 id="afb-client-a-template-for-angular-applications">afb-client: a template for Angular Applications</h2>
 299
 300 <p>Another package ‘<strong>afb-client</strong>’ is also available for testing. <br>
 301 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.</p>
 302
 303 <p>This application is not available as WGT file yet and it should be started manually without any specific security context:</p>
 304
 305 <pre><code>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
 306 </code></pre>
 307
 308 <p>Then you can access it from a browser: <br>
 309 <a href="http://[board_ip]:1235/opa/?token=132456789">http://[board_ip]:1235/opa/?token=132456789</a></p>
 310
 311 <p>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.</p></div></body>
 312 </html>