docs: added documentation for usage of the Jackson Labx LC_XO GPSDO, used on USRP B2X0 devices

4 files changed, 84 insertions, 2 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index 17744db7d..fa6e98918 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -26,6 +26,7 @@ SET(manual_sources
     coding.rst
     dboards.rst
     gpsdo.rst
+    gpsdo_b2x0.rst
     general.rst
     images.rst
     stream.rst
diff --git a/host/docs/gpsdo.rst b/host/docs/gpsdo.rst
index 1e9019a0f..1cf1dae29 100644
--- a/host/docs/gpsdo.rst
+++ b/host/docs/gpsdo.rst
@@ -1,5 +1,5 @@
 ========================================================================
-UHD - Internal GPSDO Application Notes
+UHD - Internal GPSDO Application Notes (USRP-N2x0/E1X0 Models)
 ========================================================================
 
 .. contents:: Table of Contents
diff --git a/host/docs/gpsdo_b2x0.rst b/host/docs/gpsdo_b2x0.rst
new file mode 100644
index 000000000..bca10e99a
--- /dev/null
+++ b/host/docs/gpsdo_b2x0.rst
@@ -0,0 +1,80 @@
+========================================================================
+UHD - Internal GPSDO Application Notes (USRP-B2X0 Models)
+========================================================================
+
+.. contents:: Table of Contents
+
+This application note describes the use of integrated GPS-disciplined
+oscillators with Ettus Research USRP devices. It pertains specifically
+to the Jackson Labs LC_XO device unless noted otherwise.
+
+------------------------------------------------------------------------
+Specifications
+------------------------------------------------------------------------
+* **Receiver type**: 50 channel with WAAS, EGNOS, MSAS
+* **10MHz ADEV**: 5e-11 over >24h
+* **1PPS RMS jitter**: <50ns 1-sigma
+* **Holdover**: <20us over 3h
+
+**Phase noise**:
+
++------------+-------------+------------+
+|            |     TCXO    |    OXCO    |
++============+=============+============+
+| **1Hz**    | -65dBc/Hz   | -75dBc/Hz  |
++------------+-------------+------------+
+| **10Hz**   |  -102dBc/Hz | -110dBc/Hz |
++------------+-------------+------------+
+| **100Hz**  | -132dBc/Hz  | -132dBc/Hz |
++------------+-------------+------------+
+| **1kHz**   | -148dBc/Hz  | -142dBc/Hz |
++------------+-------------+------------+
+| **10kHz**  | -152dBc/Hz  | -145dBc/Hz |
++------------+-------------+------------+
+| **100kHz** | <-155dBc/Hz | -150dBc/Hz |
++------------+-------------+------------+
+
+**Antenna Types:**
+
+The GPSDO is capable of supplying a 3V for active GPS antennas or supporting passive antennas.
+
+------------------------------------------------------------------------
+Installation Instructions
+------------------------------------------------------------------------
+To install the GPSDO, you must insert it into the slot on the board
+near the 10 MHz Reference SMA. Keep in mind that the two sides of the
+GPSDO have a different number of pins. When inserting the GPSDO, make
+sure to press down firmly and evenly. When turning on the USRP B2X0 device,
+a green LED should illuminate on the GPSDO. This signifies that the unit
+has successfully been placed.
+
+**NOTE: The pins on the GPSDO are very fragile. Be sure to press down
+evenly, or the pins may bend or break. Once the GPSDO is in place,
+we very highly discourage further removal, as this also risks damaging
+the pins.**
+
+------------------------------------------------------------------------
+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.
+
+GPS data is obtained through the **mboard_sensors** interface. To retrieve
+the current GPS time, use the **gps_time** sensor:
+
+::
+
+    usrp->get_mboard_sensor("gps_time");
+
+The returned value will be the current epoch time, in seconds since
+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.
+
+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.
diff --git a/host/docs/index.rst b/host/docs/index.rst
index 27523c139..65069059f 100644
--- a/host/docs/index.rst
+++ b/host/docs/index.rst
@@ -32,7 +32,8 @@ Application Notes
 * `Daughterboard Application Notes <./dboards.html>`_
 * `Transport Application Notes <./transport.html>`_
 * `Synchronization Application Notes <./sync.html>`_
-* `Internal GPSDO Application Notes <./gpsdo.html>`_
+* `Internal GPSDO Application Notes (USRP-N2X0/E1X0 Models) <./gpsdo.html>`_
+* `Internal GPSDO Application Notes (USRP-B2X0 Models) <./gpsdo_b2x0.html>`_
 * `Calibration Application Notes <./calibration.html>`_
 
 ^^^^^^^^^^^^^^^^^^^^^