Application Specification

The base of a StateWORKS run-time system is the RTDB. A specification of an application is a specification of all objects used by a VFSM specification. This is done using the Project Editor in StateWORKS Studio, and the result of the specification is a set of files covering all information about objects that is required to build the RTDB. The files are in:

• proprietary format used to build an RTDB-based application
• XML format that is the documentation of the specification

RTDB

RTDB is a Real Time Database that contains objects as defined in a StateWORKS specification. In addition, it contains a VFSM Executor.

The RTDB is the basis of the run-time system and the SWLab simulator. It is available as a C++ library.

I/O Object Properties

To specify the application (RTDB), we have to create all objects used by the VFSM specification. In addition to control values and actions required by the VFSM specification, the objects have several properties reflecting their physical character. For instance, a timer (TI object) needs a Const value to define the timeout. Objects that store numerical (analog) values like NI or NO have properties determining automatic scaling. Several objects require the definition of auxiliary information like unit, format, etc.

To define I/O object properties, double-click on an object in the Project Editor Object Names list. The I/O Properties pane will appear with editable fields corresponding to the object Type: VFSM, CMD, AL, TI, CNT, ECNT, DI, DO, NI, NO, SWIP, STR, XDA, DAT, PAR, UDC, TAB, OFUN, UNIT.

All objects contain the following property fields regardless of their type: Type, Name, and Description.

VFSM Object

The VFSM properties contain the following fields:

Property	Description
MyCmd	The first object in the I/O Object Dictionary: the name of the VFSM command object (CMD).
2. Object name	The second object in the I/O Object Dictionary. The object name can be taken from a combo box that lists all objects in the system defined in the VFSM I/O Object Dictionary.
3. Object name	The third object in the I/O Object Dictionary.
…	…
Last Object name	The last object in the I/O Object Dictionary.

This means the VFSM object contains a list of all objects owned by the state machine.

CMD Object

The CMD properties contain only one field:

Property	Description
Type	An h-file name (without extension) that contains the CMD names (section C).

AL Object

The AL properties contain the following fields:

Property	Description
Category	A number for which usage depends on the application. For instance, it can be used to define an alarm priority: 1 - Error 2 - Warning 4 - Info Alarms are written into AlarmLog.txt if their priority belongs to a priority level defined by a parameter AL_CatKeyPar (keyword). For instance, if AL_CatKeyPar = 5, parameters with priorities 1 and 4 will be written into AlarmLog.txt. Each project has its own AlarmLog.txt file created in its Conf directory. If Category is different from 1, 2, or 4, the alarm will not be written into AlarmLog.txt. Thus, the AlarmLog.txt file is only created if at least one alarm in the project belongs to a priority level defined by the parameter AL_CatKeyPar. If the parameter AL_CatKeyPar is missing, the default parameter value of 7 is used, i.e., all alarms will be written into AlarmLog.txt.
Text	An alarm text. The text may include resource IDs beginning with IDS_ and parameter names beginning with %. When running, RTDB translates: - the resource ID IDS_ into text found in resources. If the ID is unknown, the keyword is displayed. - the parameter name into a parameter value. PAR, NO, NI, and DAT parameters can be used. If the parameter is unknown, the parameter name is displayed. Text, resource IDs, and parameters are separated by a space character. Example: The text IDS_ValueTooHigh (%Par_Voltage V) could be displayed as Voltage too high (10.2 V) for English resources or Die Spannung ist zu hoch (10,2 V) for German resources.

Caution

When using IDS_ in the Text field, the resource.h file must be in the directory of the .swd file.

In addition, the alarm text is completed by an automatically generated time stamp.

TI Object

The TI properties contain the following fields:

Property	Description
Const	By Value Boolean: if True, the Const Value is enabled; otherwise, the Object Name. Object Name The object name (normally a PAR object) that defines the Const value. Const Value The Const value. The timeout can be defined either in the Const Value field or indirectly in the Object Name field. At any time, only one field is enabled. If By Value equals True, the Const Value field is enabled, and the name of a parameter (PAR), numerical value (NI), data (DAT), or value from a table (TAB) object that defines the timeout value can be entered there. The Object Name can be taken from a combo box that lists all appropriate (PAR, NI, DAT, TAB) objects in the system.
Clock	A timeout base. It can only be taken from a combo box which contains three values: min, sec, and 100ms. It is recommended to use the shorter base to obtain higher timeout accuracy (sec is shorter than min).

CNT Object

The CNT properties contain the following fields:

Property

Description

Const

By Value Boolean: if True, the Const Value is enabled; otherwise, the Object Name. Object Name The object name (normally a PAR object) that defines the Const value. Const Value The Const value. The Const value can be defined either in the Const Value field or indirectly in the Object Name field. At any time, only one field is enabled. If By Value equals True, the Const Value field is enabled, and the name of a parameter (PAR), numerical value (NI), data (DAT), or value from a table (TAB) object that defines the Const value can be entered there. The Object Name can be taken from a combo box that lists all appropriate (PAR, NI, DAT, TAB) objects in the system.

ECNT Object

The ECNT properties contain the following fields:

Property	Description
Const	By Value Boolean: if True, the Const Value is enabled; otherwise, the Object Name. Object Name The object name (normally a PAR object) that defines the Const value. Const Value The Const value. The Const value can be defined either in the Const Value field or indirectly in the Object Name field. At any time, only one field is enabled. If By Value equals True, the Const Value field is enabled, and the name of a parameter (PAR), numerical value (NI), data (DAT), or value from a table (TAB) object that defines the Const value can be entered there. The Object Name can be taken from a combo box that lists all appropriate (PAR, NI, DAT, TAB) objects in the system.
Input	A name of an object for which state (value) changes (events) are counted. The name can only be taken from a combo box that lists all objects in the system.
Up Value	A counted value. The value can only be taken from a combo box that lists values corresponding to the selected Input. For instance: - for a DI object, the list contains: FALSE, TRUE - for a PAR object, the list contains: UNDEF, DEF, CHANGED, INIT - for a VFSM object, the list contains: states of the state machine.

DI Object

The DI properties contain only one field:

Property	Description
Invert	Boolean: if True, the DI value will be inverted.

DO Object

The DO properties contain only one field:

Property	Description
Invert	Boolean: if True, the DO value will be inverted.

NI Object

The NI properties contain the following fields:

Property	Description
Format	A format of the object’s numerical value. The format can only be taken from a combo box that contains all C-used formats except string. The float format has three representations (see printf conversions): - float: most convenient (e or f) - %en: exponential. For instance, 3.5e-12 - %fn: fixed point. For instance, 1.2345 - %gn: use if the exponent is less than -4 or greater than or equal to the precision; otherwise use %f. The number n = 1...8 in %en and %fn represents the number of digits after the decimal point. The format is used when the object value is sent to the client.
Unit	A string that can be taken from a combo box which contains a list of predefined strings. Alternatively, any string can be entered. The string length is limited by the field size (164 characters).
Scale Mode	A predefined value taken from the combo box: - $\text{Lin}$: the input value will be corrected linearly by Scale Factor and Offset - $\text{Exp}$: the input value will be exponentially transformed by Scale Factor and Offset.
Scale Factor	A number by which the input number will be multiplied.
Offset	A number that will be added to the input number.
Threshold	A number. If the NI value is lower than the Threshold, the client will not be updated.

The input value is (Input → y, Scale Factor → a, Offset → b):

Scale Mode

$\begin{aligned} \text{lin: } & y = ax + b \\ \text{exp: } & y = e^{ax + b} \\ \end{aligned}$

NO Object

The NO properties contain the following fields:

Property	Description
Format	A format of the object’s numerical value. The format can only be taken from a combo box that contains all C-used formats except string. The float format has three representations (see printf conversions): - float: most convenient (e or f) - %en: exponential. For instance, 3.5e-12 - %fn: fixed point. For instance, 1.2345 - %gn: use if the exponent is less than -4 or greater than or equal to the precision; otherwise use %f. The number n = 1...8 in %en and %fn represents the number of digits after the decimal point. The format is used when the object value is sent to the client.
Unit	A string that can be taken from a combo box which contains a list of predefined strings. Alternatively, any string can be entered. The string length is limited by the field size (164 characters).
Scale Mode	A predefined value taken from the combo box: - $\text{Lin}$: the output value will be corrected linearly by Scale Factor and Offset - $\text{Exp}$: the output value will be exponentially transformed by Scale Factor and Offset.
Scale Factor	A number by which the output number will be multiplied.
Offset	A number that will be added to the output number.
Out Data	A name of the object whose value will be used as the output value (NO does not have its own output value). It can only be taken from the combo box that lists all parameters and tables in the system.

The output value is (Output → y, Scale Factor → a, Offset → b):

Scale Mode

$\begin{aligned} \text{lin: } & y = ax + b \\ \text{exp: } & y = e^{ax + b} \\ \end{aligned}$

SWIP Object

The SWIP properties contain the following fields:

Property	Description
Input	An object name that is controlled by the SWIP object. It is taken from a combo box that contains all PAR, NI, and UDC objects in the system.
Limit Low	By Value Boolean: if True, the Const Value is enabled; otherwise, the Object Name. Object Name The object name (normally a PAR object) that defines the Limit Low value. Const Value The Limit Low value. The Limit Low value can be defined either in the Const Value field or indirectly in the Object Name field. At any time, only one field is enabled. If By Value equals True, the Const Value field is enabled, and the name of a parameter (PAR) or numerical value (NI) object that defines the Const Limit Low value can be entered there. The Object Name can be taken from a combo box that lists all appropriate (PAR, NI) objects in the system.
Limit High	By Value Boolean: if True, the Const Value is enabled; otherwise, the Object Name. Object Name The object name (normally a PAR object) that defines the Const value. Const Value The Limit High value. The Limit High value can be defined either in the Const Value field or indirectly in the Object Name field. At any time, only one field is enabled. If By Value equals True, the Limit High field is enabled, and the name of a parameter (PAR) or numerical value (NI) object that defines the Const Limit High value can be entered there. The Object Name can be taken from a combo box that lists all appropriate (PAR, NI) objects in the system.

STR Object

The STR properties contain the following fields:

Property	Description
Input	An object name that is analyzed by the STR object. It is taken from a combo box that contains all input objects (PAR and DAT) in the system that can contain strings.
Regular Expression	By Value Boolean: if True, the Expression is enabled; otherwise, the Object Name. Object Name The object name that defines the Regular Expression string. Expression The Regular Expression string.
List of substrings	A list of data objects which will receive the found substrings for further evaluation. The list is prepared in a dialog window that displays in the Object column all DAT, PAR, and NI* objects in the system. Note that the result of the string analysis may have a non-string format (in such a case, the resulting string is automatically transformed into the required format).

Caution

*The NI object can be used to store the result only if the required format is not a string.

XDA Object

The XDA properties contain only one field:

Property	Description
Size	A number that defines the size of the memory to be reserved for a user-written output function.

DAT Object

The DAT properties contain the following fields:

Property	Description
Format	A format of the object’s numerical value. The format can only be taken from a combo box that contains all C-used formats. The float format has three representations (see printf conversions): - float: most convenient (e or f) - %en: exponential. For instance, 3.5e-12 - %fn: fixed point. For instance, 1.2345 - %gn: use if the exponent is less than -4 or greater than or equal to the precision; otherwise use %f. The number n = 1...8 in %en and %fn represents the number of digits after the decimal point. The format is used when the object value is sent to the client.
Unit	A string that can be taken from a combo box which contains a list of predefined strings. Alternatively, any string can be entered. The string length is limited by the field size (164 characters).

PAR Object

The PAR properties contain the following fields:

Property	Description
Category	A string that defines a parameter type. The parameter type defines the persistence of the parameter. It is usually taken from the combo box that contains the following types: - EP: the parameter is taken from the Registry HKEY_CURRENT_USER/Software/SWSoftware/SWSys/EP at system start. If it is not found in the Registry, it is taken from the SWD file. Any parameter change is written to the Registry. The EP parameters are individual parameters for each user. - EP_LM_ADMIN: the parameter is taken from the Registry HKEY_LOCAL_MACHINE/Software/SWSoftware/SWSys/EP_ADMIN at system start. If it is not found in the Registry, it is taken from the SWD file. Any parameter change is written to the Registry if the user has Administrator rights. The EP_LM_ADMIN parameters are common parameters used by all users. - EP_LM_USERS: the parameter is taken from the Registry HKEY_LOCAL_MACHINE/Software/SWSoftware/SWSys/EP_USERS at system start. If it is not found in the Registry, it is taken from the SWD file. Any parameter change is written to the Registry. The EP_LM_USERS parameters are common parameters used by all users. - PP: the parameter is always taken from the SWD files at system start. - PP_Coded: the parameter is always taken from the SWD files at system start. For RTDB, there is no difference between PP and PP_Coded types. It is only a formal differentiation to mark parameters that are set in code (PP_Coded).
Format	A format of the object’s numerical value. The format can only be taken from a combo box that contains all C-used formats. The float format has three representations (see printf conversions): - float: most convenient (e or f) - %en: exponential. For instance, 3.5e-12 - %fn: fixed point. For instance, 1.2345 - %gn: use if the exponent is less than -4 or greater than or equal to the precision; otherwise use %f. The number n = 1...8 in %en and %fn represents the number of digits after the decimal point. The format is used when the object value is sent to the client.
Unit	A string that can be taken from a combo box which contains a list of predefined strings. Alternatively, any string can be entered. The string length is limited by the field size (164 characters).
Low limit value	A number that defines the low limit of the parameter value. The value is not evaluated by RTDB; it is intended to be used by the application program.
High limit value	A number that defines the high limit of the parameter value. The value is not evaluated by RTDB; it is intended to be used by the application program.
Initial value	A number that is the (initial) parameter value after start-up.

UDC Object

The UDC properties contain the following fields:

Property	Description
Unit	A string that can be taken from a combo box which contains a list of predefined strings. Alternatively, any string can be entered. The string length is limited by the field size (164 characters).
Up Input	A name of an object whose state (control value) changes are counted (upwards). The name is taken from a combo box that lists all objects in the system.
Up Value	A counted value. The value is taken from a combo box that lists values corresponding to the selected Up Input. For instance: - for a DI object, the list contains: FALSE, TRUE - for a PAR object, the list contains: UNDEF, DEF, CHANGED, INIT - for a VFSM object, the list contains: states of the state machine.
Down Input	A name of an object whose state (value) changes are counted (downwards). The name is taken from a combo box that lists all objects in the system.
Down Value	A counted value. The value is taken from a combo box that lists values corresponding to the selected Down Input.
Clear Input	A name of an object whose state (value) changes clear the counter. The name is taken from a combo box that lists all objects in the system.
Clear Value	A clear value. The value is taken from a combo box that lists values corresponding to the selected Clear Input.

TAB Object

The TAB properties contain only one field:

Property	Description
Table Rows	A list of objects that are in the table. The list is automatically indexed beginning from 0. The list is prepared in a dialog window that displays in the Object column all DAT, PAR, and NI objects in the system.

OFUN Object

The OFUN properties contain the following fields:

Property	Description
Function Name	The name of the user-written function that is to be found in the Output Function Unit.
Unit Name	The name of the Output Function Unit. The name can only be taken from a combo box that displays all Output Function Units in the system.

UNIT Object

The UNIT properties contain the following fields:

Property	Description
Phys Address	A number that defines a hardware physical address. It can be used by an I/O handler.
Comm Port	A string, for instance: COM1, COM2, … It can be used by an I/O handler.
1. Object name	The first object in the UNIT specification table. The object name can be taken from a combo box that lists all objects in the system defined in the UNIT specification table.
2. Object name	The second object in the UNIT specification table.
…	…
Last Object name	The last object in the UNIT specification table.

The UNIT object is a list of all objects that can be accessed by an I/O handler or Output Function.

I/O Handler

Real I/O devices that are situated outside the scope of the RTDB-based execution system are linked to the system by means of a specific interface — the I/O Handler. These I/O handlers are hardware-dependent pieces of software. They cannot be standardized and are different for each variety of hardware.

To simplify interfacing, the Project Editor uses I/O Units. An I/O Unit is a list of objects that are used when writing I/O handlers. Typically, DI, DO, NI, and NO object types are used in I/O Units, but in general any object type can be used there.

String Resources

Text properties (Text of AL and Unit of NI, NO, DAT, PAR, UDC) can be set as plain text or as string constants. Using string constants allows internationalization of text. A string constant has the form IDS_StringName.

String constants are prepared in the String Resources editor and stored as a text file, StringRes.txt. When building the configuration, two files are generated in the Conf folder:

• resources.h
• StringRes.src

These files are read by RTDB when starting the application.

Unit property string

If the string is a resource ID beginning with IDS_, RTDB, when running, translates it into a text found in the resource. If the ID does not exist, the Unit is ignored and the parameter value is used.

The usage of resource IDs in the Unit field allows (language-dependent) enumeration values to be passed to the application program. For instance, if the resource ID contains a string IDS_Movement = {none, slow, normal, fast}:

• Initial value = 0 will be passed to the client as none,
• Initial value = 1 will be passed to the client as slow, etc.

If the string is in curly parentheses {} and contains several words separated by commas (,), the words are also interpreted as enumeration values. For instance, if the string is {,slow,,fast }:

• Initial value = 0 will be passed to the client as is, i.e. 0,
• Initial value = 1 will be passed to the client as slow,
• Initial value = 2 will be passed to the client as is, i.e. 2,
• Initial value = 3 will be passed to the client as fast.

The enumeration value can be defined by an integer value. Hence, if the Format is not integer, the value will be rounded/translated to an integer. For instance, with Format = float and Unit = {Zero,One,Two,,,,Six}, the following sequence of parameter values:

-0.9 0.0  1.9 2.1 3.0 5.1234 6.0 70.0

will be sent to clients as:

-0.9 Zero One Two 3.0 5.1234 Six 70.0

Caution

When using IDS_ in the Text field, the resource.h file must be in the directory of the .swd file.

Building Configuration

The configuration specification results in the following files:

ProjectName.swd	Information about all objects in text form. On start-up, it is read by an RTDB-based application and used to build the RTDB.
resource.h	C header file containing #defines defining string constants used by object specifications.
StringRes.src	File containing texts of string constants defined in resource.h.
spec.cpp	The content of the ProjectName.swd file as a C++ file (all object definitions as C++ initialized strings); used in embedded systems.

These files are accompanied by an XML file:

ProjectName.xml	The entire specification information covering both the VFSM specification and the Project specification. Effectively, it is an XML equivalent of the ProjectName.prj file. Primarily, it is used as project documentation.

All these files can be generated at any time during specification, with errors being displayed in the Configuration Error Message window.

Each VFSM has its own set of files.

Configuration Error Messages

The Configuration Error Messages window is displayed after building the configuration. It shows:

• errors and irregularities in object properties (missing or erroneous properties)
• warnings concerning missing files (missing resource.h)
• finite state machine verification results

Not all errors have a serious effect on the run-time system. As a rule, the run-time system works despite these errors; it allows testing of incompletely specified systems.

Message Types

• Error: Error Messages should not be ignored. Starting StateWORKS Execution may lead to unpredictable results.
• Warning: A Warning Message signals that an I/O Property has a default value or an INIT entry has not been used in the specification. In most cases, it does not have any significant effect on system functioning. StateWORKS Execution should function properly.
• Information: An Information Message signals a missing property that does not have any significant effect on system functioning. StateWORKS Execution will function properly.
• VFSM Verification: States without exit transitions and unreachable states; error-free verification is acknowledged by an “OK” statement.

Testing

A built configuration can be tested within StateWORKS Studio using the simulator SWLab and the monitors SWMon and SWQuickPro.

These programs may be started using the corresponding “Tools” menu commands. On startup, SWLab uses the configuration of the currently loaded project.

SWLab

SWLab is an RTDB-based application with a user interface simulating a few digital inputs and outputs as well as analog (numerical) inputs and outputs. It uses the same RTDB library that is the basis of StateWORKS applications. Thus, testing a specified system of state machines with SWLab guarantees the same system behavior in the developed application.

Monitors

There are two monitors: SWMon and SWQuickPro.

SWMon allows several objects to be displayed at the same time. You can select either objects owned by a state machine or by an I/O unit. Alternatively, you can prepare a user list of objects to be displayed; the list can be stored and used at any time. The object properties that can be displayed and set in SWMon are not complete; properties that are irrelevant or dangerous for testing are not accessible.

SWQuickPro allows one object to be displayed at a time. SWQuickPro displays and allows setting of all object properties; be careful when changing some property values. In addition, SWQuickPro stores all Get and Set operations in a log file that can be used as a command file. The command file can also be prepared manually in a text editor. The command files can be executed in different modes, allowing automatic testing of RTDB-based applications running either in SWLab or in the final application.