Google Git
Sign in
eclipse / www.eclipse.org / kuksa / 192526a8028b7a1252532c7a1007333f97863d21 / . / documentation / index.html
blob: d4110c4e51d0fdcff850460d4f01a38a9d836992 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en-us">
<head>
<meta charset="utf-8">
<meta name="robots" content="all,follow">
<meta name="googlebot" content="index,follow,snippet,archive">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Eclipse Kuksa documentation</title>
<meta name="author" content="" />
<meta name="keywords" content="iot, smart mobility, kuksa, appstacle">
<meta name="description" content="Eclipse KUKSA community website">
<meta name="generator" content="Hugo 0.42.1" />
<link href='//fonts.googleapis.com/css?family=Roboto:400,100,100italic,300,300italic,500,700,800' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css">
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<link href="https://www.eclipse.org/kuksa/css/animate.css" rel="stylesheet">
<link href="https://www.eclipse.org/kuksa/css/style.turquoise.css" rel="stylesheet" id="theme-stylesheet">
<link href="https://www.eclipse.org/kuksa/css/style.kuksa.css" rel="stylesheet" id="theme-stylesheet">
<link href="https://www.eclipse.org/kuksa/css/custom.css" rel="stylesheet">
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
<link rel="shortcut icon" href="https://www.eclipse.org/kuksa/img/favicon.ico" type="image/x-icon" />
<link rel="apple-touch-icon" href="https://www.eclipse.org/kuksa/img/kuksa-icon.png" />
<link href="https://www.eclipse.org/kuksa/css/owl.carousel.css" rel="stylesheet">
<link href="https://www.eclipse.org/kuksa/css/owl.theme.css" rel="stylesheet">
<link rel="alternate" href="https://www.eclipse.org/index.xml" type="application/rss+xml" title="Eclipse KUKSA">
<meta property="og:title" content="Eclipse Kuksa documentation" />
<meta property="og:type" content="website" />
<meta property="og:url" content="/kuksa/documentation//" />
<meta property="og:image" content="img/kuksa-incubation-logo-h-428x128.png" />
<link rel="stylesheet" type="text/css" href="//www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css" />
<script src="//www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>
<script src="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/eclipsefdn.videos.min.js"></script>
<link href="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/eclipsefdn-video.min.css" rel="stylesheet" type="text/css">
<script>eclipseFdnVideos.replace();</script>
</head>
<body>
<div id="all">
<header>
<div class="navbar-affixed-top" data-spy="affix" data-offset-top="200">
<div class="navbar navbar-default yamm" role="navigation" id="navbar">
<div class="container">
<div class="navbar-header">
<a class="navbar-brand home" href="https://www.eclipse.org/kuksa/">
<img src="https://www.eclipse.org/kuksa/img/kuksa-incubation-logo-h-428x128.png" alt="Eclipse Kuksa documentation logo" class="hidden-xs hidden-sm" height="80">
<img src="https://www.eclipse.org/kuksa/img/kuksa-incubation-logo-h-428x128.png" alt="Eclipse Kuksa documentation logo" class="visible-xs visible-sm" height="50">
<span class="sr-only">Eclipse Kuksa documentation - go to homepage</span>
</a>
<div class="navbar-buttons">
<button type="button" class="navbar-toggle btn-template-main" data-toggle="collapse" data-target="#navigation">
<span class="sr-only">Toggle Navigation</span>
<i class="fa fa-align-justify"></i>
</button>
</div>
</div>
<div class="navbar-collapse collapse" id="navigation">
<ul class="nav navbar-nav navbar-right">
<li class="dropdown">
<a href="/kuksa/">Home</a>
</li>
<li class="dropdown">
<a href="/kuksa/about/">About</a>
</li>
<li class="dropdown">
<a href="/kuksa/documentation/">Documentation</a>
</li>
<li class="dropdown">
<a href="/kuksa/blog/">Blog</a>
</li>
<li class="dropdown">
<a href="/kuksa/contributing/">Contributing</a>
</li>
<li class="dropdown">
<a href="/kuksa/resources/">Resources</a>
</li>
</ul>
</div>
<div class="collapse clearfix" id="search">
<form class="navbar-form" role="search">
<div class="input-group">
<input type="text" class="form-control" placeholder="Search">
<span class="input-group-btn">
<button type="submit" class="btn btn-template-main"><i class="fa fa-search"></i></button>
</span>
</div>
</form>
</div>
</div>
</div>
</div>
</header>
<div id="heading-breadcrumbs">
<div class="container">
<div class="row">
<div class="col-md-12">
<h1>Eclipse Kuksa documentation</h1>
</div>
</div>
</div>
</div>
<div id="content">
<div class="container">
<div class="row">
<div class="col-md-12">
<div>
<p>Eclipse Kuksa builds a platform to connect vehicles to the cloud and enable the development of specific applications of connected driving. This documentation covers the core pillars as follows: 1. the Eclipse Kuksa IDE, 2. the Eclipse Kukse In-Vehicle Platform, and 3. the Eclipse Kuksa Cloud Platform.</p>
<p>This documentation intends to give a high-level overview of the Eclipse Kuksa components. For more detailed information and documentation on the different aspects, we recommend consulting the respective repositories and their Readme files. The development around Eclipse Kuksa divides into seven repositories. An overview of these repositories and what they focus on is available on the Kuksa Website under <a href="https://www.eclipse.org/kuksa/resources/">Resources</a>.</p>
<h1 id="1-eclipse-kuksa-ide">1. Eclipse Kuksa IDE</h1>
<h2 id="1-1-introduction">1.1 Introduction</h2>
<p>Extensions are available for two different kind of existing IDEs.
* The latest extension is available for MS Visual Studio Code in form of a downloadable extension from the <a href="https://marketplace.visualstudio.com/items?itemName=Eclipse-Kuksa-Team.kuksa-ide&amp;utm_source=VSCode.pro&amp;utm_campaign=AhmadAwais">marketplace</a>.
* The second extension is a custom Eclipse Che Assembly. A quick start can be found <a href="https://kuksa-che-ide.readthedocs.io/en/latest/quick/index.html">here</a>.</p>
<p>Eclipse Kuksa offers various APIs for implementing vehicle applications based on AGL (Eclipse Kuksa IDE based on Eclipse Che) or docker (Eclipse Kuksa IDE based on VSCode) as well as provisioning built applications at the Eclipse Kuksa App Store. This enables accessing existing communication interfaces for secure data transmission, storage, management, and authentication without having to take separate measurements for processing or interpreting the data.</p>
<p>Eclipse Kuksa also supports the simplified deployment of new applications for both the cloud and vehicle components. Configuration, building and deployment can be done at the push of a button without further configuration or processing. Depending on the application, different development tools (e.g. Logging, Debugging, Tracing,&hellip;) can be included. Of course, syntax highlighting, code completion, and other necessary IDE functions are supported. For instance, the in-vehicle Eclipse Kuksa Che stack for AGL development activities features including Yocto based SDKs in order to support target specific programming shown in the screenshot below. After compiling and building software, the deployment on a specific target can be triggered by only specifying a target IP within a dedicated deployment process. <a href="https://www.eclipse.org/community/eclipse_newsletter/2018/july/kuksa.php">Click here</a> to read more. The Eclipse Kuksa IDE provides an easy and straight forward mechanism to create new projects based on AGL as outlined <a href="https://gitlab-pages.idial.institute/pedro.cuadrachamorro/kuksa-ide/samples/index.html">here</a>.</p>
<p style="text-align:center;">
<a href="/kuksa/docimgs/Kuksa_IDE.png">
<img src="/kuksa/docimgs/Kuksa_IDE.png" width="60%" alt="Kuksa IDE"/>
</a><br/>
</p>
<p>Ecslipe Kuksa Demo Apps for the In-Vehicle platform can be found at the <a href="https://github.com/eclipse/kuksa.apps/tree/master/invehicle-apps">according repository</a>.
Eclipse Kuksa Demo Cloud Apps can be at <a href="https://github.com/eclipse/kuksa.apps/tree/master/cloud-apps">the same repository at a different location</a>.</p>
<h2 id="1-2-eclipse-kuksa-ide-based-on-vscode">1.2 Eclipse Kuksa IDE based on VSCode</h2>
<p>The VSCode Kuksa extension is a package of four different extensions bundled into one. These are as follows:
1. Kuksa: Initialize Workspace
2. Kuksa: Configure Kuksa Environment(YAML)
3. Kuksa: Generate Docker Image
4. Kuksa: Publish to AppStore</p>
<p>The user can trigger extensions from the Command Palette and also from the <em>Editor Header</em>. The Eclispe Kuksa extension follows the VSCode Extension file structure with standard folders like <code>.vscode</code> and <code>src</code>. It also includes the essential configuration files like <code>launch.json</code>, <code>tasks.json</code> and <code>tsconfig.json</code>.
Apart from the standard folders, there is also a Kuksa specific folder, which contains python and shell scripts.</p>
<p>An important configuration file of a VSCode extension is the <em>Extension Manifest</em>. This file should be located at the root of the extension directory structure. Essentially, it is a <code>package.json</code> file which contains a mix of <code>Node.js</code> and VSCode specific fields. The fields <em>activationEvents</em> and <em>contributes</em> are especially important since every extension uses a combination of these two and the VSCode API for extending VSCode’s functionality. The <em>Extension Manifest</em> also determines how the extension looks in the VS Code Marketplace with the icon, author, licence, and repository.</p>
<h3 id="1-2-1-initializing-the-workspace">1.2.1 Initializing the Workspace</h3>
<p>The <code>Kuksa: Initialize Workspace</code> extension was conceived as a way to provide new developers with the Kuksa project structure. The command generates the directories and required build scripts. It also creates an empty <code>yaml</code> configuration file to be used in the next steps. The entire tree structure is as follows:
* docker
* build.sh
* include
* kuksa.yaml</p>
<p>The user has to provide the IDE with the desired name of the project and the project structure will be generated with the required files and directories.
At the first step, the OS, on which VSCode is running, will be checked. Currently, only Unix-based Operating Systems like Linux or MacOS are supported. Next, the user is asked to provide a valid name for the project. Invalid or duplicate project names will lead to an error and eventual termination of the process. Once this is successful, the corresponding bash script is triggered and the project folder is opened automatically in VSCode.</p>
<h3 id="1-2-2-generating-a-docker-image">1.2.2 Generating a Docker Image</h3>
<p>The command <code>Kuksa: Generate Docker Image</code> is intended to automate the process of creating a Docker image from a particular Dockerfile and tag it appropriately so that it can be used as an artifact for Eclispe Hawkbit and consequently the Eclipse Kuksa AppStore.
The command is also responsible for copying the <code>QEMU</code> binary to the Kuksa project directory so that it can be compiled with the source code. The underlying script of this command is again a Bash script, which is created during initialization of the project.
It is important to note that the files and folders mentioned as part of the Dockerfile have to be present in the proper system paths.</p>
<h3 id="1-2-3-configuring-the-kuksa-environment-yaml">1.2.3 Configuring the Kuksa Environment (YAML)</h3>
<p>The command <code>Kuksa: Configure Kuksa Environment</code> helps the developer to generate the configuration file needed for publishing an application. The command triggers a HTML form which holds some required fields to be filled.
Some of the required fields are as follows:</p>
<ul>
<li>Application Name</li>
<li>App Version and Description</li>
<li>Corresponding Docker Image</li>
<li>Eclipse Hawkbit, Appstore and KeyCloak URL</li>
<li>Corresponding Credentials</li>
</ul>
<p>The form features a <em>tabbed</em> look for the <em>General</em>, <em>AppStore</em> and <em>Keycloak</em> fields.
The configuration file is generated based on the YAML format. A Python script converts the field objects into the YAML format.</p>
<p>Finally, publishing an application to the Eclipse Kuksa Appstore can be performed. The according command is responsible for packaging and deploying new or updated Kuksa applications to Eclipse Hawkbit and registering the App at the Kuksa AppStore. Keeping in mind the usability, this complex process is scaled down to only selecting a single configuration file (the same one explained above).
A Python script runs in the backend of this command. This script gets the authentication token from KeyCloak, creates a new application category if required, creates a new application or updates on an existing application and uploads corresponding artifacts to Eclipse Hawkbit.
Apart from being integrated as part of the IDE, it also covers KeyCloak authentication which is now applied over all Kuksa WebServices. The configuration file generated by the previous commands holds all the crucial information like the credentials and URLs for the script to work. REST APIs use these details to post and get responses from the URLs.</p>
<h2 id="1-3-eclipse-kuksa-ide-based-on-eclipse-che">1.3 Eclipse Kuksa IDE based on Eclipse Che</h2>
<p>The Eclipse Kuksa extension to Eclipse Che is based on GWT and hence Eclipse Che 6.X (not Eclipse Che 7.X and later).</p>
<h3 id="1-3-1-system-requirements">1.3.1 System requirements</h3>
<p>The neccessary prerequisite to build and deploy Eclipse Che Kuksa are:</p>
<ul>
<li>A running docker instance on a Linux host system (tested with Ubuntu 18.04).</li>
<li>Maven</li>
</ul>
<p>Additionally, steps for building and running a Eclipse Che Kuksa instance in version 6.X are available <a href="https://kuksa-che-ide.readthedocs.io/en/latest/">here</a>.</p>
<h3 id="1-3-2-how-to-setup-the-ide">1.3.2 How to setup the IDE</h3>
<p>To set up Eclipse Che Kuksa, the following steps are necessary. If one wants to build and deploy AGL applications &amp; services within Che:</p>
<ul>
<li>Create a new workspace with Automotive Grade Linux (AGL) as selected stack</li>
<li>Go to &ldquo;Profile&rdquo; → &ldquo;Preferences&rdquo; → &ldquo;Remote Targets&rdquo; and add a new Remote Target with the device IP and the according User, e.g. &ldquo;root&rdquo;. Then select the Target.</li>
<li>Go to Profile → Preferences → Yocto Settings and add a new SDK with a Name, e.g. &ldquo;agl-rover&rdquo;, a Version, e.g. &ldquo;1.0.0&rdquo; and a link to an appropriate AGL SDK, e.g. the AGL <a href="https://github.com/app4mc-rover">Rover</a> SDK from &ldquo;<a href="https://owncloud.idial.institute/s/YiS5wceBmSj4gyr&quot;">https://owncloud.idial.institute/s/YiS5wceBmSj4gyr&quot;</a>, as Download Link. Then select the added Yocto SDK. To avoid connection trouble, open the Terminal and ssh into the appropriate Device: <code>ssh &lt; User &gt;@&lt; IP &gt;</code>.</li>
</ul>
<h3 id="1-3-3-model-driven-development-of-agl-applications-and-services">1.3.3 Model-driven Development of AGL Applications and Services</h3>
<p>The Eclipse Che Kuksa instance simplifies the development of AGL applications and services. AGL features the usage of automotive applications based on HTML5, JavaScript, and C/C++, which run on top of AGL. While applications realize a distinct use case, services offers functionality to all applications. For more information please refer to the <a href="https://docs.automotivelinux.org">AGL documentation</a>.</p>
<p>The following sections demonstrate the development of AGL applications/services in a model-driven way based on the tool RAML2AGL (cf. Section <a href="https://github.com/eclipse/kuksa.ide/tree/master/che-6#raml2agl">Raml2AGL</a> ) as well as the building and deployment of AGL applications/services to a remote device running AGL (cf. Section <a href="https://github.com/eclipse/kuksa.ide/tree/master/che-6">Building &amp; Deploying</a>).</p>
<h1 id="2-kuksa-in-vehicle-platform">2. Kuksa In-Vehicle platform</h1>
<p><a href="https://www.eclipse.org/kuksa/">Eclipse Kuksa</a> includes an open and secure cloud platform that interconnects a wide range of vehicles to the cloud via open in-car and internet connections and is supported by an integrated open source software development ecosystem. The <a href="https://github.com/eclipse/kuksa.invehicle">in-vehicle repo</a> contains in-vehicle platform code as well as required layers and bindings to build a Kuksa adapted AGL (Automotive Grade Linux) distribution. If not using AGL, any other platform can be chosen that supports docker. For the former, Eclipse Kuksa provides a wrapper project around AGL. From its side, AGL uses Yocto/Bitbake building system to build an automotive domain specific Linux distribution. Therefore, this projects provides a building system that adds Kuksa&rsquo;s specific Bitbake layers on top of the original AGL. The scripts in this project help ease the process of building an AGL image by simple using a few commands. This project includes the yocto recipes found in meta-kuksa project.</p>
<h2 id="2-1-build-agl-image-sdk-rpi3">2.1 Build AGL Image/SDK RPI3</h2>
<p>Please have a look at the repositories <a href="https://github.com/eclipse/kuksa.invehicle/tree/0.2.0/agl-kuksa">readme file</a>.</p>
<h2 id="2-2-roverapp">2.2 RoverApp</h2>
<p><a href="https://app4mc-rover.github.io/rover-docs/content/installation.html#">This tutorial</a> contains how to set up a Rover-specific Raspbian image from scratch and the basic workflow to run the Roverapp applications.</p>
<h1 id="3-eclipse-kuksa-cloud-platform">3. Eclipse Kuksa Cloud Platform</h1>
<p>The Eclipse Kuksa project consists of a cloud backend. This backend provides services that interact with the vehicles and thus enable the owners to manage their vehicles and provide interfaces to third-party services.</p>
<h2 id="3-1-getting-started-with-the-cloud-platform">3.1 Getting started with the cloud platform</h2>
<p>The <a href="https://github.com/eclipse/kuksa.cloud/tree/master">Eclipse Kuksa Cloud Repository</a> contains the source code for some of the services and descriptors to set up an instance of the cloud backend. The two services developed within the Kuksa Cloud repository are an <a href="https://github.com/eclipse/kuksa.cloud/tree/master/kuksa-appstore">app store</a> and a <a href="https://github.com/eclipse/kuksa.cloud/tree/master/utils/hono-influxdb-connector">Hono-InfluxDB-Connector</a> which writes data from Eclipse Hono to an InfluxDB. Please refer to the Readme files in the linked directories for more details on how to use and extend the two services. There is also an example application to showcase the integration with a third-party service. The particular example is part of a use case where the owner gets an e-mail once the car senses an error which it would signal with a <a href="https://github.com/eclipse/kuksa.cloud/tree/master/examples/malfunction-indicator-light">malfunction indication light (MIL)</a>.</p>
<p>In addition, the Kuksa Cloud Repository provides scripts and resources to enable developers and operators to setup their own instance of the Kuksa cloud on a running Kubernetes instance. This is also important because the Kuksa Clouds makes use of a number of Open Source projects like Eclipse Hono, Eclipse hawkBit or Keycloak instead of solving the same challenges with custom solutions. More information on the deployment is located in the <a href="https://github.com/eclipse/kuksa.cloud/tree/master/deployment">deployment</a> folder. The recomended way for the deployment is to use the <a href="https://github.com/eclipse/kuksa.cloud/tree/master/deployment/helm">Helm chart</a>. As mentioned above, the deployment of the Kuksa cloud requires <a href="kubernetes.io">Kubernetes</a> which is either available through many cloud providers or needs to be setup before.</p>
</div>
</div>
</div>
</div>
</div>
<footer id="footer">
<div class="container">
<div class="col-md-4 col-sm-6">
<h4>Legal</h4>
<ul>
<li><a href="https://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
<li><a href="https://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
<li><a href="https://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
<li><a href="https://www.eclipse.org/legal/epl-2.0/">Eclipse Public License</a></li>
<li><a href="https://www.eclipse.org/legal/">Legal Resources </a></li>
<li><a href="https://www.eclipse.org/security/">Eclipse Security </a></li>
</ul>
</div>
<div class="col-md-4 col-sm-6" align="center">
<p><strong>Eclipse Kuksa</strong> has its origins in the <a href="https://itea3.org/project/appstacle.html">APPSTACLE project</a> that is part of the European ITEA3 programme</p>
<hr class="hidden-md hidden-lg hidden-sm"/>&nbsp;<p>
<a href="https://itea3.org/"> <img src="https://www.eclipse.org/kuksa/img/itea3.png" class="img-responsive" width="200" alt="ITEA3"/></a>
<p>Copyright © 2019 <a href="http://eclipse.org">The Eclipse Foundation</a>. <br/>All Rights Reserved.</p>
</div>
<div class="col-md-4 col-sm-6">
<p class="pull-right">
Template by <a href="http://bootstrapious.com/free-templates">Bootstrapious</a>.
<br/>Ported to Hugo by <a href="https://github.com/devcows/hugo-universal-theme">DevCows</a>
</p>
</div>
</div>
</footer>
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-5WLCZXC');</script>
</div>
<script src="//code.jquery.com/jquery-3.1.1.min.js" integrity="sha256-hVVnYaiADRTO2PzUGmuLJr8BLUSjGIZsDYGmIJLv2b8=" crossorigin="anonymous"></script>
<script src="//maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery-cookie/1.4.1/jquery.cookie.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/waypoints/4.0.1/jquery.waypoints.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/Counter-Up/1.0/jquery.counterup.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery-parallax/1.1.3/jquery-parallax.js"></script>
<script src="//maps.googleapis.com/maps/api/js?v=3.exp"></script>
<script src="https://www.eclipse.org/kuksa/js/hpneo.gmaps.js"></script>
<script src="https://www.eclipse.org/kuksa/js/gmaps.init.js"></script>
<script src="https://www.eclipse.org/kuksa/js/front.js"></script>
<script src="https://www.eclipse.org/kuksa/js/owl.carousel.min.js"></script>
</body>
</html>