bpod_core.fsm.StateMachine
- class bpod_core.fsm.StateMachine
Bases:
BaseModelRepresents a state machine with a collection of states.
- classmethod from_dict(data) StateMachine
Creates a StateMachine instance from a dictionary.
- Parameters:
data (
dict) – A dictionary representation of a state machine.- Returns:
A StateMachine instance created from the provided dictionary.
- Return type:
- classmethod from_file(filename) StateMachine
Creates a StateMachine instance from a JSON or YAML file.
- Parameters:
filename (
os.PathLikeorstr) – The path to the file containing the state machine.- Returns:
A StateMachine instance created from the contens of the file.
- Return type:
- Raises:
FileNotFoundError – If the file does not exist.
ValueError – If the file extension is not .json, .yaml or .yml.
- classmethod from_json(json_str) StateMachine
Creates a StateMachine instance from a JSON string.
- Parameters:
json_str (
strorbytes) – A JSON string representation of a state machine.- Returns:
A StateMachine instance created from the provided JSON string.
- Return type:
- Raises:
pydantic.ValidationError – If the JSON string is not valid.
Notes
This is a thin wrapper around
model_validate_json()
- classmethod from_yaml(yaml_str) StateMachine
Creates a StateMachine instance from a YAML string.
- add_state(name, timer=0.0, transitions=None, actions=None, comment=None) None
Adds a new state to the state machine.
- Parameters:
name (
str) – The name of the state to be added.timer (
float, optional) – The duration of the state’s timer in seconds. Default to 0.transitions (
collections.abc.Mapping, optional) – A dictionary mapping conditions to target states for transitions. Defaults to an empty dictionary.actions (
collections.abc.Mapping, optional) – A dictionary of actions to be executed on entering the state. Defaults to an empty dictionary.comment (
str, optional) – An optional comment describing the state.
- Raises:
ValueError – If a state with the given name already exists in the state machine.
- Return type:
- set_global_counter(index, event, threshold) None
Configure a global timer with the specified parameters.
- set_global_timer(index, duration, onset_delay=0.0, channel=None, value_on=0, value_off=0, send_events=True, loop=0, loop_interval=0, onset_trigger=0) None
Configure a global timer with the specified parameters.
- Parameters:
index (
int) – The index of the global timer to configure.duration (
float) – The duration of the global timer in seconds.onset_delay (
float, optional) – The onset delay of the global timer in seconds. Default is 0.0.channel (
str, optional) – The channel affected by the global timer. Default is None.value_on (
int, optional) – The value to set the channel to when the timer is active. Default is 0.value_off (
int, optional) – The value to set the channel to when the timer is inactive. Default is 0.send_events (
bool, optional) – Whether the global timer sends events. Default is True.loop (
int, optional) – The number of times the timer should loop. Default is 0.loop_interval (
float, optional) – The interval in seconds between loops. Default is 0.onset_trigger (
int, optional) – An integer whose bits indicate other global timers to trigger.
- Return type:
- to_digraph() Digraph
Returns a graphviz Digraph instance representing the state machine.
The Digraph includes:
A point-shaped node representing the start of the state machine,
An optional ‘exit’ node if any state transitions to ‘exit’,
Record-like nodes for each state displaying state name, timer, comment and output actions, and
Edges representing state transitions based on conditions.
- Returns:
A graphviz Digraph instance representing the state machine.
- Return type:
Digraph
Notes
This method depends on the Graphviz system libraries to be installed. See https://graphviz.readthedocs.io/en/stable/manual.html#installation
- to_file(filename, overwrite=False, create_directory=False) None
Write the state machine to a file.
Depending on the file extension, different outputs are produced:
.json: writes a JSON representation of the state machine,
.yaml, .yml: writes a YAML representation of the state machine,
.pdf, .svg, .png: renders a state diagram and stores it to the specified file.
- Parameters:
filename (
os.PathLikeorstr) – Destination path. The file extension determines the output type.overwrite (
bool, optional) – If False (default) and the file already exists, a FileExistsError is raised. If True, existing files will be overwritten.create_directory (
bool, optional) – If True, the parent directory of the destination path will be created if it doesn’t exist. Default is False.
- Raises:
FileExistsError – If the destination file already exists and overwrite is False.
FileNotFoundError – If the parent directory of the destination path does not exist and create_directory is False.
ValueError – If the file extension is not one of: .json, .pdf, .svg, .png.
- Return type:
Notes
Rendering diagrams depends on the Graphviz system libraries to be installed. See https://graphviz.readthedocs.io/en/stable/manual.html#installation
- to_json(indent=None, exclude_defaults=True) str
Returns the state machine as a JSON string.
- Parameters:
indent (
intorNone, optional) – If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.exclude_defaults (
bool, optional) – Whether to exclude fields that are set to their default values. Defaults to True.
- Returns:
A dictionary representation of the state machine.
- Return type:
-
conditions:
Conditions A dictionary of conditions.
-
global_counters:
GlobalCounters A dictionary of global counters.
-
global_timers:
GlobalTimers A dictionary of global timers.
- model_config: ClassVar[ConfigDict] = {'title': 'State Machine', 'validate_assignment': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].