FW Profile Editor Quick Guide

The FW Profile Editor is a web-based tool to create, edit, save and share UML models compliant with the FW Profile. The FW Profile is a UML Profile which uses State Machines and Activity Diagrams to model the functional behaviour of software applications. A FW Profile Model therefore consists of a diagram (either a state machine diagram or an activity diagram) and the properties associated to the diagram. The FW Profile uses the name Procedure to designate the entity represented by an activity diagrams.

The FW Profile is language-independent but a C-language implementation of its constructs is available here. The FW Profile Editor provides a code generator which targets this implementation.

The FW Profile and its C-language implementation are defined here.

Table of contents

Editing a Model's Diagram

The FW Profile Editor can be opened in multiple tabs within the same browser or in multiple windows of the same browser. Each tab or window is used to edit a diagram representing either a state machine or a procedure.

Add Elements

Diagram elements are added by clicking the appropriate entries in the left menu:


Resize and Move Elements

Every element can be moved by drag&drop. When moving, the center of each element snaps to the center of other elements for easier alignment. Resizable elements can be made smaller or bigger by dragging the bottom-right corner. The minimum size of every element is determined by the amount of text written in it.


Selecting Multiple Elements

Multiple elements can be selected by pressing the left mouse button on an empty space at the desktop and dragging the mouse while still holding the left button. A selection box is created, and all elements which are entirely covered by the selection box are selected upon the mouse button release. Elements can be selected individually by left mouse click.


Zoom

An entire diagram can be zoomed out temporarily by pressing and holding the right mouse button. While the zoom mode is active, moving the mouse will shift the dashed rectangle, which indicates the visible screen area. Releasing the mouse button zooms in back to 100%.


Transitions

In order to create a transition (a connection from one element to another), the starting element needs to be selected by clicking it. Then, the small blue circle (which appears on the element) can be dragged to the destination element. Once the dragging stops by releasing the mouse button, a transition (for state machines) or control flow (for procedures) is created between the two elements:


Transition adjustments

Transition (or control flow) arrow can be adjusted by dragging the red circle in the middle, which apears on hover. Dragging the red circle creates a vertex, or moves an existing one. Dragging the red circle while holding Shift key on the keyboard shifts the position of the arrow. Clicking the red circle without dragging deletes the vertex, and clicking the red circle while holding Shift key resets the position to its default place. Dragging the black circle at the start of an arrow or dragging the arrow's tip to another state (or node) reconnects the arrow to that state (or node), while preserving all the triggers, actions and guards.


Self-Connection

A self-connection on a state or action node can be created by selecting the state in question and clicking "To Self" in the left menu:


Embedded State Machines

There are currently two ways to embed a state machine into the state of another state machine. Note that there is no embedding mechanism for procedures (i.e. it is not possible to embed a procedure within the action node of another procedure).

Directly Embedded State Machine

All elements on top of any existing state are considered as embedded into that particular state. The elements must be positioned so that they do not overlap with the edge of the embedding state. It is allowed to create multi-level structures of embedded state machines.


Externally Embedded State Machine

If an embedded state machine is too big to be drawn on the containing state directly, it can be created in a separate document and linked to any state later. The embedded state machine can be opened in a separate window/tab by double clicking the embedding state, or by clicking the green edit button next to the selected document name. All changes to the embedded document are propagated to its parent and child state machines.


Editing a Model's Properties

Model properties are edited through dialog boxes. Clicking on a state or a transition (state machine) or on an action node or control flow (procedure) shows a dialog box to define its actions and guards. When no element is selected or when more than one element is selected a dialog box appears for editing the global properties of a model.

Actions and Guards

To each action or guard a Description is associated where the behaviour executed by the action or guard is described. This description appears on the diagram when the 'description' option is selected for displaying the diagram.

The code to be generated for the action or guard is determined by selecting one of three options:

The Define Function option covers the case where the action or guard is implemented by a function whose implementation must be provided by the user. In the example in the figure, the entry action of state S1 is implemented by function S1EntryActionFnc. This function is declared in the header file created by the code generator but the user must provide an implementation for it.

The Call Function option covers the case where the action or guard is implemented by a function which is defined elsewhere, either in an #include file specified through the Global Properties dialog box or as a Define Function for some other element in the same model.

The Run Code option covers the case where the user defines the code implementing the action or guard directly in the tool. In the figure below, for instance, the exit action of state S1 must increment variable var by 3 and the corresponding code is directly entered in the dialog box for the action.

With the Run Code option, the user is responsible for defining the code implementing the action or guard but the tool offers two "code templates" for two common situations: an "Else" guard which always returns true and a guard which waits for N execution cycles before returning true. The Else guard should only be used on the last transition coming out of a decision node or choice pseudo-state. This constraint is not enforced by the tool and is therefore under the responsibility of the user.


Global Properties

The global properties dialog box is used to set the model name, its variables and include files and its display options.

Model Name

Each model must have a name and may, optionally, be assigned to a project. A project is intended to group logically related models. Projects cannot be nested within each other (i.e. a project cannot contain lower-level projects).


Model Variables and Include Files

The model variables and include files are only relevant to the code generation process.

Any number of variables may be defined for a model. Variables are intended to support the definition of the guards and actions of the model. During code generation, they are mapped to static variables in the body file generated for the model.

By default, the header and body files generated by the editor #include several files provided by the FW Profile implementation library. Additional files may be included in the 'custom includes' fields. This option is useful when an action or guard is defined through the 'Call Function' option as it allows user-defined functions to be used to implement actions or guards.


Display Options

There are two display options which are set in the Global Properties dialog box. The first one concerns the order in which transitions originating from the same state (State Machines) or control flows originating from the same decision node (Procedures). The order of a transition is shown on the diagram if "Show transition order" is set to 'Yes'. The order of a transition may be in the dialog box associated to the transition.

The second display option determines which kind of text is shown on a diagram for the actions and guards. In one case, the action or guard description is shown; in the other case, the name of the function associated to the action or guard is shwon.


Files Menu

Clicking the 'Files' menu entry shows a dialog to perform various actions on the FW Profile models. Some actions are only accessible to users who have signed in. In order to sign in a user should first register. Registration is free and only requires the user to enter a valid e-mail address.


Presets

The 'Presets' menu allows a user to create a new procedure or state machine diagram. New users can start from one of three pre-defined examples.

Load

This menu lists all models currently in the repository. Models may be grouped in projects and are therefore listed by project. Note that models do not need to be assigned to a project (projectless models are listed first). Clicking on a project name expands or collapses the list of models in the project. Clicking a model name causes the model to be loaded. After a model has been loaded, the user can edit it. The small icons at the left and right side of the file name are used as follows:

A user shares a model by giving access to it to other users. Either read-only or read-write access can be granted. Sharing is reversible: the owner of the model can un-share the model at any time. A user who receives a model in sharing from another user can in turn share it on with other users (but if the owner of the model un-shares it, then all other users lose access to it).

Save

The 'Save' menu allows a user to save the currently loaded model. When a model is saved, a project name can be specified (a project is intended to contain logically related models). If a model with the given name is already present then this model is overwritten (but a warning is given first).

A model can be either saved or committed. If a model is saved, its local copy is overwritten. If instead it is committed, a new entry in the history is created and the previous version of the model is retained. The history of a model can be inspected by clicking the 'clock' icon which is shown on the right side of the model name.

Actions

It is possible to perform the actions listed below on a set of files which have been selected in the 'load' menu. If no file is selected, or if the action is not defined for multiple files, then the action is performed on the currently loaded diagram only.


Code Generation

Clicking the 'Code' menu entry shows the C code generated for the currently loaded model. For a model XYZ, three files are generated: a header file XYZ.h, a body file XYZ.c, and a main file XYZMain.c. The header file and the body file are intended to be deployed within the user's application. They must be linked with the FW Profile library downloadable from here. The generated code is documented using doxygen-style comments.

The header file declares the function to create one instance of the state machine or procedure in model XYZ. The implementation of this function depends on the code generation option selected by the user.

The state machine or procedure is configured with a set of function pointers as follows:

The XYZMain.c file contains stub implementations of the actions and guards configured with the "Define Function" option and a main program which exercises the state machine or procedure in model XYZ. The intention is that this file may be used to performa a quick verification of the implementation of the XYZ model.


Error Messages

When the editor encounters an error, a bubble slides down from the top of the screen containing the error message. By default, the bubble disappears after few seconds. If there is a need to keep the error message on screen for a longer time, hovering the mouse over the bubble effectively cancels the auto-hide interval. In this case, the message will stay on screen until it is clicked.