Java ANTLR HTML C Shell Xtend Other
Permalink
Failed to load latest commit information.
Documentrospection 1.0.0-SNAPSHOT Jan 4, 2017
compilers mockups with a different stereotype in UML Feb 17, 2017
language Deleted LFS untracked jars Feb 9, 2017
model Deleted LFS untracked jars Feb 9, 2017
org.emftext.commons.antlr3_4_0 1.0.0-SNAPSHOT Jan 4, 2017
org.thingml.eclipse.feature 1.0.0-SNAPSHOT Jan 4, 2017
org.thingml.eclipse.ui mockups with a different stereotype in UML Feb 17, 2017
org.thingml.eclipse.updatesite 1.0.0-SNAPSHOT Jan 4, 2017
org.thingml.eclipse 1.0.0-SNAPSHOT Jan 4, 2017
org.thingml.editor.eclipse 1.0.0-SNAPSHOT Jan 4, 2017
org.thingml.editor.standalone provide users with stacktraces and invite them to submit issue Jan 20, 2017
org.thingml.editor.standaloneApp 1.0.0-SNAPSHOT Jan 4, 2017
org.thingml.model some updates Feb 2, 2017
org.thingml.parser 1.0.0-SNAPSHOT Jan 4, 2017
org.thingml.samples changed to Apache 2.0 license Jan 4, 2017
testJar A bit closer Feb 7, 2017
testframework added command to run jenkins Feb 6, 2017
.gitattributes *.g files should be seen as ANTLR files, not GAP Feb 14, 2017
.gitignore Ignore test config, quell arduino upload script Apr 28, 2016
AUTHORS changed to Apache 2.0 license Jan 4, 2017
HEADER changed to Apache 2.0 license Jan 4, 2017
Jenkinsfile correct repository name Jan 23, 2017
LICENSE changed to Apache 2.0 license Jan 4, 2017
NOTICE changed to Apache 2.0 license Jan 4, 2017
README.md Update README.md Feb 9, 2017
pom.xml 1.0.0-SNAPSHOT Jan 4, 2017
update_plugins.bat release 0.7.0 Jan 4, 2017
update_plugins.md update Feb 3, 2015
update_plugins.sh update eclipse plugins Jan 22, 2017

README.md

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:

  • 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). 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.

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

❗ ❗ If you are contributing to this repository, please install Git LFS and track all jar files: git lfs track "*.jar"

🔷 Prerequisites ❗

ThingML can compile code for various platforms and languages. Please make sure you follow the required steps

🔹 Java

If you are going to compile Java code from ThingML, please:

  • Make sure you have a proper JDK (a JRE is not sufficient)
  • Install Maven

🔹 Javascript

If you are going to compile JavaScript (Node.JS) code from ThingML, please:

🔹 UML

If you are going to compile UML Diagrams from ThingML, please:

🔹 Arduino

If you are going to compile Arduino code from ThingML, please:

🔹 C

If you are going to compile C code from ThingML, please:

  • Use a C-friendly OS (such as Linux) with a decent build toolchain (make, gcc), potentially in a Virtual Box

🔷 Getting Started

🔹 Installation

The easiest way to get started with ThingML is to use the ThingML plugins in the Eclipse IDE.

  1. Download Eclipse for Java Developers
  2. Install and Launch Eclipse
  3. Install EMFText plugins: Help -> Install New Software... -> Add... and choose EMFText as a name and http://update.emftext.org/release as location, and then OK. Select EMFText and continue with the install procedure ⏳
  4. Install the latest release of the ThingML plugins:
    1. Download the latest update site
    2. In Eclipse Help -> Install New Software... -> Add... -> Archive..., and select the zip you have just downloaded, give a name to this update site and then OK
    3. Select ThingML and continue the install procedure ⏳

Another update site is also available for ThingML at http://thingml.org/dist/update/. This update site contains all the latest features but might be less stable.

You are now ready to use ThingML. ✌

🔹 Compiling ThingML code

Once you have created (or imported) ThingML files in your workspace, simply right click on a ThingML file in order to compile it. A HEADS / ThingML should be present in the menu and you can then select which compiler to use: Java, JavaScript, C, etc.

The ThingML file you want to compile should contain a configuration

The generated code will be located in a thingml-gen folder in your current project

How to compile and run generated Java code

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

  • Right click on pom.xml (in thingml-gen/java/your-configuration)
  • Run as -> Maven build...
  • In Goals type: clean install exec:java

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.

How to compile and run generated JavaScript (Node.JS) code

❗ In 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

  • Right click on package.json (in thingml-gen/nodejs/your-configuration)
  • Run as -> npm install
  • Right click on main.js
  • Run as -> Node Application

How to visualize generated UML (PlantUML) diagrams

❗ Install PlantUML plugins in Eclipse using this update site: http://plantuml.sourceforge.net/updatesitejuno/ (See below for how to install plugins in Eclipse)

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

How to compile and run generated C code

  • Open a terminal at ...thingml-gen/posix/your-configuration
  • make
  • ./your-configuration

How to compile and run generated Arduino code

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

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

🔷 Compile ThingML from the sources

You need Maven and a proper JDK8+

git clone https://github.com/SINTEF-9012/ThingML.git
cd ThingML
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-1.0.0-SNAPSHOT-jar-with-dependencies.jar
--- ThingML help ---
Typical usages:
   java -jar compilers.registry-1.0.0-SNAPSHOT-jar-with-dependencies.jar \
   -c <compiler> \
   -s <source> \
   [-o <output-dir>]\
   [-d]
 Options:
   --compiler, -c
     Compiler ID (Mandatory)
   --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
   --output, -o
     Optional output directory - by default current directory is used
   --source, -s
     A thingml file to compile (should include at least one configuration)

Compiler Id must belong to the following list:
??     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
??     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

To generate a new update site:

cd ThingML
mvn clean install
cd org.thingml.editor.standaloneApp
mvn -f pom_eclipse.xml clean install
rm ../org.thingml.eclipse.ui/lib/*.*
cp target/org.thingml.editor.standaloneApp-*-jar-with-dependencies.jar ../org.thingml.eclipse.ui/lib/thingml.jar
cd ../org.thingml.eclipse.updatesite
mvn -f pom_eclipse.xml clean install

The update site will be located in org.thingml.eclipse.updatesite/target/repository

🔷 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, ESP8266, 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 EMFText grammar.

As EMFText is not supported anymore, we are currently migrating the syntax (and an updated metamodel) to XText.

🔹 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):

  • Model-Based Software Engineering to Tame the IoT Jungle
    Brice Morin, Nicolas Harrand and Franck Fleurey
    To appear in IEEE 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
    In MODELS’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.
    In MODELS’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.
    In INDIN’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.
    In CBSE’16: 19th International ACM Sigsoft Symposium on Component-Based Software Engineering. Venice, Italy, April 5-8, 2016

🔹 How to embed ThingML in my toolchain?

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>1.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

🔷 More

Visit thingml.org to find out more about ThingML !

ThingML is released under OSI-compliant Apache 2.0 license