Merge branch 'gps_work'

7 files changed, 223 insertions, 119 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 88b217f1b..1b07834fb 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
diff --git a/host/include/uhd/usrp/gps_ctrl.hpp b/host/include/uhd/usrp/gps_ctrl.hpp
index bd679b165..6ff00e03c 100644
--- a/host/include/uhd/usrp/gps_ctrl.hpp
+++ b/host/include/uhd/usrp/gps_ctrl.hpp
@@ -22,6 +22,8 @@
 #include <boost/utility.hpp>
 #include <boost/function.hpp>
 #include <boost/date_time/posix_time/posix_time_types.hpp>
+#include <vector>
+#include <uhd/types/sensors.hpp>
 
 using namespace boost::posix_time;
 
@@ -38,16 +40,14 @@ public:
   static sptr make(gps_send_fn_t, gps_recv_fn_t);
 
   /*!
-   * Get the current GPS time and date
-   * \return current GPS time and date as boost::posix_time::ptime object
+   * Retrieve the list of sensors this GPS object provides
    */
-  virtual ptime get_time(void) = 0;
-  
+  virtual std::vector<std::string> get_sensors(void) = 0;
+
   /*!
-   * Get the epoch time (as time_t, which is int)
-   * \return current GPS time and date as time_t
+   * Retrieve the named sensor
    */
-   virtual time_t get_epoch_time(void) = 0;
+  virtual uhd::sensor_value_t get_sensor(std::string key) = 0;
 
   /*!
    * Tell you if there's a supported GPS connected or not
diff --git a/host/lib/usrp/gps_ctrl.cpp b/host/lib/usrp/gps_ctrl.cpp
index 3bee26340..3cef1ef19 100644
--- a/host/lib/usrp/gps_ctrl.cpp
+++ b/host/lib/usrp/gps_ctrl.cpp
@@ -17,23 +17,26 @@
 
 #include <uhd/usrp/gps_ctrl.hpp>
 #include <uhd/utils/msg.hpp>
+#include <uhd/utils/props.hpp>
 #include <uhd/exception.hpp>
+#include <uhd/types/sensors.hpp>
+#include <boost/algorithm/string.hpp>
+#include <boost/assign/list_of.hpp>
 #include <boost/cstdint.hpp>
 #include <boost/date_time/posix_time/posix_time.hpp>
 #include <boost/thread/thread.hpp>
-#include <boost/algorithm/string/trim.hpp>
 #include <boost/tokenizer.hpp>
 
 using namespace uhd;
 using namespace boost::gregorian;
 using namespace boost::posix_time;
 using namespace boost::algorithm;
+using namespace boost::this_thread;
 
 /*!
  * A GPS control for Jackson Labs devices (and other NMEA compatible GPS's)
  */
 
-//TODO: multiple baud rate support (requires mboard_impl changes for poking UART registers)
 class gps_ctrl_impl : public gps_ctrl{
 public:
   gps_ctrl_impl(gps_send_fn_t send, gps_recv_fn_t recv){
@@ -42,74 +45,41 @@ public:
 
     std::string reply;
     bool i_heard_some_nmea = false, i_heard_something_weird = false;
-
     gps_type = GPS_TYPE_NONE;
-
-//    set_uart_baud_rate(GPS_UART, 115200);
-    //first we look for a Jackson Labs Firefly (since that's what we sell with the USRP2+...)
-
+    
+    //first we look for a Jackson Labs Firefly (since that's what we provide...)
     _recv(); //get whatever junk is in the rx buffer right now, and throw it away
     _send("HAAAY GUYYYYS\n"); //to elicit a response from the Firefly
 
     //then we loop until we either timeout, or until we get a response that indicates we're a JL device
     int timeout = GPS_TIMEOUT_TRIES;
     while(timeout--) {
-      reply = safe_gps_read();
-      if(trim_right_copy(reply) == "Command Error") {
+      reply = _recv();
+      if(reply.find("Command Error") != std::string::npos) {
         gps_type = GPS_TYPE_JACKSON_LABS;
         break;
       } 
       else if(reply.substr(0, 3) == "$GP") i_heard_some_nmea = true; //but keep looking for that "Command Error" response
       else if(reply.length() != 0) i_heard_something_weird = true; //probably wrong baud rate
-      boost::this_thread::sleep(boost::posix_time::milliseconds(200));
+      sleep(milliseconds(200));
     }
 
     if((i_heard_some_nmea) && (gps_type != GPS_TYPE_JACKSON_LABS)) gps_type = GPS_TYPE_GENERIC_NMEA;
 
-    //otherwise, we can try some other common baud rates looking to see if a GPS is connected (todo, later)
     if((gps_type == GPS_TYPE_NONE) && i_heard_something_weird) {
       UHD_MSG(error) << "GPS invalid reply \"" << reply << "\", assuming none available" << std::endl;
     }
 
-    bool found_gprmc = false;
-
     switch(gps_type) {
     case GPS_TYPE_JACKSON_LABS:
       UHD_MSG(status) << "Found a Jackson Labs GPS" << std::endl;
-      //issue some setup stuff so it spits out the appropriate data
-      //none of these should issue replies so we don't bother looking for them
-      //we have to sleep between commands because the JL device, despite not acking, takes considerable time to process each command.
-       boost::this_thread::sleep(boost::posix_time::milliseconds(FIREFLY_STUPID_DELAY_MS));
-      _send("SYST:COMM:SER:ECHO OFF\n");
-       boost::this_thread::sleep(boost::posix_time::milliseconds(FIREFLY_STUPID_DELAY_MS));
-      _send("SYST:COMM:SER:PRO OFF\n");
-       boost::this_thread::sleep(boost::posix_time::milliseconds(FIREFLY_STUPID_DELAY_MS));
-      _send("GPS:GPGGA 0\n");
-       boost::this_thread::sleep(boost::posix_time::milliseconds(FIREFLY_STUPID_DELAY_MS));
-      _send("GPS:GGAST 0\n");
-       boost::this_thread::sleep(boost::posix_time::milliseconds(FIREFLY_STUPID_DELAY_MS));
-      _send("GPS:GPRMC 1\n");
-       boost::this_thread::sleep(boost::posix_time::milliseconds(FIREFLY_STUPID_DELAY_MS));
-
-//      break;
+      init_firefly();
 
     case GPS_TYPE_GENERIC_NMEA:
       if(gps_type == GPS_TYPE_GENERIC_NMEA) UHD_MSG(status) << "Found a generic NMEA GPS device" << std::endl;
-      found_gprmc = false;
-      //here we loop around looking for a GPRMC packet. if we don't get one, we don't have a usable GPS.
-      timeout = GPS_TIMEOUT_TRIES;
-      while(timeout--) {
-        reply = safe_gps_read();
-        if(reply.substr(0, 6) == "$GPRMC") {
-          found_gprmc = true;
-          break;
-        }
-        boost::this_thread::sleep(boost::posix_time::milliseconds(200));
-      }
-      if(!found_gprmc) {
-        if(gps_type == GPS_TYPE_JACKSON_LABS) UHD_MSG(error) << "Firefly GPS not locked or warming up." << std::endl;
-        else UHD_MSG(error) << "GPS does not output GPRMC packets. Cannot retrieve time." << std::endl;
-        gps_type = GPS_TYPE_NONE;
+      if(get_time() == ptime()) {
+          UHD_MSG(status) << "No valid GPRMC packet found. Ignoring discovered GPS.";
+          gps_type = GPS_TYPE_NONE;
       }
       break;
 
@@ -118,71 +88,134 @@ public:
       break;
 
     }
-
-
   }
 
   ~gps_ctrl_impl(void){
+    /* NOP */
+  }
 
+  //return a list of supported sensors
+  std::vector<std::string> get_sensors(void) {
+    std::vector<std::string> ret = boost::assign::list_of
+        ("gps_gpgga")
+        ("gps_gprmc")
+        ("gps_gpgsa")
+        ("gps_time")
+        ("gps_locked");
+    return ret;
   }
 
-  std::string safe_gps_read() {
-    return _recv();
+  uhd::sensor_value_t get_sensor(std::string key) {
+    if(key == "gps_gpgga"
+    or key == "gps_gprmc"
+    or key == "gps_gpgsa") {
+        return sensor_value_t(
+                 boost::to_upper_copy(key),
+                 get_nmea(boost::to_upper_copy(key.substr(4,8))),
+                 "");
+    }
+    else if(key == "gps_time") {
+        return sensor_value_t("GPS epoch time", int(get_epoch_time()), "seconds");
+    }
+    else if(key == "gps_locked") {
+        return sensor_value_t("GPS lock status", locked(), "locked", "unlocked");
+    }
+    else {
+        UHD_THROW_PROP_GET_ERROR();
+    }
   }
 
-  ptime get_time(void) {
+private:
+  void init_firefly(void) {
+    //issue some setup stuff so it spits out the appropriate data
+    //none of these should issue replies so we don't bother looking for them
+    //we have to sleep between commands because the JL device, despite not acking, takes considerable time to process each command.
+     sleep(milliseconds(FIREFLY_STUPID_DELAY_MS));
+    _send("SYST:COMM:SER:ECHO OFF\n");
+     sleep(milliseconds(FIREFLY_STUPID_DELAY_MS));
+    _send("SYST:COMM:SER:PRO OFF\n");
+     sleep(milliseconds(FIREFLY_STUPID_DELAY_MS));
+    _send("GPS:GPGGA 1\n");
+     sleep(milliseconds(FIREFLY_STUPID_DELAY_MS));
+    _send("GPS:GGAST 0\n");
+     sleep(milliseconds(FIREFLY_STUPID_DELAY_MS));
+    _send("GPS:GPRMC 1\n");
+     sleep(milliseconds(FIREFLY_STUPID_DELAY_MS));
+    _send("GPS:GPGSA 1\n");
+     sleep(milliseconds(FIREFLY_STUPID_DELAY_MS));
+  }
+ 
+  //retrieve a raw NMEA sentence
+  std::string get_nmea(std::string msgtype) {
+    msgtype.insert(0, "$");
     std::string reply;
-    ptime now;
-    boost::tokenizer<boost::escaped_list_separator<char> > tok(reply);
-    std::vector<std::string> toked;
+    if(not gps_detected()) {
+        UHD_MSG(error) << "get_nmea(): unsupported GPS or no GPS detected";
+        return std::string();
+    }
     int timeout = GPS_TIMEOUT_TRIES;
-    bool found_gprmc = false;
-    switch(gps_type) {
-    case GPS_TYPE_JACKSON_LABS: //deprecated in favor of a single NMEA parser
-    case GPS_TYPE_GENERIC_NMEA:
+    while(timeout--) {
+        reply = _recv();
+        if(reply.substr(0, 6) == msgtype)
+          return reply;
+        boost::this_thread::sleep(milliseconds(GPS_TIMEOUT_DELAY_MS));
+    }
+    UHD_MSG(error) << "get_nmea(): no " << msgtype << " message found";
+    return std::string();
+  }
 
-      while(timeout--) {
-        reply = safe_gps_read();
-        if(reply.substr(0, 6) == "$GPRMC") {
-          found_gprmc = true;
-          break;
-        }
-        boost::this_thread::sleep(boost::posix_time::milliseconds(200));
-      }
-      UHD_ASSERT_THROW(found_gprmc);
-
-      tok.assign(reply);
-      toked.assign(tok.begin(), tok.end());
-
-      UHD_ASSERT_THROW(toked.size() == 12); //if it's not we got something weird in there
-
-      now = ptime( date( 
-                         greg_year(boost::lexical_cast<int>(toked[9].substr(4, 2)) + 2000), //just trust me on this one
-                         greg_month(boost::lexical_cast<int>(toked[9].substr(2, 2))), 
-                         greg_day(boost::lexical_cast<int>(toked[9].substr(0, 2))) 
-                       ),
-                   hours(  boost::lexical_cast<int>(toked[1].substr(0, 2)))
-                 + minutes(boost::lexical_cast<int>(toked[1].substr(2, 2)))
-                 + seconds(boost::lexical_cast<int>(toked[1].substr(4, 2)))
-                 );
-      break;
-    case GPS_TYPE_NONE:
-    default:
-      throw uhd::runtime_error("get_time(): Unsupported GPS or no GPS detected\n");
-      break;
+  //helper function to retrieve a field from an NMEA sentence
+  std::string get_token(std::string sentence, size_t offset) {
+    boost::tokenizer<boost::escaped_list_separator<char> > tok(sentence);
+    std::vector<std::string> toked;
+
+    tok.assign(sentence);
+    toked.assign(tok.begin(), tok.end());
+
+    if(toked.size() <= offset) {
+      UHD_MSG(error) << "get_token: too few tokens in reply " << sentence;
+      return std::string();
     }
-    return now;
+    return toked[offset];
+  }
+
+  ptime get_time(void) {
+    std::string reply = get_nmea("GPRMC");
+
+    std::string datestr = get_token(reply, 9);
+    std::string timestr = get_token(reply, 1);
+
+    if(datestr.size() == 0 or timestr.size() == 0) {
+        return ptime();
+    }
+
+    //just trust me on this one
+    return ptime( date( 
+                     greg_year(boost::lexical_cast<int>(datestr.substr(4, 2)) + 2000),
+                     greg_month(boost::lexical_cast<int>(datestr.substr(2, 2))), 
+                     greg_day(boost::lexical_cast<int>(datestr.substr(0, 2))) 
+                   ),
+                  hours(  boost::lexical_cast<int>(timestr.substr(0, 2)))
+                + minutes(boost::lexical_cast<int>(timestr.substr(2, 2)))
+                + seconds(boost::lexical_cast<int>(timestr.substr(4, 2)))
+             );
   }
   
   time_t get_epoch_time(void) {
-      return (get_time() - boost::posix_time::from_time_t(0)).total_seconds();
+      return (get_time() - from_time_t(0)).total_seconds();
   }
 
   bool gps_detected(void) {
     return (gps_type != GPS_TYPE_NONE);
   }
 
-private:
+  bool locked(void) {
+      std::string reply = get_nmea("GPGGA");
+      if(reply.size() <= 1) return false;
+
+      return (get_token(reply, 6) != "0");
+  }
+
   gps_send_fn_t _send;
   gps_recv_fn_t _recv;
 
@@ -195,7 +228,6 @@ private:
   static const int GPS_TIMEOUT_TRIES = 10;
   static const int GPS_TIMEOUT_DELAY_MS = 200;
   static const int FIREFLY_STUPID_DELAY_MS = 200;
-
 };
 
 /***********************************************************************
diff --git a/host/lib/usrp/usrp2/mboard_impl.cpp b/host/lib/usrp/usrp2/mboard_impl.cpp
index 6bf412a3e..61ceb95ca 100644
--- a/host/lib/usrp/usrp2/mboard_impl.cpp
+++ b/host/lib/usrp/usrp2/mboard_impl.cpp
@@ -149,7 +149,13 @@ usrp2_mboard_impl::usrp2_mboard_impl(
         (_mimo_clocking_mode_is_master?"master":"slave") << std::endl;
 
     //init the clock config
-    _clock_config = clock_config_t::internal();
+    if(_iface->mb_eeprom["gpsdo"] == "internal" or
+       _iface->mb_eeprom["gpsdo"] == "external") {
+        _clock_config = clock_config_t::external();
+    }
+    else {
+        _clock_config = clock_config_t::internal();
+    }
     update_clock_config();
 
     //init the codec before the dboard
@@ -174,6 +180,13 @@ usrp2_mboard_impl::usrp2_mboard_impl(
         _iface->poke32(U2_REG_RX_CTRL_CLEAR(i), 1); //resets sequence
     }
     //------------------------------------------------------------------
+
+    //initialize VITA time to GPS time
+    if( _gps_ctrl.get()
+    and _gps_ctrl->gps_detected()) {
+        UHD_MSG(status) << "Setting device time to GPS time...\n";
+        set_time_spec(time_spec_t(double(_gps_ctrl->get_sensor("gps_time").to_int()+1)), false);
+    }
 }
 
 usrp2_mboard_impl::~usrp2_mboard_impl(void){UHD_SAFE_CALL(
@@ -375,7 +388,10 @@ void usrp2_mboard_impl::get(const wax::obj &key_, wax::obj &val){
 
     case SUBDEV_PROP_SENSOR_NAMES:{
             prop_names_t names = boost::assign::list_of("mimo_locked")("ref_locked");
-            if (_gps_ctrl.get()) names.push_back("gps_time");
+            if (_gps_ctrl.get()) {
+                std::vector<std::string> gs = _gps_ctrl->get_sensors();
+                names.insert(names.end(), gs.begin(), gs.end());
+            }
             val = names;
         }
         return;
@@ -389,8 +405,8 @@ void usrp2_mboard_impl::get(const wax::obj &key_, wax::obj &val){
             val = sensor_value_t("Ref", this->get_ref_locked(), "locked", "unlocked");
             return;
         }
-        else if(key.name == "gps_time" and _gps_ctrl.get()) {
-            val = sensor_value_t("GPS time", int(_gps_ctrl->get_epoch_time()), "seconds");
+        else if(uhd::has(_gps_ctrl->get_sensors(), key.name) and _gps_ctrl.get()) {
+            val = _gps_ctrl->get_sensor(key.name);
         }
         else {
             UHD_THROW_PROP_GET_ERROR();