blob: 092b9911041adf307691d2e8bcfd1391ee3af4ea [file] [log] [blame]
<!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>Concepts - Eclipse Mita</title>
<meta name="generator" content="Hugo 0.42.1" />
<meta name="description" content="The documentation of Eclipse Mita.">
<link rel="canonical" href="../concepts/">
<meta property="og:url" content="/concepts/">
<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('/mita/fonts/icon.woff')
format('woff'),
url('/mita/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">
Concepts
</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 class="current" title="Concepts" href="../concepts/">
Concepts
</a>
<ul id="scrollspy">
</ul>
</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 title="System Setup" href="../language/setup/">
System Setup
</a>
<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>
</ul>
</li>
<li>
<span class="section">Platforms</span>
<ul>
<a title="XDK110" href="../platforms/xdk110/">
XDK110
</a>
</ul>
</li>
</ul>
</div>
</div>
</div>
</nav>
</div>
<article class="article">
<div class="wrapper">
<h1>Concepts </h1>
<h2 id="platform">Platform</h2>
<div class="admonition note">
<p class="admonition-title">TLDR; A platform is the thing you are writing programs for.</p>
<p>Platforms describe the thing that you are writing software for; this thing is literally the piece of hardware and software platform running on it.
You do not have create that platform.
Platforms consist of something you can configure (<em>configuration items</em>),
something you can read from at runtime (<em>modalities</em>),
something you can send and receive data through (<em>signals</em>)
and something you can react to (<em>events</em>).</p>
</div>
<p>Mita compiles to C code. There are a lot of specifics which we need to know so that we can generate code which runs on your embedded device.
The compiler needs to know how to start up the device, how to work with time, what components are available, what events they have, how to use and configure them.</p>
<p>Mita encapsulates all this information in what we call a <em>platform</em>. Platforms are provided by third parties (e.g. the vendor who built an embedded IoT development kit), not you the developer.
As part of that platform we get a <em>platform description</em> and a bunch of <em>code generators</em> capable of producing different aspects of the C code we generate.</p>
<p>In this section we will not go in detail on the generators, but talk about the <em>platform description</em>. The terminology introduced here matters to you as user of Mita.
We use it when talking about Mita programs, and subsequently throughout this documentation.</p>
<h3 id="system-resource">System Resource</h3>
<p>An IoT platform consists of many different components.
It will have some form of connectivity (think WiFi, LoRa or Bluetooth),
a bunch of sensors such as an accelerometer or temperature sensor,
and maybe some low-level input/output like <a href="https://en.wikipedia.org/wiki/GPIO">general-purpose IO</a>, <a href="https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus">SPI</a> or <a href="https://en.wikipedia.org/wiki/I2C">I2C</a>.</p>
<p>In Mita we call those components system resources, as they are finite resources available to you as developer.
Some system resources can be instantiated multiple times (see the <a href="../language/setup/">setup section</a>), others only exist once.
However, all system resources share the same features. They can be configured using <em>configuration-items</em>, can provide data at runtime using <em>modalities</em>, can offer means to communicate with the outside world using <em>signals</em> and can provide <em>events</em> for you to react to.</p>
<h3 id="configuration-items">Configuration Items</h3>
<p>Configuration items are the things of a system resource that can be configured.
For example, an acceleration sensor might have a range in which it is capable of operating. This range can be changed.
Or a light sensor might take some time to measure how much light is available - the more time spent measuring the better the measurement, but the longer it takes. This measurement time can be configured.
Configuration items all have a data type and are prescribed by the platform definition.</p>
<p>For example, the Bosch Cross Domain Development Kit (<a href="../platforms/xdk110/">XDK110 platform</a>) supports a light sensor where one can configure the measurement time (they call it <em>integration time</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="nx">MS_200</span><span class="p">;</span>
<span class="p">}</span></code></pre></div>
<h3 id="modalities">Modalities</h3>
<p>Modalities are things that can change at runtime, for example sensor values or the signal strength of a radio. Modalities are prescribed by the platform definition. You as developer do not have to set them up but they are simply available to you.
There is a read method defined for them which allows you to read the modality at any time. For example, take the light sensor of the (<a href="../platforms/xdk110/">XDK110 platform</a>):</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">every</span> <span class="mi">100</span> <span class="nx">milliseconds</span> <span class="p">{</span>
<span class="kd">let</span> <span class="nx">lightLevel</span> <span class="o">=</span> <span class="nx">light</span><span class="p">.</span><span class="nx">intensity</span><span class="p">.</span><span class="nx">read</span><span class="p">();</span>
<span class="p">}</span></code></pre></div>
<p>Modalities have special behavior when it comes to reading several of them at once. For example, a three-axis sensor will return values for all three axis in the same sample (think of a three-axis accelerometer). Thus when reading the x, y and z modalities one after the other, as developers we would expect them to come from the same sample:</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">every</span> <span class="mi">100</span> <span class="nx">milliseconds</span> <span class="p">{</span>
<span class="kd">let</span> <span class="nx">x</span> <span class="o">=</span> <span class="nx">accelerometer</span><span class="p">.</span><span class="nx">x_axis</span><span class="p">.</span><span class="nx">read</span><span class="p">();</span>
<span class="kd">let</span> <span class="nx">y</span> <span class="o">=</span> <span class="nx">accelerometer</span><span class="p">.</span><span class="nx">y_axis</span><span class="p">.</span><span class="nx">read</span><span class="p">();</span>
<span class="kd">let</span> <span class="nx">z</span> <span class="o">=</span> <span class="nx">accelerometer</span><span class="p">.</span><span class="nx">z_axis</span><span class="p">.</span><span class="nx">read</span><span class="p">();</span>
<span class="c1">// x, y, z come from the same sample
</span><span class="c1"></span><span class="p">}</span></code></pre></div>
<p>The code generator that ships with the system resource (in this case the code generator provided by the <a href="../platforms/xdk110/">XDK110 platform</a>) can choose to group modality access, so that the data read from them is coherent.</p>
<h3 id="signals">Signals</h3>
<p>Signals provide means to exchange data with the outside world.
It depends on the system resource that defines the signal what is represented by that signal.
To understand what they are, let&rsquo;s look at a few examples of <em>signal instances</em> first:</p>
<ul>
<li>Bluetooth Low Energy has GATT characteristics through which data is exchanged. In Mita, a GATT characteristic is a signal instance.</li>
<li>REST-style APIs talk about resources on which one perform actions (e.g. read or write). In Mita such a resource is a signal instance.</li>
<li>MQTT publishes messages to specific topics. In Mita a particular MQTT topic is a signal instance that one can publish and subscribe to.</li>
<li>In I2C buses communication is centered around registers which can be read or written to. In Mita an I2C register is a signal instance.</li>
<li>General purpose IO enables users to configure the hardware pins to specific behavior. In Mita a particular GPIO pin is a signal instance.</li>
</ul>
<p>As developers we configure those signal instances within the setup block of a system resource. 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">backend</span> : <span class="kt">HttpRestClient</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">temperature</span> <span class="o">=</span> <span class="nx">resource</span><span class="p">(</span><span class="nx">endpoint</span><span class="o">=</span><span class="s2">&#34;/temperature&#34;</span><span class="p">,</span> <span class="nx">writeMethod</span><span class="o">=</span><span class="nx">PUT</span><span class="p">);</span>
<span class="p">}</span></code></pre></div>
<p>What is a signal then? A signal is the &ldquo;prototype&rdquo; of a signal instance.
It&rsquo;s the thing provided by the platform specification that prescribes that the <code>HttpRestClient</code> has a <code>resource</code>.</p>
<h2 id="event-loop">Event Loop</h2>
<div class="admonition note">
<p class="admonition-title">TLDR; The event loop executes all code in your program.</p>
<p>All events that your program handles, thus all code that your program consists off, is executed sequentally by the event loop.
This eases code generation and prevents concurrency issues. It also means there is no concurrency at all, thus you get no timing
guarantees and long running operations can block all your code.</p>
</div>
<p>Mita is an event based language, because this programming style maps well to how IoT devices work. Most of the time an IoT device is sleeping to conserve energy.
Every now and then it will wake up, either based on time or some external event, do some measurement, computation and communication, and go back to sleep.
Mita lets you write programs that match this pattern well by reacting to events.</p>
<p><img src="eventLoop.png" alt="Event Loop" /></p>
<p>All events that happen on the system are placed in the <em>event loop</em> and handled sequentially.
This strategy has two main advantages.
Firstly, all code runs in a well defined context, namely the event loop task, as compared to some executing in an interrupt service routine context, some in a timer context and some in a task context. This makes it easier to generate predictable code.
Secondly, we do not have to worry about concurrency (yet). All code runs sequentually, there simply is no concurrency we would have to worry about.</p>
<p>However, it also suffers from two major drawbacks: no timing guarantees and no concurrency.
As developers we do not get guarantees how long it will take between an event happening and our code reacting to it.
If, for example, a previous event handler is &ldquo;running late&rdquo;, we might react to the event far too late.
Also, all our code running sequentally is a blessing (see above) and a curse. It means that while a long-running operation is on-going our whole program has to wait for that operation to complete.
For example, making an HTTP request over a slow network can take a long time, all the while our device will be dead waiting for that event to complete.</p>
<p>Future versions of Mita will address these issues and allow for some forms of concurrency.</p>
<h2 id="element-size-inference">Element Size Inference</h2>
<div class="admonition note">
<p class="admonition-title">TLDR; Element Size Inference is the way we manage memory.</p>
<p>Mita allocates all memory on the stack, there is no <code>malloc</code> or <code>free</code>. To do this we need to know at compile time how much memory
we need for things. Developers (most of the time) do not have to tell us how much memory is required, we infer it using <em>element size inference</em>.</p>
</div>
<p>Mita allocates all memory on the stack, there is no <code>malloc</code> or <code>free</code>.
This makes the memory use of our programs more predictable and easier to debug (free&rsquo;ing some memory you&rsquo;re still using is a really bad idea).
It also means that, at compile time, we have to know how much memory we need. In C you, the developer, have to tell the compiler. In Mita we try to infer
that from your code. This way you do not have tell us how much space your string needs, or how big that array literal is. For example:</p>
<div class="highlight"><pre class="chroma"><code class="language-TypeScript" data-lang="TypeScript"><span class="nx">fn</span> <span class="nx">main() {</span>
<span class="kd">var</span> <span class="nx">message</span> <span class="o">=</span> <span class="s2">&#34;{ \&#34;sensor\&#34;: \&#34;&#34;</span><span class="p">;</span>
<span class="k">if</span><span class="p">(</span><span class="nx">isAccelerometerActive</span><span class="p">())</span> <span class="p">{</span>
<span class="nx">message</span> <span class="o">+=</span> <span class="s2">&#34;accel&#34;</span><span class="p">;</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="nx">message</span> <span class="o">+=</span> <span class="s2">&#34;gyro&#34;</span><span class="p">;</span>
<span class="p">}</span>
<span class="nx">message</span> <span class="o">+=</span> <span class="sb">`&#34;, &#34;value&#34;: </span><span class="si">${</span><span class="nx">getSensorValue</span><span class="p">()</span><span class="si">}</span><span class="sb"> }`</span><span class="p">;</span>
<span class="nx">println</span><span class="p">(</span><span class="nx">message</span><span class="p">);</span>
<span class="p">}</span></code></pre></div>
<p>Notice how we never had to say how big message is or will become. Towards the end we even append some interpolated string and the compiler is still able to infer the worst-case size of the string.</p>
<p>We also use this feature to do many checks at compile time. For example, if we can infer the size of your array and the position you&rsquo;re trying access at compile time,
we can tell you if that access will work out or not; before you run your code.</p>
<aside class="copyright" role="note">
&copy; 2018 The Eclipse Mita Project &ndash;
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.
</aside>
<footer class="footer">
<nav class="pagination" aria-label="Footer">
<div class="previous">
<a href="../download/" title="Download">
<span class="direction">
Previous
</span>
<div class="page">
<div class="button button-previous" role="button" aria-label="Previous">
<i class="icon icon-back"></i>
</div>
<div class="stretch">
<div class="title">
Download
</div>
</div>
</div>
</a>
</div>
<div class="next">
</div>
</nav>
</footer>
</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>