States machine manager and event interpreter. More...

#include <sm_statemachine.h>

Public Member Functions
void	deinitialize ()
	Deinitialization of the queues and states. More...

void	setName (const std::string &new_name)
	Sets name of the state machine. More...

const std::string &	getName () const
	Gets name of the state machine. More...

template<class STATE >
void	createState ()
	Creates new state. More...

template<class STATE >
void	createState (const STATE &new_state)
	Creates new state from the copy constructor. More...

template<class STATE >
STATE *	setActiveState (bool output=true)
	Sets active state by class name. More...

SUPER_STATE *	setActiveState (int state_id, bool output=true)
	Sets active state by class id. More...

template<typename STATE >
int	getStateId ()
	Given a state class name returns its id. More...

template<typename... STATES>
bool	isStateActive ()
	Checks if given state is active by state class name. More...

bool	isStateActive (int id)
	Checks if given state is active by state id. More...

bool	isStateActive (std::initializer_list< int > id_list)
	Checks if given states are active by the list of state id. More...

EventStatus	executeEvent (const Event0< SUPER_STATE > &event, bool silently=false)
	Executes event in the active state. More...

EventStatus	executeEvent (const Event1< SUPER_STATE > &event, bool silently=false)
	Executes event in the active state. More...

EventStatus	executeEvent (const Event2< SUPER_STATE > &event, bool silently=false)
	Executes event in the active state. More...

EventStatus	executeEvent (const Event3< SUPER_STATE > &event, bool silently=false)
	Executes event in the active state. More...

void	addEvent (const Event0< SUPER_STATE > &event, double timeoutSec=EVENT_DEFAULT_TIMEOUT_SEC, EventPriority priority=LOW_PRIORITY_EVENT, EventStatus(SUPER_STATE::*terminateEvent)=DEFAULT_TERMINATE_EVENT)
	Adds event without parameters to the event execution queue. More...

void	addEvent (const Event1< SUPER_STATE > &event, double timeoutSec=EVENT_DEFAULT_TIMEOUT_SEC, EventPriority priority=LOW_PRIORITY_EVENT, EventStatus(SUPER_STATE::*terminateEvent)=DEFAULT_TERMINATE_EVENT)
	Adds event with one parameter to the event execution queue. More...

void	addEvent (const Event2< SUPER_STATE > &event, double timeoutSec=EVENT_DEFAULT_TIMEOUT_SEC, EventPriority priority=LOW_PRIORITY_EVENT, EventStatus(SUPER_STATE::*terminateEvent)=DEFAULT_TERMINATE_EVENT)
	Adds event with two parameters to the event execution queue. More...

void	addEvent (const Event3< SUPER_STATE > &event, double timeoutSec=EVENT_DEFAULT_TIMEOUT_SEC, EventPriority priority=LOW_PRIORITY_EVENT, EventStatus(SUPER_STATE::*terminateEvent)=DEFAULT_TERMINATE_EVENT)
	Adds event with three parameters to the event queue. More...

double	getDtSec () const

EventStatus	iterate (double cycleTimeSec)
	Iterates an execution cycle of the state machine. More...

void	clear (bool highPriority=true, bool lowPriority=true)
	Clears event queue. More...

size_t	length (EventPriority priority=LOW_PRIORITY_EVENT)
	Returns length of the event queue. More...

ErrorHandle< SUPER_STATE > &	getErrorHandle ()
	Returns reference to the error handler. More...

const ErrorHandle< SUPER_STATE > &	getErrorHandle () const
	Returns const reference to the error handler. More...

bool	warning (const Error &error)
	Executes warning routine, add error code to the error list. More...

bool	forcedDisengaged (const Error &error)
	Executes forced disengaged routine, add error code to the error list. More...

bool	shutdown (const Error &error)
	Executes shutdown routine, add error code to the error list. More...

bool	emergencyStop (const Error &error)
	Executes e-stop routine, add error code to the error list. More...

Friends
class	ErrorHandle< SUPER_STATE >

Detailed Description

template<class SUPER_STATE>
class mcx::state_machine::StateMachine< SUPER_STATE >

States machine manager and event interpreter.

Creates and initializes the states, adds events to the queue, executes events from the queue.

Member Function Documentation

◆ addEvent() [1/4]

template<class SUPER_STATE >

void mcx::state_machine::StateMachine< SUPER_STATE >::addEvent	(	const Event0< SUPER_STATE > &	event,
		double	timeoutSec = `EVENT_DEFAULT_TIMEOUT_SEC`,
		EventPriority	priority = `LOW_PRIORITY_EVENT`,
		EventStatusSUPER_STATE::*	terminateEvent = `DEFAULT_TERMINATE_EVENT`
	)

inline

Adds event without parameters to the event execution queue.

Parameters

event	- event without parameters to add to the queue.
timeoutSec	- time in sec after which terminate callback is called.
priority	- priority of the event.
terminateEvent	- terminate callback, which is called if the event is not complete before timeout.

Example Usage:: EventStatus HeatingOil::heatOilEvent() {

if (getOilTemp() < t_celsius) {

doHeatOil();

return EVENT_REPEAT;

}

setActiveState<OffState>();

return EVENT_DONE;

}

EventStatus HeatingOil::terminateEvent() {

emergencyStop({ESTOP_OPENED});

}

...

// adding heating event with timeout 120 seconds. if timeout happens

// terminateEvent is called and state is switched to e-stop.

fsm.addEvent(&SuperState::heatOilEvent, 120);

See also: EventStatus

◆ addEvent() [2/4]

template<class SUPER_STATE >

void mcx::state_machine::StateMachine< SUPER_STATE >::addEvent	(	const Event1< SUPER_STATE > &	event,
		double	timeoutSec = `EVENT_DEFAULT_TIMEOUT_SEC`,
		EventPriority	priority = `LOW_PRIORITY_EVENT`,
		EventStatusSUPER_STATE::*	terminateEvent = `DEFAULT_TERMINATE_EVENT`
	)

inline

Adds event with one parameter to the event execution queue.

Parameters

event	- event with one parameter to add to the queue.
timeoutSec	- time in sec after which terminate callback is called.
priority	- priority of the event.
terminateEvent	- terminate callback, which is called if the event is not complete before timeout.

Example Usage:: EventStatus HeatingOil::heatOilEvent(double t_celsius) {

if (getOilTemp() < t_celsius) {

doHeatOil();

return EVENT_REPEAT;

}

setActiveState<OffState>();

return EVENT_DONE;

}

EventStatus HeatingOil::terminateEvent() {

emergencyStop({ESTOP_OPENED});

}

...

// adding heating event with temperature 45 °C and timeout 120 seconds.

// if timeout happens terminateEvent is called and state is switched to e-stop.

fsm.addEvent({&SuperState::heatOilEvent, 45}, 120);

See also: EventStatus

◆ addEvent() [3/4]

template<class SUPER_STATE >

void mcx::state_machine::StateMachine< SUPER_STATE >::addEvent	(	const Event2< SUPER_STATE > &	event,
		double	timeoutSec = `EVENT_DEFAULT_TIMEOUT_SEC`,
		EventPriority	priority = `LOW_PRIORITY_EVENT`,
		EventStatusSUPER_STATE::*	terminateEvent = `DEFAULT_TERMINATE_EVENT`
	)

inline

Adds event with two parameters to the event execution queue.

Parameters

event	- event with two parameters to add to the queue.
timeoutSec	- time in sec after which terminate callback is called.
priority	- priority of the event.
terminateEvent	- terminate callback, which is called if the event is not complete before timeout.

Example Usage:: EventStatus HeatingOil::heatOilEvent(double t_celsius_pre_heat,

double t_celsius_main_heater) {

if (getOilTemp() < t_celsius_pre_heat) {

doPreHeatOil();

return EVENT_REPEAT;

} else if (getOilTemp() < t_celsius_main_heater) {

doMainHeatOil();

return EVENT_REPEAT;

}

setActiveState<OffState>();

return EVENT_DONE;

}

EventStatus HeatingOil::terminateEvent() {

emergencyStop({ESTOP_OPENED});

}

...

// adding heating event with preliminary heating temperature 30 °C and

// main heating temperature 45 °C, timeout 120 seconds.

// if timeout happens terminateEvent is called and state is switched to e-stop.

fsm.addEvent({&SuperState::heatOilEvent, 30, 45}, 120);

See also: EventStatus

◆ addEvent() [4/4]

template<class SUPER_STATE >

void mcx::state_machine::StateMachine< SUPER_STATE >::addEvent	(	const Event3< SUPER_STATE > &	event,
		double	timeoutSec = `EVENT_DEFAULT_TIMEOUT_SEC`,
		EventPriority	priority = `LOW_PRIORITY_EVENT`,
		EventStatusSUPER_STATE::*	terminateEvent = `DEFAULT_TERMINATE_EVENT`
	)

inline

Adds event with three parameters to the event queue.

Parameters

event	- event with three parameters to add to the queue.
timeoutSec	- time in sec after which terminate callback is called.
priority	- priority of the event.
terminateEvent	- terminate callback, which is called if the event is not complete before timeout.

Example Usage:: EventStatus HeatingOil::heatOilEvent(int next_state_id,

double t_celsius_pre_heat, double t_celsius_main_heater) {

if (getOilTemp() < t_celsius_pre_heat) {

doHeatOil();

return EVENT_REPEAT;

} else if (getOilTemp() < t_celsius_main_heater) {

setActiveState(next_state_id);

return EVENT_DONE;

}

}

EventStatus HeatingOil::terminateEvent() {

emergencyStop({ESTOP_OPENED});

}

...

// adding heating event with return state id, preliminary heating

// temperature 30 °C and main heating temperature 45 °C, timeout 120 seconds.

// if timeout happens terminateEvent is called and state is switched to e-stop.

fsm.addEvent(&SuperState::heatOilEvent, OffState::id, 30, 45 120);

See also: EventStatus

◆ clear()

template<class SUPER_STATE >

void mcx::state_machine::StateMachine< SUPER_STATE >::clear	(	bool	highPriority = `true`,
		bool	lowPriority = `true`
	)

inline

Clears event queue.

Parameters

highPriority	- true - to clear high priority queue.
lowPriority	- true to clear low priority queue.

◆ createState() [1/2]

template<class SUPER_STATE >

template<class STATE >

void mcx::state_machine::StateMachine< SUPER_STATE >::createState ( )

inline

Creates new state.

Before the state can be used, it needs to be created and registered in the state machine. The state is created by a default constructor.

Template Parameters

STATE - class name which represents the state.

Example Usage:: robot_states_fsm.createState<InitState>();

robot_states_fsm.createState<OffState>();

robot_states_fsm.createState<EngagedState>();

◆ createState() [2/2]

template<class SUPER_STATE >

template<class STATE >

void mcx::state_machine::StateMachine< SUPER_STATE >::createState ( const STATE & new_state )

inline

Creates new state from the copy constructor.

This method is useful when there is a data which needs to be shared between states.

Parameters

new_state - constructor of the new state.

Example Usage:: // Data which is shared between states

struct SharedStateMachineData {

double engage_timeout_sec;

bool is_system_referenced;

...

}

SharedStateMachineData state_data;

...

robot_states_fsm.createState(InitState(state_data));

robot_states_fsm.createState(OffState(state_data));

robot_states_fsm.createState(EngagedState(state_data));

◆ deinitialize()

template<class SUPER_STATE >

void mcx::state_machine::StateMachine< SUPER_STATE >::deinitialize ( )

inline

Deinitialization of the queues and states.

If not called, will be called automatically in the destructor.

◆ emergencyStop()

template<class SUPER_STATE >

bool mcx::state_machine::StateMachine< SUPER_STATE >::emergencyStop ( const Error & error )

inline

Executes e-stop routine, add error code to the error list.

If active state has e-stop routine implemented, adds new error code to the error list, executes e-stop routine.

Parameters

error - error code which should be triggered

Returns: true - if e-stop has been handled in the active state.

◆ executeEvent() [1/4]

template<class SUPER_STATE >

EventStatus mcx::state_machine::StateMachine< SUPER_STATE >::executeEvent	(	const Event0< SUPER_STATE > &	event,
		bool	silently = `false`
	)

inline

Executes event in the active state.

Parameters

event	- event without parameters to execute.
silently	- don't produce log output.

Returns: returns execution status.

Example Usage:: EventStatus HeatingOil::heatOilEvent() {

if (oil_is_cold) {

doHeatOil();

return EVENT_REPEAT;

} else {

// compile time state transition

robot_states_fsm.setActiveState<OffState>();

}

return EVENT_DONE;

}

...

fsm.executeEvent(&SuperState::heatOilEvent);

See also: EventStatus

◆ executeEvent() [2/4]

template<class SUPER_STATE >

EventStatus mcx::state_machine::StateMachine< SUPER_STATE >::executeEvent	(	const Event1< SUPER_STATE > &	event,
		bool	silently = `false`
	)

inline

Executes event in the active state.

Parameters

event	- event with one parameter to execute.
silently	- don't produce log output.

Returns: returns execution status.

Example Usage:: EventStatus HeatingOil::heatOilEvent(int id) {

if (oil_is_cold) {

doHeatOil();

return EVENT_REPEAT;

} else {

// runtime state transition

robot_states_fsm.setActiveState(id);

}

return EVENT_DONE;

}

...

fsm.executeEvent({&SuperState::heatOilEvent, state_id});

See also: EventStatus

◆ executeEvent() [3/4]

template<class SUPER_STATE >

EventStatus mcx::state_machine::StateMachine< SUPER_STATE >::executeEvent	(	const Event2< SUPER_STATE > &	event,
		bool	silently = `false`
	)

inline

Executes event in the active state.

Parameters

event	- event with two parameters to execute.
silently	- don't produce log output.

Returns: returns execution status.

Example Usage:: EventStatus HeatingOil::heatOilEvent(int id, int max_number_of_trials) {

// event will terminate after max_number_of_trials of trials

if (oil_is_cold && (number_of_trials++ < max_number_of_trials)) {

doHeatOil();

return EVENT_REPEAT;

} else {

// runtime state transition

setActiveState(id);

}

return EVENT_DONE;

}

...

fsm.executeEvent({&SuperState::heatOilEvent, state_id, 2400});

See also: EventStatus

◆ executeEvent() [4/4]

template<class SUPER_STATE >

EventStatus mcx::state_machine::StateMachine< SUPER_STATE >::executeEvent	(	const Event3< SUPER_STATE > &	event,
		bool	silently = `false`
	)

inline

Executes event in the active state.

Parameters

event	- event with three parameters to execute.
silently	- don't produce log output.

Returns: returns execution status.

Example Usage:: EventStatus HeatingOil::heatOilEvent(int id, int max_number_of_trials, int t_celsius) {

if ((getOilTemp() < t_celsius) && (number_of_trials++ < max_number_of_trials)) {

doHeatOil();

return EVENT_REPEAT;

} else {

robot_states_fsm.setActiveState(id);

}

return EVENT_DONE;

}

...

fsm.executeEvent({&SuperState::heatOilEvent, state_id, 2400, 55});

See also: EventStatus

◆ forcedDisengaged()

template<class SUPER_STATE >

bool mcx::state_machine::StateMachine< SUPER_STATE >::forcedDisengaged ( const Error & error )

inline

Executes forced disengaged routine, add error code to the error list.

If active state has forced disengaged routine implemented, adds new error code to the error list, executes forced disengaged routine.

Parameters

error - error code which should be triggered

Returns: true - if warning has been handled in the active state.

◆ getErrorHandle() [1/2]

template<class SUPER_STATE >

ErrorHandle<SUPER_STATE>& mcx::state_machine::StateMachine< SUPER_STATE >::getErrorHandle ( )

inline

Returns reference to the error handler.

Returns: returns reference to the error handler.

◆ getErrorHandle() [2/2]

template<class SUPER_STATE >

const ErrorHandle<SUPER_STATE>& mcx::state_machine::StateMachine< SUPER_STATE >::getErrorHandle ( ) const

inline

Returns const reference to the error handler.

Returns: returns const reference to the error handler.

◆ getName()

template<class SUPER_STATE >

const std::string& mcx::state_machine::StateMachine< SUPER_STATE >::getName ( ) const

inline

Gets name of the state machine.

Returns: name of the state machine.

◆ getStateId()

template<class SUPER_STATE >

template<typename STATE >

int mcx::state_machine::StateMachine< SUPER_STATE >::getStateId ( )

inline

Given a state class name returns its id.

Template Parameters

STATE - state class name.

Returns: state id.

◆ isStateActive() [1/3]

template<class SUPER_STATE >

template<typename... STATES>

bool mcx::state_machine::StateMachine< SUPER_STATE >::isStateActive ( )

inline

Checks if given state is active by state class name.

Template Parameters

STATES - single or multiple state names.

Returns: returns success if one of the given state is active.

◆ isStateActive() [2/3]

template<class SUPER_STATE >

bool mcx::state_machine::StateMachine< SUPER_STATE >::isStateActive ( int id )

inline

Checks if given state is active by state id.

Parameters

id	- state id.

Returns: returns success if given state is active.

◆ isStateActive() [3/3]

template<class SUPER_STATE >

bool mcx::state_machine::StateMachine< SUPER_STATE >::isStateActive ( std::initializer_list< int > id_list )

inline

Checks if given states are active by the list of state id.

Parameters

id_list - list of state ids.

Returns: returns success if one of the given states is active.

◆ iterate()

template<class SUPER_STATE >

EventStatus mcx::state_machine::StateMachine< SUPER_STATE >::iterate ( double cycleTimeSec )

inline

Iterates an execution cycle of the state machine.

Parameters

cycleTimeSec - cycle time of the iteration in seconds.

Returns: status of the executed event.

See also: EventStatus

◆ length()

template<class SUPER_STATE >

size_t mcx::state_machine::StateMachine< SUPER_STATE >::length ( EventPriority priority = LOW_PRIORITY_EVENT )

inline

Returns length of the event queue.

Parameters

priority	- select type of the queue.
lowPriority	- true to clear low priority queue.

Returns: returns length of the selected queue.

◆ setActiveState() [1/2]

template<class SUPER_STATE >

template<class STATE >

STATE* mcx::state_machine::StateMachine< SUPER_STATE >::setActiveState ( bool output = true )

inline

Sets active state by class name.

Template Parameters

STATE - state to switch to.

Parameters

output - flag to produce output to console.

Example Usage:: robot_states_fsm.setActiveState<InitState>();

◆ setActiveState() [2/2]

template<class SUPER_STATE >

SUPER_STATE* mcx::state_machine::StateMachine< SUPER_STATE >::setActiveState	(	int	state_id,
		bool	output = `true`
	)

inline

Sets active state by class id.

Every state has a unique id, which can be used to set active state at runtime.

Parameters

state_id	- id of the state to switch to.
output	- flag to produce output to console.

Example Usage:: EventStatus heatOilEvent(int state_to_return_id) {

if (oil_is_cold) {

doHeatOil();

return EVENT_REPEAT;

} else {

robot_states_fsm.setActiveState(state_to_return_id);

}

return EVENT_DONE;

}

◆ setName()

template<class SUPER_STATE >

void mcx::state_machine::StateMachine< SUPER_STATE >::setName ( const std::string & new_name )

inline

Sets name of the state machine.

Parameters

new_name - name of the state machine.

◆ shutdown()

template<class SUPER_STATE >

bool mcx::state_machine::StateMachine< SUPER_STATE >::shutdown ( const Error & error )

inline

Executes shutdown routine, add error code to the error list.

If active state has shutdown routine implemented, adds new error code to the error list, executes shutdown routine.

Parameters

error - error code which should be triggered

Returns: true - if shutdown has been handled in the active state.

◆ warning()

template<class SUPER_STATE >

bool mcx::state_machine::StateMachine< SUPER_STATE >::warning ( const Error & error )

inline

Executes warning routine, add error code to the error list.

If active state has warning routine implemented, adds new error code to the error list, executes warning routine.

Parameters

error - error code which should be triggered

Returns: true - if warning has been handled in the active state.

The documentation for this class was generated from the following files:

state_machine/sm_state.h
state_machine/sm_statemachine.h

Public Member Functions

Friends

Detailed Description

template<class SUPER_STATE> class mcx::state_machine::StateMachine< SUPER_STATE >

Member Function Documentation

◆ addEvent() [1/4]

◆ addEvent() [2/4]

◆ addEvent() [3/4]

◆ addEvent() [4/4]

◆ clear()

◆ createState() [1/2]

◆ createState() [2/2]

◆ deinitialize()

◆ emergencyStop()

◆ executeEvent() [1/4]

◆ executeEvent() [2/4]

◆ executeEvent() [3/4]

◆ executeEvent() [4/4]

◆ forcedDisengaged()

◆ getErrorHandle() [1/2]

◆ getErrorHandle() [2/2]

◆ getName()

◆ getStateId()

◆ isStateActive() [1/3]

◆ isStateActive() [2/3]

◆ isStateActive() [3/3]

◆ iterate()

◆ length()

◆ setActiveState() [1/2]

◆ setActiveState() [2/2]

◆ setName()

◆ shutdown()

◆ warning()

template<class SUPER_STATE>
class mcx::state_machine::StateMachine< SUPER_STATE >