Home

1. Software Release information

Release date: 2015-06-15
Release version: v1.0
Version requirements:

1. GSS synthesis engine: D compiler on a POSIX OS
2. GUI: Windows 7+ 64 bit, Eclipse IDE Juno, Yakindu SCT v2.0.1
3. Interface to DPCM: PHP v5.3
4. Features of the released components

Features of the GSS synthesis engine:

• assemble the library components necessary to support the application top-level behaviour and requirements;
• set up the configurable components and generate the application source files and projects;
• compile the application projects and generate the binaries necessary to program the target nodes, with different configurations (e.g., different node IDs).

Features of the interface to the DPCM repository:

• connect to and navigate the DPCM infrastructure;
• collect the node application specifications and configurations from the DPCM project repository;
• retrieve and save the GSS component library;
• save in the repository the descriptions for the application components relevant for run-time CMT monitoring and configuration;
• save in the repository the code to program and configure all the nodes of the project.

Features of the GUI:

• open the application specifications created from the data in the project repository;
• allow the definition of top-level application behaviour using state charts;
• allow the definition of the interfaces and the requirements of the top-level application;
• interactive simulation and debug of the top-level application behaviour;
• control the operation of the GSS and the interface to the DPCM repository, e.g., to start application synthesis and sync the library and the synthesis results with the repository;
• retrieve synthesis results and graphically present most salient characteristics.

2. Developer guide

2.1 GSS

2.1.1 Source tree

The component files are under the "gss" directory in the development tool repository:

• the "bin" directory collects the binaries results from the compilation;
• the "obj" folder collects the objects created during the compilation;
• the "src" directory holds all source files;
• the "tests" folder includes all the test cases for the tool.

The tool is written entirely in D language, which allows a productivity close to script writing while maintaining native execution speed and strong type checking.

2.1.2 Execution start

Program execution starts with the "main()" function in "main.d" in the "src" directory.

First, the command line options are processed followed by some sanity checks. Any failed check issues an explanatory error message and aborts program execution.

2.1.3 Load of the library of components

The execution proceeds by loading all components from the library in the constructor of the class ComponentLibrary, which can be found in the source file "gss/src/componentlibrary.d". This iterates over all files in the library directory with the specified extension and creates a library component for each of them - an instance of the class "LibraryComponent".

2.1.4 Load of a library component

After initialization, the constructor of the "LibraryComponent" class calls the member function "component_read()" which starts the actual parsing of the component format and performs a series of syntax and consistency checks while creating and filling the data structure of the component.

After the XML file of the component is read, it is checked for syntax errors and parsed into a document structure in memory. Then the elements of the document are recursively processed, each by a specific function with a similar structure.

Several checks are performed while processing the XML elements. First, any unrecognized element is signaled as error and aborts program execution. Another check verifies that there are no multiple element instances where the component specification accepts only one. This is done using the function "check_unique()" and the data in the "Counts" structure. Furthermore, file-wide associative arrays keep track of the properties declared by the component specification to detect and report illegal duplicates.

The component data structure is stored in a set of nested structures which follow the structure of the XML component file.

At the top level, there is a structure for component "Properties", "Behavior" and "Views", whose internal structures follow closely the structure of the specification of the XML component.

2.1.5 Load of the specification components

The read of the application specification components is started from the "main()" function right after the library components were loaded. It follows the same processing path as the load of the library components, except for the type of the component which is set to "spec".

2.1.6 Application synthesis

The library and specification components are passed next to the synthesis solver in the "main()" function. First, the library and specification components are stored in the solver data structure, then the solver is started.

The data structure is rather complex. It is divided in two large categories: library elements and (partial) solution.

Each element in the solver library has a pointer to the corresponding library component, a unique ID and a list of its instances in the solution. Then it lists its behavioral resources and interfaces in a way that is both efficient to search during the application synthesis, and is also fast to track back to the corresponding property on the original library component.

The solution data structure holds some project-related data retrieved from the application specification component, including the list of node IDs for which to generate the code for programming and configuration.

These are followed by the detailed description of the properties exercised in the current state of the solution. For instance, the structure describing a behavior resource require includes a pointer to the instance of the library component that originated it, a pointer to the require data in the original library component, and wiring information regarding the provide that satisfied it and under which name (in case the match was done using one of its aliases).

The properties are created each time an element is instantiated in the solution and removed when the library element instance is removed from the solution. The properties populate two lists: one with open properties, that can be matched, and one with wired properties, which have already been matched. For fast search, the lists are organized a bi-dimensional associative arrays indexed by property (main) name and the instance ID.

Each instance of a library element in the solution receives a unique ID and a pointer towards the library element that it instantiates. Moreover, there are two lists of instances: one indexed by instance ID for fast search and one LIFO which helps to keep track of the combinations explored during solution search.

The first step of the solver is to create the problems to solve. This amounts to introduce the application specification elements in the solution as sticky elements in function "problem_create()". While creating the problem specification, the function also checks that the specification is compatible with the library of components (e.g., there are no conflicts between the specification elements).

The solver attempts to satisfy all the requirements of any type of the library elements that are instantiated in the solution by recursively calling the "recursive_solver()" function until there are no more unsatisfied requirements.

The solver performs an exhaustive search for possible solutions. However, the complexity and the effort is reduced by conditions that help cutting early unproductive combinations (e.g., by avoiding to instantiate library components with requirements that cannot be satisfied by the existing library).

2.1.7 Solution save and code generation

For each found solution, gss generates:

• a connectivity matrix of the components and their connectivity;
• the configuration file for the CMT;
• the source code for the synthesized application;
• the binary code suitably configured for node programming (e.g., with the proper node ID).

2.2 Interface with the DPCM infrastructure

The interface with the DPCM infrastructure mainly consists in the interface with data in the CouchDB databases provided as a web service. Thus, to simplify the interface it was implemented in PHP scripts and leverages a popular CouchDB library, PHPonCouch.

The scripts are located under the "pr" directory an consist of the following.

PHPonCouch library, installed under "pr/php-on-couch". This provides all the primitives needed to access and modify the contents of the CouchDB databases of the DPCM repository.

A set of utility functions in "pr/dpcm_util.php". These are build on top of the primitives provided by the PHPonCouch library to simplify the support of the most frequent activities needed by the DPCM integration components of the Development Tool.

The script that downloads the problem specification for all nodes in the project is "dt-project-setup.php". Its operations consists in contacting the server, downloading the active project, navigating the repository to download the data of the active project, performing consistency checks and creating the initial specifications for the application synthesis component of the Development Tool.

The script that handles the library components of the Development Tool is "lib.php". This collects all the local library components, parses their metadata and upload them to the Library Repository and the opposite, downloading the components from the library on the server and create a copy in the local library for an efficient use during the application synthesis.

The script "dt.php" is installed on the server to be used by a CMT service that allows the user to select and download from the repository the binaries to program specific nodes.

2.3 GUI

The sources are found in the "gui/ws_plugin_yakindu" folder. More specifically, the parts customized for the Development Tool are the following.

Under "gui/ws_plugin_yakindu/org.yakindu.sct.model.sgraph" was changed the EMF model (sgraph.ecore) to add support for the format extensions needed by the synthesis engine.

To the actions in "gui/ws_plugin_yakindu/org.yakindu.sct.generator.genmodel.ui" was added code to the *.action modules for the control of the synthesis engine, the export of the Yakindu SCT components and to extend the menus.

The code to save in the Yakindu projects the extra elements needed by the Development Tool library components was added in *.STextUIModule.java in the folder "gui/ws_plugin_yakindu/org.yakindu.sct.model.stext.ui".

"gui/ws_plugin_yakindu/org.max.plugin.view" implements the graphical interface allowing to add and edit the metadata properties to the top-level specification components. "gui/ws_plugin_yakindu/org.max.plugin.view.feature" is used to publish "gui/ws_plugin_yakindu/org.max.plugin.view".

"gui/ws_plugin_yakindu/Utilities" holds helper functions used by other modules.

The new features are published by "gui/ws_plugin_yakindu/UpdateSiteProject".

3. Known issues

Currently the solver stops after the finding the first solution.

4. Additional platform support

Most of the toolset (GSS and the integration with the DPCM repository) works also on Linux. Porting the GUI on Linux by maintaining the same version of Eclipse and Yakindu SCT should not require too much effort.

5. Installation information

Installation instructions can be found in deliverable D2.5 - Installation & Configuration guides and user manuals.

Please check the WSN-DPCM Public Documents area: http://wsn-dpcm.eu/index.php?option=com_content&view=article&id=58&Itemid=41

6. Contact information

Mihai Lazarescu mihai.lazarescu@polito.it