Repository files navigation

The ThingML approach is composed ofi) amodeling language,ii) a set oftools andiii) amethodology. The modeling language combines well-proven software modeling constructs for the design and implementation of distributed reactive systems:

• statecharts and components (aligned with the UML) communicating through asynchronous message passing
• an imperative platform-independent action language
• specific constructs targeted at IoT applications.

The ThingML language is supported by a set of tools, which include editors, transformations (e.g. export to UML) and an advanced multi-platform code generation framework, which support multiple target programming languages (C, Java, Javascript). Themethodology documents the development processes and tools used by both the IoT service developers and the platform experts.

ThingML is distributed under theApache 2.0 licence, and has been developed by @ffleurey and @brice-morin of the Networked Systems and Services department of SINTEF in Oslo, Norway, together with a vibrantopen-source community. ThingML is now owned byTellu, but remains open-source.

Issues, bug reports and feature requests should be submitted to theissue tracker on GitHub

This section should contain up to date information about getting the latest version of ThingML and getting started with it.

The currentrecommended version of ThingML is version 2.X.X. Tagged versions are available on theGithub release page:

• A standalone JAR which can be used from the command line: look for the most recent*.jar file on the releases page
• An eclipse update site to install the ThingML IDE in eclipse: look for the most revent*.zip on the releases page

Version 1.X.X is not maintained and should not be used (maintenance was stopped in Q3 2017). Version 2.X.X introduces a complete rewrite of the parser and editors based on XText. A few syntactical changes make the ThingML programs written for version 1 not compatible with version 2. There are also a few constructs which were evaluated in version 1 and were not re-implemented in version 2 (e.g. groups, streams, etc).

The ThingML command line compiler is distributed as a standalone JAR. Itrequires Java 8 or newer. The latest version (*.jar) can be found onthe releases pages

The command line tool contains all the code generators and plugins which are part of this repository.

Usage:java -jar ThingML2CLI.jar will provide usage information and a list of options.

1. Install "Eclipse IDE for Java and DSL Developers" from theEclipse website.
2. Download the most recent update site (*.zip) fromthe releases pages.
3. Launch Eclipse
4. Install the ThingML plugins from the*.zip file:Help -> Install New Software... -> Add... -> Archive...

Usage: Once ThingML plugins are installed,*.thingml files will open with the ThingML editors. Right-click on*.thingml files and useHEADS / ThingML sub-menu to compile a ThingML file. Generated code will be put in athingml-gen folder at the root of the eclipse project. Remember that only ThingML files containing aconfiguration can be compiled.

Warning: Currently the image on Dockerub is not automatically updated. You should build the image from the Dockerfile to get an up-to-date version of ThingML.

If you have docker, you can use the build container with Eclipse and ThingML at thethingmleditor repository or thethingmleditor docker hub

The goal of this section is to give a list of example which should work out of the box

Note: over the years and versions, we have collected a lot of different samples and projects made with ThingML. However most of them are not maintained and updated to work with the latest version of ThingML. This might be confusing if you are getting started.

Examples which should be working out of the box:

• Basic Arduino examples:https://github.com/ffleurey/ThingMLArduinoDemo. The "1.Basics" folder contains a set of simple ThingML/Arduino programs dealing with digital IOs.

• Multi-platform Breakout game (Arduino, Posix C, Java and Javascript):https://github.com/ffleurey/ThingML-PongTutorial. This example demonstrate how to create platform independent components with ThingML.

• Arduino <-> Java communication (Serial):https://github.com/ffleurey/ThingML-PressureLogger. This program shows has to create 2 ThingML programs communicating over a serial port. One program is running on an Arduino and collects sensor measurement. The other is a running as a Java program collecting the measurement from the Arduino over the USB/Serial connection and displaying curves. This example is quite minimalistic but should be easy to customize for your own sensor/needs. It shows various features of ThingML like the Serial communication plugin and the possibility of adding Maven dependencies to your ThingML programs.

• Raspberry Pi GPIOs:https://github.com/ffleurey/ThingML-RPI-BlinkA couple of very simple examples showing how to blink an LED on the Raspberry Pi using either C or NodeJS.

Example having known incompatibilities:

Note: Some old samples may be easy to fix but other may use features which have been removed from ThingML.

• Example from theorg.thingml.samples in this repository. This folder contains many samples which were made with various versions of ThingML. It is good to explore to see different things that can be done with ThingML but it is not the place to get working samples when getting started.

• Tutorials from the HEADS project:https://github.com/HEADS-project/training/tree/master/1.ThingML_Basics. This tutorial is based on ThingML v1.0 which is no longer maintained.

The ThingML compiler generate platform specific source code in C, Java, Javascript or Go. This section give short guidelines on how the generated code should be complied and executed.

When compiling to Java, ThingML creates a complete Maven project which is ready to build withmvn clean install and execute withmvn exec:java.

Prerequisites:

• Make sure you have a properJDK (a JRE is not sufficient)
• InstallMaven

Using Eclipse:

Configure Eclipse so that it uses the JDK:Window -> Preferences -> Java -> Installed JREs (make sure it points to a JDK)

• Right click onpom.xml (inthingml-gen/java/your-configuration)
• Run as -> Maven build...
• InGoals type:clean install exec:java

If Maven claims it cannot find apom.xml file, change the base directory in theRun as -> Maven build... window using theWorkspace... button, so that it points tothingml-gen/java/your-configuration.

Nothing special. Open the generatedindex.html file in your System Browser (ideally Chrome or Firefox)

Do not use the default web browser embedded into Eclipse!

ThingML creates a standard Node.js package.

Prerequisites:

• NodeJS: InstallNode.JS

Using Eclipse:

From this update site:Node.JS - http://www.nodeclipse.org/updates/enide-2015/, installFeatures included in Enide Studio .Features Set andNodeclipse Node.js .Features Set1.0.2.201509250223

• Right click onpackage.json (inthingml-gen/nodejs/your-configuration)
• Run as -> npm install
• Right click onmain.js
• Run as -> Node Application

The files generated by the UML generator are text files which uses the PlantUML format. PlantUML will perform the layout and export the diagrams as images.

Prerequisites:

• InstallGraphviz
• InstallPlantUML (not needed if using the Eclipse plugin)

Using Eclipse:

Install PlantUML plugins in Eclipse using this update site:http://hallvard.github.io/plantuml/

• Window -> Show View -> Other... -> PlantUML

Make sure you have Graphviz installed. It is required by the Eclipse plugin. If you have issues getting PlantUML to work, follow the instructions fromhttp://plantuml.com/eclipse

The generated code is a complete C project which include a Makefile.

• Open a terminal in the filder containing the generated code
• Compile withmake
• Run with./your-configuration

Prerequisites:

• Use a C-friendly OS (such as Linux)
• Installgcc andmake + the libraries you are using.

Note: Virtual box is an option. Ubuntu on Windows 10 works fine as long as there are no graphics/hardware drivers involved.

• Open the generated file in the Arduino IDE
• Compile
• Upload to your board

Prerequisites:

• InstallArduino IDE
• Install any Arduino libraries which you are using from your ThingML program

For more information about how to use the Arduino IDE and Arduino boards, have a look atthe Arduino documentation.

• Open a terminal atthingml-gen/go/your-configuration
• To run the program directly:go run *.go
• To compile to an executable file:go build *.go

Prerequisites:

• Install the appropriateGo distribution
• Install theGo state-machine library used by ThingMLgo get github.com/SINTEF-9012/gosm

For more information about Go package structures, have a look at theGo documentation

Teensy compiler has not be tested for some time. Expect some possible issues when trying it.

Prerequisites:

• InstallTeensyduino IDE

or

• Installcross compiled arm toochain
• Installteensy command line loader

You need Git, Maven, and a proper JDK8+

git clone https://github.com/TelluIoT/ThingML.gitcd ThingMLmvn clean installcd languagemvn clean install

The command-line interface JAR (containing all you need to compile ThingML files) can be found here:

cd compilers/registry/targetjava -jar compilers.registry-2.0.0-SNAPSHOT-jar-with-dependencies.jar --- ThingMLhelp ---Typical usages:    java -jar your-jar.jar -t<tool> -s<source> [-o<output-dir>] [--options<option>][-d]Usage:<main class> [options]  Options:    --compiler, -c      Compiler ID (Mandatory unless --tool (-t) is used)    --create-dir, -d      Create a new directory named after the configurationfor the output      Default:false    --help, -h      Display this message.      Default:false    --list-plugins      Display the list of available plugins      Default:false    --options      additional optionsfor ThingML tools.    --output, -o      Optional output directory - by default current directory is used    --source, -s      A thingml file to compile (should include at least one configuration)    --tool, -t      Tool ID (Mandatory unless --compiler (-c) is used)Compiler Id must belong to the following list:??     sintefboard     - Generates C++ basedin codefor Arduino.??     posixmt - Generates C codefor Linux or other Posix runtime environments (GCC compiler).??     java    - Generates plain Java code.??     arduino - Generates C/C++ codefor Arduino or other AVR microcontrollers (AVR-GCC compiler).??     UML     - Generates UML diagramsin PlantUML??     browser - Generates Javascript code that can runin common Web Browsers.??     nodejsMT        - Generates Multi-Process Javascript code (one nodejs process per instance)for the NodeJS platform.??     nodejs  - Generates Javascript codefor the NodeJS platform.??     posix   - Generates C/C++ codefor Linux or other Posix runtime environments (GCC compiler).??     debugGUI        - Generates html/js mock-upfor other a ThingML external connectorTool Id must belong to the following list:??     testconfigurationgen    - Generatestest configurationfor things annnotated with @test"input # output".

Nowhere! Or almosteverywhere, from microcontrollers to the cloud!

A ThingML fileper se is a design-time specification of the structure (components) and behavior (state machines) of a reactive system. It cannot be directly executed.

A ThingML file can however be compiled (or transformed) to Java/JavaScript/C/Arduino source code, which can in turn be compiled and executed on a platform. Code generated from ThingML has been successfully executed on a large number of platforms: PC Windows/Linux, Raspberry Pi 1, 2 and 3, Intel Edison, Arduino Uno/Mega/Yun/Mini, ESP8266/ESP32, Trinket, Teensy, and probably others.

A set of tutorials is availablehere. The tutorials describe the most common features of ThingML. In addition,an extensive set of tests describes pretty much all the concepts available. Have a look there is you wonder how to express something. Should this information be insufficient, have a look below.

The ThingML language is formalized into an EMF-based metamodel. The textual syntax is formalized as anXText grammar.

ThingML is backed by a set of scientific publications (PDFs can easily be found one.g. Google Scholar):

• Model-Based Software Engineering to Tame the IoT Jungle
  Brice Morin, Nicolas Harrand and Franck Fleurey
  InIEEE Software, Special Issue on Internet of Things, 2017.
• ThingML, A Language and Code Generation Framework for Heterogeneous Targets
  N. Harrand, F. Fleurey, B. Morin and K.E. Husa
  InMODELS’16: ACM/IEEE 19th International Conference on Model Driven Engineering Languages and Systems. Practice and Innovation track. St Malo, France, October 2-7, 2016
• MDE to Manage Communications with and between Resource-Constrained Systems
  F. Fleurey, B. Morin, A. Solberg and O. Barais.
  InMODELS’11: ACM/IEEE 14th International Conference on Model Driven Engineering Languages and Systems. Wellington, New Zealand, October 2011.

ThingML has also been used together with other approaches:

• Agile Development of Home Automation System with ThingML
  A. Vasilevskiy, B. Morin, Ø. Haugen and P. Evensen.
  InINDIN’16: 14th IEEE International Conference on Industrial Informatics. Poitiers, France, July 18-21, 2016
• A Generative Middleware for Heterogeneous and Distributed Services
  B. Morin, F. Fleurey, K.E. Husa, and O. Barais.
  InCBSE’16: 19th International ACM Sigsoft Symposium on Component-Based Software Engineering. Venice, Italy, April 5-8, 2016

This currently does not work. Pending a solution to Issue #241

Embed the command-line inteface JARdescribed previously in this readme in your classpath.

You can also include ThingML as a Maven dependency in your project:

<dependency>     <groupId>org.thingml</groupId>     <artifactId>compilers.registry</artifactId>     <version>2.0.0-SNAPSHOT</version></dependency>...<repository>    <id>thingml-snapshot</id>    <name>thingml-snapshot</name>    <url>http://maven.thingml.org/thingml-snapshot/</url></repository><repository>    <id>thingml-release</id>    <name>thingml-release</name>    <url>http://maven.thingml.org/thingml-release/</url></repository>

Rather than being monolithic blobs, compilers are implemented in a modular way around a set of extension points defined in theThingML Code Generation Framework.

Well, it is up to you to implement a compiler for whatever language that is not supported by default. What are you waiting for?

FilemyFile =newFile("source.thingml");ThingMLModelmyModel =ThingMLCompiler.loadModel(myFile);//Do somethingThingMLCompiler.saveAsThingML(myModel,"target.thingml");//orThingMLCompiler.saveAsXMI(myModel,"target.xmi");

Protip1: Make sure you have a good understanding of theThingML metamodel

Protip2: Have a look at thehelper functions which simplify some typical treatments

Models saved this way will contain all the imports that the original file refered to in one big file

This feature might currently be broken as we migrated to XText.