Discovery Options Reference

This document describes configuration options for the gateway’s discovery system. The discovery system maps ROS 2 graph entities (nodes, topics, services, actions) to SOVD entities (areas, components, apps).

Discovery Modes

The gateway supports three discovery modes, controlled by the discovery.mode parameter:

Discovery Modes
Mode	Description
`runtime_only`	Use ROS 2 graph introspection only. Nodes are discovered at runtime and mapped to SOVD entities using heuristic rules. (default)
`manifest_only`	Only expose entities declared in the manifest file. Runtime discovery is disabled.
`hybrid`	Manifest defines the structure, runtime links to discovered nodes.

Runtime Discovery Options

When using runtime_only or hybrid mode, the following options control how ROS 2 nodes are mapped to SOVD entities.

Synthetic Components

discovery:
  runtime:
    create_synthetic_components: true
    grouping_strategy: "namespace"
    synthetic_component_name_pattern: "{area}"

When create_synthetic_components is true:

Components are created as logical groupings of Apps
grouping_strategy: "namespace" groups nodes by their first namespace segment
synthetic_component_name_pattern defines the component ID format

Topic-Only Namespaces

Some ROS 2 systems have topics published to namespaces without any associated nodes. This is common with:

Isaac Sim and other simulators
External bridges (MQTT, Zenoh, ROS 1)
Dead/orphaned topics from crashed processes

The topic_only_policy controls how these namespaces are handled:

discovery:
  runtime:
    topic_only_policy: "create_component"
    min_topics_for_component: 1

Topic-Only Policies
Policy	Description
`ignore`	Don’t create any entities for topic-only namespaces. Use this to reduce noise from orphaned topics.
`create_component`	Create a Component with `source: "topic"` for each topic-only namespace. (default)
`create_area_only`	Only create the Area, but don’t create a Component. Useful when you want the namespace visible but not as a component.

The min_topics_for_component parameter (default: 1) sets the minimum number of topics required before creating a component. This can filter out namespaces with only a few stray topics.

Configuration Example

Complete YAML configuration for runtime discovery:

ros2_medkit_gateway:
  ros__parameters:
    discovery:
      mode: "runtime_only"

      runtime:
        # Map nodes to Apps
        expose_nodes_as_apps: true

        # Group Apps into Components by namespace
        create_synthetic_components: true
        grouping_strategy: "namespace"
        synthetic_component_name_pattern: "{area}"

        # Handle topic-only namespaces
        topic_only_policy: "create_component"
        min_topics_for_component: 2  # Require at least 2 topics

Command Line Override

Override discovery options via command line:

ros2 launch ros2_medkit_gateway gateway.launch.py \
  discovery.runtime.topic_only_policy:="ignore" \
  discovery.runtime.min_topics_for_component:=3