A Reproducible Log for Tuning QoS and URDF Together in ROS 2

When a robot model renders incorrectly at the same time that its joint messages stop arriving, the fault rarely lies in one place. This article gives a practical operating method: a reproducible step-by-step record with inputs, observations, exceptions and an owner for each stage of the work. The scenario below uses two official ROS 2 Jazzy sources as reference evidence — the Quality of Service settings documentation and the URDF visual model tutorial. It is written for engineers building learning pathways on robot description pipelines, where the same session must cover transport behavior and geometry definition. The record owner is the integration engineer; every entry below is one row in that engineer's log.

Step 1: Record the Input Configuration Before Launch

The owner opens the log with the exact inputs. The URDF file is a minimal tree: one cylinder for base_link and one box for right_leg, joined by a fixed joint with a parent–child reference to the base. The launch command loads the model into robot_state_publisher and starts RViz through display.launch.py. On the communication side, the joint state publisher uses the default QoS profile for publishers, which the documentation describes as "keep last" history with a queue size of 10, "reliable" reliability, "volatile" durability, and system default liveliness. The observation column notes that no exception occurred at startup. The exception field stays empty because nothing failed yet. This row establishes the baseline: geometry inputs are two visual shapes under one root link, and transport inputs are the default profile rather than the sensor data profile.

Step 2: Observe the Initial Rendering and Message Flow

With the launch running, the owner records what RViz shows. The fixed frame is base_link, and the cylinder has its origin at the geometric center, so half of it falls below the grid. The leg overlaps the base because both shapes share the same origin when only the joint parent and child are defined without an origin offset. The joint messages do arrive under the reliable default, and no messages are dropped. The observation is that the visual overlap is a geometry exception, not a transport exception. The owner logs this under exceptions as "visual overlap from missing joint origin — see URDF origin and joint layout exercises". The transport column is clean because reliability is holding. No restart is needed for the communication side.

Step 3: Reproduce the Fix for the Model Geometry

The owner edits the file to add origins. The joint origin uses xyz="0 -0.22 0.25" in the parent frame, placing the child up and to the side; the leg's visual origin uses rpy="0 1.57075 0" xyz="0 0 -0.3" to rotate and offset the box. Inputs are the modified XML and the same launch command. Observations are that RViz stops overlapping the two shapes and the leg appears attached to the side of the torso. The exception field records "none after edit", and the owner note says the change is reproducible in a fresh session because the file and command are both saved. This row is the difference between passing a tutorial and reproducing an environment: the owner can hand the file and command to another engineer on ROS 2 discovery and node startup records and get the same picture.

Step 4: Switch Joint Publication to the Sensor Data Profile

Next the owner changes the publisher for joint states away from the default profile. The source material says the sensor data profile uses best effort reliability and a smaller queue size because receiving the latest sample quickly matters more than receiving every sample. Inputs are the same URDF and launch, plus a QoS override to sensor data. The observation is that messages now move faster under load but some samples may be lost if the network is not robust. The exception column notes "hypothetical: if run over a lossy wireless link, late joint states are dropped and RViz lags behind the true pose". This hypothetical example is labelled hypothetical, and the owner marks that it must be re-run on real hardware before being treated as fact. The learning point is that best effort is a choice with a cost, not a free speed gain.

Step 5: Test Incompatibility Between Profiles

The owner then makes the subscriber use a different profile on purpose to see what breaks. The QoS documentation warns that if different profiles are used between publisher and subscription, they can be incompatible and prevent message delivery. Inputs are one side on default reliable and the other forced to a mismatched durability or reliability setting. Observations are that RViz freezes because no joint state arrives, even though the model file itself is correct. The exception entry is "profile incompatibility blocked delivery — geometry is fine, transport is not". The owner records that the URDF fix from step 3 did not fail; only the communication did. This separates the two failure modes cleanly for anyone following the pathway.

Step 6: Close the Record With Owner Sign-Off and Reuse

The final row lists the durable artifacts: the URDF with joint and visual origins, the launch command, the two QoS configurations that were tested, and the hypothetical wireless result still pending validation. The owner signs the log and notes that the reliable default is safer for joint states on a wired bench, while the sensor data profile fits a high-rate stream where timeliness beats completeness. The durable value of this method is that a second engineer reads the inputs, sees the same observations, hits the same exceptions, and knows who to ask. It does not restate that QoS and URDF are both important; it shows one session where each was changed in turn and the result was written down. That is what makes the next debugging session on the same robot shorter than the last.