bpod_core.fsm¶

Module defining classes and types for creating and managing state machines.

Classes¶

class bpod_core.fsm.Actions ¶

Bases: ValidatedDict

A collection of actions.

class bpod_core.fsm.Condition ¶

Bases: BaseModel

A condition in the state machine.

class bpod_core.fsm.Conditions ¶

Bases: ValidatedDict

A collection of conditions.

class bpod_core.fsm.GlobalCounter ¶

Bases: BaseModel

A global counter in the state machine.

class bpod_core.fsm.GlobalCounters ¶

Bases: ValidatedDict

A collection of global counters.

class bpod_core.fsm.GlobalTimer ¶

Bases: BaseModel

A global timer in the state machine.

class bpod_core.fsm.GlobalTimers ¶

Bases: ValidatedDict

A collection of global timers.

class bpod_core.fsm.State ¶

Bases: BaseModel

A state in the state machine.

class bpod_core.fsm.StateMachine ¶

Bases: BaseModel

Definition of a Bpod finite-state machine.

classmethod from_dict(data) ¶

Create 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:: StateMachine

Notes

This is a thin wrapper around model_validate()

classmethod from_file(filename) ¶

Create a StateMachine instance from a JSON or YAML file.

Parameters:

filename (PathLike | str) – The path to the file containing the state machine.

Returns:

A StateMachine instance created from the contents of the file.

Return type:

StateMachine

Raises:

FileNotFoundError – If the file does not exist.
NotImplementedError – If the file extension is not .json, .yaml or .yml.
ValueError – If the file content is not valid JSON or YAML.

classmethod from_json(json_str) ¶

Create a StateMachine instance from a JSON string.

Parameters:: json_str (str | bytes) – A JSON string representation of a state machine.
Returns:: A StateMachine instance created from the provided JSON string.
Return type:: StateMachine
Raises:: ValueError – If the JSON string is not valid or does not represent a StateMachine.

Notes

This is a thin wrapper around model_validate_json()

classmethod from_yaml(yaml_str) ¶

Create a StateMachine instance from a YAML string.

Parameters:: yaml_str (str | bytes) – A YAML string representation of a state machine.
Returns:: A StateMachine instance created from the provided YAML string.
Return type:: StateMachine
Raises:: ValueError – If the YAML string is not valid or does not represent a StateMachine.

add_state(name, timer=0.0, transitions=None, actions=None, comment=None) ¶

Add a new state to the state machine.

Parameters:

name (str) – The name of the state to be added.
timer (float, default: 0.0) – The duration of the state’s timer.
transitions (dict[str, str | str] | None, default: None) – An optional dictionary mapping conditions to target states for transitions.
actions (dict[str, int] | None, default: None) – An optional dictionary of actions to be executed on entering the state.
comment (str | None, default: None) – An optional comment describing the state.

Raises:

ValueError – If a state with the given name already exists in the state machine.

check() ¶

Check validity of the state machine.

Raises:: ValueError – If the state machine is invalid.

Notes

This method only checks the general structure of the state machine, not its compatibility with the hardware. For the latter, see validate_state_machine().

set_condition(index, channel, value) ¶

Configure a condition with the specified parameters.

Parameters:

index (int) – The index of the condition. Zero-based.
channel (str) – The channel or global timer attached to the condition.
value (bool) – The value of the condition channel if the condition is met

Return type:

None

set_global_counter(index, event, threshold) ¶

Configure a global counter with the specified parameters.

Parameters:

index (int) – The index of the global counter. Zero-based.
event (str) – The name of the event to count.
threshold (int) – The count threshold to generate an event

Return type:

None

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.0, onset_trigger=0) ¶

Configure a global timer with the specified parameters.

Parameters:

index (int) – The index of the global timer to configure. Zero-based.
duration (float) – The duration of the global timer.
onset_delay (float, default: 0.0) – The onset delay of the global timer.
channel (str | None, default: None) – The channel affected by the global timer.
value_on (int, default: 0) – The value to set the channel to when the timer is active.
value_off (int, default: 0) – The value to set the channel to when the timer is inactive.
send_events (bool, default: True) – Whether the global timer sends events.
loop (int, default: 0) – The number of times the timer should loop
loop_interval (float, default: 0.0) – The interval between loops.
onset_trigger (int, default: 0) – An integer whose bits indicate other global timers to trigger.

Return type:

None

to_dict(*, exclude_defaults=True) ¶

Return the state machine as a dictionary.

Parameters:: exclude_defaults (bool, default: True) – Whether to exclude fields that are set to their default values.
Returns:: A dictionary representation of the state machine.
Return type:: dict

to_digraph(color_stroke='black', color_fill='white', color_highlight='lightblue', color_back='red') ¶

Return a graphviz Digraph instance representing the state machine.

Parameters:

color_stroke (tuple[int, int, int] | tuple[int, int, int, float] | str | Color, default: 'black') – Color for fonts, node outlines, and edges.
color_fill (tuple[int, int, int] | tuple[int, int, int, float] | str | Color, default: 'white') – Background color of state nodes.
color_highlight (tuple[int, int, int] | tuple[int, int, int, float] | str | Color, default: 'lightblue') – Background color of state header and comment rows.
color_back (tuple[int, int, int] | tuple[int, int, int, float] | str | Color, default: 'red') – Color for edges resulting from >back transitions.

Returns:

A graphviz Digraph instance representing the state machine.

Return type:

Digraph

Notes

This method depends on the Graphviz system libraries to be installed.

to_file(filename, *, overwrite=False, create_directory=False) ¶

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 (PathLike | str) – Destination path. The file extension determines the output type.
overwrite (bool, default: False) – If False and the file already exists, a FileExistsError is raised. If True, existing files will be overwritten.
create_directory (bool, default: False) – If True, the parent directory of the destination path will be created if it doesn’t exist.

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.

Notes

Rendering diagrams depends on the Graphviz system libraries to be installed.

to_json(indent=None, *, exclude_defaults=True) ¶

Return the state machine as a JSON string.

Parameters:

indent (None | int, default: None) – 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, default: True) – Whether to exclude fields that are set to their default values.

Returns:

A JSON string representation of the state machine.

Return type:

str

to_yaml(*, exclude_defaults=True) ¶

Return the state machine as a YAML string.

Parameters:: exclude_defaults (bool, default: True) – Whether to exclude fields that are set to their default values.
Returns:: A YAML string representation of the state machine.
Return type:: str

conditions: Conditions¶: A dictionary of conditions.

global_counters: GlobalCounters¶: A dictionary of global counters.

global_timers: GlobalTimers¶: A dictionary of global timers.

property hash: bytes ¶: Hash of the state machine.

name: Annotated[str, FieldInfo(annotation=NoneType, required=True, title='State Machine Name', description='The name of the state machine', metadata=[MinLen(min_length=1)])]¶: The name of the state machine.

states: States¶: A dictionary of states.

property valid: bool ¶: Returns True if the state machine is valid, False otherwise.

class bpod_core.fsm.States ¶

Bases: ValidatedDict

A collection of states.

property transition_targets: set[str] ¶: A set of all transition targets.

class bpod_core.fsm.Transitions ¶

Bases: ValidatedDict

A collection of state transitions.

Functions¶

bpod_core.fsm.dec_hook(obj_type, obj) ¶

Decode a dictionary into a BaseModel instance.

Return type:: Any

bpod_core.fsm.enc_hook(obj) ¶

Encode a BaseModel instance into a dictionary.

Return type:: Any

Attributes¶

bpod_core.fsm.StateName¶

A valid state machine state name.

alias of Annotated[str, FieldInfo(annotation=NoneType, required=True, title=’State Name’, description=’The name of the state’, metadata=[MinLen(min_length=1), _PydanticGeneralMetadata(pattern=re.compile(‘^(?!>)(?!exit$)(?!back$).+$’))]), WrapValidator(func=_validate_state_name, json_schema_input_type=PydanticUndefined)]