search

TelluIoT / ThingML

The ThingML modelling language
https://github.com/TelluIoT/ThingML
Apache License 2.0
103 stars 32 forks source link
arduino c eclipse-modeling golang internet-of-things java javascript model-driven-development modeling-language state-machine statechart thingml uml xtext

readme

ThingML

The ThingML approach is composed of i) a modeling language, ii) a set of tools and iii) a methodology. The modeling language combines well-proven software modeling constructs for the design and implementation of distributed reactive systems:

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). The methodology documents the development processes and tools used by both the IoT service developers and the platform experts.

ThingML is distributed under the Apache 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 vibrant open-source community. ThingML is now owned by Tellu, but remains open-source.

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

Installing ThingML

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

Versions and Distribution

The current recommended version of ThingML is version 2.X.X. Tagged versions are available on the Github release 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).

ThingML Command Line Compiler

The ThingML command line compiler is distributed as a standalone JAR. It requires Java 8 or newer. The latest version (*.jar) can be found on the 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.

ThingML Eclipse-Based IDE

  1. Install "Eclipse IDE for Java and DSL Developers" from the Eclipse website.
  2. Download the most recent update site (*.zip) from the 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 use HEADS / ThingML sub-menu to compile a ThingML file. Generated code will be put in a thingml-gen folder at the root of the eclipse project. Remember that only ThingML files containing a configuration can be compiled.

Docker-Based Distribution

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 the thingmleditor repository or the thingmleditor docker hub

Sample ThingML programs

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:

Example having known incompatibilities:

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

Compiling ThingML Generated Code

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.

JAVA / Maven

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

Prerequisites:

Using Eclipse:

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

If Maven claims it cannot find a pom.xml file, change the base directory in the Run as -> Maven build... window using the Workspace... button, so that it points to thingml-gen/java/your-configuration.

javascript for web browsers

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

Do not use the default web browser embedded into Eclipse!

Javascript for Node.JS

ThingML creates a standard Node.js package.

Prerequisites:

Using Eclipse:

From this update site: Node.JS - http://www.nodeclipse.org/updates/enide-2015/, install Features included in Enide Studio .Features Set and Nodeclipse Node.js .Features Set 1.0.2.201509250223

Visualize UML Diagrams (PlantUML)

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:

Using Eclipse:

Install PlantUML plugins in Eclipse using this update site: http://hallvard.github.io/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 from http://plantuml.com/eclipse

Posix C

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

Prerequisites:

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

Arduino C

Prerequisites:

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

Go

Prerequisites:

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

Teensy C

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

Prerequisites:

or

Compile ThingML from the sources

You need Git, Maven, and a proper JDK8+

git clone https://github.com/TelluIoT/ThingML.git
cd ThingML
mvn clean install
cd language
mvn clean install

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

cd compilers/registry/target
java -jar compilers.registry-2.0.0-SNAPSHOT-jar-with-dependencies.jar
 --- ThingML help ---
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 configuration for the output
      Default: false
    --help, -h
      Display this message.
      Default: false
    --list-plugins
      Display the list of available plugins
      Default: false
    --options
      additional options for 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++ based in code for Arduino.
 ??     posixmt - Generates C code for Linux or other Posix runtime environments (GCC compiler).
 ??     java    - Generates plain Java code.
 ??     arduino - Generates C/C++ code for Arduino or other AVR microcontrollers (AVR-GCC compiler).
 ??     UML     - Generates UML diagrams in PlantUML
 ??     browser - Generates Javascript code that can run in common Web Browsers.
 ??     nodejsMT        - Generates Multi-Process Javascript code (one nodejs process per instance) for the NodeJS platform.
 ??     nodejs  - Generates Javascript code for the NodeJS platform.
 ??     posix   - Generates C/C++ code for Linux or other Posix runtime environments (GCC compiler).
 ??     debugGUI        - Generates html/js mock-up for other a ThingML external connector

Tool Id must belong to the following list:
 ??     testconfigurationgen    - Generates test configuration for things annnotated with @test "input # output".

🔷 FAQ

🔹 Where can ThingML code run?

Nowhere! Or almost everywhere, from microcontrollers to the cloud!

A ThingML file per 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.

🔹 How to express this or that in ThingML?

A set of tutorials is available here. 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.

🔹 How is ThingML formalized?

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

🔹 All that code is wonderful, but I need some Science... 📚

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

ThingML has also been used together with other approaches:

🔹 How to embed ThingML in my toolchain?

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

Embed the command-line inteface JAR described 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>

🔹 The code generated by ThingML for Java/JS/C/Arduino does not exactly fit my needs

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

🔹 Why can't I generate Python/Lua/Ruby/you-name-it?

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

🔹 How can I programatically process ThingML models?

File myFile = new File("source.thingml");
ThingMLModel myModel = ThingMLCompiler.loadModel(myFile);
//Do something
ThingMLCompiler.saveAsThingML(myModel, "target.thingml");
//or
ThingMLCompiler.saveAsXMI(myModel, "target.xmi");

Protip1: Make sure you have a good understanding of the ThingML metamodel

Protip2: Have a look at the helper 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.

🔷 More

ThingML is released under OSI-compliant Apache 2.0 license