Troubleshooting

This page covers some common problems encountered when installing and using the Staubli ROS2 driver. If your issue is not listed here, check the robot logs first (see Show robot logs) — the VAL3 application logs most error conditions with a description.

Connection issues

“Failed to connect to robot” at driver startup

The driver prints this error and exits if it cannot receive a valid state message from the robot within the connection timeout (5 seconds).

Check in order:

The VAL3 application is loaded and running on the pendant (the status LED next to ros2_server should be green, not flashing).
The robot IP is reachable from your PC:
```
ping 192.168.0.254
```
The PC Ethernet interface is configured with address 192.168.0.1 and mask 255.255.255.0. Any other address will be silently ignored by the robot.
The cable is connected to the J204 port on the CS9 controller, not J205 or any other port.
The sockets are configured on the pendant (E/S > Socket) with the correct remote IP matching your PC address.

Robot connects but disconnects after ~2 hours

The VAL3 addons alter and advCtrlFunctions are running in demo mode. In demo mode, the addons stop functioning after 2 hours, which causes the control task to fail. To fix this, obtain a full license for both addons from Staubli and install it on the controller.

Motion issues

Driver connects but the robot does not move

The hardware interface connects and publishes joint states, but sending a trajectory has no effect. Check the following:

Operation mode: the robot must be in AUTO mode, or in MANUAL mode with motion explicitly enabled (press the pause button — the blue LED should be ON and steady, not flashing).
E-stop: verify the emergency stop button is released and the safety has been restarted if needed.
Brakes: the brakes must also be released to exit the STOP mode.
Controller state: confirm the trajectory controller is active:
```
ros2 control list_controllers
```
The joint_trajectory_controller must be listed as active.

Robot stops unexpectedly mid-motion

The VAL3 application transitions to STOP mode if it detects a problem. Check the robot logs for the cause (see Show robot logs). Common entries:

ERROR ros2_server::controlTask : Error, command sequence delay too high (5)

This means the robot did not receive a command from the ROS2 driver for 5 or more consecutive control cycles (~20 ms at 250 Hz). Causes:

The Ethernet link is shared with other traffic or goes through a switch with buffering. Use a dedicated point-to-point Ethernet cable between the PC and the J204 port.
The ROS2 PC is overloaded and missing control loop deadlines. Check CPU usage; consider using a real-time kernel.
The driver crashed. Check the driver terminal for errors. A typical error occurs when a controller requests a mode switch (e.g., position → velocity) without passing through STOP first. This is a driver-level constraint; see control_modes for the correct transition sequence.

“NaN detected in command reference” in driver log

The active controller sent a NaN position command. This typically means the controller was activated before the robot state was valid, so its internal reference was never initialized.

Visualization issues

Rviz opens but the robot model is not visible

The URDF may not have loaded correctly, or the fixed frame is wrong.

Check that the Fixed Frame in Rviz is set to world (or whatever frame is appropriate for your setup).
In the launch terminal, look for URDF parse errors or mesh loading errors.

Rviz shows the robot but joint positions do not update

The joint_state_broadcaster is not active or has crashed.

ros2 control list_controllers

If joint_state_broadcaster is active, check that a robot_state_publisher node is running and that the TF tree is being published:

ros2 node list | grep robot_state_publisher

You can also verify that the /joint_states topic is being published:

ros2 topic hz /joint_states