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.

../../_images/state_transition_diagram.svg

UML state diagram of the VCU.

State machine can be added to VCU by enabling the CONFIG_VCU_STATES Kconfig option.

Core Concepts

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_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
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

Functions

states_t states_get()

Get the current states.

Returns:

states_t Current states.

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.

struct states_callback
#include <vcu/ctrl/states.h>

State transition callback.

Public Members

states_t states

When transition from/to what states to call the callback.

states_handler_t handler

State transition handler.

void *user_data

User data for the callback functions.