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.

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: V₀ ± DV.	V₀ – DV < Vc < V₀ + 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: V₀+ DV (1 + t/Dt); DV and Dt are constants.	V₁ = V₀+ DV(1 + t /Dt) AND V₁ – DV < Vc < V₁ + 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⁽¹⁾	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 : V₀ Terminal: N Timeout: N	V₀ = V(t₀) where t₀ is the speed at the time of transition into the state.
3.	Accelerating	Driver increases speed set point.	Controlling: True; Vc: V₀+ DV (1 + t/Dt); Terminal: N Timeout: TO₁	DV, Dt and TO₁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 < V₀ 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.