State Machine
Overview
The state machine is part of the control system that manages the various states of the system. It provides a way to handle the transition of states using callback functions.
The state machine is defined as a Hierarchical state machine,
where the black filled circles represent the initial state and the initial state
transition of the state machine, meaning which substate to enter when
transitioning to the parent state. So the initial state of the VCU is
RTD_BLINK
.
UML state diagram of the VCU.
State machine can be added to VCU by enabling the CONFIG_VCU_STATES
Kconfig
option.
Core Concepts
States: Each state is represented by a bit in the
states_state
and can be queried usingstates_get()
.State Transitions: State transitions are requested using
states_transition()
with a command from thestates_trans_cmd
. However, the command is only executed if the source state of the command matches the current state. The validity can be checked usingstates_valid_transition()
or get the information of the command fromstates_transition_info()
.Callbacks: Modules can register callbacks via
STATES_CALLBACK_DEFINE
to be called when entering or exiting a state.
Runtime Behavior
Execution Context: State transition callbacks are executed in the same context as the thread requesting the transition, ensuring thread safety.
Usage
Requesting State Transitions
Use states_transition()
to request a state transition:
states_transition(TRANS_CMD_DISABLE);
Handling State Transitions
Define callbacks for state transitions using STATES_CALLBACK_DEFINE
.
For example:
static void my_callback(enum states_state state, bool is_entry, void *user_data) {
if (is_entry) {
printf("Entered state: %s\n", states_state_str(state));
} else {
printf("Exited state: %s\n", states_state_str(state));
}
}
STATES_CALLBACK_DEFINE(STATE_RUNNING, my_callback, NULL);
API Reference
- group States
Control system state machine.
Defines
-
STATES_CALLBACK_DEFINE_NAMED(_name, _states, _handler, _user_data)
Same as STATES_CALLBACK_DEFINE, but with a custom name for the callback.
-
STATES_CALLBACK_DEFINE(states, handler, user_data)
Define a callback for state transition.
Note
Since the name of the callback is derived from the name of
handler
, if the same handler is used for multiple callbacks, STATES_CALLBACK_DEFINE_NAMED can be used instead to prevent linker errors.- Parameters:
states – [in] When transition from/to what states to call the callback. Multiple states_state can be specified using bitwise OR operator (|).
handler – [in] Handler of the state transition.
user_data – [in] Pointer to custom data for the callback.
Typedefs
-
typedef uint32_t states_t
State machine states type, where each bit represents a state defined in states_state.
-
typedef void (*states_handler_t)(enum states_state state, bool is_entry, void *user_data)
State transition handler type.
- Param state:
[in] to transition from/to.
- Param is_entry:
[in] True when transitioning to the state. False when transition from.
- Param user_data:
[inout] Pointer to custom data for the callback provided by STATES_CALLBACK_DEFINE.
Enums
-
enum states_state
State machine states.
Values:
-
enumerator STATE_INVALID = 0
-
enumerator STATE_ERR_FREE = BIT(0)
-
enumerator STATE_READY = BIT(1)
-
enumerator STATE_RTD_BLINK = BIT(2)
-
enumerator STATE_RTD_STEADY = BIT(3)
-
enumerator STATE_RTD_READY = BIT(4)
-
enumerator STATE_RTD_SOUND = BIT(5)
-
enumerator STATE_RUNNING = BIT(6)
-
enumerator STATE_ERR = BIT(7)
-
enumerator STATE_ALL = UINT32_MAX
-
enumerator NUM_STATE = 8
-
enumerator STATE_INVALID = 0
-
enum states_trans_cmd
State transition commands.
Values:
-
enumerator TRANS_CMD_INVALID = 0
-
enumerator TRANS_CMD_ERR
-
enumerator TRANS_CMD_ERR_CLEAR
-
enumerator TRANS_CMD_PEDAL
-
enumerator TRANS_CMD_PEDAL_CLEAR
-
enumerator TRANS_CMD_RTD
-
enumerator TRANS_CMD_RTD_FINISH
-
enumerator TRANS_CMD_DISABLE
-
enumerator NUM_TRANS_CMD
-
enumerator TRANS_CMD_INVALID = 0
Functions
-
bool states_valid_transition(enum states_trans_cmd cmd)
Test if a state transition command is valid.
- Parameters:
cmd – [in] State transition command.
- Return values:
true – If the command can be executed.
false – If the command cannot be executed.
-
void states_transition(enum states_trans_cmd cmd)
Execute a state transition command to transition to a new state.
Warning
Must not be called from an ISR or within a state transition callback.
- Parameters:
cmd – [in] State transition command.
-
const char *states_state_str(enum states_state state)
Get the string representation of a state.
- Parameters:
state – [in] State.
- Returns:
const char* String representation.
-
int states_states_str(char *buf, size_t size, states_t states)
Get the string representation of states separated by commas in the same semantic as snprintf.
- Parameters:
buf – [out] Buffer to store the string representation.
size – [in] Size of the buffer.
states – [in] States.
- Returns:
int Number of bytes written to the buffer, excluding the null terminator which would be written if the buffer is large enough.
-
const struct states_trans_cmd_info *states_transition_info(enum states_trans_cmd cmd)
Get the information of a state transition.
- Parameters:
cmd – [in] State transition command.
- Returns:
const struct states_trans_cmd_info* Pointer to the state transition command information.
-
struct states_trans_cmd_info
- #include <vcu/ctrl/states.h>
State transition command information.
Public Members
-
enum states_state src
Source state to transition from.
-
enum states_state dst
Destination state to transition to.
-
const char *name
String representation of the command.
-
const char *desc
Description of the command.
-
enum states_state src
-
STATES_CALLBACK_DEFINE_NAMED(_name, _states, _handler, _user_data)