language/setup/index.html

<!DOCTYPE html>
  
  
  
  
   <html class="no-js"> 

  <head lang="en-us">
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,user-scalable=no,initial-scale=1,maximum-scale=1">
    <meta http-equiv="X-UA-Compatible" content="IE=10" />
    <title>System Setup - Eclipse Mita</title>
    <meta name="generator" content="Hugo 0.54.0" />

    
    <meta name="description" content="The documentation of Eclipse Mita.">
    
    <link rel="canonical" href="../../language/setup/">
    

    <meta property="og:url" content="/language/setup/">
    <meta property="og:title" content="Eclipse Mita">
    <meta property="og:image" content="/images/mita.svg">
    <meta name="apple-mobile-web-app-title" content="Eclipse Mita">
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

    <link rel="shortcut icon" type="image/x-icon" href="../../images/favicon.ico">
    <link rel="icon" type="image/x-icon" href="../../images/favicon.ico">

    <style>
      @font-face {
        font-family: 'Icon';
        src: url('/fonts/icon.eot');
        src: url('/fonts/icon.eot')
               format('embedded-opentype'),
             url('/fonts/icon.woff')
               format('woff'),
             url('/fonts/icon.ttf')
               format('truetype'),
             url('/fonts/icon.svg')
               format('svg');
        font-weight: normal;
        font-style: normal;
      }
    </style>

    <link rel="stylesheet" href="../../stylesheets/application.css">
    <link rel="stylesheet" href="../../stylesheets/temporary.css">
    <link rel="stylesheet" href="../../stylesheets/palettes.css">
    <link rel="stylesheet" href="../../stylesheets/highlight/highlight.css">

    
    
    
    <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Ubuntu:400,700|Ubuntu&#43;Mono">
    <style>
      body, input {
        font-family: 'Ubuntu', Helvetica, Arial, sans-serif;
      }
      pre, code {
        font-family: 'Ubuntu Mono', 'Courier New', 'Courier', monospace;
      }
    </style>

    
    <link rel="stylesheet" href="../../css/custom.css">
    
    <script src="../../javascripts/modernizr.js"></script>

    

  </head>
  <body class="palette-primary-blue-grey palette-accent-light-blue">




<div class="backdrop">
	<div class="backdrop-paper"></div>
</div>

<input class="toggle" type="checkbox" id="toggle-drawer">
<input class="toggle" type="checkbox" id="toggle-search">
<label class="toggle-button overlay" for="toggle-drawer"></label>

<header class="header">
	<nav aria-label="Header">
  <div class="bar default">
    <div class="button button-menu" role="button" aria-label="Menu">
      <label class="toggle-button icon icon-menu" for="toggle-drawer">
        <span></span>
      </label>
    </div>
    <div class="stretch">
      <div class="title">
        System Setup
      </div>
    </div>

    
    <div class="button button-twitter" role="button" aria-label="Twitter">
       <a href="https://twitter.com/eclipse_mita" title="@eclipse_mita on Twitter" target="_blank" class="toggle-button icon icon-twitter"></a>
    </div>
    

    
    <div class="button button-github" role="button" aria-label="GitHub">
      <a href="https://github.com/eclipse/mita" title="@eclipse/mita on GitHub" target="_blank" class="toggle-button icon icon-github"></a>
    </div>
    
    
        
  </div>
  <div class="bar search">
    <div class="button button-close" role="button" aria-label="Close">
      <label class="toggle-button icon icon-back" for="toggle-search"></label>
    </div>
    <div class="stretch">
      <div class="field">
        <input class="query" type="text" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck>
      </div>
    </div>
    <div class="button button-reset" role="button" aria-label="Search">
      <button class="toggle-button icon icon-close" id="reset-search"></button>
    </div>
  </div>
</nav>
</header>

<main class="main">
	<div class="drawer">
		<nav aria-label="Navigation">
  <a href="../../" class="project">
    <div class="banner">
      
        <div class="logo">
          <img src="../../images/mita.svg">
        </div>
      
      <div class="name">
        <strong>Eclipse Mita </strong>
        
      </div>
    </div>
  </a>

  <div class="scrollable">
    <div class="wrapper">
      

      <div class="toc">
        
        <ul>
          




<li>
  
    



<a  title="Download" href="http://github.com/eclipse/mita">
	
	Download
</a>



  
</li>



<li>
  
    



<a  title="Concepts" href="../../concepts/">
	
	Concepts
</a>



  
</li>



<li>
  
    <span class="section">Language</span>
    <ul>
      
        
        



<a  title="Introduction" href="../../language/introduction/">
	
	Introduction
</a>



      
        
        



<a  title="Basics" href="../../language/basics/">
	
	Basics
</a>



      
        
        



<a  title="Packages" href="../../language/packages/">
	
	Packages
</a>



      
        
        



<a class="current" title="System Setup" href="../../language/setup/">
	
	System Setup
</a>


<ul id="scrollspy">
</ul>


      
        
        



<a  title="Types" href="../../language/types/">
	
	Types
</a>



      
        
        



<a  title="Arrays" href="../../language/arrays/">
	
	Arrays
</a>



      
        
        



<a  title="Functions" href="../../language/functions/">
	
	Functions
</a>



      
        
        



<a  title="Foreign Function Interface" href="../../language/foreignfunctioninterface/">
	
	Foreign Function Interface
</a>



      
        
        



<a  title="Events" href="../../language/events/">
	
	Events
</a>



      
        
        



<a  title="Exceptions" href="../../language/exceptions/">
	
	Exceptions
</a>



      
        
        



<a  title="Generated Types and Functions" href="../../language/generatedthings/">
	
	Generated Types and Functions
</a>



      
    </ul>
  
</li>



<li>
  
    <span class="section">Platforms</span>
    <ul>
      
        
        



<a  title="Integrators Guide" href="../../platforms/integratorsguide/">
	
	Integrators Guide
</a>



      
        
        



<a  title="Arduino Uno" href="../../platforms/arduinouno/">
	
	Arduino Uno
</a>



      
        
        



<a  title="CGW" href="../../platforms/cgw/">
	
	CGW
</a>



      
        
        



<a  title="XDK110" href="../../platforms/xdk110/">
	
	XDK110
</a>



      
        
        



<a  title="x86" href="../../platforms/x86/">
	
	x86
</a>



      
    </ul>
  
</li>


        </ul>
        

        
      </div>
    </div>
  </div>
</nav>

	</div>

	<article class="article">
		<div class="wrapper">
            

<p>System resources have properties which we can configure.
For example, an accelerometer has an acceleration range, a filter bandwidth and some power modes which we can change.
If we wanted to use Bluetooth for communication we would have to set up the GATT characteristics, device name and advertising interval.
If we wanted to connect to a WLAN network, we would have to configure the network name and a preshared key.</p>

<h2 id="system-resource-instantiability">System Resource Instantiability</h2>

<p>Some system resources (e.g. an HTTP client) can even be used multiple times, others can exist exactly once.
If you try and set up a system resource multiple times, and the resource can only be setup once, the compiler will tell you.
Let&rsquo;s look at the three different types of <em>instantiability</em> that exist in Mita.</p>

<h3 id="multiple">Multiple</h3>

<p>Software system resources (e.g. application level protocol implementations - think HTTP or MQTT) can exist multiple times,
thus you can <em>instantiate</em> them multiple times using the <code>setup</code> keyword. Let&rsquo;s look at an HTTP client:</p>
<div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="kr">package</span> <span class="nx">main</span><span class="p">;</span>
<span class="kr">import</span> <span class="nx">platforms</span><span class="p">.</span><span class="nx">xdk110</span><span class="p">;</span>

<span class="nx">setup</span> <span class="nx">sensorBackend</span> : <span class="kt">HttpRestClient</span> <span class="p">{</span>
	<span class="p">...</span>
<span class="p">}</span>

<span class="nx">setup</span> <span class="nx">controlService</span> : <span class="kt">HttpRestClient</span> <span class="p">{</span>
	<span class="p">...</span>
<span class="p">}</span></code></pre></div>
<p>The <code>HttpRestClient</code> can exist multiple times.
To identify the instance of the system resource we want to use, we have to name that instance (here, <code>sensorBackend</code> and <code>controlService</code>).
We will see in a moment what would be inside the setup blocks.</p>

<h3 id="once">Once</h3>

<p>Other system resources can only be set up once, but we want to give them a name so that we can refer to them later on.
Connectivity is a prime example:</p>
<div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="kr">package</span> <span class="nx">main</span><span class="p">;</span>
<span class="kr">import</span> <span class="nx">platforms</span><span class="p">.</span><span class="nx">xdk110</span><span class="p">;</span>

<span class="nx">setup</span> <span class="nx">devnet</span> : <span class="kt">WLAN</span> <span class="p">{</span>
	<span class="p">...</span>
<span class="p">}</span>

<span class="nx">setup</span> <span class="nx">sensorBackend</span> : <span class="kt">HttpRestClient</span> <span class="p">{</span>
	<span class="nx">transport</span> <span class="o">=</span> <span class="nx">devnet</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>
<p>Here we configure the WLAN connectivity, and use it for HTTP client. For that to work we had to name the WLAN (<code>devnet</code> in this case).
However, if we were to add a second WLAN setup block (e.g. <code>setup production : WLAN { }</code> the compiler would produce an error, as there can be only one WLAN configuration (there is only one WLAN chip on the device).</p>

<h3 id="none">None</h3>

<p>Uninstantiable system resources are things built into the platform which we can only configure, but we cannot name them.
A typical example would be sensors. They are described by the platform, they can be configured, but renaming them does not make sense.
For example:</p>
<div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="kr">package</span> <span class="nx">main</span><span class="p">;</span>
<span class="kr">import</span> <span class="nx">platforms</span><span class="p">.</span><span class="nx">xdk110</span><span class="p">;</span>

<span class="nx">setup</span> <span class="nx">accelerometer</span> <span class="p">{</span>
	
<span class="p">}</span></code></pre></div>
<h2 id="configuration-items">Configuration Items</h2>

<p>System resources can have properties which change their behavior and generally configure how they work.
In Mita those things are called <em>configuration items</em>.
Configuration items are defined by the platform and are there for you, the developer, to fill in if you need to.
For example, a light sensor needs some time to &ldquo;collect light&rdquo;, i.e. to measure the current light intensity.
In Mita that time becomes configurable through a <em>configuration item</em>:</p>
<div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="kr">package</span> <span class="nx">main</span><span class="p">;</span>
<span class="kr">import</span> <span class="nx">platforms</span><span class="p">.</span><span class="nx">xdk110</span><span class="p">;</span>

<span class="nx">setup</span> <span class="nx">light</span> <span class="p">{</span>
	<span class="nx">integration_time</span> <span class="o">=</span> <span class="p">.</span><span class="nx">MS_12_5</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>
<div class="admonition note">
<p class="admonition-title">Use content assist to explore your options</p>
<p>In every <code>setup</code> block you can always use content assist (<code>Ctrl + Space</code> on Windows and Linux, <code>Cmd + Space</code> on Mac) to explore what configuration items you have available.
Don&rsquo;t worry about using a &ldquo;wrong value&rdquo; either. Configuration items are strongly typed and the compiler is going to tell you if you request a configuration that doesn&rsquo;t make sense.</p>
</div>

<h2 id="signal-instances">Signal Instances</h2>

<p>Mita uses the concept of <a href="../../concepts/">signals and signal instances</a> to model input and output of the device.
Each system resource defines which signals it has available, and what attributes those signals have.
To learn which signals you can use, have a look at the platform reference or use auto-complete within the <code>setup</code> block.</p>
<div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="kr">package</span> <span class="nx">main</span><span class="p">;</span>
<span class="kr">import</span> <span class="nx">platforms</span><span class="p">.</span><span class="nx">xdk110</span><span class="p">;</span>

<span class="nx">setup</span> <span class="nx">phone</span> : <span class="kt">BLE</span> <span class="p">{</span>
	<span class="kd">var</span> <span class="nx">ping</span> <span class="o">=</span> <span class="nx">bool_characteristic</span><span class="p">(</span><span class="nx">UUID</span><span class="o">=</span><span class="mh">0xCAFE</span><span class="p">);</span>
<span class="p">}</span></code></pre></div>
<p>The example above configures the Bluetooth Low Energy (<code>BLE</code>) system resource available on the XDK. This system resource sports - amonst others - a <code>bool_characteristic</code> signal.
We instantiate this signal and thereby create a BLE GATT characteristic with the <em>UUID</em> ending in <code>0xCAFE</code>. So that we can reference this <em>signal instance</em> in our code, we give it the name <code>ping</code>.</p>

<p>In our code we can use the signal instances to read and write from them (which in the example would send a Bluetooth notification):</p>
<div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="nx">every</span> <span class="mi">1</span> <span class="nx">second</span> <span class="p">{</span>
	<span class="nx">phone</span><span class="p">.</span><span class="nx">ping</span><span class="p">.</span><span class="nx">write</span><span class="p">(</span><span class="kc">true</span><span class="p">);</span>
<span class="p">}</span></code></pre></div>

			
<aside class="copyright" role="note">
  <div class="incubation">
    <a href="https://www.eclipse.org/projects/what-is-incubation.php" target="_blank">
      <img src="../../images/incubating.png" />
    </a>
  </div>
  <div class="logo">
    <a href="https://www.eclipse.org" target="_blank">
      <img src="../../images/eclipse_foundation_logo.svg" />
    </a>
  </div>
  <p class="notice">
    
    Documentation built with
    <a href="https://www.gohugo.io" target="_blank">Hugo</a>
    using the
    <a href="http://github.com/digitalcraftsman/hugo-material-docs" target="_blank">Material</a> theme.
  </p>
  <p class="quickLinks">
    <a href="http://www.eclipse.org/legal/privacy.php" target="_blank">
      &gt; Privacy Policy
    </a>
    <a href="http://www.eclipse.org/legal/termsofuse.php" target="_blank">
      &gt; Terms of Use
    </a>
    <a href="http://www.eclipse.org/legal/copyright.php" target="_blank">
      &gt; Copyright Agent
    </a>
    <a href="http://www.eclipse.org/legal" target="_blank">
      &gt; Legal
    </a>
    <a href="https://eclipse.org/security" target="_blank">
      &gt; Report a Vulnerability
    </a>
  </p>
</aside>
		</div>
	</article>

	<div class="results" role="status" aria-live="polite">
		<div class="scrollable">
			<div class="wrapper">
				<div class="meta"></div>
				<div class="list"></div>
			</div>
		</div>
	</div>
</main>

    <script>
    
      var base_url = '';
      var repo_id  = '';
    
    </script>

    <script src="../../javascripts/application.js"></script>
    

    <script>
      /* Add headers to scrollspy */
      var headers   = document.getElementsByTagName("h2");
      var scrollspy = document.getElementById('scrollspy');

      if(scrollspy) {
        if(headers.length > 0) {
          for(var i = 0; i < headers.length; i++) {
            var li = document.createElement("li");
            li.setAttribute("class", "anchor");

            var a  = document.createElement("a");
            a.setAttribute("href", "#" + headers[i].id);
            a.setAttribute("title", headers[i].innerHTML);
            a.innerHTML = headers[i].innerHTML;

            li.appendChild(a)
            scrollspy.appendChild(li);
          }
        } else {
          scrollspy.parentElement.removeChild(scrollspy)
        }


        /* Add permanent link next to the headers */
        var headers = document.querySelectorAll("h1, h2, h3, h4, h5, h6");

        for(var i = 0; i < headers.length; i++) {
            var a = document.createElement("a");
            a.setAttribute("class", "headerlink");
            a.setAttribute("href", "#" + headers[i].id);
            a.setAttribute("title", "Permanent link")
            a.innerHTML = "#";
            headers[i].appendChild(a);
        }
      }
    </script>

    

    <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.8.0/highlight.min.js"></script>
    <script>hljs.initHighlightingOnLoad();</script>
  </body>
</html>