GSME ACS SRS

Document Sample
GSME ACS SRS Powered By Docstoc
					           E U R O P E A N S O U T H E R N O B S E R V A T ORY
           Organisation Européenne pour des Recherches Astronomiques dans l'Hémisphère Austral

           Europäische Organisation für astronomische Forschung in der südlichen Hemisphäre




    Generic State Machine Engine
 Software Requirements Specification


                            Doc. No.: xxx-SPE-ESO-xxxxx-xxxx

                                        Issue: 1.0 draft

                                      Date: 18/06/2010




               Name                              Date            Signature
Prepared: L. Andolfato

               Name                              Date            Signature
Approved: G. Chiozzi

               Name                              Date            Signature
Released: M. Peron
              Generic State Machine Engine for ACS
                                                        Doc.    xxx-SPE-ESO-xxxxx-xxxx
ESO           Software Requirements Specification
                                                        Issue
                                                        Date
                                                                1.0 draft
                                                                18/06/2010
                                                        Page    2 of 35



                                       CHANGE RECORD


ISSUE         DATE         SECTION/PAGE         REASON/INITIATION
                           AFFECTED             DOCUMENTS/REMARKS

1.0 / draft   2010-06-18   All                  First draft.
                    Generic State Machine Engine for ACS
                                                                    Doc.              xxx-SPE-ESO-xxxxx-xxxx
    ESO             Software Requirements Specification
                                                                    Issue
                                                                    Date
                                                                                      1.0 draft
                                                                                      18/06/2010
                                                                    Page              3 of 35


TABLE OF CONTENTS
1     INTRODUCTION                                                                                             5
    1.1    PURPOSE                                                                                             5
    1.2    SCOPE                                                                                               5
    1.3    APPLICABLE DOCUMENTS                                                                                5
    1.4    REFERENCE DOCUMENTS                                                                                 5
    1.5    ABBREVIATIONS AND ACRONYMS                                                                          6
    1.6    GLOSSARY                                                                                            7
    1.7    OVERVIEW                                                                                            8
2     OVERALL DESCRIPTION                                                                                      9
    2.1    REACTIVE SYSTEMS AND STATE MACHINES MODELS                                                           9
    2.2    MODEL INDEPENDENT STATE MACHINE ENGINE                                                               9
    2.3    MODEL REPRESENTATION                                                                                11
    2.4    GENERIC STATE MACHINE ENGINE                                                                        12
    2.5    GENERIC STATE MACHINE ENGINE FOR ACS                                                                14
    2.6    GENERIC STATE MACHINE ENGINE FOR VLT                                                                16
    2.7    ERROR HANDLING                                                                                      17
    2.8    LOGGING                                                                                             18
    2.9    UNIT TESTS                                                                                          18
3     SCXML ENGINE REQUIREMENTS                                                                                19
    3.1     FUNCTIONAL REQUIREMENTS                                                                            19
       3.1.1 Model Independent State Machine Engine [SR1.1.1]                                                  19
       3.1.2 SCXML State Machine Model [SR1.1.2]                                                               19
       3.1.3 Support of SCXML Features [SR1.1.3]                                                               19
       3.1.4 Actions Mapping [SR1.1.4]                                                                         19
       3.1.5 Guards Mapping [SR1.1.5]                                                                          20
       3.1.6 Activity Mapping [SR1.1.6]                                                                        20
       3.1.7 Action Grouping [SR1.1.7]                                                                         20
       3.1.8 Guard Grouping [SR1.1.8]                                                                          20
       3.1.9 Action Group Initialization [SR1.1.9]                                                             20
       3.1.10    Action Group De-initialization [SR1.1.10]                                                     21
       3.1.11    Actions, Guards and Activities Shared Data [SR1.1.11]                                         21
       3.1.12    Actions Invocation within an Action [SR1.1.12]                                                21
       3.1.13    Trigger Event Access within Actions, Guards, Activities [SR1.1.13]                            21
       3.1.14    Action and Guard Reuse [SR1.1.14]                                                             21
       3.1.15    Action and Guard Extensibility [SR1.1.15]                                                     22
       3.1.16    Error Handling within Actions, Guards, and Activities [SR1.1.16]                              22
       3.1.17    Logging within Actions, Guards, Activities, Shared Data [SR1.1.17]                            22
       3.1.18    State Machine Engine Logging [SR1.1.18]                                                       22
       3.1.19    State Machine Engine Logging History [SR1.1.19]                                               22
       3.1.20    State Machine Engine Error Handling [SR1.1.20]                                                23
       3.1.21    State Machine Engine Status [SR1.1.21]                                                        23
       3.1.22    Generation of Events from Inside Action and Activities [SR1.1.22]                             23
       3.1.23    Handling of Rejected Events [SR1.1.23]                                                        23
       3.1.24    Event Interface [SR1.1.24]                                                                    23
       3.1.25    Mapping of Events [SR1.1.25]                                                                  23
       3.1.26    Extensibility of Shared Data [SR1.1.26]                                                       24
    3.2     PERFORMANCE REQUIREMENTS                                                                           24
       3.2.1 Memory Consumption [SR1.2.1]                                                                      24
       3.2.2 Event Propagation Time [SR1.2.2]                                                                  24
       3.2.3 Transition Execution Time [SR1.2.3]                                                               24
       3.2.4 Action Invocation Time [SR1.2.4]                                                                  24
    3.3     INTERFACE REQUIREMENTS                                                                             24
    3.4     EXTERNAL REQUIREMENTS                                                                              24
       3.4.1 Support of Java [SR1.4.1]                                                                         24
       3.4.2 Support of C++ [SR1.4.2]                                                                          24
                    Generic State Machine Engine for ACS
                                                                    Doc.             xxx-SPE-ESO-xxxxx-xxxx
    ESO             Software Requirements Specification
                                                                    Issue
                                                                    Date
                                                                                     1.0 draft
                                                                                     18/06/2010
                                                                    Page             4 of 35

      3.4.3   Unit Tests [SR1.4.3]                                                                            25
      3.4.4   Online Documentation [SR1.4.4]                                                                  25
4     GENERATOR REQUIREMENTS                                                                                  26
    4.1     FUNCTIONAL REQUIREMENTS                                                                           26
       4.1.1 Configuration [SR2.1.1]                                                                          26
       4.1.2 Software Component Skeleton and Start-up/Shutdown [SR2.1.2]                                      26
       4.1.3 Event Handling [SR2.1.3]                                                                         26
       4.1.4 Supported Events [SR2.1.4]                                                                       27
       4.1.5 Asynchronous Events [SR2.1.5]                                                                    27
       4.1.6 Synchronous Events [SR2.1.6]                                                                     27
       4.1.7 Generation of Sequence of Events [SR2.1.7]                                                       27
       4.1.8 Generation of Parallel Events [SR2.1.8]                                                          28
       4.1.9 Handling of Superseded Events [SR2.1.9]                                                          28
       4.1.10    Action, Guards and Activity Skeletons [SR2.1.10]                                             28
       4.1.11    Access to Unit Testing Setup [SR2.1.11]                                                      28
       4.1.12    Start-up and Shutdown Unit Test [SR2.1.12]                                                   28
       4.1.13    Statistics on the Generated/hand-written Lines of Code [SR2.1.13]                            28
       4.1.14    Statistics on Size of the Model [SR2.1.14]                                                   29
       4.1.15    Deletion of Generated Files [SR2.1.15]                                                       29
       4.1.16    Backup of Partially Generated Files [SR2.1.16]                                               29
       4.1.17    Location of Generated Files [SR2.1.17]                                                       29
       4.1.18    Code Generator Log [SR2.1.18]                                                                29
       4.1.19    Documentation of Generated Code [SR2.1.19]                                                   29
    4.2     PERFORMANCE REQUIREMENTS                                                                          30
    4.3     INTERFACE REQUIREMENTS                                                                            30
    4.4     EXTERNAL REQUIREMENTS                                                                             30
       4.4.1 Support of Alma Common Software Platform [SR2.4.1]                                               30
       4.4.2 Support of Very Large Telescope Platform [SR2.4.2]                                               30
       4.4.3 Support for MagicDraw Tool [SR2.4.3]                                                             30
       4.4.4 Default State Machine Model [SR2.4.4]                                                            30
       4.4.5 Unit Tests [SR2.4.5]                                                                             30
       4.4.6 Online Documentation [SR2.4.6]                                                                   31
5     MODEL REQUIREMENTS                                                                                      32
    5.1     FUNCTIONAL REQUIREMENTS                                                                           32
       5.1.1 UML Profile [SR3.1.1]                                                                            32
       5.1.2 Component Model [SR3.1.2]                                                                        32
       5.1.3 Component Model Consistency [SR3.1.3]                                                            32
       5.1.4 Component Model Interface Reusability [SR3.1.4]                                                  32
       5.1.5 Platform Independent Component Model [SR3.1.5]                                                   33
       5.1.6 Deployment Model [SR3.1.6]                                                                       33
    5.2     PERFORMANCE REQUIREMENTS                                                                          33
    5.3     INTERFACE REQUIREMENTS                                                                            33
    5.4     EXTERNAL REQUIREMENTS                                                                             33
6     NOTES                                                                                                   34
                  Generic State Machine Engine for ACS
                                                                Doc.           xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                Issue
                                                                Date
                                                                               1.0 draft
                                                                               18/06/2010
                                                                Page           5 of 35



1 INTRODUCTION

1.1     Purpose
The present document defines and describes the operational and functional requirements of the Generic State
Machine Engine (GSME).

1.2     Scope
This document describes the functions that the GSME shall provide in order to build applications based on state
machine models, using one of the following software platforms:
     Alma Common Software (ACS)
     Very Large Telescope Software (VLTSW)

1.3     Applicable Documents
The following documents, of the exact issue shown, form part of the GSME documentation to the extent
specified herein. In the event of conflict between the documents referenced herein and the content of this
document, the content of this document shall be considered as a superseding requirement.

          Title                                            Reference                       Issue Date


                                       Table 1 – Applicable documents.



1.4     Reference Documents
The following documents contain additional information required to fully understand the terminology used, the
software environment in which GSME shall be integrated and the characteristics of the interface to external
systems.

           Title                                              Author                              Edition
           IEEE Std. 1012, Standard for Software
  RD01                                                        IEEE                                1986
           Verification and Validation Plans
           IEEE Std. 830, Recommended Practice for
  RD02                                                        IEEE                                1993
           Software Requirements Specifications
           IEE (UK), Guidelines for documentation of
  RD03                                                        IEE                                 1985
           software in industrial computer systems
  RD04     Modeling Reactive Systems with Statecharts         D. Harel, M. Politi             1998
           Tabular Notions for State Machine-Based            M. Herrmannsdoerfer, S. Konrad,
  RD05
           Specifications                                     B. Berenbach
  RD06     Workstation Software Framework                     L. Andolfato, R. Karban         2008
           State Chart XML: State Machine Notation for
  RD07                                                        W3C Working Draft                   2010
           Control Abstraction
  RD08     UML 2.2                                            OMG                                 2009
           ALMA Software Integration Development Tools
  RD09     and Integration Guidelines                         P. Sivera                           2005
           (COMP-70.80.00.00-002-L-GEN)
           ACS Architecture                                   G. Chiozzi, H. Sommer, J.
  RD10                                                                                            2009
           (COMP-70.25.00.00.002-G-DSN)                       Schwarz
                 Generic State Machine Engine for ACS
                                                                Doc.           xxx-SPE-ESO-xxxxx-xxxx
 ESO             Software Requirements Specification
                                                                Issue
                                                                Date
                                                                               1.0 draft
                                                                               18/06/2010
                                                                Page           6 of 35

           Title                                              Author                             Edition
  RD11     ACS Error System                                   B. Jeram, G. Chiozzi               2007
  RD12     ACS Logging and Archiving                          K. Zagar, R. Georgieva             2007
  RD13     ACS Alarm System                                   A. Caproni                         2010
  RD14     ACS Configuration Database                         A. Caproni, S. Harrington          2005
           Statecharts: a visual formalism for complex
  RD15                                                        D. Harel                           1987
           systems
  RD16     On the development of reactive systems             D. Harel, A. Pnueli                1985
           Design Methods for Reactive Systems:
  RD17                                                        R. J. Wieringa                     2003
           Yourdon, Statemate and the UML
           Auto-coding UML Statecharts for Flight
  RD18                                                        E. Benowitz                        2006
           Software
           Introduction to Automata Theory, Languages,
  RD19                                                        J. Hopcroft, J. D. Ullman          1976
           and Computation
           UML vs Classical vs Rhapsody Statecharts: Not
  RD20                                                        M. L. Crane, J Dingel              2005
           All Models are Created Equal
  RD21     Statecharts in the Making: A Personal Account      D. Harel                           2009
           Development of a state machine sequencer for
                                                              L. J. Reder, A. Booth, J. Hsieh, K.
  RD22     the Keck Interferometer: evolution, development                                        2004
                                                              Summer
           & lessons learned using a CASE tool approach
           VLT Software Basic Tools and Working
  RD23                                                        P. Sivera                          2004
           Environment Guidelines
  RD24     VLT Common Software Overview                       G. Filippi                         1995
  RD25     VLT Common Software Installation Manual            S. Feyrin                          2009
           An Object-oriented event-driven architecture for
  RD26                                                        G. Chiozzi                         1995
           the VLT Telescope Control Software
           Design Patterns. Elements of Reusable Object-      E. Gamma, R. Helm, R. E.
  RD27                                                                                           1994
           Oriented Software                                  Johnson
                                       Table 2 – Reference documents.



1.5     Abbreviations and Acronyms
This document employs several abbreviations and acronyms to refer concisely to an item, after it has been
introduced. The following list is aimed to help the reader in recalling the extended meaning of each short
expression:

   ACS             Alma Common Software
   ALMA            Atacama Large Millimeter Array
   APE             Active Phasing Experiment
   API             Application Programming Interface
   CCS             Central Common Software
   CORBA           Common Object Request Broker Architecture
   EVH             Event Handling toolkit
   FSM             Finite State Machine
   GSME            Generic State Machine Engine
   GUI             Graphical User Interface
   IEE             Institute of Electrical Engineer
   IEEE            Institute of Electrical and Electronic Engineers
   SCXML           StateCharts eXtensible Markup Language
                   Generic State Machine Engine for ACS
                                                                 Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO               Software Requirements Specification
                                                                 Issue
                                                                 Date
                                                                                 1.0 draft
                                                                                 18/06/2010
                                                                 Page            7 of 35

   SM                State Machine
   TBD               To Be Defined
   UML               Unified Modeling Language
   VLT               Very Large Telescope
   VLTI              Very Large Telescope Interferometer
   VLTSW             Very Large Telescope Software
   WS                WorkStation
   WSF               Workstation Software Framework


1.6       Glossary
This glossary defines those terms (single words or phrases) mentioned in the requirements specification and that
can introduce ambiguities. The following definitions shall be considered part of the requirements specification.

         ACS Component: Alma Common Software Component is a Software Component running on ACS
          Software Platform as specified in [RD10].
         ACS Platform: Alma Common Software Platform is based on Linux operating system (Red Hat
          distribution), Java/GNU C++/Python programming languages, and ACS middleware as specified in
          [RD10].
         Finite State Machine: also known as Finite Automaton or Finite State System as defined in [RD19]:
          “The finite automaton is a mathematical model of a system, with discrete inputs and outputs. The
          system can be in any one of a finite number of internal configurations or states. The state of a system
          summarizes the information concerning past inputs that is needed to determine the behavior of the
          system on subsequent input”.
         Middleware: a Middleware is a piece of software that runs on a Software Platform and provides at least
          the following services to the Software Components: communication services (i.e. distributed Software
          Components can exchange information), error handling, logging, alarm handling
         SCXML: SCXML is a general purpose event-based state machine language that combines concepts
          from CCXML and Harel Statecharts. SCXML standard is defined in [RD07].
         State Machine: depending on the context, the term State Machine refers to Finite State Machine,
          Statecharts, or SCXML.
         State Machine Engine: a State Machine Engine is a software implementation of a State Machine
          Model. An example of a State Machine Engine is the SCXML Engine which executes SCXML Models.
         State Machine Model: in the context of Finite State Machine, it is the Transition Diagram as defined
          in [RD19]; in the context of Statecharts, it is the Statecharts diagram defined in [RD15]; in the context
          of UML, it is the UML State Machine Diagram as defined in [RD08]; in the context of SCXML it is
          an SCXML Model as defined in [RD07].
         Statecharts: Statecharts are a “broad extension of the conventional formalism of state machines and
          state diagrams that is relevant to the specification and design of complex discrete-event systems”.
          Statecharts “extend conventional state transition diagrams with essentially three elements, dealing,
          respectively, with the notation of hierarchy, concurrency, and communication” [RD15].
         Software Component: a Software Component is an application, or a process, or a library, which
          provides some services and runs on a Software Platform.
         Software Platform: a Software Platform is defined by an operating system, one or more programming
          language and a Middleware.
         VLT Process: Very Large Telescope Module is a Software Component running on VLT Software
          Platform as specified in [RD24].
         VLT Platform: Very Large Telescope Software Platform is based on Linux operating system
          (Scientific Linux distribution), GNU C++/TCL-TK programming languages, and CCS/EVH
          middleware as specified in [RD24, RD25, and RD26].
                  Generic State Machine Engine for ACS
                                                             Doc.           xxx-SPE-ESO-xxxxx-xxxx
    ESO           Software Requirements Specification
                                                             Issue
                                                             Date
                                                                            1.0 draft
                                                                            18/06/2010
                                                             Page           8 of 35

1.7      Overview
The structure of this document is driven by IEEE standards [RD01, RD02] with respect to the template and the
contents. IEE Std. “Guidelines for documentation of software in industrial computer systems” [RD03] has been
another valuable guideline.

Requirements are numbered using the following conventions:

[SRa.b.c]

Where:

SR       stands for Software Requirement

a        is the requirement group:
                  1 engine requirements
                  2 code generator requirements
                  3 model requirements

b        is the requirement type:
                  1 functional requirements
                  2 performance requirements
                  3 interface requirements
                  4 external requirements

c        is the requirement number
                    Generic State Machine Engine for ACS
                                                                    Doc.            xxx-SPE-ESO-xxxxx-xxxx
    ESO             Software Requirements Specification
                                                                    Issue
                                                                    Date
                                                                                    1.0 draft
                                                                                    18/06/2010
                                                                    Page            9 of 35



2 OVERALL DESCRIPTION

2.1       Reactive Systems and State Machines Models
A reactive system is a system that according to [RD04]:

         Continuously interacts with its environment using inputs and outputs that are either continuous in time
          or discrete.
         The inputs and outputs are often asynchronous meaning that they may arrive or change values
          unpredictably at any point in time (in contrast transformational systems repeatedly wait for all its inputs
          to arrive, carry out some processing, and outputs the results when processing is done).
         It must be able to respond to high priority events when it is busy doing something else (interrupts).
         Its operation and reaction to inputs often reflects stringent time requirements.
         It has many possible operational scenarios, depending on the current mode of operation and the current
          values of its data as well as its past behavior.
         It is very often based on interacting processes (entities) that operate in parallel

Examples are:

         Control systems such as chemical and manufacturing systems
         Embedded systems such as avionics, automotive, and telecommunication systems
         Online interactive systems such as automatic teller machines (ATMs), flight reservation systems
         Graphical User Interfaces (GUI)
         Games

Finite State Machines (FSM) are used to specify the "discrete part" of the behavior of reactive systems where
[RD05]:

         There is a finite and discrete set of states
         There is a discrete and manageable set of inputs
         Change of state is only performed in response to inputs (which can be any type of events such as
          commands, replies to commands, timers, UNIX signals, file I/O events, etc.)1

Statecharts is an extension of the Finite State Machine notation which was introduced by D. Harel to specify the
behavior of avionic systems (Israel Aircraft Industries) [RD21]. Statecharts notation has been included in the
UML standard [RD08], and it is an important component of all major tools for the development of software for
reactive systems: STATEMATE (IBM), Rhapsody (IBM), SCADE (Esterel Technologies), VisualSTATE (IAR
Systems), Stateflow (extension of Simullink, The MathWorks), LabView (National Instruments).

A subset of the Statecharts features have been implemented in the Workstation Software Framework (WSF)
[RD06] and successfully applied to the development of many control and coordination applications for the
VLTI (PRIMA, Delay Lines, Interferometric Supervisor Software), New Generation CCD (NGC), Active Phase
Experiment (APE).


2.2       Model Independent State Machine Engine
A State Machine Engine is an executable implementation of a State Machine Model. State Machine Engines can
be developed using different approaches: from the simple “switch” statements, or the State Design Pattern, up to
building an interpreter of State Machine Models. The definitions of “Model Independent State Machine Engine”
1
    Inputs can also be “internal” events: events triggered by actions/activities executed by the state machine itself.
                 Generic State Machine Engine for ACS
                                                               Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO             Software Requirements Specification
                                                               Issue
                                                               Date
                                                                               1.0 draft
                                                                               18/06/2010
                                                               Page            10 of 35

and “Model Dependent State Machine Engine” have been introduced in this document to classify two different
types of State Machine Engines: the ones whose implementation does not change when a different State
Machine Model is executed and the ones whose implementation does change.

In a Model Dependent SM Engine the model (states, transitions, etc.) is (hard) coded in the implementation
language and therefore defined at compile-time. Examples are:

       SM Engine based on "switch" statements
       SM Engine based on State Pattern [RD27] (like the Workstation Software Framework [RD06])

Disadvantages of this approach are:

       SM model must be defined at compile-time
       The size of the application is usually larger since it includes the logic of the SM
       SM Model and source code may easily get out-of-synch if the code is not generated from the model
        every time it is compiled

Advantages of this approach are:

       Performances and memory consumption can be optimized (since the State Machine Engine is build
        specifically for that given model)
       There is no need of the model once the application is built (or generated). In many cases the model can
        be reconstructed from the application if/when needed.

In a Model Independent SM Engine the model is stored in memory. The SM Engine provides APIs to create
states, transitions, etc and build up an in-memory representation of the model. The algorithm works with the in-
memory representation of the model to decide which transitions to take, which states to visit, which actions to
execute.

Disadvantages of this approach:

       Performances and memory consumptions may not be as good as the one of Model Dependent SM
        Engines
       The model is needed for the execution of the application
       No type-safe invocation of actions/activities

Advantages of this approach:

       SM Engine can be reused by the applications
           o Applications are smaller
           o Similar advantages of the libraries
       SM Model can be defined at:
           o Compile-time using the APIs provided by the SM Engine to build up the SM model.
              Development of actions, data, events is done using a compiled programming language.
           o Run-time using a parser which reads a SM Model Representation and calls the SM Engine APIs
              to instantiate the model. Note that in a fully Run-time SM Engine also data, actions and events
              are defined in the model and interpreted (i.e. the action language is interpreted). This approach
              provides the flexibility of changing at runtime the complete behavior of the application (similar
              to OSF scripts or the instrument templates) without the need of recompiling the application.
           o Partially at compile time and partially at run-time: data, actions and events are defined at
              compile time while states and transitions are loaded and interpreted at run-time.
                 Generic State Machine Engine for ACS
                                                               Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO             Software Requirements Specification
                                                               Issue
                                                               Date
                                                                               1.0 draft
                                                                               18/06/2010
                                                               Page            11 of 35

The decision of selecting which approach is the best is similar to evaluating the advantages and disadvantages of
interpreted vs. compiled programming languages. The mix case, where actions and data are compiled while the
state machine logic (states and transitions) are interpreted, is an interesting alternative that minimizes the
disadvantages of the compiled programming languages and introduces some of the advantages of the interpreted
languages: there is no need to recompile if the SM logic changes. Recompilation is needed only if data/actions
change which could be a positive effect since it forces the type checking.

The ability of quickly modifying the application behavior (i.e. the SM logic) without the need for recompiling
the code becomes an important feature in all the scenarios where last minute changes in the requirements have
to be quickly implemented and tested (for example during commissioning/deployment). As a matter of fact both
VLT and ACS platforms provide a scripting language (TCL/TK for VLT, Python for ACS) for fast prototyping
and coding of high level procedures that are very likely to change during commissioning (VLT OSF scripts for
calibration, system start-up/shutdown, automatic acquisition of performance data, etc.). The lack of this feature
in WSF has been experienced during the APE commissioning where the coded SM logic for the calibration
procedures had to be modified several times due to incomplete requirements. The need of a Model Independent
SM Engine is also one of the lessons learned in the development of the State Machine Sequencer for the Keck
Interferometer [RD22].


2.3     Model Representation
State machine models can be represented using:
     Tabular form (State Diagrams or State Transition Diagrams)
         incompleteness of a specification can be easily identified as empty cells in the table
         tables are relatively compact
        - difficult to understand using visual inspection
        - composite and orthogonal state representation is not easy to describe
     Annotated in the source code: SM model is annotated in the source code which is preprocessed and
        translated into code to be compiled (for example the Boost Statechart Library, the SMC State Machine
        Compiler).
     UML
         It is a standard from OMG [RD08]
         UML is supported by many tools (although adherence to the standard may not be the same)
        - The UML XMI representation was supposed to be read only by tools and it includes a lot of
            additional information which are not related to the state machine model.
        - Statecharts semantics is not completely and unambiguously specified (i.e. the same model running
            on different SM Engine can have different behavior) [RD20]
     SCXML
         It is a standard from WWW Consortium [RD07]
         It is more readable than UML since it focus only on Statecharts, actions, and data
         Statecharts semantics is specified better than in UML (since it includes the algorithm)
        - Not yet supported by many UML tools (only IBM Rational SW Architect and MagicDraw)
     Text file: in WSF the SM model is described in a text file using a simple syntax. From this text file the
        code is generated. When using UML tools (like Rational ROSE or MagicDraw), WSF converts the
        UML model into the text file and then it generates code from the text file.

Advantages/Disadvantages of text file:
    Text editors are free and it is easy to exchange data files (UML tools can be expensive and usually some
       training is required)
    Some people do not like UML and/or graphical tools, they prefer text based syntax
    Simple text based syntax is easy to manipulate using tools like grep, awk
   - Big model (more than 20 states and 50 transitions for example) are difficult to understand using text
       files
                   Generic State Machine Engine for ACS
                                                                   Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO               Software Requirements Specification
                                                                   Issue
                                                                   Date
                                                                                   1.0 draft
                                                                                   18/06/2010
                                                                   Page            12 of 35

      -   It is difficult to understand composite/orthogonal state relations using textual representation

Advantages/Disadvantages of graphical tools:
    Big models can be split in views
    Statecharts are based on a graphical (topological) notation which makes very intuitive the representation
       of composite and orthogonal states
   - Different tools have different file format and very often they cannot be exchanged (this is important to
       consider when migrating to a different tool).

Among the SM Model representation described above, SCXML is the only one that provides a readable
standard text representation of SM Models and defines precisely the semantics. In addition some UML
graphical tools are starting supporting the SCXML format adding the graphical view to the textual
representation. Finally SCXML Engines are Model Independent since they can execute any SM Model in
SCXML format.


2.4       Generic State Machine Engine
A Generic State Machine Engine is simply a SM Engine that allows generating from the same SM Model,
Software Component skeletons that can be compiled on different Software Platforms. The ability to support
multiple platforms increases SM Model reuse and therefore reduces development and test time.

The main goal of the Generic State Machine Engine project is to develop a tool that can facilitate the creation of
state machine based Software Components for the VLT and ACS Software Platforms. The architecture is built
on top of a Java and C++ SCXML Engine which executes SCXML Models. A Generator takes as input the
configuration on the target platform (Platform Configuration) and the UML Model to generate: all the Model
Dependent Code, the Build Procedure (for example the Makefile) and the SCXML Model. Examples of Model
Dependent Code are: the code to propagate the events to the SCXML Engine, Actions, Guards, and Activities
skeletons. Platform Adapters Libraries, used to provide a standard interface for services like logging, error
handling, messaging etc. (i.e. to abstract the Software Platform specific services), are compiled together with the
SCXML Engine, and the Model Dependent Code to build the Software Component (Figure 1).
                  Generic State Machine Engine for ACS
                                                                Doc.        xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                Issue
                                                                Date
                                                                            1.0 draft
                                                                            18/06/2010
                                                                Page        13 of 35




                            Figure 1 - Generic State Machine Engine Data Flow.

Table 3 provides a detailed description of the GSME elements.

     Element            Provided /          Software                          Description
                       Generated by         Platform
                                          Independent
UML Model             User               Yes               Contain the UML SM Model
SCXML Model           User / Generator   Yes               Transformation from the UML SM Model
SCXML Engine          GSME library       Yes               Executes the SCXM Model
Platform              User               No                Configure the Generator to generate code for a
Configuration                                              given Software Platform (it includes code
                                                           templates etc.)
Generator             GSME                                 Generates the SCXML Model, all the platform
                      application                          dependent code including the build procedure
Build Procedure       Generator          No                Automatic procedure to build a Software
                                                           Component for a given Software Platform. It
                                                           includes the directives needed to build/link the
                                                           SCXML Engine which may depend to the Software
                                                           Platform.
Model Dependent       Generator          No                All code which is SM Model dependent such as
Code                                                       Actions, Guards, Activities skeletons, propagation
                                                           of events to the SCXM Engine, etc. Usually this
                                                           code is also Software Platform specific.
Platform Adapters     GSME library       No                Adapts the SCXML Engine interface for services
Libraries                                                  like logging, error handling, etc. to the interface
                                                           provided by the Software Platform.
                Generic State Machine Engine for ACS
                                                           Doc.          xxx-SPE-ESO-xxxxx-xxxx
 ESO            Software Requirements Specification
                                                           Issue
                                                           Date
                                                                         1.0 draft
                                                                         18/06/2010
                                                           Page          14 of 35

Compiler            Software Platform   No              All the tools, provided by the Software Platform,
                                                        needed to build a Software Component.
Software            Compiler            No              The result of the building together the SCXML
Component                                               Engine, the Model Dependent Code, the Platform
                                                        Adapters Libraries and any other user defined
                                                        library.
                                        Table 3 - GSME Elements.



2.5    Generic State Machine Engine for ACS
The Generic State Machine Engine for ACS is an implementation of the Generic State Machine Engine to be
used to create ACS Components running on ACS Platform. It uses the Java SCXML Engine and the Java ACS
Platform Adapters Libraries.

ACS is based on CORBA which supports both synchronous and asynchronous method invocation. According to
the SCXML standard [RD07, Algorithm for SCXML Interpretation], the SCXML engine should support
asynchronous events in the sense that events are stored in a queue and processed one by one by the
engine..Therefore a mechanism to handle synchronous method invocation has to be put in place to block the
caller until the processing of the method is completed (Figure 2).
                Generic State Machine Engine for ACS
                                                            Doc.           xxx-SPE-ESO-xxxxx-xxxx
 ESO            Software Requirements Specification
                                                            Issue
                                                            Date
                                                                           1.0 draft
                                                                           18/06/2010
                                                            Page           15 of 35




                                  Figure 2 - Synchronous CORBA call.

Transformation of asynchronous CORBA calls into state machine events is straightforward as shown in Figure
3.
                Generic State Machine Engine for ACS
                                                           Doc.           xxx-SPE-ESO-xxxxx-xxxx
 ESO            Software Requirements Specification
                                                           Issue
                                                           Date
                                                                          1.0 draft
                                                                          18/06/2010
                                                           Page           16 of 35




                                 Figure 3 - Asynchronous CORBA call.


2.6    Generic State Machine Engine for VLT
The Generic State Machine Engine for VLT is an implementation of the Generic State Machine Engine to be
used to create VLT modules running on VLT Platform. It uses the C++ SCXML Engine and the C++ VLT
Platform Adapters Libraries.

VLT software is based on CCS/EVH which provides events (commands, command’s replies, timers, database
change notification, UNIX signals, file I/O, etc.) via callbacks (Figure 4).
                 Generic State Machine Engine for ACS
                                                                Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO             Software Requirements Specification
                                                                Issue
                                                                Date
                                                                                1.0 draft
                                                                                18/06/2010
                                                                Page            17 of 35




                                   Figure 4 - Asynchronous VLT command.



2.7     Error Handling
There are three different ways to handle errors:
     At model level: by having actions/activities generating error events defined in the state machine model.
        Error events can trigger a change of state or the execution of actions responsible to react to errors (for
        example by sending error replies).
                   Generic State Machine Engine for ACS
                                                                 Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO               Software Requirements Specification
                                                                 Issue
                                                                 Date
                                                                                 1.0 draft
                                                                                 18/06/2010
                                                                 Page            18 of 35

       Using an error reporter interface to report non fatal errors to platform specific error handling system. An
        instance of the error reporter class is injected in all actions/activities and is responsible to convert the
        error from the SCXML Engine context into the platform specific error handling context.
       Using exceptions to report fatal errors. For software platforms which do not supports exceptions,
        SCXML Engine exceptions have to be converted into the platform specific error structure (for example
        CCS error stack).


2.8      Logging
Java SCXML Engine logging interface: Java standard logging
C++ SCXML Engine logging interface: Log4c++

Adapters have to be provided to translate the Log4c++ logs into CCS logs specific to the VLT Software
Platform.

2.9      Unit Tests
Java SCXML Engine unit test framework: JUnit.
C++ SCXML Engine unit test framework: CppUnit.
GSME for ACS unit test framework: TAT [RD09].
GSME for VLT unit test framework: TAT [RD23].
                 Generic State Machine Engine for ACS
                                                               Doc.           xxx-SPE-ESO-xxxxx-xxxx
 ESO             Software Requirements Specification
                                                               Issue
                                                               Date
                                                                              1.0 draft
                                                                              18/06/2010
                                                               Page           19 of 35



3 SCXML Engine Requirements
This chapter lists the GSME SCXML Engine requirements.

3.1     Functional Requirements
3.1.1       Model Independent State Machine Engine [SR1.1.1]
The tool shall provide a model independent state machine engine.

Rationale: a model independent state machine engine allows changing the model (in full or in part) at run time.
A model independent state machine engine can be easily reused. The State Pattern is an example of model
dependent state machine architecture since the state classes depends on the model: the bigger the model the
larger the number of classes in the application. For more details see paragraph 2.2.
Priority: high.
Note:

3.1.2       SCXML State Machine Model [SR1.1.2]
The state machine engine shall be able to execute state machine model provided in SCXML format.

Rationale: SCXML is a W3C standard [RD07]. SCXML state machine models can be created and modified
using a text editor. SCXML format is more readable than UML XMI since it is limited to Statecharts. For more
details see paragraph 2.3.
Priority: high.
Note:

3.1.3       Support of SCXML Features [SR1.1.3]
The state machine engine shall support the following state machine features defined by the SCXML standard:
    composite states
    orthogonal states
    actions
    invoke (activities)
    guards
    shallow and deep history state
    initial and final pseudo-states
    IsIn

Rationale: these features first introduced by D. Harel [RD15] proved to be important when modeling control
applications for telescope domain using the Workstation Software Framework [RD06]. In particular composite
states reduce the number of transitions and orthogonal states the number of states.
Priority: high.
Note:

3.1.4       Actions Mapping [SR1.1.4]
Each action defined in the state machine model shall be mapped to a method of a class.

Rationale: the alternative would be to map each action to a class which can be expensive in terms of compile
time for the C++ platforms. Note that the instantiation of the class is done outside the SCXML engine and
injected in the SCXML engine at initialization time.
                  Generic State Machine Engine for ACS
                                                                  Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                  Issue
                                                                  Date
                                                                                  1.0 draft
                                                                                  18/06/2010
                                                                  Page            20 of 35

Priority: high.
Note:

3.1.5       Guards Mapping [SR1.1.5]
Each guard defined in the state machine model shall be mapped to a method of a class.

Rationale: the alternative would be to map a guard to a class which can be expensive in terms of compile time
for the C++ platforms.
Priority: high.
Note: the instantiation of the class is done outside the SCXML engine and injected in the SCXML engine at
initialization time.

3.1.6       Activity Mapping [SR1.1.6]
Each activity defined in the state machine model shall be mapped to a C++/Java class that can be executed as
separate thread.

Rationale: usually the behavior of activities is more complex than the basic behavior implemented by actions,
and therefore it may require a more sophisticated structure (several methods and attributes). This is also
consistent with the Java Callable interface.
Priority: high.
Note: the instantiation of the class is done outside the SCXML engine and injected in the SCXML engine at
initialization time.

3.1.7       Action Grouping [SR1.1.7]
The tool shall provide the possibility to group a set of actions in one class by defining the action name as follow:
className.methodName. Where className is the name of the class and methodName is the name of the
method inside the class.

Rationale: this allows to group more than one action in a class and to share common data (i.e. class attributes).
Being able to group more actions within one class introduces the possibility to easily share data (the attributes of
the class) among the group of actions.
Priority: high.
Note: after converting UML to SCXML it should be possible to identify from the action name the class and the
method.

3.1.8       Guard Grouping [SR1.1.8]
The tool shall provide the possibility to group a set of guards in one class by defining the guard name as follow:
className.methodName. Where className is the name of the class and methodName is the name of the
method inside the class.

Rationale: this allows to group more than one guard in a class and to share common data (i.e. class attributes).
Priority: high.
Note: after converting UML to SCXML it should be possible to identify from the guard name the class and the
method.

3.1.9       Action Group Initialization [SR1.1.9]
Action groups shall provide an interface to initialize the internal data structures at application's start-up or when
the application is re-initialized.
                  Generic State Machine Engine for ACS
                                                                  Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                  Issue
                                                                  Date
                                                                                  1.0 draft
                                                                                  18/06/2010
                                                                  Page            21 of 35

Rationale: relying only in the class constructor to initialize the attributes may not be enough especially if the
object is created only at start-up. An initialization method can be invoked every time there is the need to re-
initialize the application.
Priority: high.
Note:

3.1.10      Action Group De-initialization [SR1.1.10]
Action groups and activities should provide an interface to de-initialize the internal data structures.

Rationale: in Java it is the garbage collector that decides when to call the destructor (i.e. it is not known when
the destructor of Java classes is invoked).
Priority: high.
Note:

3.1.11      Actions, Guards and Activities Shared Data [SR1.1.11]
It shall be possible to share data among actions, guards and activities even if they belong to different groups.

Rationale: in addition to share data among the actions and guards in the same group, it is sometimes needed to
share data among action actions, guards, and activities which are global to the whole software component. For
example: the command-line parameters or configuration parameters used by actions belonging to different
groups.
Priority: high.
Note:

3.1.12      Actions Invocation within an Action [SR1.1.12]
It shall be possible from inside an action to invoke another action defined in another group.

Rationale: reuse of basic actions to create more complex actions.
Priority: high.
Note:

3.1.13      Trigger Event Access within Actions, Guards, Activities [SR1.1.13]
It shall be possible from inside an action, guard, or activity, to access the event which triggered the
action/guard/activity itself.

Rationale: events and the associated payload are often needed as input to execute actions, guards and activities.
Priority: high.
Note: For the actions and guards, the trigger event is the last event. For activities the last event may not coincide
with the trigger event since before the activity is scheduled other events may be processed by the engine.

3.1.14      Action and Guard Reuse [SR1.1.14]
It shall be possible to reuse actions and guards and build libraries of actions and guards.

Rationale: the possibility to reuse actions and guards by different applications reduces the development and
maintenance time. The SCXML Engine has to provide an interface to easily install or replace actions and
guards’ implementations. It should be possible for the developer to decide which actions and guards’
implementations to use in a given Software Component.
Priority: high.
Note:
                  Generic State Machine Engine for ACS
                                                                  Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                  Issue
                                                                  Date
                                                                                  1.0 draft
                                                                                  18/06/2010
                                                                  Page            22 of 35

3.1.15       Action and Guard Extensibility [SR1.1.15]
It shall be possible to extend actions and guards implementation.

Rationale: the possibility to extend actions and guards reduces the development time. Since actions and guards
are grouped in classes, extensibility could be achieved via class inheritance.
Priority: high.
Note:

3.1.16       Error Handling within Actions, Guards, and Activities [SR1.1.16]
It shall be possible to generate errors from within actions, guards, activities, and shared data structures using a
standard error interface.

Rationale: error reporting. Note that it is always possible to handle errors at model level by having
actions/guards/activities generating error events, and by defining transitions to react to error events. Here the
requirement focuses on having a standard error interface to be used from within actions/guards/activities to
propagate errors to the supporting software platform (i.e. VLT/ACS).
Priority: high.
Note:

3.1.17       Logging within Actions, Guards, Activities, Shared Data [SR1.1.17]
It shall be possible to log information from within actions, guards, activities, and shared data using a standard
logging interface.

Rationale: support for log services.
Priority: high.
Note:

3.1.18       State Machine Engine Logging [SR1.1.18]
It shall be possible to enable/disable the logging of the following information separately:

        upon event detection: the event
        upon state change: the new status
        upon guard evaluation: the full name (including the group) of the guard and the return value
        upon action invocation: the full name (including the group) of the action
        upon activity invocation: the name of the activity

Rationale: makes easier debugging/monitoring.
Priority: high.
Note:

3.1.19       State Machine Engine Logging History [SR1.1.19]
It shall be possible to configure size and access via API the content of the history of the last N transitions taken
by the state machine engine. The history shall include:

        upon event detection: the event
        upon state change: the previous and new status
        upon guard evaluation: the full name (including the group) of the guard and the return value
        upon action invocation: the full name (including the group) of the action
        upon activity invocation: the name of the activity
                  Generic State Machine Engine for ACS
                                                                  Doc.             xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                  Issue
                                                                  Date
                                                                                   1.0 draft
                                                                                   18/06/2010
                                                                  Page             23 of 35


Rationale: makes easier debugging/monitoring.
Priority: high.
Note:

3.1.20      State Machine Engine Error Handling [SR1.1.20]
The state machine engine shall generate exceptions to report fatal run-time errors (TBD).

Rationale:
Priority: high.
Note:

3.1.21      State Machine Engine Status [SR1.1.21]
The state machine engine shall provide an API to query the current status (i.e. the set of active states).

Rationale: monitoring of the application.
Priority: high.
Note:

3.1.22      Generation of Events from Inside Action and Activities [SR1.1.22]
It shall be possible from within actions and activities to generate asynchronous events.

Rationale: State Machines Models describes the reaction of the Software Components not only to external
events but also internally generated events like. An example of internally generated events is a timer event.
Priority: high.
Note:

3.1.23      Handling of Rejected Events [SR1.1.23]
It shall be possible to specify the behavior of the state machine engine when receiving events which are not
handled in the current state. The default behavior is to ignore the event.

Rationale: often it is useful for debugging purpose to monitor which events are received and ignored without
having to specify them in the model using self-transition and reject actions (time consuming and tedious
activity).
Priority: medium.
Note:

3.1.24      Event Interface [SR1.1.24]
The GSME shall provide a public interface to be used to add events to be processed.

Rationale: the event interface is used by action/activities to generate internal events. It is also used by the
platform adapters to propagate external events to the state machine engine.
Priority: high
Note:

3.1.25      Mapping of Events [SR1.1.25]
Events shall be mapped to an instance of a generic event class. The event class shall include the event name
attribute and the data (payload) associated with the event.
                  Generic State Machine Engine for ACS
                                                                  Doc.           xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                  Issue
                                                                  Date
                                                                                 1.0 draft
                                                                                 18/06/2010
                                                                  Page           24 of 35

Rationale: other attributes can be included like the type of the event or the priority if needed. Event class can be
extended via inheritance or composition.
Priority: high.
Note:

3.1.26      Extensibility of Shared Data [SR1.1.26]
It shall be possible to reuse/extend existing shared data structures.

Rationale: reusability. Data shared among groups of actions, guards and activities
Priority: high.
Note:


3.2      Performance Requirements
3.2.1       Memory Consumption [SR1.2.1]
TBD

3.2.2       Event Propagation Time [SR1.2.2]
TBD

3.2.3       Transition Execution Time [SR1.2.3]
TBD

3.2.4       Action Invocation Time [SR1.2.4]
TBD


3.3      Interface Requirements
Public interface requirements still TBD.

3.4      External Requirements
3.4.1       Support of Java [SR1.4.1]
The State Machine Engine shall support actions, activities, guards and shared data implemented in Java.

Rationale: needed to support ACS Platform.
Priority: high
Note:

3.4.2       Support of C++ [SR1.4.2]
The State Machine Engine shall support actions, activities, guards and shared data implemented in C++.

Rationale: needed to support VLT Platform.
Priority: high
Note:
                  Generic State Machine Engine for ACS
                                                                 Doc.    xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                 Issue
                                                                 Date
                                                                         1.0 draft
                                                                         18/06/2010
                                                                 Page    25 of 35

3.4.3        Unit Tests [SR1.4.3]
The State Machine Engine shall provide a set of unit test for:

       basic event types (TBD)
       actions, guards, activities
       supported SCXML features
       supported languages

Rationale: unit tests, regression tests.
Priority: high
Note:

3.4.4        Online Documentation [SR1.4.4]
The State Machine Engine source code shall contain documentation in Doxygen comments format.

Rationale: to build online documentation.
Priority: high.
Note:
                   Generic State Machine Engine for ACS
                                                               Doc.           xxx-SPE-ESO-xxxxx-xxxx
 ESO               Software Requirements Specification
                                                               Issue
                                                               Date
                                                                              1.0 draft
                                                                              18/06/2010
                                                               Page           26 of 35



4 Generator Requirements
This chapter lists the requirements on:
     the code generator tool
     the generated code
     additional services that can help the developer to finalize a software component (e.g. libraries providing
        utility functions)

4.1       Functional Requirements
4.1.1        Configuration [SR2.1.1]
The code generator shall be able to read the target software platform and other configuration options from
command line parameters or from a configuration file. The configuration file shall be located either in the
current directory or in the directory defined in GSME_ROOT environment variable. The following options shall
be supported:
     Target software platform (VLT, ACS)
     Location of fully generated code (i.e. code completely generated and that the developer should touch)
     Location of partially generated code (stubs or templates which have to be completed by the developer)
     Location of templates used to generate the code
     Location of the UML model/SCXML model (TBD)

Rationale: support multiple platforms.
Priority: high
Note:

4.1.2        Software Component Skeleton and Start-up/Shutdown [SR2.1.2]
The tool shall generate/provide an application skeleton able to compile, start-up and shut-down a Software
Component:

         directory structure
         the build procedure (makefile)
         the code to instantiate the state machine engine
         the code to load the state machine model form an SCXML file
         the code to load application configuration
         the code to initialize the actions, guards, and shared data
         the code to initialize event handlers
         the code to deinitialize the actions, guards, and shared data
         the code to remove event handlers
         the code to clean-up the state machine engine
         the run-time configuration skeleton
         the test skeleton

Rationale: create the software component.
Priority: high.
Note:

4.1.3        Event Handling [SR2.1.3]
The tool shall generate/provide all the code needed to detect events defined in the UML state machine and
propagate them to the state machine engine.
                  Generic State Machine Engine for ACS
                                                               Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                               Issue
                                                               Date
                                                                               1.0 draft
                                                                               18/06/2010
                                                               Page            27 of 35


Rationale: provide events to the state machine engine.
Priority: high.
Note:

4.1.4       Supported Events [SR2.1.4]
The tool shall support the following types of events:

       Command/replies (VLT command reply or CORBA IDL calls)
       File I/O events (including sockets)
       UNIX signals
       Timer events
       Change of attribute events (VLT DB, ACS properties)
       Internal events (generated by actions/activities and consumed by the state machine engine)
       Completion events generated by do activities when they terminates

Rationale:
Priority: high.
Note:

4.1.5       Asynchronous Events [SR2.1.5]
The tool shall support asynchronous events.

Rationale: SM usually deals with asynchronous events, i.e. the event can be stored somewhere and processed by
the SM Engine when it has time. VLT CCS messages are intrinsically asynchronous events since they are
exchanged via queues. For example a CCS command is put in the queue of the destination Software Component
and after the processing is completed the reply is added to the queue of the originator of the command.
Priority: high.
Note:

4.1.6       Synchronous Events [SR2.1.6]
The tool shall support synchronous events.

Rationale: to handle (ACS) CORBA synchronous calls. Synchronous events have to be “transformed” in
asynchronous to be able to process them when the SM Engine has the time to do it.
Priority: high.
Note:

4.1.7       Generation of Sequence of Events [SR2.1.7]
The tool shall provide to actions and activities the services needed to generate a sequence of asynchronous
events.

Rationale: this is useful when a sequence of commands has to be sent and only the last reply event needs to be
processed by the state machine engine (avoiding modeling intermediate reply events). Consider for example the
case where to initialize a device a series of successful commands have to be sent and only the final state of
device “initialized” or “not initialized” is considered important (i.e. worth modeling). The final result is a
simpler SM model that contains only what the designer really wants to model.
Priority: medium.
Note:
                  Generic State Machine Engine for ACS
                                                                   Doc.             xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                   Issue
                                                                   Date
                                                                                    1.0 draft
                                                                                    18/06/2010
                                                                   Page             28 of 35

4.1.8        Generation of Parallel Events [SR2.1.8]
The tool shall provide to actions and activities the services needed to generate in parallel a set of asynchronous
events.

Rationale: this is useful when a set of commands has to be sent in parallel and only the last reply needs to be
processed by the state machine engine (avoiding modeling the other reply events). Consider for example the
case where to fully initialize a device a set of successful commands have to be sent to sub-devices (and they can
be sent in parallel) and only the final state of device “initialized” or “not initialized” is considered important (i.e.
worth modeling).
Priority: medium.
Note:

4.1.9        Handling of Superseded Events [SR2.1.9]
The tool shall provide to actions and activities the services needed to supersede an event if received twice.

Rationale: useful to replace the execution of a command with a new one carrying more up-to-date information.
Priority: medium.
Note: This requirement has to be better specified: most of the superseding is done at model level: the tool should
provide some functions to easily reply an abort error to the originator of the superseded command.

4.1.10       Action, Guards and Activity Skeletons [SR2.1.10]
The tool shall generate a skeleton of the actions, guards and activities from the UML state machine model. The
skeleton shall include:

        standard constructor and destructor
        skeleton of the init and de-init method
        skeleton of the action/guard/run method

Rationale: this reduces the development time.
Priority: high.
Note:

4.1.11       Access to Unit Testing Setup [SR2.1.11]
The tool shall guarantee access to the unit testing infrastructure provided by the platform.

Rationale: reduce test development time.
Priority: high.
Note:

4.1.12       Start-up and Shutdown Unit Test [SR2.1.12]
The tool shall provide a unit test to verify the correct start-up and shut-down of the application.

Rationale: basic test.
Priority: high.
Note:

4.1.13       Statistics on the Generated/hand-written Lines of Code [SR2.1.13]
The tool shall provide the possibility to count the LOC generated and hand-written.
                  Generic State Machine Engine for ACS
                                                                   Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                   Issue
                                                                   Date
                                                                                   1.0 draft
                                                                                   18/06/2010
                                                                   Page            29 of 35

Rationale: collection of statistical information needed to estimate costs.
Priority: low.
Note:

4.1.14       Statistics on Size of the Model [SR2.1.14]
The tool shall provide the possibility to count the number of states, transitions, actions, activities, events in the
model.

Rationale: collection of statistical information needed to estimate costs.
Priority: low.
Note:

4.1.15       Deletion of Generated Files [SR2.1.15]
The tool shall provide the possibility to delete all (fully) generated files.

Rationale:
Priority: high.
Note:

4.1.16       Backup of Partially Generated Files [SR2.1.16]
The tool shall provide the possibility make a backup of the partially generated files before overwriting them.

Rationale: risk of losing hand-written code.
Priority: high.
Note:

4.1.17       Location of Generated Files [SR2.1.17]
The tool shall provide the possibility to specify in which directory to write generated files.

Rationale: to support different build procedures.
Priority: high.
Note:

4.1.18       Code Generator Log [SR2.1.18]
The tool shall provide a log with the list of all files generated/modified.

Rationale: debugging.
Priority: high.
Note:

4.1.19       Documentation of Generated Code [SR2.1.19]
Generated code shall contain documentation in Doxygen comments format.

Rationale: to build online documentation.
Priority: high.
Note:
                   Generic State Machine Engine for ACS
                                                                Doc.          xxx-SPE-ESO-xxxxx-xxxx
 ESO               Software Requirements Specification
                                                                Issue
                                                                Date
                                                                              1.0 draft
                                                                              18/06/2010
                                                                Page          30 of 35

4.2       Performance Requirements

4.3       Interface Requirements

4.4       External Requirements

4.4.1        Support of Alma Common Software Platform [SR2.4.1]
The tool shall generate ACS Components for the ACS software platform which is based on:

         Red Hat Linux operating system
         Java programming language
         ACS middleware

Rationale: help the development of new application based on ACS.
Priority: high.
Note:

4.4.2        Support of Very Large Telescope Platform [SR2.4.2]
The tool shall be able to generate VLT SW Modules for the VLT software platform which is based on:

         Scientific Linux operating system
         C++ programming language
         CCS middleware

Rationale: development of second generation instruments.
Priority: low.
Note:

4.4.3        Support for MagicDraw Tool [SR2.4.3]
It shall be possible to use MagicDraw UML modeling tool to define the state machine model and to export it
into SCXML format. The mapping of UML Statecharts to SCXML is TBD.

Rationale: to allow visual modeling of state machine. MagicDraw is the UML tool adopted by ESO Software
Development Division.
Priority: high
Note:

4.4.4        Default State Machine Model [SR2.4.4]
The tool shall provide a UML model of the default state machine with the basic platform specific states,
transitions, and actions.

Rationale: to speed up the design of the state machine model.
Priority: high
Note:

4.4.5        Unit Tests [SR2.4.5]
                  Generic State Machine Engine for ACS
                                                                Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                Issue
                                                                Date
                                                                                1.0 draft
                                                                                18/06/2010
                                                                Page            31 of 35

The code generator shall provide a set of unit test to test the code generation from the state machine models
with:

       supported event types
       actions, guards, activities
       supported SCXML features
       supported platforms

Rationale: testing and regression tests.
Priority: high
Note:

4.4.6       Online Documentation [SR2.4.6]
Code Generator source code shall contain comments in Doxygen format.

Rationale: to build online documentation.
Priority: high.
Note:
                  Generic State Machine Engine for ACS
                                                                  Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO              Software Requirements Specification
                                                                  Issue
                                                                  Date
                                                                                  1.0 draft
                                                                                  18/06/2010
                                                                  Page            32 of 35



5 Model Requirements
This chapter lists the GSME requirements for the models to be used to generate the code. The model is split in
two parts: one describing the component’s interface and its behavior, using a state machine, and another part
defining the deployment of the component to a specific platform. For convenience the first part is called
Component Model and the second one Deployment Model.


5.1     Functional Requirements
5.1.1       UML Profile [SR3.1.1]
The domain specific stereotypes to characterize the Component Model and the Deployment Model shall be
defined in a UML profile.
The semantics of the stereotypes and their relationships shall be documented with a meta model.

Rationale: only a subset of UML is used by the GSME and it is convenient to clearly identify (via stereotypes
and tags for example) what is the part of the UML model that should be used to generate the code and what can
be ignored.
Priority: high.
Note:

5.1.2       Component Model [SR3.1.2]
The Component Model shall contain the following information:
      The component’s public interface
      The component’s behavior, using a UML State Machine
In the public interface it shall be possible to specify the following elements:
      Synchronous operations
      Asynchronous operations
      Topics that the component can subscribe to

Rationale: the public interface is needed to generate the code to handle external events and propagate them to
the SM engine. The SM model is used to create the SCXML model.
Priority: high.
Note:

5.1.3       Component Model Consistency [SR3.1.3]
Interfaces and triggers of events for the SM shall be represented by the same model element.

Rationale: it is important to make sure that a change in the interface is automatically propagated to the SM
model and vice-versa to ensure model consistency.
Priority: medium.
Note:

5.1.4       Component Model Interface Reusability [SR3.1.4]
It shall be possible to reuse the interfaces of other Components.

Rationale: reuse of existing interfaces.
Priority: medium.
Note: a component’s public interface can extend and/or include another component’s interface.
                 Generic State Machine Engine for ACS
                                                              Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO             Software Requirements Specification
                                                              Issue
                                                              Date
                                                                              1.0 draft
                                                                              18/06/2010
                                                              Page            33 of 35



5.1.5       Platform Independent Component Model [SR3.1.5]
The Component Model shall be platform independent (i.e. it shall not include platform specific information).

Rationale: model reusability on different software platforms.
Priority: high.
Note: platform specific information (deployment information) can be added to the deployment model in order to
specify for which platform the code has to be generated.

5.1.6       Deployment Model [SR3.1.6]
The Deployment Model shall contain the following information:
     The specification of the software platform: programming language (C++, Java), middleware (ACS,
       VLT), type of publish-subscribe implementation (CORBA notification channel, DDS, none).
     The specification of the execution environment: ACS Container, VLT CCS environment
     The specification of the machine where to run the execution environment and the component
     The specification of the name of the configuration item (e.g. CMM/CVS module) that contains the
       component

Rationale: SW platform is needed to know the language and platform for which the code is generated. The name
of the package is mapped to the directory structure of the CVS/CMM module. Execution environment and
machine are optional and used to run the generated component.
Priority: medium.
Note:


5.2     Performance Requirements

5.3     Interface Requirements

5.4     External Requirements
                Generic State Machine Engine for ACS
                                                               Doc.            xxx-SPE-ESO-xxxxx-xxxx
 ESO            Software Requirements Specification
                                                               Issue
                                                               Date
                                                                               1.0 draft
                                                                               18/06/2010
                                                               Page            34 of 35



6 Notes
Below are comments/notes to be discussed and either deleted or added as new requirements:

      Add model requirement on the SM inheritance?

      Simulation mode: to be implemented at model level with orthogonal regions and IsIn operator.

      UML tags vs Naming conventions
         o The requirement to group actions can be implemented specifying a UML tag for the action
             which contains the name of the group (or even the class/method). This has two disadvantages:
                   when exporting UML Statechart to SCXML the tag will probably get lost
                   the group name is not visible in the statechart diagram (at least with MagicDraw)
                   the user has to open a second dialog to enter the group name (in case of assiciation to a
                      class, the user has also to create the class/method in a class diagram)
         o The naming convention (className.methodName) has the disadvantage that it is not formal
             (i.e. cannot be checked at model level).

      Automatic update of the change log

      Backup of fully generated files: should not be needed in case the build procedure includes by default the
       re-generation of the code from the model.

      Build procedure: by default shall the build procedure include the generation of the code and SCXML
       file from the UML model? Consider Paranal operational environment where they may have to fix a bug
       quickly without wanting to generate

      Model checking: add req. related to check the model consistency/validity?

      Handling of platform specific naming conventions: this includes VLT module prefixes etc.

      SM inheritance: done in S CXML by including XML files (to be tested)

      support for additional pseudo-states (join, fork, junctions, choice)
          o final pseudo-states (*) -> region has completed, no more transition takes place within it
          o terminate pseudo-states X -> the state machine has completed (i.e. SM terminates: object will
               not respond to events via its SM)

      states supporting deferred events

      events with priority

      change terminology to respect UML (event -> trigger, action -> effect, active state, active regions,
       regions never rest in pseudo-states)
           o signal events => asynch messages
           o time events => timers
           o change events =>
           o call events => blocking operation requested

      substate machines
      Generic State Machine Engine for ACS
                                             Doc.    xxx-SPE-ESO-xxxxx-xxxx
ESO   Software Requirements Specification
                                             Issue
                                             Date
                                                     1.0 draft
                                                     18/06/2010
                                             Page    35 of 35




                            ___oOo___

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:5
posted:8/28/2011
language:French
pages:35