diff options
Diffstat (limited to 'host/docs')
| -rw-r--r-- | host/docs/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | host/docs/gpsdo.rst | 66 | ||||
| -rw-r--r-- | host/docs/sync.rst | 19 | ||||
| -rw-r--r-- | host/docs/usrp2.rst | 8 |
4 files changed, 75 insertions, 19 deletions
diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt index 88afb9c98..be00a6655 100644 --- a/host/docs/CMakeLists.txt +++ b/host/docs/CMakeLists.txt @@ -24,6 +24,7 @@ SET(manual_sources build.rst coding.rst dboards.rst + gpsdo.rst general.rst images.rst sync.rst diff --git a/host/docs/gpsdo.rst b/host/docs/gpsdo.rst new file mode 100644 index 000000000..a0f2d67da --- /dev/null +++ b/host/docs/gpsdo.rst @@ -0,0 +1,66 @@ +======================================================================== +UHD - Internal GPSDO Application Notes +======================================================================== + +.. 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 Firefly-1A device unless noted otherwise. + +------------------------------------------------------------------------ +Specifications +------------------------------------------------------------------------ +Receiver type: 50 channel with WAAS, EGNOS, MSAS +10MHz ADEV: 1e-11 over >24h +1PPS RMS jitter: <50ns 1-sigma +Holdover: <11us over 3h +Phase noise: 1Hz: -80dBc/Hz, 10Hz: -110dBc/Hz, 100Hz: -135dBc/Hz, 1kHz: -145dBc/Hz, 10kHz: <-145dBc/Hz + +------------------------------------------------------------------------ +Installation +------------------------------------------------------------------------ +See the documentation for your device for specifics on installing the GPSDO. + +------------------------------------------------------------------------ +Configuring the USRP to use the GPSDO +------------------------------------------------------------------------ +This is necessary if you require absolute GPS time in your application, +or need to communicate with the GPSDO to obtain location, satellite info, etc. +If you only require 10MHz and PPS signals for reference or MIMO use, +(see the Synchronization application note), it is not necessary to perform +this step. + +To configure the USRP to communicate with the GPSDO, use the +usrp_burn_mb_eeprom utility: + +:: + $ cd <install-path>/share/uhd/utils + $ ./usrp_burn_mb_eeprom --key=gpsdo --val=internal + +This will configure the driver to communicate with the GPSDO on startup. + +------------------------------------------------------------------------ +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_gpgsa", "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/sync.rst b/host/docs/sync.rst index 9284d8e33..3cb13fbf3 100644 --- a/host/docs/sync.rst +++ b/host/docs/sync.rst @@ -102,22 +102,11 @@ and the user can also parse this string to determine GPS time: usrp->set_time_next_pps(uhd::time_spec_t(gps_time+1)); ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Method 3 - query the gps_time sensor +Method 3 - internal GPSDO ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This is a variant of method 2 for USRPs with internal GPSDOs. -The user can query the gps_time sensor to wait for the NMEA string. - -:: - - //wait for NMEA string from internal GPSDO - usrp->get_mboard_sensor("gps_time"); - usrp->set_time_next_pps(uhd::time_spec_t(0.0)); - - -- OR -- - - //wait for the NMEA string and set GPS time - const time_t gps_time = usrp->get_mboard_sensor("gps_time").to_int(); - usrp->set_time_next_pps(uhd::time_spec_t(gps_time+1)); +USRPs with internal GPSDOs properly configured will automatically +configure themselves to set the VITA time to current UTC time. See the +GPSDO application note for more details. ------------------------------------------------------------------------ Synchronizing channel phase diff --git a/host/docs/usrp2.rst b/host/docs/usrp2.rst index 189f937de..1b243656f 100644 --- a/host/docs/usrp2.rst +++ b/host/docs/usrp2.rst @@ -349,9 +349,8 @@ Test the PPS input with the following app: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Internal GPSDO ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -USRP-N2XX models can have an optional internal GPSDO. -To use the GPSDO with UHD, you must burn an EEPROM setting -so that UHD knows that the internal GPSDO was installed. +Please see the GPSDO application note for information on configuring and +using the internal GPSDO. **Installation instructions:** @@ -396,7 +395,8 @@ they can be queried through the API. * mimo_locked - clock reference locked over the MIMO cable * ref_locked - clock reference locked (internal/external) -* gps_time - GPS seconds (available when GPSDO installed) +* gps_time - GPS epoch seconds (available when GPSDO installed) +* gps_locked - GPS lock status ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Multiple RX channels |