docs: GPSDO no longer autoset as time and clock src

Also added instructions to safely set device time.

1 files changed, 49 insertions, 8 deletions

diff --git a/host/docs/gpsdo_x3x0.dox b/host/docs/gpsdo_x3x0.dox
index 24997d50b..9577b930d 100644
--- a/host/docs/gpsdo_x3x0.dox
+++ b/host/docs/gpsdo_x3x0.dox
@@ -46,12 +46,22 @@ pins.</b>
 
 \section gpsdox_using Using the GPSDO in Your Application
 
-By default, if a GPSDO is detected at startup, the USRP will be
-configured to use it as a frequency and time reference. The internal
-VITA timestamp will be initialized to the GPS time, and the internal
-oscillator will be phase-locked to the 10MHz GPSDO reference. If the
-GPSDO is not locked to satellites, the VITA time will not be
-initialized.
+If a GPSDO is detected at startup, the USRP will have `gpsdo` clock and time
+source options.
+
+Select these by using UHD's
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+    usrp->set_clock_source("gpsdo");
+    usrp->set_time_source("gpsdo");
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+That will lock the reference clock to the disciplined 10MHz oscillator, and
+will make the USRP listen for time signal pulses coming from the GPSDO.
+
+However, you will still need to explicitly set the device time on such a PPS
+edge, using the `set_time_next_pps` or `set_time_unknown_pps`
+calls.
 
 GPS data is obtained through the **mboard_sensors** interface. To
 retrieve the current GPS time, use the **gps_time** sensor:
@@ -65,12 +75,43 @@ January 1, 1970. This value is readily converted into human-readable
 format using the **time.h** library in C, **boost::posix_time** in C++,
 etc.
 
+\subsection Setting Device Time to GPS time
+
+If you want to set the device time to GPS time, the following procedure makes
+sure you don't encounter timing problems while doing so:
+
+1. Wait for GPS lock, and then set the time source to GPSDO,
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+    while(! (usrp->get_mboard_sensor("gps_locked",0).to_bool()) ) {
+       boost::this_thread::sleep(boost::posix_time::seconds(2));
+    }
+    usrp->set_time_source("gpsdo");
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+2. poll on `usrp->get_time_last_pps()` until a change is seen, and then sleep 200ms to allow new time data coming from the GPSDO to propagate through the system,
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+    uhd::time_spec_t last = usrp->get_time_last_pps();
+    uhd::time_spec_t next = usrp->get_time_last_pps();
+    while(next == last) {
+       boost::this_thread::sleep(boost::posix_time::seconds(0.05));
+       last = next;
+       next = usrp->get_time_last_pps();
+    }
+    boost::this_thread::sleep(boost::posix_time::seconds(0.2));
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+3.  use
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+usrp->set_time_next_pps(uhd::time_spec_t(usrp->get_mboard_sensor("gps_time").to_int()+1));
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+to set the time,
+4.  poll on `usrp->get_time_last_pps()` until a change is seen and sleep 200ms (allow NMEA string to propagate),
+5.  Verify that `usrp->get_time_last_pps()` and `usrp->get_mboard_sensor("gps_time")` return the same time.
+
+\subsection Further GPS sensors
+
 Other information can be fetched as well. You can query the lock status
 with the **gps_locked** sensor, as well as obtain raw NMEA sentences
 using the **gps_gprmc**, and **gps_gpgga** sensors. Location
 information can be parsed out of the **gps_gpgga** sensor by using **gpsd**
 or another NMEA parser.
-
-
 */
 // vim:ft=doxygen: