API review

Proposer: Chad Rockey

Present at review:

  • Eric Perko
  • Jack O'Quin


There is still a need to standardize Navigation Satellite time information. This review should resolve how to handle time from these sensors.

Please see previous discussions on this topic:




Time synchronization is the other main use of Nav Sat systems. It is useful to have a common time source where traditional time synchronization (ntp, chrony, etc) is not available. This information is often only used retroactively or sporadically to synchronize time or other information. It should be possible for GPS drivers to output this information in a manner that is standardized and able to be logged.

Proposed Message

* sensor_msgs/TimeReference

  •  # Measurement from an external time source not actively synchronized with the system clock.
      Header           # stamp is system time for which measurement was valid
                       # frame_id is not used 
      time   time_ref  # corresponding time from this external source
      string source    # (optional) name of time source

Previously Proposed Messages

* sensor_msgs/NavSatTime.msg

  •  # Time reading from a navigation satellite.
        stamp     # System time for which measurement was valid.
        frame_id  # Frame_id of the gps antenna for this measurement.
      uint16 week   # Current GPS week (rolls over every 1024 weeks)
      uint64 nsec   # Current GPS nanoseconds since last week increment

* sensor_msgs/Time.msg

  •  # Measurement from an external time source not actively synced with system clock.
        stamp     # System time for which measurement was valid.
        frame_id  # Location of the original time measurement if relevant.
      time        # Time measurement for this external source.

Question / concerns / comments

  • (Chad) I'm not currently getting notifications for edits of this page. Is this true for everyone subscribed? I'm likely going to extend this review until past the new year, possibly up until the freeze. There is currently a ticket filed about the email notification issue.

    • (Chad) OK, this has been fixed, but I'll extend the review period through 1/9/2012.

  • (Chad) The initial proposal of this message uses the GPS time standard. Is anyone familiar with the Glonass and proposed Compass/Galileo time formats?

    • (Eric) NMEA devices do not output GPS week + nanoseconds. They output a UTC timestamp. See http://gpsd.berlios.de/NMEA.txt . I don't think we want to have to convert back from UTC to week + nanoseconds.

      • (Chad) It looks like GLONASS also outputs some form of UTC. GLONASS time is based on an atomic time scale similar to GPS. This time scale is UTC as maintained by Russia (UTC (SU)) http://gps.pl/arch/GLONASSOverview.pdf.

  • (Chad) It would be possible to simply have a Header with a stamp, both in Unix epoch. This would make the message usable for other time-synchronization methods. Is there too much danger here for unnecessarily exposing multiple time systems to ROS? Are there other solutions already proposed for ROS multi-master systems?

  • (Jack) Why not have two ROS::Time fields: the one on the header.stamp is system time, another in the message is NavSat time. That way, details of the device interface are abstracted into a single time format. The two times could be reconciled using a Phase Locked Loop.

    • (Chad) I agree, a system-timestamped time measurement is the easiest solution for the end user. Of course, in this case, we've abstracted entirely away from the Nav Sats, so it would probably be more descriptive being named (sensor_msgs?)/Time or (sensor_msgs?)/TimeStamped.

    • (Eric) +1 to the just two time fields (like what is proposed above as sensor_msgs/Time). Are the rest of the header fields useful in this case? What is frame_id in this context? Actually something in the tf_tree? or something like 'system_time' or 'gps_time'?

      • (Chad) I don't think introducing frame_ids to be time or location is a good idea. I think it should still be the tf_frame id when applicable. This would just be the location of the gps antenna or a frame_id corresponding to a person, etc. We should keep the header though so that libraries like message filters time synchronization can be applied to this message.

        • (Eric) I disagree. I think frame_id should be marked as "leave blank, only left in for compatibility with existing tools". Nothing in this message can use the tf library, so I don't see a point to sometimes stamping this with a physical frame_id. I think we either specify it's the time_source (not at all a tf frame, but maybe some have the same name by coincidence) of header.stamp or we specify leave it blank in all cases.

      • (Chad) Do we think it's a good idea to include a string description of the time_source? This would be descriptions like "rover_gps" or "mainframe_atomic_clock". It would allow publishing multiple sources on the same topic without ambiguity.

        • (Eric) It feels like we would need a time_source field for both time measurements for this to be useful. For example, header.stamp is "system1_system_time" and other stamp is "gps" or maybe "atomic_clock". Basically one for the publisher and one for the common frame of reference. If we put multiple publishers on one topic, we need to identify them some other way besides topic name.

        • (Jack) A Header with ROS system time would be useful for handling the messages in bags, etc. The frame_id field should not be set. I don't see the need for two different non-system times in the same message. If that is needed, it could probably be handled by publishing messages for each source with the same ROS system time. For that, a string source field seems useful (and perhaps for other reasons).

  • (Austin) I'm not convinced that ROS needs to solve this problem. If you want your system clock synchronized to GPS time, you should be using the PPS output from your GPS and a PPS driver. Once your local system clock is synced to GPS time, your system becomes an NTP stratum-0 time source, and you can sync all of the other computers in your network from that. The process looks something like this: http://time.qnan.org/

    • (Chad) This isn't always possible to do. One common use case could be taking some sort of GPS recorder, whether it is just a logger, Android phone, or hiker's GPS and placing it somewhere without a computer (maybe on a person). You then have positions and times, but reconciling those logs with your robot's bag files will be difficult without rewriting the robot's gps driver and including a custom message. Not to mention that not everyone needs the precision/has a PPS compatible GPS unit.

  • (Jack) Note that ideally the system time in the message header should represent the moment of the reference time. The time it is received by the driver will be somewhat later than that.

  • (Jack) There are already std_msgs/Time and rosgraph_msgs/Clock messages. I suggest defining a new message, named something like sensor_msgs/ReferenceTime, or TimeRef. TimeStamped would be OK as well.

     # Measurement from an external time source not actively synchronized with 
     # the system clock.
      Header           # stamp is system time for which measurement was valid
                       # frame_id is not used 
      time   ref_time  # corresponding time from this external source
      string source    # (optional) name of time source
    • (Chad) I like this message proposal the best so far.

Meeting agenda

To be filled out by proposer based on comments gathered during API review period


Package status change

  • /!\ Action items that need to be taken.

  • {X} Major issues that need to be resolved

  • Message was approved by final email vote. See this ticket for status.

Wiki: sensor_msgs/Reviews/2011-12-25_NavSatTime_Proposal_API_Review (last edited 2012-01-20 22:00:10 by ChadRockey)