When running with a real robot, the ROS client libraries will use "wall-clock" time (i.e. the time your computer reports). When you are running in simulation, it is desirable to instead have a simulated time so that you can have accelerated, slowed, or stepped control. For example, if you are playing back sensor data into your system, you may wish to have your time correspond to the timestamps of the sensor data.

To support this, the ROS client libraries listen to a global /clock topic that is used to published simulated time within a runtime system (no messages are sent to /clock when using wall-clock time).

In order for your code to work as seamlessly as possible between simulated and wall clock time, it is important that all code use the appropriate ROS client library API for accessing time and sleeping instead of using the language-native routines. These APIs are described briefly below, though you should familiarize yourself with your client library of choice for more details.

If you are using wall-clock time, it is important that you synchronize time between the machines that you are using. ROS does not provide this functionality as there are already well-established methods (e.g. ntp) for doing this.

NOTE: this is not an API for real-time systems!

/use_sim_time parameter

The /use_sim_time Parameter is set to true whenever simulated time is being used. The reason for this Parameter is that there is a lag between when a Node starts and the first message on the /clock Topic is received.

Client implementations may have this behavior: If the /use_sim_time parameter is set, the clients will ignore wall clock time. Clients will return time 0 until they have received a value from /clock.

This holds in roscpp for: ros::Time::now() as well as for rospy: rospy.get_rostime().

So for calculations of simulated durations, clients should always wait until the first non-zero value has been received by the client before starting to measure, because simulation /clock may be at a high value while the client API still return 0 for a short lag until the first message has been received.

The time will only be updated on receipt of a message on the /clock topic.

/clock Topic

Nodes are automatically subscribed to the /clock Topic, which is a global Topic published by a Clock Server. The Clock Server publishes regular time Messages (at an unspecified rate).

Clock Server

In most cases, the Clock Server is either a simulator or a log playback tool. The Clock Server is a ROS node that is the sole publisher to the /clock topic. If it is not present, client libraries are free to infer that they can use wall-clock time. In order to resolve any issues with startup order, it is important that the /use_sim_time Parameter is set to true in any launch files using a Clock Server. If you are playing back a bag file with rosbag play, using the --clock option will run a Clock Server while the bag file is being played.

Clock Message

roslib/Clock (Up to C Turtle)

rosgraph_msgs/Clock (Diamondback and later):

time clock

Client Libraries

NOTE: for more documentation, please consult the "Code API" of the relevant ROS Package.

roscpp

//Get the time and store it in the time variable.
ros::Time time = ros::Time::now()
//Wait a duration of one second.
ros::Duration d = ros::Duration(1, 0);
d.sleep();

rospy

rospy.get_rostime() #get time as rospy.Time instance
rospy.get_time() #get time as float secs
rospy.sleep(duration)

Method signatures are dependent on the host language

Implementation Details

If the /clock topic is not active, the client libraries default to returning the wall-clock time. The /use_sim_time parameter forces clients to never look at wall-clock time. ROS does not make any efforts to synchronize wall-clock time between machines, so it is recommended that NTP or similar protocols are run on every machine.