What is the correct (standard) way of using sensor_msgs/TimeReference?

edit

Late, but:

I would think that the correct way to use it is to adjust the header of the message to contain the ROS time when the GPS message was received, and put the GPS time in the message.

I would say this is indeed correct.

Messag fields and comments (from sensor_msgs/TimeReference):

# Measurement from an external time source not actively synchronized with the system clock.

Header 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

So this states:

• header.stamp: system time for which measurement was valid (ie: when you received the data).If you have some way of compensating for the time the data was in transit, sat in a buffer or was in any other way delayed, you could intelligently compensate for that time (fi how NTP compensates for travelling time), but I've not seen any nodes doing that
• time_ref: time from this external source

Taking these two together: header.stamp tells us when the ROS node received the data from the external time source, and time_ref is the actual timestamp, decoded (if needed) from the data received from the time source.

Edit: there aren't that many packages using this message (or at least: not that I could find). Dataspeed is using it in their driver for Oxford GPS devices. This is how they initialise the message (from here):

sensor_msgs::TimeReference gps_time_ref_msg;
gps_time_ref_msg.source = "gps";
gps_time_ref_msg.header.stamp = stamp;
g_gps_utc_time = ros::Time(toUtcTime(packet->chan.chan0.gps_minutes, packet->time));
gps_time_ref_msg.time_ref = g_gps_utc_time;
pub_gps_time_ref.publish(gps_time_ref_msg);

Where stamp is the current ros::Time passed in at the beginning of the "update loop" (ie: when reading out the data coming from the Oxford GPS).