# Tasks

## Modeling a statemachine

1. Make sure the YAKINDU Modeling perspective is active.
2. Create a new project.
3. Click File > New > Other... > YAKINDU > YAKINDU Statechart Model.
4. Click Next name the sct file and click Finish
5. The YAKINDU statechart editor opens on the statechart model. It already has an initial state and an unnamed simple state connected by a transition.
6. Now you can add states and transitions from the palette.

To edit the states and transitions you can use the properties view. It has an integrated Xtext support. This makes correct editing easier. You can also change the appearance of the model elements.

On the palette you will also find a composite submachine state. This is a state that contains a complete statemachine. You can choose an existing statemachine or create a new one.

### Related topics

Statemachine Elements reference
Textual modeling lanuage Reference

## Validating a statemachine

The statemachine is validated automatically during build. The elements that cause problems get error markers. You can find the details about the problems on the problems view.

## Simulating a statemachine

The YAKINDU simulation engine supports simulation modes:

- event driven
- cycle based

The default setting is cycle based with a cycle period of 200 ms. In this mode the simulation engine processes the state machine transitions in steps of the given cycle duration. The following statechart illustrates this. It is simulated cycle based with a cycle period of 3 seconds.

What happend during simulation is the following:

1. After 3s init switches to pre1
2. After 3 further seconds recursive transition to pre1 is processed (not after 2s the transition says)
3. After 3 further seconds recursive transition to pre1 is processed again and the condition becomes true so result gets activated

In contrast to cycle based the event driven simulation mode concentrates on the events of a state machine. The same state machine above could be simulated as follows:

1. Immediately init switches to pre1
2. Immediately the event touch is raised twice
3. The condition becomes true so that the result state is reached after 2 or 3 seconds instead of 9

Start a simulation with the different modes as follows

1. Make sure the YAKINDU Simulation Perspectiv is opened.
2. Start the simulation by clicking Run > Run Configurations....
3. Select the statechart you want to simulate and the simulation mode.
4. Apply the setting and Run the simulation.

Simulation Concept
Simulation perspective
Simulation View

## Generating Code

For code generation, Yakindu Statechart Tools uses a textual generator model called SGen, that can be used to configure the code generation process. It can be created either by using the provided wizard or by creating a new text file with the file extension ‚.sgen’.
To create a generator model with the wizard,

1. Click File > New > Other... > Yakindu Statechart Genmodel
2. Type a name and click Next
3. Choose the desired generator, i.e. YAKINDU Java Code Generator
4. Check the model(s) to generate code from and click Finish

The result is an .sgen file of the following format:

    GeneratorModel for [GeneratorId] {
    	statechart [StatechartReference] {
    		feature [Feature] {
    			[ParameterName] = [ParameterValue]
    		}
    	}
    }

The [GeneratorId] is the unique id of the Generator. Yakindu Statechart Tools currently supports the following Generators out of the box:

1. yakindu::java – Generator ID for the Java Code Generator
2. yakindu::c – Generator ID for the C Code Generator
3. yakindu::cpp – Generator ID for the C++ Code Generator
4. yakindu::xpand – Generator ID for custom Xpand based Code Generators
5. yakindu::generic – Generator ID for custom Java based Code Generators

One GeneratorModel can contain several [StatechartReference]s. These are crossreference to statechart models for which the code should be generated.
For each referenced Statechart, the generator process can be configured with [Feature]s. Each Feature consists of several parameters. These parameters can be configured with [ParameterName] = [ParameterValue].

The Generator Model will be build automatically if you checked Project > Build Automatically. If you want to execute only one Generator Model, you can select
Generate Statechart Artifacts from the Package Explorer’s context menu.

## Core Features

The following section describes the Core Features which are available for each Code Generator:

#### Outlet

The Outlet feature specifies the target project and folder for the generated artifacts. It is a required feature and consists of the following parameters:

1. targetProject (String): The project where the generated artifacts are stored
2. targetFolder (String): The folder where the generated artifacts are stored

Example configuration:

    feature Outlet {
    	targetProject = "ExampleProject"
    	targetFolder = "src-gen"
    }

#### LicenseHeader

The LicenseHeader feature specifies the license text that should be added as a header to the generated artifacts. It is an optional feature and consists of the following parameters:

1. licenseText (String): The license text to add as a header

Example configuration:

    feature LicenseHeader {
    	licenseText = "Copyright (c) 2012 committers of YAKINDU and others."
    }

#### FunctionInlining

The FunctionInlining feature allows the inlining of expressions instead of generating separate functions or methods. This might reduce the readability of the generated code, but increases performance because less operation calls are neccessary.
It is an optinal feature and consists of the following parameters:

1. inlineReactions (Boolean): Inlines the expression for reactions
2. inlineEntryActions (Boolean): Inlines the expression for entry actions
3. inlineExitActions (Boolean): Inlines the expression for exit actions
4. inlineEnterSequences (Boolean): Inlines the expression for enter sequences
5. inlineExitSequences (Boolean): Inlines the expression for exit sequences
6. inlineChoices (Boolean): Inlines the expression for choices
7. inlineEnterRegion (Boolean): Inlines the expression for enter regions
8. inlineExitRegion (Boolean): Inlines the expression for exit regions
9. inlineEntries (Boolean): Inlines the expression for entries

Example configuration:

    feature FunctionInlining {
    	inlineChoices = false
    	inlineEnterRegion = true
    	inlineEntries = true
    }

#### Debug

The Debug feature dumps the Execution Model to the target folder as xmi model. It is an optinal feature and consists of the following parameters:

1. dumpSexec (Boolean): The license text to add as a header

Example configuration:

    feature Debug {
    	dumpSexec = true
    }

## Java Generator Features

#### Naming

The Naming feature allows the configuration of package names as well as class name prefix / suffix.
It is an optinal feature and consists of the following parameters:

1. basePackage (Boolean): Inlines the expression for reactions
2. implementationSuffix (Boolean): Inlines the expression for entry actions

Example configuration:

    feature Naming {
    	basePackage = "org.yakindu.sct"
    	implementationSuffix = "Impl"
    }

#### GeneralFeatures TBD

## C Generator Fetures TBD

## Create Custom Code Generators

YAKINDU Statechart Tools provides a rich feature set to supports custom code generators out of the box.
These code generators can be either written in Java, Xtend or in Xpand

### Writing a custom code generator with Xtend2/Java

First, you have to create a new Xtend2 generator project. Click File > New > Other... > YAKINDU > YAKINDU Xtend2/Java Generator Project to create a new Xtend2 Generator Project.

The wizards asks for a Project name and the name of the Generator class, where you have to specify a full qualified class name. If you check the Use Xtend checkbox, the Generator class will be initially created as an xtend class. Otherwise, Java will be used for the generator.

The check box Configure for Plugin Export adds all required extension point registrations to the new project that it can be exported as a plugin and deployed in different SCT2 installations.The Generator Model can refer to the new Generator Plugin via its unique Generator ID. If you want to contribute custom Generator Features for your Code Generator, check the Create Feature Library check box.

After a click on Finish a new project is created in your workspace. All required plugin dependencies and extension points are registered and you can start to write your code generator based on the ExecutionFlow meta model [Link].

### Executing a custom Xtend2/Java code generator

If you have configured your plugin for Plugin Export, you could use eclipse export wizard to create a deployable plugin and copy it to your plugins folder of your eclipse installation. You can refer to your plugin via its unique generator id from your Generator Model.
Since this is not very convenient, YAKINDU provides a way to execute your generator while you are developing it.
Therefore, you have to Create a new Generator Model with the generator id yakindu::generic, either by using the New Statechart Generator Model wizard or by simple creating a new text file with the file extension .sgen. the following feature allows to configure your code generator.

#### Generator

The Generator feature allows the configuration of a custom code generator located in the workspace and written in Java or another JVM language. It is a required feature and consists of the following parameters:

1. generatorProject (String, required): The name of the generator project
2. generatorClass (String, required): The full qualified class name of the code generator class.
3. configurationModule (String, optional): The full qualified class name for a guice module to configure the code generator

Example configuration:

    feature Generator {
    	generatorProject = "org.yakindu.sct.mygenerator"
    	generatorClass = "org.yakindu.sct.MyGenerator"
    }