Using Enterprise Architect (EA)

to Create Statecharts
Introduction
• Enterprise Architect (EA) is standard tool for generating Unified
Modeling Language (UML) diagrams
• This presentation describes EA version 7.0.818
• Focus is on UML statecharts, not other UML modeling elements
• EA can export its UML model in XML Metadata Interchange (XMI),
version 2.1, format
• Hierarchical StateMachine (HSM) Software Building block
(bb_state_eng in the kok_aud Synergy database)
• Creates and RTOS-independent Library from ANSI C code
• Executes a large subset of UML statechart semantics
• Uses the C preprocessor to create the tables used by the engine to
execute the statechart
• The PC program, gen_hsm, bridges the gap between EA and the
HSM engine
• Reads in and parses the XMI data exported by EA
• Checks for “ill formed” statecharts and issues any pertinent warnings
• Outputs C code that contains the statechart declaration for the HSM
building block
Development Flow
sd Statechart Engine Ov erv iew

Enterprise Architect
«use»

«use»

«generate» «use» Softw are Engineer

«write»
Compiler /Linker
Exported XMI Model

«translate»
«flow»
Product Softw a re Source Code «flow»
gen_hsm
HSM Engine Building Block

«generate» Product Image

Statechart Im plementation
Generated Statechart
Declarations (C code)
«merge»
What You Need to Know,
What• This Presentation
This presentation
statecharts
assumes aWill Cover
basic knowledge of UML

• This presentation does not cover the integration and

use of the HSM engine building block in product
code
• This presentation will build on the above knowledge
• Provide specific tips and guidelines for using EA to create
models that are compatible with the generator
• Provide examples and tips on how to implement UML
elements using EA
• Show how to check and export an EA model
• Show how to run gen_hsm
• Discuss how to integrate the gen_hsm output into product
code
Basic Rules/Conventions
For Creating EA Statecharts:
Create
Use Classes• as statechart
Containers diagrams inside UML Classes whose behavior they
for Statecharts
describe; do not create statecharts outside the context of a UML class
• EA allows statechart diagrams to be placed essentially anywhere in the
model
• EA presents all statecharts at the same modeling level as “one big
statechart”
• Even with separate diagrams, there is no such distinction in the model
• The XMI data exported by EA provides no way of differentiating between different
diagrams at the same level
• The “name” assigned to a statechart diagram in the model is not available in the
exported XMI data
• Within UML, statechart behavior is logically associated with a Class

Do this
(statechart inside a Class),
not this
(no containing Class)
Using Classes as Containers for Statecharts,
continued
• By placing statechart diagrams
inside Classes, a single EA model
can contain multiple statecharts
(see example at right)
• Each statechart will be
independently identifiable in the
exported output
• The gen_hsm tool will be able to
create unique declarations for each
statechart
• The “name” used for the statechart
will be the Class name (the name of
the statechart diagram is not
available in the XMI data)
EA Statechart Basic Rules/Conventions:
Naming Conventions
• All names on statecharts should be viewed as residing in the C language “global”
(extern) namespace.
• All names must be chosen to prevent “name clashes” with any other symbols in any program that
might use the statechart
• Use the module’s global “prefix” to help ensure names are unique
• Because names used in the model become identifiers in C code, they must follow C language
conventions – no spaces in names, etc.
• State Names
• State names are used to create the names of extern constant tables used to define the statechart
for the HSM engine; so…
• State names must be chosen so they will be unique within the entire system – use the module’s
prefix to help ensure this.
• The state names themselves will be enum tags with numeric values that uniquely identify the states
within the statechart; they should be ALL_UPPER_CASE_WITH_UNDERSCORES
• This applies to all states, even pseudostates: initial states, junction states, history states, etc.
• Event Names
• Names of the triggers for transitions must match the exact name of the event in the system
• Events should be named as if they are “global”, even if they are “private” to the module; i.e., always
follow the first convention of keeping the names unique within the system
• Because event names will be mapped to numeric values in the system (e.g., enumeration tags), the
names should be ALL_UPPER_CASE_WITH_UNDERSCORES
EA Statechart Basic Rules/Conventions:
Naming Conventions
• Action Names
- 2
• The action name is the name of the action function that will be called by
the HSM engine to perform the necessary functionality
• The implementation may choose to have this function be “extern” in
order to allow multiple C files to be used to implement the statechart, or
it may choose to make it “static”
• Follow the conventions for establishing unique function names and
avoiding name clashes within the system – use the module’s prefix on
the name.
• Name the function so that it effectively communicates as much
information about its behavior as possible – the name serves as
“documentation of intent” on the statechart diagram.
• Guard Names
• Guard names are the names of the functions called by the HSM engine to
determine whether the guard condition is true – they return a bool result
• The same points made above for action functions apply to guard
functions
• Be sure to use names that communicate the meaning of a “true” return
value to aid in the understanding of the statechart
EA Statechart Basic Rules/Conventions:
Supported State Elements
• Elements Supported by gen_hsm and the HSM
engine
• State
• Initial
• Final
• History
• Junction
• Transition
• Unsupported Elements (do not use)
• State Machine
• Synch
• Object
• Choice
• Entry (see discussion of entry/exit points in later slides)
• Exit (see discussion of entry/exit points in later slides)
• Terminate
• Fork/Join
• Object Flow
EA Statechart Basic Rules/Conventions:
Composite States
• The “State” element is used to create both Simple and Composite
states
• A Composite state is simply a state that contains another state
• No additional “properties” should be set
• The Advanced property named “Composite Element” is not used to denote
a composite state; it is used to move the contents of the composite state to
a separate diagram, which will be covered later.
• The Advanced->Custom Properties.. settings do not control anything
• The Project Browser shows the state hierarchy (see examples below)
stm Example_Statechart
stm Example_Statechart

S1 S1 is a S1

S1 is a S2
composite S2
simple state
state
EA Statechart Basic Rules/Conventions:
Entry/Exit Actions
• Entry/Exit actions for states are
created via the state’s “Operations”
dialog
• Select the state, right click and
select “Operations…”
• Select “entry” or “exit” from the
“Action:” drop-down box
• Type the name of the entry/exit
function in the “Name:” field
• Click “Save”
• To create the other function, click
“New” and then repeat the above stm Example_Statechart

sequence. NOTE: EA allows multiple S1

entry/exit actions to be defined for + entry / Name_O f_Entry_Action

a state, but gen_hsm and the HSM + exit / Name_O f_Exit_Action

engine only support one of each.

EA Statechart Basic Rules/Conventions:
• The properties of the transition are used to
Transitions
specify
• The triggering event’s name
• The action function name (if any) – “Effect”
• The guard function name (if any)
• EA requires you to type the name of the event
into the Trigger “Name:” field (or select an
existing event from the drop-down box). You
should then set the “Type:” to “Signal” and
then “Save” it
• Multiple events that cause the same transition,
with the same guard and action can be “Saved”
for the same Transition
• Transitions between the same states with
different actions or guards require a separate
stm Example_Statechart NAME_OF_1 ST_EVENT,
NAME_OF_2 ND_EVENT

transition S1 [Name_Of_Gua rd_Function]

/Name_Of_Action_Function
S2

• The special guard “ELSE” can be used to denote NAME_OF_1 ST_EVENT

a transition to be taken if all the other [EL SE]
/Name_Of_Else_Action
transitions with the same event have “false”
guard conditions
• The fields for the action and/or guard function
names can be left blank if they do not apply. No
guard is equivalent to a guard that is always
“true”.
EA Tips: Transitions
• Long event names
• The “Trigger Name:” field of the Transition
Properties dialog will not accept more than 38
characters
• If you have an event name longer than this you
can:
• Enter the first 38 characters in this field and “Save” it
• Go to the event in the Project Browser, right click on it
and select “Properties…”
• The “Name:” field here is not limited – add the extra
characters and click “OK”
• To get the diagram to reflect the extended name, you
must then double click on the transition to open its
properties box and then click “OK” – the diagram will
be updated.
• Don’t forget that compilers typically require
names to be unique within the first 32 characters
• Changing source or target of a transition
• Right click on the transition
• Select “Advanced->Set Source and Target”
• Use the drop-downs to change the source and/or
target
• Click “OK”
How to Generate a “Pseudo” Internal
• EA does not support UML internal transitions
Transition with EA.
• It is possible to get EA to display what looks like an
internal transition
• gen_hsm will detect this work-around and translate it
into an internal transition for the HSM Engine
• Select the state to contain the internal
transition. Right click and select “Operations...”
• In the “Name:” field, place the name of the
action. If there is no action, type a space
• In the “Action:” drop-down field type the name
of the triggering event.
• If there is a guard, place its name inside square
brackets (“[]”) immediately after the event
name.
• Click “Save”
• This will appear in the diagram as a standard stm Example_Statechart
UML internal transition.
S1
• gen_hsm will detect this pattern and correctly + NAME_OF_EVENT[Name_Of_G uard] / Name_Of_Action
translate it into the
HSM_INTERNAL_TRANSITION MACRO .
Entry/Exit Points:
Concept
• Entry/Exit points can be used to hide the details of a composite state on a separate
diagram while supporting transitions to/from its internal states

The two diagrams

below use
entry/exit points to
create the
equivalent of the
diagram to the
=
right.

Entry Points

+
Exit Points
Entry/Exit Points:
Cautions
• Collapsing behavior from one diagram to multiple diagrams can make it difficult to
see the “big picture”, which contradicts the most important role of the statechart
diagram
• When viewing the child diagram, transitions to/from the composite are not shown
• If the composite is itself the child of another composite, then any “inherited” transitions will not be
seen and will be easy to overlook.
• Avoid collapsing behavior using this technique
• Reserve for cases where it is needed because it greatly reduces the diagram complexity
• Reserve for cases where the model is “mature” – avoid doing this early in the design process

When viewing
this diagram Similarly, when
alone, the viewing only the
“context” for the parent diagram,
transitions the “context” for
to/from this internal behavior
composite state is lost
are lost
Entry/Exit Points:
Semantic Equivalent Using
• Junction states canJunction
be used toStates
create the exact semantic equivalent of entry/exit
points
• Each entry/exit point can be replaced by a single junction state that is contained
within the composite state
• Having the composite state be the parent of the junctions leads to the required ordering of the
entry/exit functions
• The HSM statechart engine uses junction states to implement entry/exit points: it has no separate
elements for entry/exit points
• The following use of junction states provides the exact behavior provided by the
previous diagrams using entry/exit points
Entry/Exit Points:
Diagram Comparison
+
Draw the above 2
diagrams in EA and
gen_hsm will generate
the semantic
equivalent to the right
(the change of prefix
from EE2_ to EE3_ is
only to allow both
=
diagrams to exist in the
same model without
generating conflicting
code)
Creating Entry/Exit Points in EA
• Create the Composite state in a diagram using the State element
• Select the Advanced->Composite Element property
• This will cause the composite symbol to appear in the lower right hand corner of the state
• This will also create a separate diagram for this composite state under that state in the Project Browser (the
diagram’s name will be the state’s name)
• Open the diagram for the composite state and drag the state from the Project Browser to the empty diagram. A
paste confirmation dialog will appear; keep the default selection “as Simple Link” and click “OK”
• Resize the composite state in its diagram and create its contents (new states, transitions, etc.). Do not add any
elements outside the composite state (these belong in the parent diagram)!
• To add an entry/exit point to the composite state
• In its diagram, right click on the composite state and select Embedded Elements -> Add Entry Point (or Add Exit
Point)
• Remember that the “Name:” of the entry/exit point is the name of an actual pseudostate and must follow the
state naming conventions
• The entry/exit points can be repositioned by dragging them along the composite state’s boundary.
• Create transitions between the entry/exit points and the contents of the composite state
• To display the added entry/exit points in the parent diagram
• Right click on the composite state and select Embedded Elements->Embedded Elements…
• Click in the check boxes for the entry/exit points to make them visible
• Close the Embedded Elements dialog
• Reposition the entry/exit points by dragging them along the boundary of the composite state
• The entry/exit points and the composite state itself can be used for transitions in the parent diagram
• Note that the Entry/Exit states in the EA Toolbox cannot be used to accomplish the above –
they should not be used
Orphan Elements
• When ina diagram,
you add a state to EA EA adds that state to the model
• If you delete a state from a diagram, that state remains in the model
– it is not automatically deleted
• Elements that are in the model but not on a diagram are referred to
as “orphans”
• When the model is exported in XMI format, all states in the model
will be exported
• You want to delete all orphan states prior to exporting the model
 In the example to the stm Example_Statechart

right, states I1, S2, I0

and J1 are orphans

C1
 EA makes it easy to
find these: “Edit->Find S1
in Model…”. Select
“Find Orphans” and
click “Run Search”
“Find Orphans” Example
• Warning: Deleting elements from a model is not a
reversible operation in EA. Make sure you have
archived a copy of the model before deleting
elements
• The example to the left shows part of the orphan list
when sorted by “Type”
• The elements of concern are of the type “State” or
“StateNode”. These must be deleted or they will
appear in the XMI output even though they are not
used.
• Class elements often show up as orphans if they are
not part of a diagram showing the relationships
between classes. Do not delete these; otherwise, the
Class and its contents (including its statechart) will be
deleted from the model.
 EA shows events (Triggers) as orphans even if they are used in a statechart;
so, the orphan search cannot be effectively used to track down stray events
 The orphan States and StateNodes can be selected and deleted from this list
 NOTE: If you delete a parent state, its children are also deleted. If you select
a parent and its children in the list and command the deletion of them all,
then EA will likely crash because when it tries to delete the children they may
have already been deleted during the deletion of the parent.
Checking a Model with EA
• EA provides a limited ability to check the validity of statecharts
• These checks are not very exhaustive, but should be used as
the first level of verification.
• To run EA checks
• In the Project Browser, highlight the top of the hierarchy, labeled “Model”
• Select Project->Model Validation->Validate Selected
• This will check the entire model and output any warnings to
the “Output” window
• Anything showing up in this window should be corrected
• Exception: EA incorrectly issues a warning for any junction state that has more
than one outgoing transition; e.g., “MVR0B0001 - warning
(Check_For_Overdrawn (Junction)):
Statechart violation: junction cannot
have more than one outgoing flow”. These warnings
are incorrect and should be ignored.
Exporting a Model
• Select Project-> from EA
Import/Export-
>Export Package to XMI…
• Specify the path and name of
the .xml file that is the
destination for the exported
XMI data in “Filename:”.
• Set the options as shown:
• Select “Format XMI Output”
• Select “Enable full EA
Roundtrip”
• Set XMI Type: to “UML 2.1
(XMI 2.1)”
 Click “Export”
 When the export is finished, click “Close”
Summary
• Draw the statechart in EA, using the conventions and tips described in this presentation
• Check the model using EA’s model validation. Fix any issues.
• Export the model to an XML file
• Run gen_hsm on the XML file. Fix any issues.
• Integrate the generated code into the project
• Integrate any new events into the system’s event list
• Implement any new action or guard functions
• Rename any existing action or guard functions that were renamed in the model
sd Statechart Engine Ov erv iew

Enterprise Architect
«use»

«use»

«generate» «use» Softw are Engineer

«write»
Compiler /Linker
Exported XMI Model

«translate»
«flow»
Product Softw a re Source Code «flow»
gen_hsm
HSM Engine Building Block

«generate» Product Image

Statechart Im plementation
Generated Statechart
Declarations (C code)
«merge»