diff options
Diffstat (limited to 'host/docs')
| -rw-r--r-- | host/docs/build.rst | 36 | ||||
| -rw-r--r-- | host/docs/calibration.rst | 19 | ||||
| -rw-r--r-- | host/docs/coding.rst | 2 | ||||
| -rw-r--r-- | host/docs/dboards.rst | 32 | ||||
| -rw-r--r-- | host/docs/general.rst | 32 | ||||
| -rw-r--r-- | host/docs/gpsdo.rst | 26 | ||||
| -rw-r--r-- | host/docs/identification.rst | 16 | ||||
| -rw-r--r-- | host/docs/images.rst | 47 | ||||
| -rw-r--r-- | host/docs/index.rst | 3 | ||||
| -rw-r--r-- | host/docs/stream.rst | 12 | ||||
| -rw-r--r-- | host/docs/sync.rst | 22 | ||||
| -rw-r--r-- | host/docs/transport.rst | 20 |
12 files changed, 136 insertions, 131 deletions
diff --git a/host/docs/build.rst b/host/docs/build.rst index 8a6841af6..d33bea363 100644 --- a/host/docs/build.rst +++ b/host/docs/build.rst @@ -14,12 +14,12 @@ the dependencies should be available in the package repositories for your package manager. **Mac OS X Notes:** -Install the "Xcode Developer Tools" to get the build tools (gcc and make). +Install the "Xcode Developer Tools" to get the build tools (GCC and Make). Use MacPorts to get the Boost and Cheetah dependencies. -Other dependencies can be downloaded as dmg installers from the web. +Other dependencies can be downloaded as DMG installers from the web. **Windows Notes:** -The dependencies can be acquired through installable exe files. +The dependencies can be acquired through installable EXE files. Usually, the Windows installer can be found on the project's website. Some projects do not host Windows installers, and if this is the case, follow the auxiliary download URL for the Windows installer (below). @@ -32,7 +32,7 @@ On Windows, install Cygwin with Git support to checkout the repository, or install msysGit from http://code.google.com/p/msysgit/downloads/list ^^^^^^^^^^^^^^^^ -C++ compiler +C++ Compiler ^^^^^^^^^^^^^^^^ The following compilers are known to work: @@ -44,7 +44,7 @@ The following compilers are known to work: CMake ^^^^^^^^^^^^^^^^ * **Purpose:** generates project build files -* **Version:** at least 2.6 +* **Minimum Version:** 2.6 * **Usage:** build time (required) * **Download URL:** http://www.cmake.org/cmake/resources/software.html @@ -52,8 +52,8 @@ CMake Boost ^^^^^^^^^^^^^^^^ * **Purpose:** C++ library -* **Version:** at least 1.36 (UNIX), at least 1.40 (Windows) -* **Usage:** build time + run time (required) +* **Minimum Version:** 1.36 (Linux), 1.40 (Windows) +* **Usage:** build time + runtime (required) * **Download URL:** http://www.boost.org/users/download/ * **Download URL (Windows installer):** http://www.boostpro.com/download @@ -61,8 +61,8 @@ Boost LibUSB ^^^^^^^^^^^^^^^^ * **Purpose:** USB-based hardware support -* **Version:** at least 1.0 -* **Usage:** build time + run time (optional) +* **Minimum Version:** 1.0 +* **Usage:** build time + runtime (optional) * **Download URL:** http://sourceforge.net/projects/libusb/files/libusb-1.0/ * **Download URL (Windows binaries):** http://www.libusb.org/wiki/windows_backend#LatestBinarySnapshots @@ -70,15 +70,15 @@ LibUSB Python ^^^^^^^^^^^^^^^^ * **Purpose:** used by Cheetah and utility scripts -* **Version:** at least 2.6 -* **Usage:** build time + run time utility scripts (required) +* **Minimum Version:** 2.6 +* **Usage:** build time + runtime utility scripts (required) * **Download URL:** http://www.python.org/download/ ^^^^^^^^^^^^^^^^ Cheetah ^^^^^^^^^^^^^^^^ * **Purpose:** source code generation -* **Version:** at least 2.0 +* **Minimum Version:** 2.0 * **Usage:** build time (required) * **Download URL:** http://www.cheetahtemplate.org/download.html * **Download URL (Windows installer):** http://feisley.com/python/cheetah/ @@ -90,7 +90,7 @@ http://pypi.python.org/pypi/setuptools ^^^^^^^^^^^^^^^^ Doxygen ^^^^^^^^^^^^^^^^ -* **Purpose:** generates HTML api documentation +* **Purpose:** generates HTML API documentation * **Usage:** build time (optional) * **Download URL:** http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc @@ -142,7 +142,7 @@ Build and install ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Setup the library path (Linux) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Make sure that libuhd.so is in your LD_LIBRARY_PATH +Make sure that libuhd.so is in your LD_LIBRARY_PATH, or add it to /etc/ld.so.conf and make sure to run: :: @@ -160,7 +160,7 @@ Build Instructions (Windows) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Generate the project with CMake ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* Open the cmake-gui program. +* Open the CMake GUI. * Set the path to the source code: <uhd-repo-path>/host * Set the path to the build directory: <uhd-repo-path>/host/build * Make sure that the paths do not contain spaces. @@ -187,10 +187,10 @@ Build the project in MSVC ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * Open the generated project file in MSVC. * Change the build type from "Debug" to "Release". -* Select the build all target, right click, and choose build. -* Select the install target, right click, and choose build. +* Select the "Build All" target, right-click, and choose "Build". +* Select the install target, right-click, and choose "Build". -**Note:** you may not have permission to build the install target. +**Note:** You may not have permission to build the install target. You need to be an administrator or to run MSVC as administrator. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/host/docs/calibration.rst b/host/docs/calibration.rst index 14e66a312..680a74f3b 100644 --- a/host/docs/calibration.rst +++ b/host/docs/calibration.rst @@ -7,10 +7,10 @@ UHD - Calibration Application Notes ------------------------------------------------------------------------ Self-calibration ------------------------------------------------------------------------ -The UHD comes with several self-calibration utilities for minimizing IQ imbalance and DC offset. +UHD comes with several self-calibration utilities for minimizing IQ imbalance and DC offset. These utilities perform calibration sweeps using transmit leakage into the receive path (special equipment is not required). -The results from a calibration are written to a csv file in the user's home directory. +The results from a calibration are written to a CSV file in the user's home directory. UHD will automatically apply corrections at runtime when the user re-tunes the daughterboard LO. Calibration results are specific to an individual RF board. @@ -21,10 +21,9 @@ the user should re-apply the desired setting every time the LO is re-tuned. UHD comes with the following calibration utilities: - * **uhd_cal_rx_iq_balance:** - mimimizes RX IQ imbalance vs LO frequency - * **uhd_cal_tx_dc_offset:** - mimimizes TX DC offset vs LO frequency - * **uhd_cal_tx_iq_balance:** - mimimizes TX IQ imbalance vs LO frequency - + * **uhd_cal_rx_iq_balance:** - mimimizes RX IQ imbalance vs. LO frequency + * **uhd_cal_tx_dc_offset:** - mimimizes TX DC offset vs. LO frequency + * **uhd_cal_tx_iq_balance:** - mimimizes TX IQ imbalance vs. LO frequency The following RF frontends are supported by the self-calibration utilities: @@ -33,9 +32,9 @@ The following RF frontends are supported by the self-calibration utilities: * more to come... ******************************************** -Calibration utilities +Calibration Utilities ******************************************** -UHD installs the calibration utilities into <install-path>/bin. +UHD installs the calibration utilities into **<install-path>/bin**. **Disconnect** any extrernal hardware from the RF antenna ports, and run the following from the command line. Each utility will take several minutes to complete. @@ -49,13 +48,13 @@ See the output given by --help for more advanced options, such as: manually choosing the frequency range and step size for the sweeps. ******************************************** -Calibration data +Calibration Data ******************************************** Calibration files are stored in the user's home/application directory. They can easily be moved from machine to another by copying the "cal" directory. Re-running a calibration utility will replace the existing calibration file. The old calibration file will be renamed so it may be recovered by the user. - * **Unix:** ${HOME}/.uhd/cal/ + * **Linux:** ${HOME}/.uhd/cal/ * **Windows:** %APPDATA%\\.uhd\\cal\\ diff --git a/host/docs/coding.rst b/host/docs/coding.rst index ed858ceb4..ef8cb5fe2 100644 --- a/host/docs/coding.rst +++ b/host/docs/coding.rst @@ -23,7 +23,7 @@ considered to be a "device". The device API provides ways to: See the documentation in *device.hpp* for reference. ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -High-Level: The multi usrp +High-Level: The Multi-USRP ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Multi-USRP class provides a fat interface to a single USRP with one or more channels, or multiple USRPs in a homogeneous setup. diff --git a/host/docs/dboards.rst b/host/docs/dboards.rst index d41bf824c..f434bf0c2 100644 --- a/host/docs/dboards.rst +++ b/host/docs/dboards.rst @@ -13,7 +13,7 @@ Eventually, this page will be expanded to list out the full properties of each board as well. ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Basic RX and and LFRX +Basic RX and LFRX ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Basic RX and LFRX boards have 4 frontends: @@ -23,7 +23,7 @@ The Basic RX and LFRX boards have 4 frontends: * **Frontend BA:** quadrature frontend using both antennas (QI) The boards have no tunable elements or programmable gains. -Though the magic of aliasing, you can down-convert signals +Through the magic of aliasing, you can down-convert signals greater than the Nyquist rate of the ADC. BasicRX Bandwidth (Hz): @@ -37,7 +37,7 @@ LFRX Bandwidth (Hz): * For Complex (AB or BA frontend): 66M ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Basic TX and and LFTX +Basic TX and LFTX ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Basic TX and LFTX boards have 4 frontends: @@ -47,7 +47,7 @@ The Basic TX and LFTX boards have 4 frontends: * **Frontend BA:** quadrature frontend using both antennas (QI) The boards have no tunable elements or programmable gains. -Though the magic of aliasing, you can up-convert signals +Through the magic of aliasing, you can up-convert signals greater than the Nyquist rate of the DAC. BasicTX Bandwidth (Hz): 250M @@ -64,13 +64,13 @@ LFTX Bandwidth (Hz): 33M DBSRX ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The DBSRX board has 1 quadrature frontend. -It defaults to direct conversion, but can use a low IF through lo_offset in uhd::tune_request_t +It defaults to direct conversion but can use a low IF through lo_offset in **uhd::tune_request_t**. Receive Antennas: **J3** * **Frontend 0:** Complex baseband signal from antenna J3 -The board has no user selectable antenna setting +The board has no user selectable antenna setting. Receive Gains: @@ -87,13 +87,13 @@ Sensors: DBSRX2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The DBSRX2 board has 1 quadrature frontend. -It defaults to direct conversion, but can use a low IF through lo_offset in uhd::tune_request_t +It defaults to direct conversion, but can use a low IF through lo_offset in **uhd::tune_request_t**. Receive Antennas: **J3** * **Frontend 0:** Complex baseband signal from antenna J3 -The board has no user selectable antenna setting +The board has no user-selectable antenna setting. Receive Gains: @@ -109,9 +109,9 @@ Sensors: ^^^^^^^^^^^^^^^^^^^^^^^^^^^ RFX Series ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The RFX Series boards have 2 quadrature frontends, one transmit, one receive. -Transmit defaults to low IF and Receive defaults to direct conversion. -The IF can be adjusted through lo_offset in uhd::tune_request_t +The RFX Series boards have 2 quadrature frontends: Transmit and Receive. +Transmit defaults to low IF, and Receive defaults to direct conversion. +The IF can be adjusted through lo_offset in **uhd::tune_request_t**. The RFX Series boards have independent receive and transmit LO's and synthesizers allowing full-duplex operation on different transmit and receive frequencies. @@ -282,7 +282,7 @@ Receive Frontends: * **Frontend RX1:** real-mode baseband from antenna J100 * **Frontend RX2:** real-mode baseband from antenna J140 -Note: The TVRX2 has always-on AGC, the software controllable gain is the +Note: The TVRX2 has always-on AGC; the software controllable gain is the final gain stage which controls the AGC set-point for output to ADC. Receive Gains: @@ -303,8 +303,8 @@ Daughterboard Modifications Sometimes, daughterboards will require modification to work on certain frequencies or to work with certain hardware. -Modification usually involves moving/removing a SMT component -and burning a new daughterboard id into the eeprom. +Modification usually involves moving/removing an SMT component +and burning a new daughterboard ID into the EEPROM. ^^^^^^^^^^^^^^^^^^^^^^^^^^^ DBSRX - Mod @@ -319,7 +319,7 @@ over the standard daughterboard clock lines. **Step 1: Move the clock configuration resistor** -Remove R193 (which is 10 ohms, 0603 size) and put it on R194, which is empty. +Remove R193 (which is 10 ohms, 0603 size), and put it on R194, which is empty. This is made somewhat more complicated by the fact that the silkscreen is not clear in that area. R193 is on the back, immediately below the large beige connector, J2. R194 is just below, and to the left of R193. @@ -354,7 +354,7 @@ Move R64 to R84, Move R142 to R153 Move R35 to R36, Move R117 to R115 These are all 0-ohm, so if you lose one, just short across the appropriate pads -**Step 3: Burn the appropriate daughterboard id into the EEPROM** +**Step 3: Burn the appropriate daughterboard ID into the EEPROM** With the daughterboard plugged-in, run the following commands: :: diff --git a/host/docs/general.rst b/host/docs/general.rst index 02ab26f46..ebba7b532 100644 --- a/host/docs/general.rst +++ b/host/docs/general.rst @@ -5,7 +5,7 @@ UHD - General Application Notes .. contents:: Table of Contents ------------------------------------------------------------------------ -Tuning notes +Tuning Notes ------------------------------------------------------------------------ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -20,12 +20,12 @@ 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 through the tune_request_t object, which allows for +stages of tuning through through the **tune_request_t** object, which allows for more advanced tuning. In general, Using UHD's advanced tuning is highly recommended as it makes it easy to move the DC component out of your band-of-interest. This can be done by -passing your desired LO offset to the tune_request_t object, and letting UHD +passing your desired LO offset to the **tune_request_t** object, and letting UHD handle the rest. Tuning the receive chain: @@ -69,7 +69,7 @@ Pseudo-code for dealing with settling time after tuning on receive: usrp->issue_stream_command(...); ------------------------------------------------------------------------ -Specifying the subdevice to use +Specifying the Subdevice to Use ------------------------------------------------------------------------ A subdevice specification string for USRP family devices is composed of: @@ -115,7 +115,7 @@ The frontend names are documented in the `Daughterboard Application Notes <./dboards.html>`_ ------------------------------------------------------------------------ -Overflow/Underflow notes +Overflow/Underflow Notes ------------------------------------------------------------------------ **Note:** The following overflow/underflow notes do not apply to USRP1, which does not support the advanced features available in newer products. @@ -132,26 +132,26 @@ and pushes an inline message packet into the receive stream. The host does not back-pressure the receive stream. When the kernel's socket buffer becomes full, it will drop subsequent packets. UHD detects the overflow as a discontinuity in the packet's sequence numbers, -and muxes an inline message packet into the receive stream. +and pushes an inline message packet into the receive stream. **Other devices**: The host back-pressures the receive stream. Therefore, overflows always occur in the device itself. -When the device's internal buffers become full, streaming is shutoff, +When the device's internal buffers become full, streaming is shut off, and an inline message packet is sent to the host. If the device was in continuous streaming mode, -the UHD will automatically restart streaming. +UHD will automatically restart streaming. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Underflow notes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When transmitting, the device consumes samples at a constant rate. Underflow occurs when the host does not produce data fast enough. -When the UHD detects underflow, it prints an "U" to stdout, +When UHD detects underflow, it prints a "U" to stdout, and pushes a message packet into the async message stream. ------------------------------------------------------------------------ -Threading notes +Threading Notes ------------------------------------------------------------------------ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -161,7 +161,7 @@ For the most part, UHD is thread-safe. Please observe the following limitations: **Fast-path thread requirements:** -There are three fast-path methods for a device: send(), recv(), and recv_async_msg(). +There are three fast-path methods for a device: **send()**, **recv()**, and **recv_async_msg()**. All three methods are thread-safe and can be called from different thread contexts. For performance, the user should call each method from a separate thread context. These methods can also be used in a non-blocking fashion by using a timeout of zero. @@ -169,7 +169,7 @@ These methods can also be used in a non-blocking fashion by using a timeout of z **Slow-path thread requirements:** It is safe to change multiple settings simultaneously. However, this could leave the settings for a device in an uncertain state. -The is because changing one setting could have an impact on how a call affects other settings. +This is because changing one setting could have an impact on how a call affects other settings. Example: setting the channel mapping affects how the antennas are set. It is recommended to use at most one thread context for manipulating device settings. @@ -177,9 +177,9 @@ It is recommended to use at most one thread context for manipulating device sett Thread priority scheduling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When the UHD spawns a new thread it may try to boost the thread's scheduling priority. -When setting the priority fails, the UHD prints out an error. -This error is harmless, it simply means that the thread will have a normal scheduling priority. +When UHD spawns a new thread it may try to boost the thread's scheduling priority. +When setting the priority fails, UHD prints out an error. +This error is harmless; it simply means that the thread will have a normal scheduling priority. **Linux Notes:** @@ -193,7 +193,7 @@ Replace <my_group> with a group to which your user belongs. Settings will not take effect until the user is in a different login session. ------------------------------------------------------------------------ -Misc notes +Miscellaneous Notes ------------------------------------------------------------------------ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/host/docs/gpsdo.rst b/host/docs/gpsdo.rst index e84af8500..2f3655eff 100644 --- a/host/docs/gpsdo.rst +++ b/host/docs/gpsdo.rst @@ -25,25 +25,25 @@ Specifications **Antenna Types:** -The GPSDO is capable of supplying a 3V for active GPS antennas or supporting passive antennas +The GPSDO is capable of supplying a 3V for active GPS antennas or supporting passive antennas. ------------------------------------------------------------------------ -Installation instructions +Installation Instructions ------------------------------------------------------------------------ Installation instructions can be found here: `www.ettus.com/downloads/gpsdo-kit.pdf <http://www.ettus.com/downloads/gpsdo-kit.pdf>`_ ******************************************** -Post installation task (N-Series only) +Post-installation Task (N-Series only) ******************************************** -This is necessary if you require absolute GPS time in your application, +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, +If you only require 10MHz and PPS signals for reference or MIMO use (see the `Synchronization Application Notes <./sync.html>`_), it is not necessary to perform this step. To configure the USRP to communicate with the GPSDO, use the -usrp_burn_mb_eeprom utility: +**usrp_burn_mb_eeprom** utility: :: @@ -54,7 +54,7 @@ usrp_burn_mb_eeprom utility: ./usrp_burn_mb_eeprom --args=<optional device args> --key=gpsdo --val=none ------------------------------------------------------------------------ -Using the GPSDO in your application +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 @@ -62,8 +62,8 @@ 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: +GPS data is obtained through the **mboard_sensors** interface. To retrieve +the current GPS time, use the **gps_time** sensor: :: @@ -71,10 +71,10 @@ the current GPS time, use the "gps_time" sensor: 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. +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 +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/identification.rst b/host/docs/identification.rst index 9fc53412b..4e653ad06 100644 --- a/host/docs/identification.rst +++ b/host/docs/identification.rst @@ -9,9 +9,9 @@ Identifying USRPs ------------------------------------------------------------------------ Devices are addressed through key/value string pairs. These string pairs can be used to narrow down the search for a specific device or group of devices. -Most UHD utility applications and examples have a --args parameter that takes a device address, which is expressed as a delimited string. +Most UHD utility applications and examples have an **--args** parameter that takes a device address, which is expressed as a delimited string. -See the documentation in types/device_addr.hpp for reference. +See the documentation in **types/device_addr.hpp** for reference. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Common device identifiers @@ -33,8 +33,8 @@ Every device has several ways of identifying it on the host system: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Device discovery via command line ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Devices attached to your system can be discovered using the "uhd_find_devices" program. -The find devices program scans your system for supported devices and prints +Devices attached to your system can be discovered using the **uhd_find_devices** program. +This program scans your system for supported devices and prints out an enumerated list of discovered devices and their addresses. The list of discovered devices can be narrowed down by specifying device address args. @@ -79,9 +79,9 @@ The hint argument can be populated to narrow the scope of the search. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Device properties ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Properties of devices attached to your system can be probed with the "uhd_usrp_probe" program. -The usrp probe program constructs an instance of the device and prints out its properties; -properties such as detected daughter-boards, frequency range, gain ranges, etc... +Properties of devices attached to your system can be probed with the **uhd_usrp_probe** program. +This program constructs an instance of the device and prints out its properties, +such as detected daughterboards, frequency range, gain ranges, etc... **Usage:** :: @@ -97,7 +97,7 @@ The USRP can then be identified via name, rather than a difficult to remember se A name has the following properties: * is composed of ASCII characters -* is between 0 and 20 characters +* is 0-20 characters * is not required to be unique ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/host/docs/images.rst b/host/docs/images.rst index 78280bac0..eaddfdf1d 100644 --- a/host/docs/images.rst +++ b/host/docs/images.rst @@ -17,10 +17,15 @@ The methods of loading images into the device vary among devices: * **USRP-B Series:** The host code will automatically load the FPGA at runtime. ------------------------------------------------------------------------ -Pre-built images +Pre-built Images ------------------------------------------------------------------------ Pre-built images are available for download. + +* `Master Branch images <http://files.ettus.com/binaries/master_images/>`_ +* `Maint Branch images <http://files.ettus.com/binaries/maint_images/>`_ +* `Next Branch images <http://files.ettus.com/binaries/next_images/>`_ + See the UHD wiki for the download link. The pre-built images come in two forms: @@ -31,8 +36,9 @@ The pre-built images come in two forms: ^^^^^^^^^^^^^^^^^^^^^^ Platform installers ^^^^^^^^^^^^^^^^^^^^^^ -The UNIX-based installers will install the images into /usr/share/uhd/images. -On Windows, the images will be installed to <install-path>/share/uhd/images. +The UNIX-based installers will install the images into **/usr/share/uhd/images**. + +The Windows installers will install the images into **C:/Program Files/UHD/share/uhd/images**. ^^^^^^^^^^^^^^^^^^^^^^ Archive install @@ -42,52 +48,53 @@ When installing images from an archive, there are two options: **Option 1:** Unpack the archive into the UHD installation prefix. -The UHD will always search <install-path>/share/uhd/images for image files. -Where <install-path> was set by the CMAKE_INSTALL_PREFIX at configure-time. +UHD will always search **<install-path>/share/uhd/images** for image files. +Where **<install-path>** was set by the **CMAKE_INSTALL_PREFIX** at configure-time. **Option 2:** -Unpack the archive anywhere and set the UHD_IMAGE_PATH environment variable. -The UHD_IMAGE_PATH may contain a list of directories to search for image files. +Unpack the archive anywhere and set the **UHD_IMAGES_PATH** environment variable. +**UHD_IMAGES_PATH** may contain a list of directories to search for image files. ------------------------------------------------------------------------ -Building images +Building Images ------------------------------------------------------------------------ The UHD source repository comes with the source code necessary to build both firmware and FPGA images for all supported devices. -The build commands for a particular image can be found in <uhd-repo-path>/images/Makefile. + +The build commands for a particular image can be found in **<uhd-repo-path>/images/Makefile**. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Xilinx FPGA builds ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Xilinx ISE 12.x and up is required to build the Xilinx FPGA images. -The build requires that you have a UNIX-like environment with make. -Make sure that xtclsh from the Xilinx ISE bin directory is in your $PATH. +The build requires that you have a UNIX-like environment with **Make**. +Make sure that **xtclsh** from the Xilinx ISE bin directory is in your **$PATH**. -See <uhd-repo-path>/fpga/usrp2/top/* +See **<uhd-repo-path>/fpga/usrp2/top/**. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ZPU firmware builds ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ZPU GCC compiler is required to build the ZPU firmware images. -The build requires that you have a unix-like environment with cmake and make. -Make sure that zpu-elf-gcc is in your $PATH. +The build requires that you have a UNIX-like environment with **CMake** and **Make**. +Make sure that **zpu-elf-gcc** is in your **$PATH**. -See <uhd-repo-path>/firmware/zpu +See **<uhd-repo-path>/firmware/zpu**. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Altera FPGA builds ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Quartus is required to build the Altera FPGA images. -Pre-built images can also be found in <uhd-repo-path>/fpga/usrp1/rbf +Pre-built images can also be found in **<uhd-repo-path>/fpga/usrp1/rbf**. -See <uhd-repo-path>/fpga/usrp1/toplevel/* +See **<uhd-repo-path>/fpga/usrp1/toplevel/***. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FX2 firmware builds ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The sdcc compiler is required to build the FX2 firmware images. -The build requires that you have a unix-like environment with cmake and make. +The SDCC compiler is required to build the FX2 firmware images. +The build requires that you have a UNIX-like environment with **CMake** and **Make**. -See <uhd-repo-path>/firmware/fx2 +See **<uhd-repo-path>/firmware/fx2**. diff --git a/host/docs/index.rst b/host/docs/index.rst index 9f8bd9cb1..8ad1dcb65 100644 --- a/host/docs/index.rst +++ b/host/docs/index.rst @@ -4,7 +4,7 @@ UHD - USRP Hardware Driver The UHD is the "Universal Software Radio Peripheral" hardware driver. The goal of the UHD is to provide a host driver and API for current and future Ettus Research products. -Users will be able to use the UHD driver standalone or with 3rd party applications. +Users will be able to use the UHD driver standalone or with third-party applications. ------------------------------------------------------------------------ Contents @@ -40,4 +40,3 @@ API Documentation * `Doxygen <./../../doxygen/html/index.html>`_ * `Using the API <./coding.html>`_ * `Device Streaming <./stream.html>`_ - diff --git a/host/docs/stream.rst b/host/docs/stream.rst index 9ffec22e5..054ec37dd 100644 --- a/host/docs/stream.rst +++ b/host/docs/stream.rst @@ -5,7 +5,7 @@ UHD - Device streaming .. contents:: Table of Contents ------------------------------------------------------------------------ -Introduction to streaming +Introduction to Streaming ------------------------------------------------------------------------ The concept of streaming refers to the transportation of samples between host and device. A stream is an object that facilitates streaming between host application and device. @@ -13,7 +13,7 @@ A RX stream allows the user to receive samples from the device. A TX stream allows the user to transmit samples to the device. ------------------------------------------------------------------------ -Link layer encapsulation +Link Layer Encapsulation ------------------------------------------------------------------------ The VITA49 standard provides encapsulation for sample data across a link layer. On all generation2 hardware, samples are encapsulated into VRT IF data packets. @@ -27,7 +27,7 @@ The length of an IF data packet can be limited by several factors: * Buffering on the device - size of BRAM FIFOs ------------------------------------------------------------------------ -Data types +Data Types ------------------------------------------------------------------------ There are two important data types to consider when streaming: @@ -45,7 +45,7 @@ The link-layer data type ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The link-layer or "over-the-wire" data type refers to the format of the samples sent through the link. Typically, this data type is complex-int16. -However, To increase throughput over the link-layer, +However, to increase throughput over the link-layer, at the expense of precision, complex-int8 may be used. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -54,6 +54,6 @@ Conversion The user may request arbitrary combinations of host and link data types; however, not all combinations are supported. The user may register custom data type formats and conversion routines. -See uhd/convert.hpp for futher documentation. +See **uhd/convert.hpp** for futher documentation. -TODO provide example of convert API +TODO: provide example of convert API diff --git a/host/docs/sync.rst b/host/docs/sync.rst index 55c9f81f0..4c0756555 100644 --- a/host/docs/sync.rst +++ b/host/docs/sync.rst @@ -12,13 +12,13 @@ or other applications requiring multiple USRPs operating synchronously. which does not support the advanced features available in newer products. ------------------------------------------------------------------------ -Common reference signals +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. -* A pulse-per-second (1PPS) to synchronize the sample time across devices. -* Or, the MIMO cable transmits an encoded time message from one device to another. +* A pulse-per-second (PPS) to synchronize the sample time across devices. +* A MIMO cable transmits an encoded time message from one device to another. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ PPS and 10 MHz reference signals @@ -36,7 +36,7 @@ However, some USRP models can provide these signals from an optional internal GP Sometimes the delay on the PPS signal will cause it to arrive inside the timing margin the FPGA sampling clock, causing PPS edges to be separated by less or more than 100 million cycles of the FPGA clock. If this is the case, -you can change the edge reference of the PPS signal with this special parameter: +you can change the edge reference of the PPS signal with this parameter: :: @@ -44,7 +44,7 @@ you can change the edge reference of the PPS signal with this special parameter: **Note2:** For users generating their own signals for the external SMA connectors, -the pulse-per-second should be clocked from the 10MHz reference. +the PPS should be clocked from the 10MHz reference. See the application notes for your device for specific signal requirements. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -60,13 +60,13 @@ Users of the MIMO cable may use method 1 to synchronize multiple pairs of device usrp->set_time_source("mimo"); ------------------------------------------------------------------------ -Synchronizing the device time +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. +You can use the **set_time_next_pps(...)** function to either initialize the sample time to 0 +or 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(...). +it doesn't matter what time you initialize to when using **set_time_next_pps(...)**. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Method 1 - poll the USRP time registers @@ -85,7 +85,7 @@ When the last PPS time increments, the user can determine that a PPS has occurre ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Method 2 - query the GPSDO for seconds ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Most GPSDO can be configured to output a NMEA string over the serial port once every PPS. +Most GPSDOs 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: @@ -117,7 +117,7 @@ The slave device will automatically synchronize to the time on the master device See the `MIMO Cable Application Notes <./usrp2.html#using-the-mimo-cable>`_ for more detail. ------------------------------------------------------------------------ -Synchronizing channel phase +Synchronizing Channel Phase ------------------------------------------------------------------------ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/host/docs/transport.rst b/host/docs/transport.rst index 7dc465b4c..111c46c68 100644 --- a/host/docs/transport.rst +++ b/host/docs/transport.rst @@ -17,7 +17,7 @@ that are known to perform well on a variety of systems. The transport parameters are defined below for the various transports in the UHD: ------------------------------------------------------------------------ -UDP transport (sockets) +UDP Transport (Sockets) ------------------------------------------------------------------------ The UDP transport is implemented with user-space sockets. This means standard Berkeley sockets API using send()/recv(). @@ -33,15 +33,15 @@ The following parameters can be used to alter the transport's default behavior: * **num_send_frames:** The number of send buffers to allocate **Note1:** -num_recv_frames does not affect performance. +**num_recv_frames** does not affect performance. **Note2:** -num_send_frames does not affect performance. +**num_send_frames** does not affect performance. **Note3:** -recv_frame_size and send_frame_size can be used to +**recv_frame_size** and **send_frame_size** can be used to increase or decrease the maximum number of samples per packet. -The frame sizes default to an MTU of 1472 bytes per IP/UDP packet, +The frame sizes default to an MTU of 1472 bytes per IP/UDP packet and may be increased if permitted by your network hardware. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -58,8 +58,8 @@ The following mechanisms affect the transmission of periodic update packets: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Resize socket buffers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -It may be useful increase the size of the socket buffers to -move the burden of buffering samples into the kernel, or to +It may be useful to increase the size of the socket buffers to +move the burden of buffering samples into the kernel or to buffer incoming samples faster than they can be processed. However, if your application cannot process samples fast enough, no amount of buffering can save you. @@ -74,7 +74,7 @@ The following parameters can be used to alter socket's buffer sizes: Latency Optimization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Latency is a measurement of the time it takes a sample to travel between the host and device. -Most computer hardware and software is bandwidth optimized which may negatively affect latency. +Most computer hardware and software is bandwidth optimized, which may negatively affect latency. If your application has strict latency requirements, please consider the following notes: **Note1:** @@ -112,7 +112,7 @@ FastSendDatagramThreshold registry key to change documented here: * http://www.microsoft.com/windows/windowsmedia/howto/articles/optimize_web.aspx#appendix_e ------------------------------------------------------------------------ -USB transport (libusb) +USB Transport (LibUSB) ------------------------------------------------------------------------ The USB transport is implemented with libusb. Libusb provides an asynchronous API for USB bulk transfers. @@ -147,7 +147,7 @@ A driver package must be installed to use a USB-based product with UHD: * Download the driver from the UHD wiki page. * Unzip the file into a known location. We will refer to this as the <directory>. -* Open the device manager and plug-in the USRP. You will see an unrecognized USB device in the device manager. +* Open the device manager and plug in the USRP. You will see an unrecognized USB device in the device manager. * Right click on the unrecognized USB device and select update/install driver software (may vary for your OS). * In the driver installation wizard, select "browse for driver", browse to the <directory>, and select the .inf file. * Continue through the installation wizard until the driver is installed. |