Introduction to YASMIN

YASMIN (Yet Another State MachINe) is a project focused on implementing robot behaviors using Finite State Machines (FSM). It is available for ROS 2, Python and C++.

YASMIN simplifies the development of complex robot behaviors by providing an intuitive framework for defining states, transitions, and hierarchical state machines. Whether you're building navigation systems, manipulation tasks, or multi-robot coordination, YASMIN offers the tools and flexibility to model your robot's behavior effectively. With built-in support for ROS 2 actions, services, and topics, YASMIN bridges the gap between high-level behavior specification and low-level robot control, enabling rapid prototyping and deployment of sophisticated robotic applications.

Features

• ROS 2 Integration: Integrates with ROS 2 for easy deployment.
• Multi-Language Support: Available for both Python and C++.
• Rapid Prototyping: Designed for fast iteration of behaviors.
• Predefined States: Includes states for ROS 2 actions, services, and topics.
• Web Viewer: Integrated web viewer for real-time monitoring.
• XML: Load and create state machines from XML files.

ROS 2 Integration

Note: The following examples are shown in Python. All features are also available in C++. See the tutorials section for examples in both languages.

Action States

ActionState encapsulates ROS 2 action client operations within a state machine. It manages goal creation, feedback processing, and result handling with built-in timeout and retry mechanisms.

from yasmin_ros import ActionState
from example_interfaces.action import Fibonacci

# Create an action state
action_state = ActionState(
    Fibonacci,
    "/fibonacci",
    create_goal_handler=lambda blackboard: Fibonacci.Goal(order=5),
    outcomes={"succeeded", "aborted", "canceled"}
)

Service States

ServiceState manages communication with ROS 2 services, handling request creation and response processing:

from yasmin_ros import ServiceState
from example_interfaces.srv import AddTwoInts

# Create a service state
service_state = ServiceState(
    AddTwoInts,
    "/add_two_ints",
    create_request_handler=lambda blackboard: AddTwoInts.Request(a=3, b=5),
    outcomes={"succeeded", "aborted"}
)

Monitor States

MonitorState subscribes to ROS 2 topics and processes incoming messages, useful for behavior triggered by sensor data or events:

from yasmin_ros import MonitorState
from std_msgs.msg import String

# Create a monitor state
monitor_state = MonitorState(
    String,
    "/topic",
    outcomes={"valid", "invalid"},
    monitor_handler=lambda blackboard, msg: "valid" if msg.data else "invalid"
)

Publisher States

PublisherState publishes messages to ROS 2 topics as part of state machine execution:

from yasmin_ros import PublisherState
from std_msgs.msg import String

publisher_state = PublisherState(
    String,
    "/topic",
    message_handler=lambda blackboard: String(data="Hello")
)

Distributions & Support

YASMIN supports multiple ROS 2 distributions. Check the table below for compatibility:

ROS 2 Distro	Build and Test	Docker Image
Foxy
Galactic
Humble
Iron
Jazzy
Kilted
Rolling

Installation

Debian Packages

Install YASMIN and all its packages directly from the ROS package repository. Replace $ROS_DISTRO with your ROS 2 distribution (e.g., humble, iron, jazzy):

sudo apt install ros-$ROS_DISTRO-yasmin ros-$ROS_DISTRO-yasmin-*

Building from Source

For the latest features or to contribute to development, build YASMIN from source. This method clones the repository into your ROS 2 workspace, installs dependencies, and compiles the packages:

cd ~/ros2_ws/src
git clone https://github.com/uleroboticsgroup/yasmin.git
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build

After building, source your workspace to make YASMIN available:

source ~/ros2_ws/install/setup.bash