Summary

scxmlrun is a stand-alone SCXML processor written in C++ with the following features:

• it is built on top of QtSCXML
• it can be used as a command-line program that simply reads from and writes to local files.
• input/output events can also be received/transmitted over the network via the MQTT protocol.
• several JavaScript functions, including SCXML.raise and SCXML.send for raising/sending events in the JSON format, are introduced for interfacing with the underlying SCXML engine.

Example: echo

The following statechart, which we here call "echo.scxml", receives a single echo event, prints out its data parameter onto the console, and then terminates.

<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" initial="q1">  
  <state id="q1">  
    <transition target="q2" event="echo"><script>console.log (_event.data)</script></transition>  
  </state>  
  <final id="q2"/>  
</scxml>

Reading event(s) from a local file

$ echo '{"event":{"name":"echo","data":"hello"}}' | scxmlrun echo.scxml  
hello

Reading event(s) via MQTT

$ scxmlrun echo.scxml --sub echo &  
$ mosquitto_pub -t echo -m '{"event":{"name":"echo","data":"world"}}'  
world

To see how SCXML processes interact with each other via MQTT, take a look at the ping_pong example.

To browse examples, check out this list.
For the usage of scxmlrun, see the man page which will be accessible through man scxmlrun after installation.

Installation on Docker

• run make docker-build to build a new docker image for scxmlrun
• run make docker-run to spawn a container process and enter into it
• (in the container, try make -C /root/tests test)

Installation on Debian/Ubuntu

Prerequisites

• Qt5 libraries including: libQt5Core, libQt5Qml, and libQt5Network

  run: apt-get install qt5-default qtbase5-dev qtbase5-private-dev
  run: apt-get install qtdeclarative5-dev qtdeclarative5-private-dev

  Note: as of Sep 2018, the packages for Ubuntu are based on Qt v5.9.5.

• QtSCXML
  download the corresponding version of the QtSCXML source package
  run: wget https://github.com/qt/qtscxml/archive/v5.9.5.tar.gz

  expand the archive, then build and install QtSCXML
  run: cd qtscxml-5.9.5/src/scxml; qmake && make && make install

• Mosquitto: MQTT broker and development library
  run: apt-get install mosquitto mosquitto-clients libmosquitto-dev

• JSON for C++: JSON parser/serializer
  run: apt-get install nlohmann-json-dev

Build

• run: make && make install in the top directory.

Testing

Once installation is done, try the following.

• run: make -C ./tests test

• run: make -C ./tests test-mqtt

  Note: you may need to install shelltest (by running apt-get install shelltestrunner).

Installation on macOS/Darwin

Refer to this note.

Remarks

replacing the underlying SCXML engine

Although QtSCXML is assumed as the default SCXML engine of scxmlrun, it is not difficult to switch to another one.

For instance, uSCXML can be used instead of QtSCXML.
To try this option, see this note.