smach.state_machine module

class smach.state_machine.StateMachine(outcomes, input_keys=[], output_keys=[])

Bases: Container

This is a finite state machine smach container. Note that though this is a state machine, it also implements the L{smach.State} interface, so these can be composed hierarchically, if such a pattern is desired.

States are added to the state machine as 3-tuple specifications:

• label

• state instance

• transitions

The label is a string, the state instance is any class that implements the L{smach.State} interface, and transitions is a dictionary mapping strings onto strings which represent the transitions out of this new state. Transitions can take one of three forms:

• OUTCOME -> STATE_LABEL

• OUTCOME -> None (or unspecified)

• OUTCOME -> SM_OUTCOME

static add(label, state, transitions=None, remapping=None)

Add a state to the opened state machine.

@type label: string @param label: The label of the state being added.

@param state: An instance of a class implementing the L{State} interface.

@param transitions: A dictionary mapping state outcomes to other state labels or container outcomes.

@param remapping: A dictrionary mapping local userdata keys to userdata keys in the container.

static add_auto(label, state, connector_outcomes, transitions=None, remapping=None)

Add a state to the state machine such that it automatically transitions to the next added state.

Each state added will receive an additional transition from it to the state which is added after it for every outcome given via connector_outcomes.

@type label: string @param label: The label of the state being added.

@param state: An instance of a class implementing the L{State} interface.

@type connector_outcomes: list of string @param connector_outcomes: For which of the added state’s outcomes a transition to the next added state should be generated.

@param transitions: A dictionary mapping state outcomes to other state labels. If one of these transitions follows the connector outcome specified in the constructor, the provided transition will override the automatically generated connector transition.

check_consistency()

Check the entire state machine for consistency. This asserts that all transition targets are states that are in the state machine. If this fails, it raises an L{InvalidTransitionError} with relevant information.

check_state_spec(label, state, transitions)

Validate full state specification (label, state, and transitions). This checks to make sure the required variables are in the state spec, as well as verifies that all outcomes referenced in the transitions are registered as valid outcomes in the state object. If a state specification fails validation, a L{smach.InvalidStateError} is thrown.

execute(parent_ud=None)

Run the state machine on entry to this state. This will set the “closed” flag and spin up the execute thread. Once this flag has been set, it will prevent more states from being added to the state machine.

get_active_states()

Get a description of the current states. Note that this is specific to container implementation.

@rtype: list of string

get_children()

Get the children of this container. This is empty for leaf states.

@rtype: dict of string: State @return: The sub-states of this container.

get_initial_states()

Get the initial states description.

@rtype: list of string

get_internal_edges()

Get the internal outcome edges of this container. Get a list of 3-tuples (OUTCOME, LABEL_FROM, LABEL_TO) which correspond to transitions inside this container.

@rtype: list of 3-tuple

is_running()

Returns true if the state machine is running.

request_preempt()

Propagate preempt to currently active state.

This will attempt to preempt the currently active state.

set_initial_state(initial_states, userdata=<smach.user_data.UserData object>)

Set initial active states of a container.

@type initial_states: list of string @param initial_states: A description of the initial active state of this container.

@type userdata: L{UserData} @param userdata: Initial userdata for this container.