Tutorials: Write a ROSTime concept article and tutorial

[clalancette]

Understanding how time works in ROS 2 can be challenging, especially when dealing with simulation. We should have a tutorial which goes over how ROS 2 deals with time, both real and simulated.

We have the following outline and notes already about ROS time

Conceptual

• Use the design article as a starting point for the conceptual article
• The audience is different; the design article is for developers working on time, the concepts article is for users of time
• So, don’t touch on why it was developed or the reasoning behind it’s design decisions
• Things to talk about:
  • All ROS users should be using ROS Time concepts
  • Use it for everything now hardware related
  • If you’re writing a ROS node you should be using ROS Time from the node
  • What ROS Time is:
    • ROS Time is a time abstraction that supports changing the speed of time, jumping time, etc
    • ROS Time is designed to allow you to use time primitives that will let you interact with with a system that may be paused or run at a non real time factor
    • The goal is that your algorithm will not be affected by the a change in the rate of time
      • Include example of an algorithm showing that
    • You want your algorithm to rely on the ROS Time abstraction so it will not be affected by running faster/slower/paused
    • Utilized with playback and simulation
    • Facilitates debugging. Pausing a system in a problem state, you can debug it much better.
    • Speeding up long running experiments to get results faster.

Tutorial

Background

ROS Time is a time abstraction that supports speeding up, slowing down, pausing, stopping and restarting time when running a simulation or experiment (ROS Time Concepts page)

Simulated time: gets the time from a message being published on a topic - can be artificially sped up, slowed down, paused, stopped, etc

System time: the time your computer thinks it is

It’s important to use rostime because so that your code is more reusable and it’s easier to incorporate with other pieces of ros code

In this tutorial were going to give you a script that creates a sin wave - this emulates your time dependent data source. Its a made up signal that doesnt serve any real world purpose. It’s a signal, represented by publishing an integer over time, then we’re gonna mess with time

We're going to see how to turn on simulated time using rostime and affect the flow of time and see how using ros time vs system time reacts

Goal

Use a generic example to demonstrate features of ROS Time, and understand its benefit over system time

OR

Learn how to apply ROS Time to your own nodes, and therefore be able to manipulate time in playback and simulations seamlessly

Quick points

• Script = command line options run on rosbag itself
• GUI = ros1 gui
• Dont want to expose complexity of a real bag file - just start with “a time source (generic)”. Using a rosbag or simulator would be the time source realistically
• Realistically, time source would be playing back a rosbag file or running a simulator. We’re starting them where rostime becomes relevant
• Goal is to teach good habits to use rostime so when they do use a simulator everything just works. Like learning how to clear the state with a method and say register this jump call back on the clock
• Real world = you have a bag that you’re playing back. GUI = is equivalent to just playing the rosbag and using command line options, we’re just adding the visuals
• People are using a static function that just gets system time, and when they do that rostime is broken in their systems, which makes them not reusable
• “When you’re playing back bag files, it may loop. We’re simulating it with a jump. This could represent something like a pause for 5 seconds,
• Teach people to code defensively by showing them how to handle all edge cases
• What causes time to jump? Bag files looping (ending and jumping back to the beginning), simulator running coarsely, when you start and stop the time source, when you switch between system time and sim time
  pausing : sleeping on the ros clock and not on the system clock
• Speed up, slow down, and pause all go together (first part of the tutorial)
• The wave will be used for both parts (manipulating and jumping) - rqt-plot to visualize
• Write a little script to input the wave, and add an averager? (22:50)
• Write an averager. Estimate of where the “vehicle” is
• Sinusoid input, signal with smaller noise wave
• Time source GUI will print out nicely, reader doesn’t have to worry about that, we tell them what it’s doing
• Then there’s another script that does the averaging over time function, and reader modifies to change from system time to rostime, start with running on system time and point out the issues, then after changing to rostime show how it fixes, and then add a callback to show how it fixes the jump problems
• Give them a time source that they’ll run (script generating double sinusoidal wave)
• Set up the GUI: buttons: speed up, slow down, pause, start rostime, stop rostime, reset, loop, jump forward
• Utilize rqt-plot for the visual (python)
• But first prototype with just terminal interface (keys for the buttons and output in the terminal)

Main points

• Turning simulated time on and off
• Pausing simulated time to… ?
• Slow simulated time down to debug
• Speed simulated time up to run through long experiments
• Switch between simulated time and system time
• Deal with time jumps

Steps

• Time source
  • Sine wave script plotting some arbitrary integer against time
  • Equivalent to whatever time source one would be analyzing, normally a rosbag
• rqt_plot
  • Visualization of the time source and the changes ROS Time functions can have on a time source
  • Equivalent to whatever output one would see while manipulating their time source, e.g. output of experiment results or simulation
• GUI / keyboard input for prototype
  • Speed up, slow down, pause, stop, reset, loop, jump time
  • Some options are equivalent to command-line tools one would run on a rosbag or simulation (slow, fast, pause, stop, start)
  • The rest are just there to emulate issues in playback or simulation (loop, jump), so the reader can fix it (reset)
• With the script, demonstrate toggling between simulated and system time
• Have the publisher output what type of time it’d publishing and the value, and the current system time
• Ensure that the playback tool restores to system time when exited and stops publishing the clock
• Manipulating time
  • For each manipulation:
    • Explain why you would realistically do that (working with a bag file, simulation, etc)
    • Utilize the tool and its options to manipulate the time source
    • Describe the resulting effect on rqt_plot visualization and what it represents
  • Manipulations:
    • Pausing
    • Speeding up time
    • Slowing down time
    • Switching between system time and sim time
• Time jumps
  • There are several situations that will cause a time jump, including toggling between system and simulated time as we just did in the last section.
  • Jumps in time can sacrifice the integrity of your data when dealing with playbacks or simulation (explain real world example).
  • To deal with time jumps, one solution is to register a callback to clear the internal state of your time source (system? node?)
  • Show the steps to cause the time jump
  • Show what happens without the callback registered
  • Explain the issue, describe whatever happens to the wave in rqt_plot
  • Register the callback (code)
  • Show what happens with the callback registered, point out the improvements over the previous example

Summary

This tutorial has taught you how to…
(does this tutorial teach any “how to” applicable steps or is it more for the sake of showing what ROS Time does, where in reality ROS Time will normally just work on its own in the background when people playback bags or simulations?)

[peterdavidfagan]

Hi @clalancette,

I saw a request on Twitter for people to help with closing issues in this repository. I thought I would try to play my part since I am a user of ROS who has yet to contribute to the project. I'd be happy to be assigned to this issue and to work on it starting next week.

[clalancette]

@peterdavidfagan That is fantastic, thanks for volunteering! I've gone ahead and assigned it to you. Hopefully the notes above are enough to get you started; do feel free to ask questions here (though I'm not personally an expert in ROSTime, so we may need to call in some backup).

Once you have something done, please open a pull request and we can review it. Thanks again.

[peterdavidfagan]

Sounds great thanks @clalancette looking forward to contributing to the docs.

[peterdavidfagan]

I just wished to provide a brief update on this, the past weeks have been quite busy for me so and I had a bit of an irregular schedule so I didn't have the opportunity to start working on this tutorial. Now that my schedule has become more regular again I have looked to schedule time to start this work sometime this week. I hope to provide further updates later this week.

[peterdavidfagan]

This is still on my list to do but I am a small bit behind on other items so it will be after I clear these that I have time to work on this.