State machine functions

execCancelStateTransition()

Function prototype:

void execCancelStateTransition(void);

Parameters: none

Returns: nothing

For the currently executing state machine, the current state number is copied to the next state number.

This function should not be called from an interrupt routine as it will cause unpredictable results.

execDisableStateMachine()

Function prototype:

boolean execDisableStateMachine(word or byte Machine);

Parameters: Machine state machine to be disabled

Returns: true if it succeeded or false if it failed. It will fail if the parameter passed is invalid.

This function sets this current state of a machine to zero (disabled).

This function can be called at any time (including from within the state machine to be disabled).

The current state table should not be accessed directly.

execEnableStateMachine()

Function prototype:

boolean execEnableStateMachine(word or byte Machine, byte InitialState);

Parameters: Machine state machine to be enabled
InitialState initial state of that state machine

Returns: true if it succeeded or false if it failed. It will fail if the parameters passed are invalid or if that state machine is already enabled, or if the state machine was disabled while it was being processed (which will always run to completion) and a request to enable was made while it was still being processed.

The executive starts up with all the state machines disabled unless the current state table is defined by the application as having other initial values.

If a controlled startup is required, then it is recommended to use this function.

execGetCurrentState()

Function prototype:

byte execGetCurrentState(word or byte Machine);

Parameters: Machine state machine to get current state of

Returns: the state number of the specified state machine or 0 if an invalid state machine number is passed (0 also indicates that a state machine is disabled).

This number is updated when the event processing function completes.

The current state machine can be determined by calling execGetStateMachine.

execGetNextState()

Function prototype:

byte execGetNextState(void);

Parameters: none

Returns: the state number that the currently being processed state machine will be set to when event processing function completes. If no state machine is being processed (this will only occur if this function is called from an interrupt routine or the idle routine) then zero will be returned.

execGetStateMachine()

Function prototype:

word or byte execGetStateMachine(void);

Parameters: none

Returns: the number of the state machine which is currently being processed. If no state machine is being processed (this will only occur if this function is called from an interrupt routine, or if called from the application idle) then the number of the last state machine to have been processed will be returned.

execSetCurrentState()

Function prototype:

boolean execSetCurrentState(word or byte Machine, byte NewState);

Parameters: Machine state machine to set current state of
NewState the state to change the state machine to

Returns: true if it succeeded or false if it failed. It will fail if the state specified is not a valid state for the state machine specified (or if the state machine number is invalid).

Use this function for (temporary) debugging purposes only.

Use execCancelStateTransition or execSetNextState to override the default state transition from within a state transition function. Use execEnableStateMachine to set the initial state of a state machine.

Use of this function may give misleading results in event tracing.

execSetNextState()

Function prototype:

boolean execSetNextState(byte NextState);

Parameters: NextState the state to divert the transition to

Returns: true if it succeeded or false if it failed. It will fail if the state specified is not a valid state for the current state machine.

This function is used to override the ‘next state’ value in the state transition table, in order to divert the state transition to another state.

This function should not be called from an interrupt routine as it will cause unpredictable results.