ROS 2 and Vulcanexus Interface Reference¶

This page is the central ROS 2/Vulcanexus interface reference for open-robin. The workspace is the hardware-agnostic open module: an intent-driven welding demo that runs on synthetic data with no physical hardware, MoveIt, or Gazebo. The package names below are the current source of truth for the documentation and validation commands you will use when integrating the modules.

Runtime Baseline¶

Item	Current value	Evidence
ROS 2 distribution	Jazzy	`vulcanexus_ws/ws_setup.sh` sources `/opt/vulcanexus/jazzy/setup.bash`.
Vulcanexus base image	`eprosima/vulcanexus:jazzy-desktop-4.3.1`	`vulcanexus_ws/Dockerfile`.
ROS workspace	`/workspace/ros2_packages`	Mounted from `vulcanexus_ws/src` by `docker-compose.yaml`.
Compose service	`vulcanexus` / container `vulcanexus-bridge`	`docker-compose.yaml`.
Primary setup entry point	`source /workspace/ros2_packages/ws_setup.sh`	Used by the launch and validation commands below.
FIWARE DDS mapping file	`config-dds.json`	Mounted into Orion-LD as `/root/.orionld`.

DDS discovery requires Orion-LD and the ROS 2 publishers to use the same DDS domain. The checked-in DDS mapping file uses domain 0, and both Compose services (orion-ld and vulcanexus) set ROS_DOMAIN_ID=0 so Orion-LD discovers /robin/telemetry out of the box. If you change one, change all three. The FIWARE mapping details are documented in docs/reference/fiware_ngsi_ld_dds_mapping.rst.

Package Inventory¶

Package	Role
`welding_msgs`	Intent message and skill action definitions for the intent pipeline.
`welding_http_bridge`	HTTP / NGSI-LD (Orion-LD) to ROS 2 bridge; publishes `/intents`.
`welding_supervisor`	Intent-to-skill mission controller; routes `/intents` to skill actions.
`welding_home_skill`	Lifecycle skill: move the arm to home (simulation by default).
`welding_seam_skill`	Lifecycle skill: execute a weld seam and publish `ProcessTelemetry`.
`welding_manual_skill`	Lifecycle skill: adjust process parameters (clamped to safe ranges).
`welding_recommendation_skill`	Lifecycle skill: request AI welding parameters over HTTP.
`welding_demo`	Launch orchestrator; `welding_robin_sim.launch.py` is the no-hardware demo.
`robin_interfaces`	Generic ROBIN ROS 2 messages, services, and actions (telemetry schema + the richer set used by hardware-mode integrations).
`robin_telemetry`	ROS bag telemetry aggregator; combines recorded Fronius/geometry topics into `ProcessTelemetry` on `/robin/telemetry`.
`robin_description`	Hardware-agnostic URDF/xacro and meshes for the cell (UR10e + Fronius torch + Garmo profilometer + table). No nodes.

Package Layer Diagram¶

        graph TD
   UI["ROBIN Dashboard"]
   API["Process Intelligence API"]
   ORION["Orion-LD / NGSI-LD"]
   HTTP["welding_http_bridge"]
   INTENT["/intents<br/>welding_msgs/msg/Intent"]
   SUP["welding_supervisor"]
   SKILLS["welding_* skill action servers"]
   HW["hardware-mode backends<br/>(adopter-provided)"]
   TEL["/robin/telemetry<br/>robin_interfaces/msg/ProcessTelemetry"]
   MINTAKA["Mintaka / TROE history"]

   UI --> API
   API --> ORION
   ORION --> HTTP
   UI --> HTTP
   HTTP --> INTENT
   INTENT --> SUP
   SUP --> SKILLS
   SKILLS -. "use_simulation:=false" .-> HW
   SKILLS --> TEL
   TEL --> ORION
   ORION --> MINTAKA
   MINTAKA --> API

Nodes and Executables¶

Package	Executable or node	Main interface / purpose
`welding_http_bridge`	`welding_http_bridge`	HTTP server on `:8766` (`/intent`, Orion notifications); publishes `/intents`.
`welding_supervisor`	`welding_supervisor`	Subscribes `/intents`; routes to skill action servers; publishes `/doe/launch` and `/weld_errors`; calls `weld/pause`.
`welding_home_skill`	`welding_home_skill`	Action `welding_home_skill/execute` (`MoveToHome`); owns `/joint_states` in simulation.
`welding_seam_skill`	`welding_seam_skill`	Action `welding_seam_skill/execute` (`ExecuteSeam`); publishes `/robin/telemetry`; hosts `weld/pause`.
`welding_manual_skill`	`welding_manual_skill`	Action `welding_manual_skill/execute` (`ManualAdjust`); hardware mode calls `/fronius/set_*`.
`welding_recommendation_skill`	`welding_recommendation_skill`	Action `welding_recommendation_skill/execute` (`RequestAIRecommendation`); HTTP to `ROBIN_API_URL`.
`robin_telemetry`	`telemetry_aggregator`	Aggregates recorded `/robin/data/fronius` and `/robin/weld_dimensions` into `/robin/telemetry` for the ROS bag replay demo.

The skills run in simulation by default. A use_simulation:=false hardware mode delegates to generic interfaces (/move_home, /execute_bead, /fronius/set_*) that an adopter implements for their own robot and power source.

Messages¶

`welding_msgs/msg`¶

Message	Purpose
`Intent`	Intent bus message: type, JSON data, source, modality, priority, confidence.

`robin_interfaces/msg`¶

Message	Purpose
`ProcessTelemetry`	DDS/FIWARE telemetry snapshot: bead ID, progression, height, width, speed, current, voltage, and cross-sectional area.
`BeadGeometry` / `WeldProgression` / `WelderData` / `ActiveBead`	Weld geometry, progression, and welder data.
`ExperimentBead` / `ExperimentBeadSpec` / `PlateLayout` / `WeldPlate`	Experiment and plate definitions.

Actions¶

Action	Package	Goal
`ExecuteSeam`	`welding_msgs`	Cartesian weld-seam goal (seam_id, weld_speed, wire_feed_rate).
`MoveToHome`	`welding_msgs`	Home the arm (use_fast_speed).
`ManualAdjust`	`welding_msgs`	Adjust a process parameter (name, value, unit).
`RequestAIRecommendation`	`welding_msgs`	Request AI welding parameters (process_id, mode).
`ExecuteBead` / `WeldExperiment`	`robin_interfaces`	Bead / experiment execution targets for hardware-mode integrations.

Services¶

robin_interfaces provides the generic typed setters and calibration/planning services used by hardware-mode integrations, including SetFloat32 / SetInt32 (typed setters, e.g. /fronius/set_*), SetCtwd, SetTcpMode, FindSurface, CalibrateWireTip, CalibratePlatePlane, StartWeld, PlanExperiment, ApproveExperimentPlan, ReserveSlots, and ClearReservedSlots. The supervisor and seam skill use weld/pause (std_srvs/SetBool).

Core Topics¶

Topic	Type	Role
`/intents`	`welding_msgs/msg/Intent`	Operator/dashboard intents into the supervisor.
`/robin/telemetry`	`robin_interfaces/msg/ProcessTelemetry`	Normalized telemetry to the Orion-LD DDS bridge.
`/joint_states` / `/joint_states_manual`	`sensor_msgs/msg/JointState`	Arm pose (home skill owns `/joint_states`; seam skill animates via `/joint_states_manual`).
`/doe/launch` / `/weld_errors`	`std_msgs/msg/String`	DOE launch notifications and operator-visible errors.

ROS 2 to FIWARE Data Path¶

The reusable telemetry integration path is:

ROS 2 source -> /robin/telemetry -> Orion-LD DDS -> NGSI-LD Process entity -> TROE/Mintaka history -> API/dashboard.

In the no-hardware demo welding_seam_skill publishes synthetic robin_interfaces/msg/ProcessTelemetry on /robin/telemetry; config-dds.json maps DDS topic rt/robin/telemetry to NGSI-LD entity urn:ngsi-ld:Process:ros_bridge with attribute urn:robin:processTelemetry. For a real process, publish the same message from a node fed by your robot/sensor topics.

Dashboard and API Actions Back to ROS 2¶

The human input path is:

dashboard/API action -> pendingIntent in Orion-LD or direct HTTP -> welding_http_bridge -> /intents -> welding_supervisor -> welding_* skill action server.

welding_http_bridge supports two entry points:

POST /intent for direct testing or dashboard fallback.
Orion-LD subscription notifications when pendingIntent changes on Process entities.

welding_supervisor consumes /intents and routes the message to the appropriate skill action server. The ROS4HRI/ROS4RI role, intent, skill, task, and mission mapping is documented in docs/reference/ros4hri_ros4ri_alignment.rst.

Validation Commands¶

These commands are intended for a Linux Docker environment with the vulcanexus container running.

Build the workspace:

$ docker compose up -d vulcanexus
$ docker exec vulcanexus-bridge bash -lc \
    'cd /workspace/ros2_packages && source ws_setup.sh && colcon build --symlink-install'

List current packages:

$ docker exec vulcanexus-bridge bash -lc \
    'source /workspace/ros2_packages/ws_setup.sh && ros2 pkg list | grep -E "^(robin_|welding_)" | sort'

Expected package names:

robin_description
robin_interfaces
robin_telemetry
welding_demo
welding_home_skill
welding_http_bridge
welding_manual_skill
welding_msgs
welding_recommendation_skill
welding_seam_skill
welding_supervisor

Inspect key interfaces:

$ docker exec vulcanexus-bridge bash -lc \
    'source /workspace/ros2_packages/ws_setup.sh && ros2 interface show robin_interfaces/msg/ProcessTelemetry'
$ docker exec vulcanexus-bridge bash -lc \
    'source /workspace/ros2_packages/ws_setup.sh && ros2 interface show welding_msgs/msg/Intent'

Run the no-hardware intent path:

$ docker exec vulcanexus-bridge bash -lc \
    'source /workspace/ros2_packages/ws_setup.sh && ros2 launch welding_demo welding_robin_sim.launch.py'

In a second terminal:

$ curl -s -X POST http://localhost:8766/intent \
    -H 'Content-Type: application/json' \
    -d '{"intent": "START_PROCESS", "data": {"seam_id": "seam_01"}}'
{"status": "published", "intent": "START_PROCESS"}

Validate the DDS topic is visible after a telemetry publisher is active:

$ docker exec vulcanexus-bridge bash -lc \
    'source /workspace/ros2_packages/ws_setup.sh && ros2 topic list | grep /robin/telemetry'

Runtime Assumptions and Limits¶

The source-level package and interface inventory can be inspected on any platform. Full ROS 2 runtime validation is expected on Linux with Docker and the Vulcanexus image.
The intent/skill path uses simulation behavior by default; no physical hardware, MoveIt, or Gazebo is required.
Driving real hardware requires adopter-provided nodes that advertise the skills’ hardware-mode interfaces (/move_home, /execute_bead, /fronius/set_*), launched with use_simulation:=false.
DDS/FIWARE validation depends on aligned ROS/DDS domain IDs and host networking behavior. If Orion-LD does not discover /robin/telemetry, check ROS_DOMAIN_ID in both Compose services and config-dds.json.