CBA ItemBuilder Workshop: Session 11

Ulf Kroehne

Paris, 2022/11/07 - 2022/11/08

Session 11: Finite-State Machine (1)

Overview Session 11

User-Interface

• State Machine Tree View / State Machine Syntax
• Definition of States

Finite-State Machine

• Small example
• Syntax for definition of Events and Rules
• Use of Operators and Conditions

Finite-State Machine – User Interface

The CBA ItemBuilder’s user-interface for Finite-State Machines consists of two editors: The State Machine Tree View and the State Machine Rules Editor (open both with menu Project > Edit State Machine).

• State Machine Tree View

• State Machine Rules Editor

• Add States using the context menu

• Add Syntax for Events: and Rules:

• If no Finite-State Machine is used in a Project File, the Rule Files contains no syntax (i.e. it is empty by default).

State Machine Tree View

How to Create States?

1. Right-click the text Machine VERSION_01_01.
2. Select New Child > State.
3. Double-click <not set>.
4. Configure State and press OK.

State Configuration

State Type

• START: Each FSM needs one Start-state (required).
• NORMAL: Regular states are Normal-states.
• END: State-machines end in an End-state (not required).

State Name

• Each state needs a valid name.
• Only letters, digits, and underscores are allowed.
• The first character must not be a digit.

Page to Open

• Should be either empty, if no page is assigned, or a valid Page Name.

State Machine Tree View – Minimal Set of States

A minimal configuration should have at least two States:

• A Start-State (here: ST_START)
• A Normal-State (here: ST_RUNNING)

• Make sure to not accidentally nest the states:

• Siblings are not required for a simple configuration:

• Regions are not required for a simple configuration:

• Configuration of states is also possible in the Properties-view, but avoid typos in Page-names!

• The State Machine Tree View might look more complicated as it actually is to define states. However, remember that the context menu is used and that you have to click on the text Machine Version_01_01.

State Machine Syntax – Parts

Minimal Syntax:

Events: EV_Placeholder;
Rules: ST_Start -> ST_Running {true}

Line 1 (Part I)

• Syntax starts with the keyword Events: followed by a list of events.
• At least one event is necessary (here a placeholder EV_Placeholder).
• If multiple events are defined, use , (comma) as separator.
• The event definition must end with a ; (semicolon).

Line 2 (Part II)

• The keyword Rules: is required for the 2nd part.
• At least one rule for the Start-state (ST_Start) to the Normal-state (ST_Running) is required.
• This start-rule is executed always ({true}).

State Machine Rules Editor

A few notes in advance …

• Remember the Auto-Completion-Feature (press Ctrl/Strg + Space).
• A red cross marks errors / mistakes in the syntax.

Changes in the State Machine Rules Editor and in the State Machine Tree View are confirmed by closing the editor. After defining States or Events, close both editors to make sure the model is updated!

When closing one of the two editors (either State Machine Rules Editor or State Machine Tree View), close also the other before request the editors again!

• Use comments (/* ... */ or //) to document syntax or to remove syntax temporary.

Small Example

It’s about the ?-Button:

Two States

• State_Hint_Visible: Test-taker not yet used drag-and-drop (a hint might be required)
• State_Hint_Invisible: Drag-and-drop observed (no hint required)

Rules¹

Events: EV_Changed;
Rules: Start -> State_Hint_Visible {true}
State_Hint_Visible => State_Hint_Invisible {EV_Changed | setHidden(HintButton)}

1. Simplified: The full Finite-State Machine contains code for the Reset-button.

Syntax Overview

User-Defined FSM-Events¹

• Definition of FSM-events² in the State Machine Rules Editor
• Linking of FSM-events to components in the Page Editor (or Properties-view)

Definition of FSM-Rules³

• Start-Rules (->) vs. Regular Rules (=>)
• Triggers for Transitions ({})
• Execute Operators in Transitions (|)
• Process events within States (internal)
• Conditional rules wit Guards (: [Cond])
• Syntax for State-entry and -exit rules

The CBA ItemBulider’s Finite-State Machine syntax is not complicated.

But be careful with the different characters (e.g., -> vs. =>), as they have an explicit meaning.

1. FSM-Event are defined in syntax and linked to components in the Page Editor / Properties-view.

2. Events names followed by numbers define Timed Events.

3. Rule and Transition are almost synonyms. Rules define a Finite-State Machine, and Transitions are executed.

Start-Rules & Regular-Rules

Start Rule (->)

StartState -> StateA {true}

• The source (e.g., StartState) must be a state of type START.
• The target (e.g., StateA) must be a state of type NORMAL.
• The Condition {true} is always fulfilled (i.e., the transition is executed).

Regular Rule (=>)

StateA => StateB {TriggerEvent}

• The source (e.g., StateA) must be a state of type NORMAL.
• The target (e.g., true) must be a state of type NORMAL.
• The Transition is executed, if an event {TriggerEvent} occurs in StateA.

How to read the syntax? A transition is defined from StateA to StateB for TriggerEvent.

Operators in Rules

Finite-State Machines are mainly used to trigger Operators (i.e., to change the item) either due to user-interactions (i.e. Events linked to components) or (internal) Timers.

Regular Rule with Operator (|)

StateA => StateB {TriggerEvent | Operator()}

• The Operator() is executed, when the Transition defined in this Rule is executed.
• Hence, the Operator() is executed when the FSM is in StateA and the TriggerEvent occurs.

CBA ItemBuilder Syntax defines various Operators for FSMs to

• Change components (show/hide, active, …)
• Show dialog pages and to change page areas
• … (many more, see next slide)

CBA ItemBuilder Syntax defines various Operators¹ for FSM-Rules …

• Operators for Runtime Commands: next_task, back_task, cancel_task
• Operators for Calculator engine: calcOp, calcOpnd, calcSettings
• Operators for ExternalPageFrames: callExternalPageFrame
• Operators for dialog pages: openDialog, closeDialog
• Operators for Inputfields: focus, insertText
• Operators to trigger FSM-Events: raise
• Operators for Variables: set, reset
• Operators for Pages: scrollEmbeddedPage, scrollTopLevelPage
• Operators for PageAreas: setEmbeddedPage
• Operators for components with Component State: setActive / unsetActive, setFrozen / unsetFrozen
• Operators for components: setHidden / unsetHidden
• Operators for Audio/ Video components: initMediaPlayer, setMediaPlayer, setMediaPlayerVolume

…

1. Currently unsupported / no longer supported operators: recommend, setCurrentPage

…

• Operators for Global Properties: setGlobalProperty
• Operators to change FSMs: initFSM, setFSMEvent, setFSMState
• Operators for ImageMaps: setValueDisplayMode
• Operators for TextFields: setHighlightable / unsetHighlightable
• Operators for FrameSelectGroups: setMultiselect / unsetMultiselect, setNoDeselect / unsetNoDeselect, setSelectable / unsetSelectable
  
• Operators for Trace-Data: trace_snapshot, trace_text, trace_typed_snapshot, trace_typed_text
• Operators for Trees: tree_copy, tree_move

Rules with Conditions

Finite-State Machines differentiate a finite number of States. However, in practice, this restriction is circumvented by the use of Conditions (i.e., Guards) that can incorporate Variables in Boolean expressions.

Rule for Regular States with Condition ([])

StateFrom => StateTo { EventName : [Condition] }

Possible Scenarios:

• If the FSM is not StateFrom: Nothing will happen if EventName occurs.
  (Note: this is the default and has nothing to do with the Condition.)

• If the FSM is in StateFrom:
  • Nothing will happen if EventName occurs, if Condition is not met.
  • The FSM will change to StateTo, if EventName occurs and if the specified Condition is fulfilled.

Rules with Conditions and Operators

Rules for transitions between regular States with Condition and Operators can be defined.

Combination of [] and |:

StateFrom => StateTo { EventName : [Condition] | OperatorA(), OperatorB() }

How to read the syntax? A transition is defined from StateFrom to StateTo is defined for EventName. If the Condition is fulfilled when EventName occurs and the FSM is in State StateFrom, the FSM will change to StateTo and execute the Operators OperatorA() and OperatorB().

• One or multiple Operators are possible.
• The Condition needs to be Boolean expression (with one or multiple components).

Multiple Conditions in One Rule

Conditions can be complex Boolean expressions, but Bracketing need to be considered!

Single Condition

// V1 == 1 
state1 => state2 {EventName : [V1==0]}

Two Conditions

// V1 == 1 and V2==2
state1 => state2 {EventName : ([V1==1] and [V2==2])}

Three Conditions

// V1 == 1 or V2==2 
state1 => state2 {EventName : ([V1==1] or [V2==2])}

Four Conditions

// (V1 == 1 or V2==2) and (V3==3) 
state1 => state2 {EventName : (([V1==1] or [V2==2]) and [V3==3])} 

Multiple Rules for a Complete FSM

A complete Finite-State Machine definition in the CBA ItemBuilder usually includes more than the minimum required two rules.

Idea

• Rules are defined only for events that should be processed within a State.
• Events can be processed to trigger Operators without changing the State of the FSM (self-transition or keyword internal).
• Events can also change the current State of a FSM if a rule is defined.

Pragmatic Approach

• If (although not suggested) multiple rules are defined for the identical event within a particular State, then the first defined rule is executed.

• Multiple Finite-State Machines (see session FSM-2) can process one Event multiple times.

Conditions in Start Rules (->)

In most cases, the rule that defines the Transition between a Start-state and a Normal-state is defined with a condition that is always fulfilled (i.e., using the default {true}).

For Project Files with several Tasks, the Start-rule (->) allow conditions:

Possible Conditions

• Task-Name (T1 or T2):
  S -> N1 {isCurrentTask(T1)}
S -> N2 {isCurrentTask(T2)}
  

• Page-Name (P1 or P2):¹
  S -> N1 {current_page(P1)}
S -> N2 {current_page(P2)}
  

Default

• S -> N {true}

• This is an advanced features, the default is {true}.

1. The Page-Name is defined in the Task Definition.

Don’t Repeat Yourself

If identical operators should be executed when a FSM enters a particular State (i.e., entry) or leaves pa particular State (i.e., exit).

Don’t repeat syntax for operators, if possible.

Operators executed when a FSM changes to a particular State:

• Syntax using keyword entry:

State entry {operator1(), operator2()}

Operators executed when a FSM leaves a particular State:

• Syntax using keyword exit:

State exit {operator1(), operator2()}

Trigger Operators with internal Transitions

Self-Transitions (i.e., Identical From- and To-States)

StateA => StateA { EventName : [Condition]  | Operator()}

• Technically, the StateA is left and re-entered.

The transition StateA => StateA means that StateA is re-entered:

• State-entry and State-exit are executed.
• Timed Events are started again (see session 13).

Keyword internal

StateA internal { EventName : [Condition]  | Operator()}

• Identical outcome as StateA => StateA, but StateA is not re-entered.

Use the keyword internal to avoid re-entering States (and re-starting Timed Events). This should be the default to execute Operators in States.

FSM-Summary for Item Authors (1)

CBA ItemBuilder FSMs use User-Defined States:

• A FSM is always in exactly one State at a time.
• A FSM will change it’s State, if a rule is defined for a particular Event.
• Conditions allow to differentiate, which Rule applies (if multiple Rules are defined in a particular State for a particular Event).
• After processing the Event, the FSM will be in a new State (if internal is not used).
• Operators can be used in State-transitions, usually triggered by Events.

The Required FSM-Events:

• Events are defined in Syntax by providing unique Event Names.
• Events can be linked to components (using Asign Raised Event or similar in the Page Editor).

• Preview (and use) of Tasks that use the Finite-State Machine concept of the CBA ItemBuilder is only possible, if the syntax is correct.

It is impossible / very unlikely to define a valid Finite-State Machine syntax using trial & error.

End of Session 11: Finite-State Machine (1)

Helpful to remember

• Difference between States of type NORMAL (multiple) vs. START (one).
• Symbols: ->, =>, {}, |, [] and keyword internal
• Syntax Schema
  Events: EV1, EV2;
Rules: S->N1{true}
N1=>N2{EV1}
• Hotkey for the State Debug Window: Strg/Ctrl + M

General idea

• CBA ItemBuilder Finite-State Machines an be understood as a powerful device to implement interactive items. The provided tool requires content to result in innovative items.

• Finite-State Machines will be used in the hands-on in session 12.

• What else have you learned?