YASMIN Plugins Manager

Plugin Types

C++ Plugins

C++ states are discovered through the ROS 2 pluginlib resource index. Any class registered with base_class_type="yasmin::State" in a plugins.xml file is detected automatically.

<library path="lib/libmy_states">
  <class name="my_package/MyState"
         type="my_package::MyState"
         base_class_type="yasmin::State">
    <description>A custom C++ state.</description>
  </class>
</library>

The plugin identifier for C++ states follows the package_name/ClassName convention.

Python Plugins

Python states are found by importing each ROS 2 package and inspecting every .py module (up to three directory levels deep). A class is accepted when it:

• Is a subclass of yasmin.State (but not State itself)
• Is defined in the inspected module (not re-imported)
• Can be instantiated without constructor arguments

The plugin identifier is module.submodule.ClassName.

XML State Machines

XML state machines are located by recursively walking each package’s share directory for .xml files whose root element is <StateMachine>. The identifier is package_name/file.xml.

Caching

Discovered plugins are cached to ~/.cache/yasmin_plugins_manager/plugins_cache.json. The cache location can be overridden with the YASMIN_CACHE environment variable. The cache is invalidated automatically when:

• The cache format version changes
• The ROS environment changes (distro, AMENT_PREFIX_PATH, Python version, or platform)
• Tracked files or directories have different modification times or sizes
• The set of installed packages changes
• The YASMIN_DISCOVERY_IGNORE_PACKAGES ignore list changes — the list is stored as part of the cache state so results are always consistent with the current env var value
• The cache age exceeds max_cache_age_sec (when set)

To force a full rescan regardless of cache state:

discover_plugins --force-refresh

Ignoring Packages and Files

There are three ways to exclude plugins from discovery:

Package-level Ignore

Add the following export to the package’s package.xml:

<export>
  <yasmin_plugins_manager ignore="true"/>
</export>

File-level Ignore (XML)

Place the following comment as the first non-empty line of the XML file:

<!-- YASMIN_IGNORE_DISCOVERY -->

Environment Variable

Set YASMIN_DISCOVERY_IGNORE_PACKAGES to a comma-, semicolon-, or colon-separated list of package names. The ignore list is stored as part of the cache state, so changing it automatically invalidates the cache and triggers a full re-discovery:

export YASMIN_DISCOVERY_IGNORE_PACKAGES="pkg_a,pkg_b"

Discovery Node

The package ships a discover_plugins console command that runs a full discovery scan and prints the results:

# Default (uses cache)
ros2 run yasmin_plugins_manager discover_plugins

# Force rescan
ros2 run yasmin_plugins_manager discover_plugins --force-refresh

# Print full plugin metadata
ros2 run yasmin_plugins_manager discover_plugins --verbose

# Invalidate cache older than 60 seconds
ros2 run yasmin_plugins_manager discover_plugins --max-cache-age-sec 60

Plugin Metadata

Each discovered plugin exposes the following metadata (when available):

• Outcomes — The list of possible state outcomes
• Description — A human-readable summary
• Outcome descriptions — Per-outcome descriptions
• Input keys — Blackboard keys the state reads
• Output keys — Blackboard keys the state writes
• Parameters — Configurable parameters with names, types, defaults, and descriptions

You can inspect metadata for any individual plugin through the CLI:

ros2 yasmin info yasmin_pcl/VoxelGridState