Skip to content

ROS2 Bridge

The PhyTrace ROS2 Bridge is a drop-in container node that connects any ROS2 robot to PhyCloud without modifying your existing robot code. It subscribes to standard ROS2 topics, normalizes every message to the PhyTrace UDM, and streams batched telemetry to PhyCloud over HTTP. Once data is in PhyCloud, PhySafe can enforce safety rules against it in real time and PhyComp can run compliance checks across your fleet.

Architecture

graph LR
    A[ROS2 Robot Topics] --> B[PhyTrace Bridge Node]
    B --> C[UDM Normalization]
    C --> D[HTTP Batch Sink]
    D --> E[PhyCloud]
    E --> F[PhySafe]
    E --> G[PhyComp]
    E --> H[Phylyze]

Internal pipeline:

graph TD
    A["/odom, /battery_state, /scan\n/imu/data, /cmd_vel, /gps/fix\n/diagnostics, /goal_pose\n/joint_states, /delivery/status"] -->|ROS2 messages| B[topic_handlers.py]
    B -->|typed dicts| C[UDMBuilder]
    C -->|UDMEvent| D[CloudSink]
    D -->|HTTP POST batch| E[PhyCloud API]

Quick Start

# Set your credentials, then:
docker compose -f ros2_bridge/docker-compose.yml up --build

Full setup with environment variables:

PHYCLOUD_ENDPOINT=https://api.phycloud.phyware.io/v1 \
PHYCLOUD_API_KEY=your-api-key \
SOURCE_ID=my-robot-001 \
SOURCE_TYPE=delivery_robot \
docker compose -f ros2_bridge/docker-compose.yml up --build

The bridge uses network_mode: host so it automatically discovers ROS2 DDS traffic from your robot stack.

No ROS2 installed? Use the built-in simulation: 

cd ros2_bridge && pip install -r requirements.txt -e .
python -c "from delivery_robot_sim.sim_runner import run_simulation; print(run_simulation(num_ticks=100))"

Topic Coverage

Topic ROS2 Type UDM Domain Description
/odom nav_msgs/Odometry Location, Motion Robot odometry — position, orientation, velocity
/battery_state sensor_msgs/BatteryState Power Battery voltage, SoC, and charging state
/scan sensor_msgs/LaserScan Perception Laser scanner range array
/imu/data sensor_msgs/Imu Motion Orientation, angular velocity, linear acceleration
/cmd_vel geometry_msgs/Twist Motion Commanded linear and angular velocity
/gps/fix sensor_msgs/NavSatFix Location WGS84 GPS fix — lat, lon, altitude
/diagnostics diagnostic_msgs/DiagnosticArray Operational Hardware/software diagnostic status and errors
/goal_pose geometry_msgs/PoseStamped Navigation Current navigation goal in the map frame
/joint_states sensor_msgs/JointState Actuators Joint names, positions, velocities, efforts
/delivery/status std_msgs/String (JSON) Operational, Payload Delivery task state and payload metadata

Topics not present on your robot are silently skipped — no configuration needed.

Configuration

Variable Default Description
PHYCLOUD_ENDPOINT http://localhost:8000/api/v1 PhyCloud ingestion API base URL
PHYCLOUD_API_KEY (empty) API authentication key
SOURCE_ID / ROBOT_ID delivery-robot-001 Unique robot identifier
SOURCE_TYPE / ROBOT_TYPE delivery_robot Robot class (amr, agv, drone, etc.)
FLEET_ID (none) Fleet grouping identifier
SITE_ID (none) Site or facility identifier
SAMPLE_RATE_HZ 5.0 UDM event publish rate
BATCH_SIZE 10 Events per HTTP batch request

PhySafe & PhyComp Integration

Once telemetry is in PhyCloud, the rest of the PhyWare platform activates automatically:

  • PhySafe evaluates every inbound event against your configured safety rules — e.g. geofence violations, battery thresholds, or unexpected motion states — and raises alerts in real time.
  • PhyComp runs continuous compliance checks across your fleet against standards such as ISO 10218 and the EU AI Act, using the structured UDM fields (operational state, error logs, navigation goals) populated by this bridge.

No additional integration work is required — both products consume the same UDM events the bridge already produces.

Full Onboarding Guide

For complete setup instructions, real-robot deployment, simulation usage, example UDM event payloads, testing, and troubleshooting, see the ROS2 Bridge Onboarding Guide.