A Cruise Control Requirements FSM Model

This simple system example to illustrate various aspects of creating and using a requirements FSM.

Step 1: Elicitation

The requirements elicitation session yielded the following list of requirements. Those are listed in two notations: user stories for user requirements and predicates for other requirements information (including non-functional requirements if were in the example scope)[1]

User story 1:      As a driver, I want to start speed control that keeps the car at the same speed as at that moment, so my workload driving the car and my risk of speeding are lowered.

User story 2:      As a driver, I want to increase the speed set point by fixed increments or at a constant rate, so I can adjust the speed to different conditions.

User story 3:      As a driver, I want to be able to lower the controlled speed by letting the car coast, decelerating until it reaches the desired speed, so I can adjust the speed to changing conditions.

Predicate 1:         Coasting downhill may accelerate the car preventing the possibility to lower the set point that way.

User story 4:      As a driver I want to stop speed control temporarily, so I can have an agile control when needed.

User story 5:      As a driver, I want to resume speed control at the last set point, so I can go back to sleep.

Predicate 2:         Speed can be controlled by controlling the throttle, sending the throttle module the following commands:

(a)   Hold – start control, keep throttle at current position;

(b)   Move, D – move the throttle by D throttle units. -100 < D < 100.

(c)   Release – release the throttle to manual (foot) control; it goes back to the level set by driver’s foot.

In response to any of those throttle commands, the throttle module returns a status code: OK, or ERROR_CODE.

Step 2: Analysis

The requirements analyst reads and examines all the elicited requirements again to make sure they are clear, unambiguous etc.

Step 3: Constructing a requirements FSM model.

RA realizes that the requirements describe a system that responds to driver commands by moving between distinct behaviors. This kind of reactive system is lends itself to modeling by an FSM. RA decides to construct a requirements FSM to further analyze the system and assist in improving the requirements.

Analyzing those requirements, we can come up with the following list of events:

E1: Start – start constant speed control,

E2: Stop – stop speed control

E3: Up pressed – increase speed

E4: Up released – got to desired speed

E5: Down pressed – want to reduce speed

E6: Down released – got to desired speed

E7: Throttle error

And we identify some conditions that can qualify as states: Constant speed, Accelerating, Decelerating, and No control. Next, we will specify those states to each of the requirements FSM notations described above. To do that, for the state variable constraints notation, we need to define properties (represented by variables) that characterize system operation in its various states, and those will be:

(1)   Controlling – a Boolean (true or false) that indicates if speed is being controlled by the system or not.

(2)   Vc – a continuous variable representing the car’s speed as it is read by the system.

State (name)

Specifications

State variable constraints

State invariant

Constant speed

The system shall control car speed as reported by the input variable Vc, keeping it constant by controlling throttle position.

Controlling: True

Vc: V0 ± DV.

V0 – DV < Vc < V0 + DV

Accelerating

The system shall continue to control the car speed, the set point speed is incremented by DV initially, and every Dt sec. afterwards.

DV and Dt are constants.

Controlling: True;

Vc: V0 + DV (1 + t/Dt);

DV and Dt are constants.

V1 = V0 + DV(1 + t /Dt) AND

V1 – DV < Vc < V1 + DV

Decelerating

The system shall stop controlling the throttle, letting it drop to idle and allow the car to coast to lower speed.

Controlling: False;

Vc(t + dt)  < Vc(t);

Vc(t + dt)  < Vc(t);

No control

-    Initial

The system does not control the car speed.

Controlling: False;

Vc: ≥ 0;

Vc: ≥ 0;

From this point on it will be very cumbersome to work with all three notations, and we will continue with the state variable constraints notation. These definition enable us now to determine which state the system need to switch to in response to each event, completing the FSM:

State transitions table:

No

State

Event

Next State

Comments, rationale

1.                 

No control

Start

Constant speed

Ref: TBD

2.                 

Constant speed

Stop

No control

Ref: TBD

3.                 

Constant speed

Up pressed

Accelerating

Ref: TBD

4.                 

Accelerating

Up released

Constant speed

Ref: TBD

5.                 

Constant speed

Down pressed

Decelerating

Ref: TBD

6.                 

Decelerating

Down released

Constant speed

 

Or the equivalent state transitions diagram:

Step 4: Event-state analysis

The Event-state analysis (ESA) guides the analyst or engineer to complete the FSM model, identifying missing states and transitions. With this example scenario, it is recommended to perform it before getting back to SME’s to review and approve requirements, so we can discuss missing information at their level at the next meeting.

The input to the analysis is the FSM model as specified below by the Key FSM notation – states and transition tables; we choose to use the state variables as the state specifications notation:

Table 1: States

 

State name

Description

Specification(1)

Comments 

1.                 

No control

Regular driving, driver controls speed, system is inactive.

Controlling : false;

Vc : N/A

Terminal: N

Timeout: N

No timeout – no restriction on the time the driver drives normally, without speed control.

2.                 

Constant speed

Cruise control is active, maintaining constant speed.

Controlling : true;

Vc : V0

Terminal: N

Timeout: N

V0 = V(t0) where t0 is the speed at the time of transition into the state.

3.                 

Accelerating

Driver increases speed set point.

Controlling: True;

Vc: V0 + DV (1 + t/Dt);

Terminal: N

Timeout: TO1

DV, Dt and TO1 are factory set constants determining the acceleration: DV/D.

4.                 

Decelerating

Chosen speed reducing method is coasting.

Controlling: False;

Vc: ≥ 0;

Terminal: N

Timeout: N

Vc should be specified as < V0

A SME decision that there is no need for timeout limiting coasting, since it reduces speed and the driver will leave the button eventually.

 

And the state transitions table –

Table 2: State transitions table

 

State

Event : Guard cond.

Next state

Documentation, Comments 

1.                 

No control

Start

Constant speed

Obvious, nothing to add.

2.                 

Constant speed

Stop

No control

Obvious, nothing to add.

3.                 

Constant speed

Up pressed

Accelerating

Obvious, nothing to add.

4.                 

Constant speed

Down released

Decelerating

Obvious, nothing to add.

5.                 

Constant speed

Throttle error

No control

A SME decision to stop control on error.

6.                 

Accelerating

Up released

Constant speed

Obvious, nothing to add.

7.                 

Accelerating

Throttle error

No control

A SME decision to stop control on error.

8.                 

Accelerating

Timeout

No control

SME decision not to let the driver accelerate indefinitely.

9.                 

Decelerating

Down released

Constant speed

Obvious, nothing to add.

10.               

Decelerating

Throttle error

No control

A SME decision to stop control on error.

 

Nice and compact little FSM; let’s see what can we gain from applying the event-state analysis to it.

The first step of ESA is to review and ensure we have an exhaustive list of events relevant to the system. A well-engineered system should have a master list of all events, internal and external; that is an excellent place to start. RA reviews that list, or even asks one or two SMEs to review it in case an additional affect the system under analysis and should be added to the FSM’s events list.

Reviewing a master events list at the car scope, we run into a “suspect” event: Driver applies brakes, or (“breaks applied” for short). It is obvious to any driver that applying the brakes we are trying to reduce speed, and this is relevant to a system that controls speed. We therefore add this event to the list:

E8: Breaks applied

The Key FSM model also specifies a timeout variable for each state; it can be null – no timeout and the analyst has to justify this choice; accordingly a default “timeout” event should be considered for each state:

E9: Timeout

The next step is to apply all events to all states, adding to the state transitions table:

Table 3: State transitions table after ESA

 

State

Event : Guard cond.

Next state (a)

Documentation, Comments

1.                 

No control

Start

Constant speed

As intended.

2.                 

No control

Stop

No transition

Irrelevant at this state.

3.                 

No control

Up pressed

No transition

Interaction design decision not to respond to up and down button at when not controlling speed.

4.                 

No control

Up released

No transition

- “ -

5.                 

No control

Down pressed

No transition

- “ -

6.                 

No control

Down released

No transition

- “ -

7.                 

No control

Throttle error

No transition

Irrelevant at this state.

8.                 

No control

Breaks applied

No transition

Irrelevant at this state.

9.                 

No control

Timeout

No transition

No timeout.

10.               

Constant speed

Start

No transition

Irrelevant at this state.

11.               

Constant speed

Stop

No control

As intended.

12.               

Constant speed

Up pressed

Accelerating

As intended.

13.               

Constant speed

Up released

No transition

Impossible (pressing the button transitions to another state first).

14.               

Constant speed

Down pressed

Decelerating

As intended.

15.               

Constant speed

Down released

 

Impossible (pressing the button transitions to another state first).

16.               

Constant speed

Throttle error

No control

A SME decision to switch off control when getting an error.

17.               

Constant speed

Breaks applied

No control

A SME decision to switch off control when breaks are applied.

18.               

Constant speed

Timeout

No transition

No timeout.

19.               

Accelerating

Start

No transition

Disabled; interaction design decision not to respond to this button at this state.

20.               

Accelerating

Stop

No transition

Disabled; interaction design decision not to respond to this button at this state.

21.               

Accelerating

Up pressed

No transition

Not possible; already pressed.

22.               

Accelerating

Up released

Constant speed

As intended.

23.               

Accelerating

Down pressed

No transition

Disabled; interaction design decision not to respond to this button at this state.

24.               

Accelerating

Down released

No transition

Disabled; interaction design decision not to respond to this button at this state.

25.               

Accelerating

Throttle error

No control

SME decision to stop control on error event.

26.               

Accelerating

Breaks applied

No control

SME decision to stop control when beaks applied.

27.               

Accelerating

Timeout

Constant speed

SME decision to switch to constant speed.

28.               

Accelerating

Timeout

No control

SME decision not to let the driver accelerate indefinitely.

29.               

Decelerating

Start

No transition

Disabled; interaction design decision not to respond to this button at this state.

30.               

Decelerating

Stop

No transition

Disabled; interaction design decision not to respond to this button at this state.

31.               

Decelerating

Up pressed

No transition

Disabled; interaction design decision not to respond to this button at this state.

32.               

Decelerating

Up released

No transition

Disabled; interaction design decision not to respond to this button at this state.

33.               

Decelerating

Down pressed

No transition

Not possible; already pressed.

34.               

Decelerating

Down released

Constant speed

As intended.

35.               

Decelerating

Throttle error

No control

SME decision to stop control on error event.

36.               

Decelerating

Breaks applied

No control

SME decision to stop control when beaks applied.

And the state transition diagram for this complete version:

The main additions here are timeout, and the additional event of breaks applied.

Discussion of the example

(a)      The complete state transitions table has 36 rows compared with the 6 of the first, “nominal” version. Most are “No transitions” (yellow rows) but those are also important, at least for decision and rationale documentation.

(b)      New meaningful new transitions (red rows): 4. Note that the main addition here is the introduction of timeout and breaks applied events. An exception analysis reveals that in this case virtually all exception conditions end up generating a throttle error – an event already on the list, so no addition there.

(c)      Many events require no transition for simple reasons: either the event is impossible in this state, or a decision was made not to respond to the event and even disable it in some way. Many common FSM notations and models just leave those rows out as not-interesting; ESA requires to have those rows and specify “No transition”, documenting the reasoning. This prevents accidental response when code changes are made for continued development. Reasoning documentation supports safer maintenance. Key FSM implementation uses those rows to make sure there are no transitions in those cases, preventing arbitrary responses.

(d)      Some event – state combinations require SME to decide what to do: which state to transition to or no transition. The analyst may present the question to a SME directly; the decision will be reviewed by the whole team later on. If there are too many such cases, an elicitation follow-up meeting to provide those decisions is justified.

(e)      Some transition decisions are the result of interaction design. This interface design process still produces requirement decisions (even if it may be considered being further downstream).

(f)       All rows contain rationale documentation in the documentation / comments column. Important for maintenance, when another developer considers to modify the FSM can read the reason for its definition and avoid errors. Some trivial rows are documented with “as intended” to record that this transition implements a basic system response to the event. For tracing transition decision, references to specific requirements, SME statement, etc.

Step 5: Implementation

Lastly, since the control structure here are two system parameters, an FSM engine that supports that type of control , i.e. sets values per state definitions, enables no code implementation of the FSM itself, only a speed control module and accelerating small module for incrementing the set point are required, external to the FSM itself as illustrated by the following diagram:

 

 



[1] The author does not believe in nor accept the dogma of making every piece of input information a user story so it can be added to the tasks backlog as Scrum requires or practice.