VRPN 06.04

Clock synchronization in VRPN

Since VRPN connections pass messages from one machine to another, server time stamps on a message are in the time frame of the server. Most clients will want to know the time stamps in the local time frame. By default, VRPN uses the vrpn_Clock class to perform 4 hz "quick syncs" on connections obtained by calling vrpn_get_connection_by_name. The clock offset calculated by these quick syncs is used to transform the server time frame time stamp into a client time frame time stamp. The end result of all of this is that the default behavior of VRPN is to pass messages to clients with local time frame time stamps.

Clients who wish to either disable synchronization or alter the synchronization characteristics should manually pre-set the connection characteristics by calling vrpn_get_connection_by_name with specific frequency and syncWindow arguments as detailed in vrpn_Connection.h before calling vrpn_*_Remote constructors (pass a sync time of 0 to disable).

Servers should always use vrpn_Synchronized_Connection objects so that clients can choose whether to be synchronized or not.

Clock synchronization relies on prompt client-server roundtrips, so clients and servers which do not relinquish control and allow the connection mainloop routine to be serviced on a regular basis will encounter problems. DO NOT SPIN WAIT INSIDE A CLIENT OR SERVER. If users need to perform some task after a specific time interval, then they should use timers to relinquish control until that time. The clock synchronization accuracy is limited by the rate at which the connection is serviced, so for accurate synchronization you are best off if you use threads to fork off the vrpn handling and use shared memory to read and write the data the vrpn callbacks are updating.

If you are only going to service the connection at typical frame rates and still want consistent time stamps, then you can turn off the time stamp adjustment by calling vrpn_get_connection_by_name with a frequency argument of -1. This will disable clock synchronization (unless you call fullSync), so time stamps will be in the server time frame.

More details on the vrpn_Clock class

The vrpn_Clock class provides two types of clock synchronizations: full sync and quick sync. A full sync performs client-server bounces for one second and calculates a estimate of the offset between the server and client clocks from this data. In the absence of clock drift, this is the best type of clock sync to use. A quick sync performs a client-server bounce every 4/freq seconds and uses the shortest roundtrip from the last syncWindow bounces to calculate the clock offset. This type of sync is useful when the two clocks being considered drift relative to one another. In most cases, this is the type of sync which is the safest to use.

Whether writing a client or a server class, users should not have to deal direclty with the vrpn_Clock class. A vrpn_Synchronized_Connection class has been created which is derived from the vrpn_Connection class, so any code which uses vrpn_Connection ptrs will not need to be aware of clock synchronization (beyond supplying non-default args as described above). Code which allocates connections should allocate vrpn_Synchronized_Connection objects (no new args for servers; freq and sync window size args for clients, but they have reasonable defaults).

Eventually the vrpn_Clock class will disappear and clock sync messages will just become another system message type. This will most likely happen when the network research group implements a more robust clock synchronization scheme.