<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>UHD - General Application Notes</title>
<style type="text/css">
body{
font-family:Arial, Helvetica, sans-serif;
font-size:11pt;
color:black;
background-color:white;
width:90%;
margin:0 auto 0 auto;
}
div.document div.contents{
border:1px solid #333333;
padding:10px 30px 10px 10px;
margin-left:50px;
color:inherit;
background-color:#FCFCFC;
display:inline-block;
}
div.document p.topic-title{
font-weight:bold;
}
div.document a:link, div.document a:visited{
color:#236B8E;
background-color:inherit;
text-decoration:none;
}
div.document a:hover{
color:#4985D6;
background-color:inherit;
text-decoration:none;
}
div.document h1.title{
font-size:150%;
border-left:1px solid #333333;
border-bottom:1px solid #333333;
text-align:left;
padding:10px 0px 10px 10px;
margin:10px 5px 20px 5px;
color:#333333;
background-color:inherit;
}
div.document h2.subtitle, div.section h1{
margin-top:50px;
border-bottom:1px solid #333333;
font-size:140%;
text-align:center;
padding:20px 0px 10px 0px;
color:#333333;
background-color:inherit;
}
div.section h2{
font-size:110%;
text-align:left;
padding:15px 0px 5px 0px;
text-decoration:underline;
color:#333333;
background-color:inherit;
}
div.document pre.literal-block{
border:1px inset #333333;
padding:5px;
margin:10px 5px 10px 5px;
color:inherit;
background-color:#FCFCFC;
font-size:90%;
}
div.document table{
padding:5px;
font-size:95%;
}
div.document th{
padding:3px 7px 3px 7px;
border:1px solid #333333;
text-align:center;
color:inherit;
background-color:#ECECEC;
}
div.document tr{
}
div.document td{
padding:3px 7px 3px 7px;
border:1px solid #333333;
text-align:center;
color:inherit;
background-color:#FCFCFC;
}
div.footer{
margin:50px auto 30px auto;
text-align:center;
font-size:85%;
}
</style>
</head>
<body>
<div class="document" id="uhd-general-application-notes">
<h1 class="title">UHD - General Application Notes</h1>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#tuning-notes" id="id1">Tuning Notes</a><ul>
<li><a class="reference internal" href="#two-stage-tuning-process" id="id2">Two-stage tuning process</a><ul>
<li><a class="reference internal" href="#tuning-the-receive-chain" id="id3">Tuning the receive chain:</a></li>
</ul>
</li>
<li><a class="reference internal" href="#rf-front-end-settling-time" id="id4">RF front-end settling time</a><ul>
<li><a class="reference internal" href="#pseudo-code-for-dealing-with-settling-time-after-tuning-on-receive" id="id5">Pseudo-code for dealing with settling time after tuning on receive:</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#specifying-the-subdevice-to-use" id="id6">Specifying the Subdevice to Use</a><ul>
<li><a class="reference internal" href="#usrp-family-motherboard-slot-names" id="id7">USRP Family Motherboard Slot Names</a></li>
<li><a class="reference internal" href="#daughterboard-frontend-names" id="id8">Daughterboard Frontend Names</a></li>
</ul>
</li>
<li><a class="reference internal" href="#overflow-underflow-notes" id="id9">Overflow/Underflow Notes</a><ul>
<li><a class="reference internal" href="#overflow-notes" id="id10">Overflow notes</a></li>
<li><a class="reference internal" href="#underflow-notes" id="id11">Underflow notes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#threading-notes" id="id12">Threading Notes</a><ul>
<li><a class="reference internal" href="#thread-safety-notes" id="id13">Thread safety notes</a></li>
<li><a class="reference internal" href="#thread-priority-scheduling" id="id14">Thread priority scheduling</a></li>
</ul>
</li>
<li><a class="reference internal" href="#miscellaneous-notes" id="id15">Miscellaneous Notes</a><ul>
<li><a class="reference internal" href="#support-for-dynamically-loadable-modules" id="id16">Support for dynamically loadable modules</a></li>
<li><a class="reference internal" href="#disabling-or-redirecting-prints-to-stdout" id="id17">Disabling or redirecting prints to stdout</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="tuning-notes">
<h1>Tuning Notes</h1>
<div class="section" id="two-stage-tuning-process">
<h2>Two-stage tuning process</h2>
<p>A USRP device has two stages of tuning:</p>
<ul class="simple">
<li>RF front-end: translates bewteen RF and IF</li>
<li>DSP: translates between IF and baseband</li>
</ul>
<p>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 <strong>tune_request_t</strong> object, which allows for
more advanced tuning.</p>
<p>In general, Using UHD software'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 <strong>tune_request_t</strong> object, and letting the UHD
software handle the rest.</p>
<p>The <strong>tune_request_t</strong> object can also be used with certain daughterboards to use
Integer-N tuning instead of the default fractional tuning, allowing for better spur
performance. The daughterboards that support this functionality are:</p>
<ul class="simple">
<li>WBX (all revisions)</li>
<li>WBX-120</li>
<li>SBX (all revisions)</li>
<li>SBX-120</li>
<li>CBX</li>
<li>CBX-120</li>
</ul>
<div class="section" id="tuning-the-receive-chain">
<h3>Tuning the receive chain:</h3>
<blockquote>
<p>//tuning to a desired center frequency
usrp->set_rx_freq(target_frequency_in_hz);</p>
<p class="attribution">—OR--</p>
</blockquote>
<blockquote>
//advanced tuning with tune_request_t
uhd::tune_request_t tune_req(target_frequency_in_hz, desired_lo_offset);
tune_req.args = uhd::device_addr_t("mode_n=integer"); //to use Int-N tuning
//fill in any additional/optional tune request fields...
usrp->set_rx_freq(tune_req);</blockquote>
<p>More information can be found in <a class="reference external" href="./../../doxygen/html/structuhd_1_1tune__request__t.html">tune_request.hpp</a>.</p>
</div>
</div>
<div class="section" id="rf-front-end-settling-time">
<h2>RF front-end settling time</h2>
<p>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 <strong>lo_locked</strong> sensor to become true or sleep for
a conservative amount of time (perhaps a second).</p>
<div class="section" id="pseudo-code-for-dealing-with-settling-time-after-tuning-on-receive">
<h3>Pseudo-code for dealing with settling time after tuning on receive:</h3>
<pre class="literal-block">
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(...);
</pre>
</div>
</div>
</div>
<div class="section" id="specifying-the-subdevice-to-use">
<h1>Specifying the Subdevice to Use</h1>
<p>A subdevice specification string for USRP family devices is composed of:</p>
<pre class="literal-block">
<motherboard slot name>:<daughterboard frontend name>
</pre>
<p>Ex: The subdev spec markup string to select a WBX on slot B.</p>
<pre class="literal-block">
B:0
</pre>
<p>Ex: The subdev spec markup string to select a BasicRX on slot B.</p>
<pre class="literal-block">
B:AB
-- OR --
B:A
-- OR --
B:B
</pre>
<div class="section" id="usrp-family-motherboard-slot-names">
<h2>USRP Family Motherboard Slot Names</h2>
<p>All USRP family motherboards have a first slot named <strong>A:</strong>. The USRP1 has
two daughterboard subdevice slots, known as <strong>A:</strong> and <strong>B:</strong>.</p>
</div>
<div class="section" id="daughterboard-frontend-names">
<h2>Daughterboard Frontend Names</h2>
<p>Daughterboard frontend names can be used to specify which signal path is used
from a daughterboard. Most daughterboards have only one frontend <strong>:0</strong>. A few
daughterboards (Basic, LF and TVRX2) have multiple frontend names available.
The frontend names are documented in the
<a class="reference external" href="./dboards.html">Daughterboard Application Notes</a></p>
</div>
</div>
<div class="section" id="overflow-underflow-notes">
<h1>Overflow/Underflow Notes</h1>
<p><strong>Note:</strong> The following overflow/underflow notes do not apply to USRP1,
which does not support the advanced features available in newer products.</p>
<div class="section" id="overflow-notes">
<h2>Overflow notes</h2>
<p>When receiving, the device produces samples at a constant rate.
Overflows occurs when the host does not consume data fast enough.
When UHD software detects the overflow, it prints an "O" or "D" to stdout,
and pushes an inline message packet into the receive stream.</p>
<p><strong>Network-based devices</strong>:
The host does not back-pressure the receive stream.
When the kernel's socket buffer becomes full, it will drop subsequent packets.
UHD software detects the overflow as a discontinuity in the packet's sequence numbers,
and pushes an inline message packet into the receive stream.
In this case the character "D" is printed to stdout as an indication.</p>
<p><strong>Other devices</strong>:
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 shut off,
and an inline message packet is sent to the host.
In this case the character "O" is printed to stdout as an indication.
If the device was in continuous streaming mode,
the UHD software will automatically restart streaming when the buffer has
space again.</p>
</div>
<div class="section" id="underflow-notes">
<h2>Underflow notes</h2>
<p>When transmitting, the device consumes samples at a constant rate.
Underflow occurs when the host does not produce data fast enough.
When UHD software detects the underflow, it prints a "U" to stdout,
and pushes a message packet into the async message stream.</p>
</div>
</div>
<div class="section" id="threading-notes">
<h1>Threading Notes</h1>
<div class="section" id="thread-safety-notes">
<h2>Thread safety notes</h2>
<p>For the most part, UHD software is thread-safe.
Please observe the following limitations:</p>
<p><strong>Fast-path thread requirements:</strong>
There are three fast-path methods for a device: <strong>send()</strong>, <strong>recv()</strong>, and <strong>recv_async_msg()</strong>.
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.</p>
<p><strong>Slow-path thread requirements:</strong>
It is safe to change multiple settings simultaneously. However,
this could leave the settings for a device in an uncertain state.
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.</p>
</div>
<div class="section" id="thread-priority-scheduling">
<h2>Thread priority scheduling</h2>
<p>When UHD software spawns a new thread it may try to boost the thread's scheduling priority.
When setting the priority fails, the UHD software prints out an error.
This error is harmless; it simply means that the thread will have a normal scheduling priority.</p>
<p><strong>Linux Notes:</strong></p>
<p>Non-privileged users need special permission to change the scheduling priority.
Add the following line to <strong>/etc/security/limits.conf</strong>:
:::::::::::::::::::::::::::::::::::::::::::::::::::::::</p>
<pre class="literal-block">
@<my_group> - rtprio 99
</pre>
<p>Replace <strong><my_group></strong> with a group to which your user belongs.
Settings will not take effect until the user is in a different login session.</p>
</div>
</div>
<div class="section" id="miscellaneous-notes">
<h1>Miscellaneous Notes</h1>
<div class="section" id="support-for-dynamically-loadable-modules">
<h2>Support for dynamically loadable modules</h2>
<p>For a module to be loaded at runtime, it must be:</p>
<ul class="simple">
<li>found in the <strong>UHD_MODULE_PATH</strong> environment variable,</li>
<li>installed into the <strong><install-path>/share/uhd/modules</strong> directory,</li>
<li>or installed into <strong>/usr/share/uhd/modules</strong> directory (UNIX only).</li>
</ul>
</div>
<div class="section" id="disabling-or-redirecting-prints-to-stdout">
<h2>Disabling or redirecting prints to stdout</h2>
<p>The user can disable the UHD library from printing directly to stdout by registering a custom message handler.
The handler will intercept all messages, which can be dropped or redirected.
Only one handler can be registered at a time.
Make <strong>register_handler</strong> your first call into the UHD library:</p>
<pre class="literal-block">
#include <uhd/utils/msg.hpp>
void my_handler(uhd::msg::type_t type, const std::string &msg){
//handle the message...
}
uhd::msg::register_handler(&my_handler);
</pre>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
Generated on: 2014-10-15 11:47 UTC.
</div>
</body>
</html>
