mvsim-urdf2xml
mvsim-urdf2xml is a standalone command-line tool that generates an MVSim vehicle class XML
file from a URDF robot description, or checks an existing vehicle XML file against it.
The simulator itself only reads MVSim XML files. This tool lets the URDF remain the single
source of truth for the robot geometry (wheel positions and sizes, chassis, sensor poses,
visual meshes), while MVSim-specific parameters (dynamics class, controller, friction, sensor
models) come from a small mapping file. Regenerate the XML whenever the URDF changes, or use
--check (e.g. in CI) to detect when both have diverged.
Usage
# Expand xacro files first:
xacro my_robot.urdf.xacro > my_robot.urdf
mvsim-urdf2xml my_robot.urdf mapping.yaml -o my_robot.vehicle.xml
mvsim-urdf2xml my_robot.urdf mapping.yaml --check my_robot.vehicle.xml
From ROS 2: ros2 run mvsim mvsim-urdf2xml .... It only needs Python 3 and PyYAML.
Mapping file
Example (mvsim_tutorial/urdf2xml/jackal_mapping.yaml):
# Mapping file for mvsim-urdf2xml: generates "jackal_from_urdf.vehicle.xml"
# from ../ros2_control/jackal.urdf. Regenerate it with:
# mvsim-urdf2xml ../ros2_control/jackal.urdf jackal_mapping.yaml -o jackal_from_urdf.vehicle.xml
vehicle_class: jackal_from_urdf
# URDF link used as the MVSim vehicle frame. It must be on the ground plane
# (MVSim vehicle frames are on the ground), e.g. "base_footprint".
base_link: base_link
dynamics: differential_4_wheels
# MVSim wheel tag -> URDF wheel joint
wheels:
lf_wheel: lf_wheel_joint
rf_wheel: rf_wheel_joint
lr_wheel: lr_wheel_joint
rr_wheel: rr_wheel_joint
chassis:
link: chassis_link # chassis footprint and height from its box geometry
mass: 10.0 # overrides the sum of URDF link masses
# Optional, copied verbatim:
controller: |
<controller class="${controller|twist_pid}">
<KP>56</KP> <KI>140</KI> <KD>0</KD> <max_torque>100</max_torque>
<controllers_yaml>${controllers_yaml|}</controllers_yaml>
<robot_description>${robot_description|generated}</robot_description>
</controller>
friction: |
<friction class="default">
<mu>0.8</mu>
<C_damping>0.05</C_damping>
</friction>
# Sensors: URDF link (it becomes the sensor name and TF frame_id) and the MVSim
# sensor definition to include (relative to the generated file), plus optional
# extra include arguments. The sensor pose comes from the URDF.
sensors:
- link: laser1
include: ${MVSIM_CURRENT_FILE_DIRECTORY}/../../definitions/lidar2d.sensor.xml
args:
sensor_period_sec: 0.05
base_link: the URDF link used as the vehicle frame. MVSim vehicle frames are on the ground: if the URDFbase_linkis above the ground, use a frame on the ground (e.g.base_footprint). The tool warns if wheel centers are not at their radius height. If it is notbase_link, its name is written as the vehicle<base_frame_id>, so MVSim uses it in ROS (TFs and messageframe_id) and does not publish its defaultbase_link -> base_footprintTF: the TF tree is that of the URDF.dynamics:differential,differential_3_wheels,differential_4_wheels,ackermannorackermann_drivetrain;wheelsmaps each MVSim wheel tag of that class to a URDF joint. Wheel position, diameter, width (from acylindergeometry) and mass come from the URDF, and the joint name is written as the wheeljoint_name(used by ros2_control).Ackermann classes: the front axle position and track (
f_wheels_x,f_wheels_d) come from the front wheels. Optionally,steering_jointslists the URDF steering joints, either one central joint or the two front wheel ones, whose<limit>givesmax_steer_ang_deg(for front wheel joints, from the inner wheel limits: theupperone of the left wheel and thelowerone of the right wheel) andmax_steer_rate_deg(fromvelocity).chassis: optionallinkwhoseboxgeometry gives the chassis footprint and height, and optional overridesmass,zmin,zmax. By default, the mass is the sum of the masses of the other links.controllerandfriction: XML copied verbatim.sensors: for each one, the URDFlink(it becomes the sensor name, hence its TFframe_id), the MVSim sensor definition file toinclude, optional extraargs(values may use variables of the including file, e.g.${rate|10}), and an optionalifcondition (e.g.${use_camera|false}) that wraps the sensor in an<if>tag, so the world file that includes the vehicle can enable it. The sensor pose is computed through the chain of joints frombase_link. For pinhole cameras (+Zforward), map the URDF optical frame link.visual(defaulttrue): emit the mesh visuals of non-wheel links, resolvingpackage://URIs withpackage_paths(a map package name to directory) or the ROS environment.
Examples
mvsim_tutorial/urdf2xml/jackal_mapping.yaml(above).mvsim_tutorial/urdf2xml/skid_steer_4wd_mapping.yaml: a 4-wheel skid-steer robot whose URDF (mvsim_tutorial/ros2_control/skid_steer_4wd.urdf) hasbase_footprinton the ground andbase_linkabove it. It generatesskid_steer_4wd.vehicle.xml, used bymvsim_tutorial/demo_ros2_control_skid_steer.world.xml:ros2 launch mvsim demo_ros2_control.launch.py vehicle:=skid_steer_4wd robot_description:=urdf
Without ros2_control, the generated vehicle uses its default controller (
twist_pid, driven withcmd_vel) in any world that includes it.
Sensor TFs with robot_state_publisher
When robot_state_publisher publishes the URDF TFs, set the mvsim_node parameter
publish_sensor_tf:=false so the sensor TFs are not published twice.