ROS2 Interfaces

The vyra_base/interfaces Paket enthält alle Basis-ROS2-Interfaces for das VYRA-Framework. Thise Interfaces definieren standardisierte messages, Services and Actions.

Overview

ROS2-Interfaces in VYRA bestehen from drei Typen:

  1. Messages (.msg): Datenstrukturen for Topics

  2. Services (.srv): Request/Response-Definitionen

  3. Actions (.action): Langläufige Operationen with Feedback

Alle VYRA-Module can diese Basis-Interfaces use, um standardisierte Kommunikation to gewährleisen.

Available Interfaces

Messages (msg/)

Interface

Description

VBASEUpdateParamEvent.msg

Event message for parameter changes (used by the parameter system)

VBASEVolatileLis.msg

List of all volatile keys

VBASEVolatileHash.msg

Hash value for volatile data

Services (srv/)

Interface

Description

VBASESetParam.srv

Set parameter (Request: name, value / Response: success)

VBASEReadAllParams.srv

Read all parameters (Response: list of all parameters)

VBASEStateResume.srv

State Machine resume (for Pause/Resume functionality)

VBASESecurityRequestAccess.srv

Request security access (Security Framework)

Actions (action/)

Interface

Description

VBASEInitiateUpdate.action

Initiate software update (long-running operation with progress feedback)

Interface-Metadata

Interfaces are described via JSON configuration files. These can be found in config/*.json and define how interfaces are used.

Example Metadata

Parameter-Service-Definition (config/parameter_metadata.json):

{
    "services": [
        {
            "name": "set_parameter",
            "type": "vyra_base_interfaces/srv/VBASESetParam",
            "description": "Set a parameter value",
            "implementation": "vyra_base.core.parameter.Parameter.set_parameter"
        },
        {
            "name": "read_all_params",
            "type": "vyra_base_interfaces/srv/VBASEReadAllParams",
            "description": "Read all parameters",
            "implementation": "vyra_base.core.parameter.Parameter.read_all_params"
        }
    ]
}

Purpose:

  • Automatic service registration through entity.set_interfaces()

  • Documentation of available interfaces

  • Mapping of service names to implementations

Interface-Definition

Example: Define Service

VBASESetParam.srv:

# Request
string parameter_name
string parameter_value
---
# Response
bool success
string message

Meaning:

  • Above ---: Request structure

  • Below ---: Response structure

  • Comments with #

Example: Define Message

VBASEUpdateParamEvent.msg:

# Parameter-Update-Event
string parameter_name
string old_value
string new_value
builtin_interfaces/Time timestamp

Own Module Interfaces

Each VYRA module should have its own interface package:

v2_modulemanager_*_interfaces/
├── msg/
│   └── CustomMessage.msg
├── srv/
│   └── CustomService.srv
├── action/
│   └── CustomAction.action
├── config/
│   └── metadata.json
├── CMakeLiss.txt
└── package.xml

Naming Convention:

  • Module name + _interfaces (e.g. v2_modulemanager_interfaces)

  • Prefix for interface names with module abbreviation (e.g. MM for ModuleManager)

Interface Usage

In Python Code

# Import base interfaces
from vyra_base_interfaces.srv import VBASESetParam
from vyra_base_interfaces.msg import VBASEUpdateParamEvent

# Create service client
job = create_vyra_job(
    node=entity.node,
    service_name="/my_module/set_parameter",
    service_type=VBASESetParam
)

# Create request
request = VBASESetParam.Request()
request.parameter_name = "max_speed"
request.parameter_value = "100.0"

# Call service
response = await job.call_async(request)

In JSON Metadata

{
    "services": [
        {
            "name": "my_custom_service",
            "type": "my_module_interfaces/srv/MyService",
            "description": "Mein eigener Service"
        }
    ],
    "topics": [
        {
            "name": "sensor_data",
            "type": "sensor_msgs/msg/Temperature",
            "qos": "sensor_data"
        }
    ]
}

Automatic Registration

Entity loads and registers interfaces automatically:

# In _base_.py
async def build_base():
    entity = await build_entity(project_settings)

    # Interfaces load (from JSON-Metadaten)
    base_interfaces = await _create_base_interfaces()

    # Automatische ROS2-Service-Registration
    await entity.set_interfaces(base_interfaces)

    return entity

Process:

  1. JSON metadata read (config/*.json)

  2. mport interface types

  3. Methods with @remote_service can be found

  4. Register ROS2 services

  5. Update DataSpace

Best Practices

✅ Recommended:

  • Use your VYRA base interfaces where possible

  • Create your own interface packages for module-specific types

  • Document your interfaces in JSON metadata

  • Use your namespaces for interface names (e.g. VBASE, MM)

  • Version your interface changes

❌ Avoid:

  • Direct use of ROS2 standard interfaces without wrapper

  • Excessively complex messages (> 1 KB)

  • Interfaces without metadata documentation

  • Breaking changes to existing interfaces

Colcon Build

Interfaces must be compiled with colcon build:

# In the module root
source /opt/ros/kilted/setup.bash
colcon build --packages-select vyra_base_interfaces
source install/setup.bash

After the build, the interfaces are available in Python:

from vyra_base_interfaces.srv import VBASESetParam
# ✅ Works after colcon build

Interface-Pfade

Source: src/vyra_base/interfaces/

After Build: install/vyra_base_interfaces/

Python Import: from vyra_base_interfaces.srv import * NFS-Share: /nfs/vyra_interfaces/ (for all modules accessible)

Further Information