diff options
| -rw-r--r-- | host/docs/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | host/docs/general.rst | 62 | ||||
| -rw-r--r-- | host/docs/index.rst | 1 | ||||
| -rw-r--r-- | host/docs/sync.rst | 160 | ||||
| -rw-r--r-- | host/docs/usrp2.rst | 17 |
5 files changed, 240 insertions, 1 deletions
diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt index 1a2738647..5926e062e 100644 --- a/host/docs/CMakeLists.txt +++ b/host/docs/CMakeLists.txt @@ -26,6 +26,7 @@ SET(manual_sources dboards.rst general.rst images.rst + sync.rst transport.rst usrp1.rst usrp2.rst diff --git a/host/docs/general.rst b/host/docs/general.rst index 73b820c84..ff85fb0f9 100644 --- a/host/docs/general.rst +++ b/host/docs/general.rst @@ -5,7 +5,63 @@ UHD - General Application Notes .. contents:: Table of Contents ------------------------------------------------------------------------ -Misc notes +Tuning notes +------------------------------------------------------------------------ + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Two-stage tuning process +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +A USRP device has two stages of tuning: + +* RF front-end: translates bewteen RF and IF +* DSP: translates between IF and baseband + +In a typical use-case, the user specifies an overall center frequency for the signal chain. +The RF front-end will be tuned as close as possible to the center frequency, +and the DSP will account for the error in tuning between target frequency and actual frequency. +The user may also explicitly control both stages of tuning through the tune_request_t object. + +Pseudo-code for tuning the receive chain: +:: + + //tuning to a desired center frequency + usrp->set_rx_freq(my_frequency_in_hz); + + --OR-- + + //advanced tuning with tune_request_t + uhd::tune_request_t tune_req; + tune_req.target_freq = my_frequency_in_hz; + //fill in tune request fields... + usrp->set_rx_freq(tune_req); + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +RF front-end settling time +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +After tuning, the RF front-end will need time to settle into a usable state. +Typically, this means that the local oscillators must be given time to lock before streaming begins. +Lock time is not consistent; it varies depending upon the device and requested settings. +After tuning and before streaming, the user should +wait for the "lo_locked" sensor to become true, +or sleep for a conservative amount of time (perhaps a second). + +Pseudo-code for dealing with settling time after tuning on receive: +:: + + usrp->set_rx_freq(...); + sleep(1); + usrp->issue_stream_command(...); + + --OR-- + + usrp->set_rx_freq(...); + while (not usrp->get_rx_sensor("lo_locked").to_bool()){ + //sleep for a short time in milliseconds + } + usrp->issue_stream_command(...); + +------------------------------------------------------------------------ +Threading notes ------------------------------------------------------------------------ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -46,6 +102,10 @@ Add the following line to */etc/security/limits.conf*: Replace <my_group> with a group to which your user belongs. Settings will not take effect until the user has logged in and out. +------------------------------------------------------------------------ +Misc notes +------------------------------------------------------------------------ + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Support for dynamically loadable modules ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/host/docs/index.rst b/host/docs/index.rst index 467d5f385..40fe64599 100644 --- a/host/docs/index.rst +++ b/host/docs/index.rst @@ -27,6 +27,7 @@ Application Notes * `USRP-E1XX Series Application Notes <./usrp_e1xx.html>`_ * `Daughterboard Application Notes <./dboards.html>`_ * `Transport Application Notes <./transport.html>`_ +* `Synchronization Application Notes <./sync.html>`_ ^^^^^^^^^^^^^^^^^^^^^ API Documentation diff --git a/host/docs/sync.rst b/host/docs/sync.rst new file mode 100644 index 000000000..7e9ea11f4 --- /dev/null +++ b/host/docs/sync.rst @@ -0,0 +1,160 @@ +======================================================================== +UHD - Synchronization Application Notes +======================================================================== + +.. contents:: Table of Contents + +The following application notes explain how to synchronize multiple USRPs +with the goal of transmitting or receiving time-aligned samples for MIMO +or other applications requiring multiple USRPs operating synchronously. + +**Note:** The following synchronization notes do not apply to USRP1, +which does not support the advanced features available in newer products. + +------------------------------------------------------------------------ +Common reference signals +------------------------------------------------------------------------ +USRPs take two reference signals in order to synchronize clocks and time: + +* A 10MHz reference to provide a single frequency reference for both devices, and +* A pulse-per-second (1PPS) to synchronize the sample time across devices. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Provide reference signals +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Most USRPs have front panel SMA connectors to source these reference signals. +Typically, these signals are provided by an external GPSDO. +Some USRP models can provide these signals from an optional internal GPSDO. +For users generating their own signals, +the pulse-per-second should be clocked from the 10MHz reference. +See the application notes for your device for specific signal requirements. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Set the clock configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In order to synchronize to an external clock, configure the USRP device +using the "external" clock configuration: + +:: + + usrp->set_clock_config(uhd::clock_config_t::external()); + +------------------------------------------------------------------------ +Synchronizing the device time +------------------------------------------------------------------------ +The purpose of the PPS signal is to synchronously latch a time into the device. +You can use the set_time_next_pps(...) function to either initialize the sample time to 0, +or to an absolute time such as GPS time or UTC time. +For the purposes of synchronizing devices, +it doesn't matter what time you initialize to when using set_time_next_pps(...). + +Some GPSDOs synchronize their PPS with the rising edge of the 10MHz clock, +and some synchronize with the falling edge of the clock. +You should find out which edge your GPSDO uses, +and then pass that in as an argument to set_time_next_pps(...). + +Here are two examples of how to set the PPS time to synchronize USRPs +to a clock source. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Method 1 - poll the USRP time registers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +One way to initialize the PPS edge is to poll the "last PPS" time from the USRP device. +When the last PPS time increments, the user can determine that a PPS has occurred: + +:: + + const uhd::time_spec_t last_pps_time = usrp->get_time_last_pps(); + while (last_pps_time != usrp->get_time_last_pps()){ + //sleep 100 milliseconds (give or take) + } + usrp->set_time_next_pps(uhd::time_spec_t(0.0)); + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Method 2 - query the GPSDO for seconds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Most GPSDO can be configured to output a NMEA string over the serial port once every PPS. +The user can wait for this string to determine the PPS edge, +and the user can also parse this string to determine GPS time: + +:: + + //call user's function to wait for NMEA message... + usrp->set_time_next_pps(uhd::time_spec_t(0.0)); + + -- OR -- + + //call user's function to wait for NMEA message... + //call user's function to parse the NMEA message... + usrp->set_time_next_pps(uhd::time_spec_t(gps_time+1)); + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Method 3 - query the gps_time sensor +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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)); + +------------------------------------------------------------------------ +Synchronizing channel phase +------------------------------------------------------------------------ + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Align CORDICs in the DSP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In order to achieve phase alignment between USRPs, the CORDICS in both +devices must be aligned with respect to each other. This is easily achieved +by issuing stream commands with a time spec property, which instructs the +streaming to begin at a specified time. Since the devices are already +synchronized via the 10MHz and PPS inputs, the streaming will start at exactly +the same time on both devices. The CORDICs are reset at each start-of-burst +command, so users should ensure that every start-of-burst also has a time spec set. + +For receive, a burst is started when the user issues a stream command. This stream command should have a time spec set. + +:: + + uhd::stream_cmd_t stream_cmd(uhd::stream_cmd_t::STREAM_MODE_NUM_SAMPS_AND_DONE); + stream_cmd.num_samps = spb; + stream_cmd.stream_now = false; + stream_cmd.time_spec = uhd::time_spec_t(seconds_in_future); + usrp->issue_stream_cmd(stream_cmd); + +For transmit, a burst is started when the user calls send(). The metadata should have a time spec and start of burst set. + +:: + + uhd::tx_metadata_t md; + md.start_of_burst = true; + md.end_of_burst = false; + md.has_time_spec = true; + md.time_spec = uhd::time_spec_t(time_to_send); + + //send a single packet + size_t num_tx_samps = usrp->get_device()->send( + buffs, samps_to_send, md, + uhd::io_type_t::COMPLEX_FLOAT32, + uhd::device::SEND_MODE_ONE_PACKET, timeout + ); + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Align LOs in the front-end +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +After tuning the RF front-ends, +each local oscillator may have a random phase offset due to the dividers +in the VCO/PLL chains. This offset will remain constant after the device +has been initialized, and will remain constant until the device is closed +or re-tuned. This phase offset is typically removed by the user in MIMO +applications, using a training sequence to estimate the offset. It will +be necessary to re-align the LOs after each tune command. diff --git a/host/docs/usrp2.rst b/host/docs/usrp2.rst index aaae79792..88b217f1b 100644 --- a/host/docs/usrp2.rst +++ b/host/docs/usrp2.rst @@ -397,3 +397,20 @@ 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) + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Multiple RX channels +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +There are two complete DDC chains in the FPGA. +In the single channel case, only one chain is ever used. +To receive from both channels, +the user must set the RX subdevice specification. +This hardware has only one daughterboard slot, +which has been aptly named slot "0". + +In the following example, a TVRX2 is installed. +Channel 0 is sourced from subdevice RX1, +channel 1 is sourced from subdevice RX2: +:: + + usrp->set_rx_subdev_spec("0:RX1 0:RX2"); |