mcx::state_machine::StateMachine

11 minute read

mcx::state_machine::StateMachine

States machine manager and event interpreter. More…

#include <sm_statemachine.h>

Public Functions

	Name
	StateMachine()
virtual	~StateMachine()
void	deinitialize() Deinitialization of the queues and states.
void	setName(const std::string & new_name) Sets name of the state machine.
const std::string &	getName() const Gets name of the state machine.
template <class STATE > void	createState() Creates new state.
template <class STATE > void	createState(const STATE & new_state) Creates new state from the copy constructor.
template <class STATE > STATE *	setActiveState(bool output =true) Sets active state by class name.
SUPER_STATE *	setActiveState(int state_id, bool output =true) Sets active state by class id.
template <typename STATE > int	getStateId() Given a state class name returns its id.
template <typename… STATES> bool	isStateActive() Checks if given state is active by state class name.
bool	isStateActive(int id) Checks if given state is active by state id.
bool	isStateActive(std::initializer_list< int > id_list) Checks if given states are active by the list of state id.
EventStatus	executeEvent(const Event0< SUPER_STATE > & event, bool silently =false) Executes event in the active state.
EventStatus	executeEvent(const Event1< SUPER_STATE > & event, bool silently =false) Executes event in the active state.
EventStatus	executeEvent(const Event2< SUPER_STATE > & event, bool silently =false) Executes event in the active state.
EventStatus	executeEvent(const Event3< SUPER_STATE > & event, bool silently =false) Executes event in the active state.
void	addEvent(const Event0< SUPER_STATE > & event, double timeoutSec =EVENT_DEFAULT_TIMEOUT_SEC, EventPriority priority =LOW_PRIORITY_EVENT, EventStatusSUPER_STATE::* terminateEvent =DEFAULT_TERMINATE_EVENT) Adds event without parameters to the event execution queue.
void	addEvent(const Event1< SUPER_STATE > & event, double timeoutSec =EVENT_DEFAULT_TIMEOUT_SEC, EventPriority priority =LOW_PRIORITY_EVENT, EventStatusSUPER_STATE::* terminateEvent =DEFAULT_TERMINATE_EVENT) Adds event with one parameter to the event execution queue.
void	addEvent(const Event2< SUPER_STATE > & event, double timeoutSec =EVENT_DEFAULT_TIMEOUT_SEC, EventPriority priority =LOW_PRIORITY_EVENT, EventStatusSUPER_STATE::* terminateEvent =DEFAULT_TERMINATE_EVENT) Adds event with two parameters to the event execution queue.
void	addEvent(const Event3< SUPER_STATE > & event, double timeoutSec =EVENT_DEFAULT_TIMEOUT_SEC, EventPriority priority =LOW_PRIORITY_EVENT, EventStatusSUPER_STATE::* terminateEvent =DEFAULT_TERMINATE_EVENT) Adds event with three parameters to the event queue.
double	getDtSec() const
EventStatus	iterate(double cycleTimeSec) Iterates an execution cycle of the state machine.
void	clear(bool highPriority =true, bool lowPriority =true) Clears event queue.
size_t	length(EventPriority priority =LOW_PRIORITY_EVENT) Returns length of the event queue.
ErrorHandle< SUPER_STATE > &	getErrorHandle() Returns reference to the error handler.
const ErrorHandle< SUPER_STATE > &	getErrorHandle() const Returns const reference to the error handler.
bool	warning(const Error & error) Executes warning routine, add error code to the error list.
bool	forcedDisengaged(const Error & error) Executes forced disengaged routine, add error code to the error list.
bool	shutdown(const Error & error) Executes shutdown routine, add error code to the error list.
bool	emergencyStop(const Error & error) Executes e-stop routine, add error code to the error list.

Friends

	Name
class	ErrorHandle< SUPER_STATE >

Detailed Description

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

States machine manager and event interpreter.

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

Public Functions Documentation

function StateMachine

inline StateMachine()

function ~StateMachine

inline virtual ~StateMachine()

function deinitialize

inline void deinitialize()

Deinitialization of the queues and states.

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

function setName

inline void setName(
    const std::string & new_name
)

Sets name of the state machine.

Parameters:

new_name - name of the state machine.

function getName

inline const std::string & getName() const

Gets name of the state machine.

Return: name of the state machine.

function createState

template <class STATE >
inline void createState()

Creates new state.

Template Parameters:

STATE - class name which represents the state.

Par: Example Usage:

robot_states_fsm.createState<InitState>();
robot_states_fsm.createState<OffState>();
robot_states_fsm.createState<EngagedState>();

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.

function createState

template <class STATE >
inline void createState(
    const STATE & new_state
)

Creates new state from the copy constructor.

Parameters:

new_state - constructor of the new state.

Par: 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));

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

function setActiveState

template <class STATE >
inline STATE * setActiveState(
    bool output =true
)

Sets active state by class name.

Parameters:

output - flag to produce output to console.

Template Parameters:

STATE - state to switch to.

Par: Example Usage:

robot_states_fsm.setActiveState<InitState>();

function setActiveState

inline SUPER_STATE * setActiveState(
    int state_id,
    bool output =true
)

Sets active state by class id.

Parameters:

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

Par: 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;
}

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

function getStateId

template <typename STATE >
inline int getStateId()

Given a state class name returns its id.

Template Parameters:

STATE - state class name.

Return: state id.

function isStateActive

template <typename... STATES>
inline bool isStateActive()

Checks if given state is active by state class name.

Template Parameters:

STATES - single or multiple state names.

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

function isStateActive

inline bool isStateActive(
    int id
)

Checks if given state is active by state id.

Parameters:

id - state id.

Return: returns success if given state is active.

function isStateActive

inline bool isStateActive(
    std::initializer_list< int > id_list
)

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

Parameters:

id_list - list of state ids.

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

function executeEvent

inline EventStatus executeEvent(
    const Event0< SUPER_STATE > & event,
    bool silently =false
)

Executes event in the active state.

Parameters:

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

See: EventStatus

Return: returns execution status.

Par: 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);

function executeEvent

inline EventStatus executeEvent(
    const Event1< SUPER_STATE > & event,
    bool silently =false
)

Executes event in the active state.

Parameters:

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

See: EventStatus

Return: returns execution status.

Par: 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});

function executeEvent

inline EventStatus executeEvent(
    const Event2< SUPER_STATE > & event,
    bool silently =false
)

Executes event in the active state.

Parameters:

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

See: EventStatus

Return: returns execution status.

Par: 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});

function executeEvent

inline EventStatus executeEvent(
    const Event3< SUPER_STATE > & event,
    bool silently =false
)

Executes event in the active state.

Parameters:

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

See: EventStatus

Return: returns execution status.

Par: 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});

function addEvent

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

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.

See: EventStatus

Par: 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);

function addEvent

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

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.

See: EventStatus

Par: 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);

function addEvent

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

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.

See: EventStatus

Par: 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);

function addEvent

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

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.

See: EventStatus

Par: 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);

function getDtSec

inline double getDtSec() const

function iterate

inline EventStatus iterate(
    double cycleTimeSec
)

Iterates an execution cycle of the state machine.

Parameters:

cycleTimeSec - cycle time of the iteration in seconds.

See: EventStatus

Return: status of the executed event.

function clear

inline void clear(
    bool highPriority =true,
    bool lowPriority =true
)

Clears event queue.

Parameters:

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

function length

inline size_t length(
    EventPriority priority =LOW_PRIORITY_EVENT
)

Returns length of the event queue.

Parameters:

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

Return: returns length of the selected queue.

function getErrorHandle

inline ErrorHandle< SUPER_STATE > & getErrorHandle()

Returns reference to the error handler.

Return: returns reference to the error handler.

function getErrorHandle

inline const ErrorHandle< SUPER_STATE > & getErrorHandle() const

Returns const reference to the error handler.

Return: returns const reference to the error handler.

function warning

inline bool warning(
    const Error & error
)

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

Parameters:

error - error code which should be triggered

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

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

function forcedDisengaged

inline bool forcedDisengaged(
    const Error & error
)

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

Parameters:

error - error code which should be triggered

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

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

function shutdown

inline bool shutdown(
    const Error & error
)

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

Parameters:

error - error code which should be triggered

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

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

function emergencyStop

inline bool emergencyStop(
    const Error & error
)

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

Parameters:

error - error code which should be triggered

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

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

Friends

friend ErrorHandle< SUPER_STATE >

friend class ErrorHandle< SUPER_STATE >(
    ErrorHandle< SUPER_STATE > 
);

Updated on 2022-04-05 at 16:21:27 +0200