[Commit-gnuradio] [gnuradio] 02/03: uhd: Updated USRP block documentation

[git]

This is an automated email from the git hooks/post-receive script.

jcorgan pushed a commit to branch master
in repository gnuradio.

commit 0e60616cb0435c084d9ec85972e94e3141003074
Author: Martin Braun <address@hidden>
Date:   Wed Apr 29 13:46:35 2015 -0700

    uhd: Updated USRP block documentation
---
 gr-uhd/doc/uhd.dox                        |  13 +---
 gr-uhd/include/gnuradio/uhd/usrp_block.h  |   9 +++
 gr-uhd/include/gnuradio/uhd/usrp_sink.h   | 123 ++++++++++++++++--------------
 gr-uhd/include/gnuradio/uhd/usrp_source.h |  47 ++++++------
 4 files changed, 105 insertions(+), 87 deletions(-)

diff --git a/gr-uhd/doc/uhd.dox b/gr-uhd/doc/uhd.dox
index da6d9d4..2a2658d 100644
--- a/gr-uhd/doc/uhd.dox
+++ b/gr-uhd/doc/uhd.dox
@@ -12,15 +12,10 @@ as:
     from gnuradio import uhd
 \endcode
 
-The relevant blocks are listed in the \ref uhd_blk group.
-
-A quick listing of the details can be found in Python after importing
-by using:
-
-\code
-    help(uhd)
-\endcode
-
+The relevant blocks are listed in the \ref uhd_blk group. The most important
+components are the gr::uhd::usrp_source and gr::uhd::usrp_sink blocks, which
+act as receivers/transmitters. Both are derived from gr::uhd::usrp_block, which
+defines many of the shared functions between those blocks.
 
 \section uhd_external_docs External Documentation
 
diff --git a/gr-uhd/include/gnuradio/uhd/usrp_block.h 
b/gr-uhd/include/gnuradio/uhd/usrp_block.h
index 656bb8a..5605ab8 100644
--- a/gr-uhd/include/gnuradio/uhd/usrp_block.h
+++ b/gr-uhd/include/gnuradio/uhd/usrp_block.h
@@ -30,6 +30,14 @@
 namespace gr {
   namespace uhd {
 
+    /*! Base class for USRP blocks.
+     * \ingroup uhd_blk
+     *
+     * Note that many of the functions defined here differ between
+     * Rx and Tx configurations. As an example, set_center_freq()
+     * will set the Rx frequency for a usrp_source object, and the
+     * Tx frequency on a usrp_sink object.
+     */
     class GR_UHD_API usrp_block : public gr::sync_block
     {
      protected:
@@ -38,6 +46,7 @@ namespace gr {
                  gr::io_signature::sptr input_signature,
                  gr::io_signature::sptr output_signature);
      public:
+
       /*!
        * Set the frontend specification.
        *
diff --git a/gr-uhd/include/gnuradio/uhd/usrp_sink.h 
b/gr-uhd/include/gnuradio/uhd/usrp_sink.h
index 405922b..4ccb83f 100644
--- a/gr-uhd/include/gnuradio/uhd/usrp_sink.h
+++ b/gr-uhd/include/gnuradio/uhd/usrp_sink.h
@@ -52,6 +52,71 @@ namespace gr {
 
     class uhd_usrp_sink;
 
+    /*! USRP Sink -- Radio Transmitter
+     * \ingroup uhd_blk
+     *
+     *
+     * The USRP sink block reads a stream and transmits the samples.
+     * The sink block also provides API calls for transmitter settings.
+     * See also gr::uhd::usrp_block for more public API calls.
+     *
+     * \section uhd_tx_tagging TX Stream tagging
+     *
+     * The following tag keys will be consumed by the work function:
+     *  - pmt::string_to_symbol("tx_sob")
+     *  - pmt::string_to_symbol("tx_eob")
+     *  - pmt::string_to_symbol("tx_time")
+     *  - pmt::string_to_symbol("tx_freq")
+     *  - pmt::string_to_symbol("tx_command")
+     *  - pmt::string_to_symbol(tsb_tag_name)
+     *
+     * Any other tag will be ignored.
+     *
+     * \section uhd_tx_burstys Bursty Transmission
+     *
+     * There are multiple ways to do bursty transmission without triggering
+     * underruns:
+     * - Using SOB/EOB tags
+     * - Using tagged streams (See \ref page_tagged_stream_blocks)
+     *
+     * The sob and eob (start and end of burst) tag values are pmt booleans.
+     * When present, burst tags should be set to true (pmt::PMT_T).
+     *
+     * If `tsb_tag_name` is not an empty string, all "tx_sob" and "tx_eob"
+     * tags will be ignored, and the input is assumed to a tagged stream.
+     *
+     * If sob/eob tags or length tags are used, this block understands that
+     * the data is bursty, and will configure the USRP to make sure there's
+     * no underruns after transmitting the final sample of a burst.
+     *
+     * \section uhd_tx_time Timestamps
+     *
+     * The timestamp tag value is a PMT tuple of the following:
+     * (uint64 seconds, double fractional seconds).
+     *
+     * The tx_freq tag has to be a double or a pair of form (channel, 
frequency),
+     * with frequency being a double and channel being an integer.
+     * This tag will trigger a tune command to the USRP
+     * to the given frequency, if possible. Note that oscillators need some 
time
+     * to stabilize after this! Don't expect clean data to be sent immediately 
after this command.
+     * If channel is omitted, and only a double is given, it will set this 
frequency to all
+     * channels.
+     *
+     * The command tag can carry a PMT command. See the following section.
+     *
+     * \section uhd_tx_commands Command interface
+     *
+     * There are two ways of passing commands to this block:
+     * 1. tx_command tag. The command is attached to a sample, and will 
executed
+     *    before the sample is transmitted, and after the previous sample.
+     * 2. The 'command' message port. The command is executed asynchronously,
+     *    as soon as possible.
+     *
+     * In both cases, the payload of the command is a PMT command, as described
+     * in Section \ref uhd_command_syntax.
+     *
+     * For a more general description of the gr-uhd components, see \ref 
page_uhd.
+     */
     class GR_UHD_API usrp_sink : virtual public usrp_block
     {
     public:
@@ -66,64 +131,10 @@ namespace gr {
        * gr::uhd::usrp_sink::make(const ::uhd::device_addr_t, const 
::uhd::stream_args_t, const std::string).
        */
       static sptr make(const ::uhd::device_addr_t &device_addr,
-                      const ::uhd::io_type_t &io_type,
-                      size_t num_channels);
+                       const ::uhd::io_type_t &io_type,
+                       size_t num_channels);
 
       /*!
-       * \brief Make a new USRP sink block (usually a radio transmitter).
-       *
-       * The USRP sink block reads a stream and transmits the samples.
-       * The sink block also provides API calls for transmitter settings.
-       *
-       * \section uhd_tx_tagging TX Stream tagging
-       *
-       * The following tag keys will be consumed by the work function:
-       *  - pmt::string_to_symbol("tx_sob")
-       *  - pmt::string_to_symbol("tx_eob")
-       *  - pmt::string_to_symbol("tx_time")
-       *  - pmt::string_to_symbol("tx_freq")
-       *  - pmt::string_to_symbol("tx_command")
-       *  - pmt::string_to_symbol(tsb_tag_name)
-       *
-       * Any other tag will be ignored.
-       *
-       * The sob and eob (start and end of burst) tag values are pmt booleans.
-       * When present, burst tags should be set to true (pmt::PMT_T).
-       *
-       * If `tsb_tag_name` is not an empty string, all "tx_sob" and "tx_eob"
-       * tags will be ignored, and the input is assumed to a tagged stream,
-       * as described in \ref page_tagged_stream_blocks.
-       *
-       * If sob/eob tags or length tags are used, this block understands that
-       * the data is bursty, and will configure the USRP to make sure there's
-       * no underruns after transmitting the final sample of a burst.
-       *
-       * The timestamp tag value is a PMT tuple of the following:
-       * (uint64 seconds, double fractional seconds).
-       *
-       * The tx_freq tag has to be a double or a pair of form (channel, 
frequency),
-       * with frequency being a double and channel being an integer.
-       * This tag will trigger a tune command to the USRP
-       * to the given frequency, if possible. Note that oscillators need some 
time
-       * to stabilize after this! Don't expect clean data to be sent 
immediately after this command.
-       * If channel is omitted, and only a double is given, it will set this 
frequency to all
-       * channels.
-       *
-       * The command tag can carry a PMT command. See the following section.
-       *
-       * \section uhd_tx_commands Command interface
-       *
-       * There are two ways of passing commands to this block:
-       * 1. tx_command tag. The command is attached to a sample, and will 
executed
-       *    before the sample is transmitted, and after the previous sample.
-       * 2. The 'command' message port. The command is executed asynchronously,
-       *    as soon as possible.
-       *
-       * In both cases, the payload of the command is a PMT command, as 
described
-       * in Section \ref uhd_command_syntax.
-       *
-       * For a more general description of the gr-uhd components, see \ref 
page_uhd.
-       *
        * \param device_addr the address to identify the hardware
        * \param stream_args the IO format and channel specification
        * \param tsb_tag_name the name of the tag identifying tagged stream 
length
diff --git a/gr-uhd/include/gnuradio/uhd/usrp_source.h 
b/gr-uhd/include/gnuradio/uhd/usrp_source.h
index 5a9c81a..19b3feb 100644
--- a/gr-uhd/include/gnuradio/uhd/usrp_source.h
+++ b/gr-uhd/include/gnuradio/uhd/usrp_source.h
@@ -25,7 +25,7 @@
 
 #include <gnuradio/uhd/usrp_block.h>
 
-// TODO In 3.8, UHD 3.4 will be required and we can remove all these ifdefs
+// TODO In 3.8, UHD 3.6 will be required and we can remove all these ifdefs
 #ifndef INCLUDED_UHD_STREAM_HPP
 namespace uhd {
   struct GR_UHD_API stream_args_t
@@ -52,6 +52,30 @@ namespace gr {
 
     class uhd_usrp_source;
 
+    /*! USRP Source -- Radio Receiver
+     * \ingroup uhd_blk
+     *
+     * The USRP source block receives samples and writes to a stream.
+     * The source block also provides API calls for receiver settings.
+     * See also gr::uhd::usrp_block for more public API calls.
+     *
+     * RX Stream tagging:
+     *
+     * The following tag keys will be produced by the work function:
+     *  - pmt::string_to_symbol("rx_time")
+     *
+     * The timestamp tag value is a pmt tuple of the following:
+     * (uint64 seconds, and double fractional seconds).
+     * A timestamp tag is produced at start() and after overflows.
+     *
+     * \section uhd_rx_command_iface Command interface
+     *
+     * This block has a message port, which consumes UHD PMT commands.
+     * For a description of the command syntax, see Section \ref 
uhd_command_syntax.
+     *
+     * For a more general description of the gr-uhd components, see \ref 
page_uhd.
+     *
+     */
     class GR_UHD_API usrp_source : virtual public usrp_block
     {
     public:
@@ -70,27 +94,6 @@ namespace gr {
                        size_t num_channels);
 
       /*!
-       * \brief Make a new USRP source block (usually a radio receiver).
-       *
-       * The USRP source block receives samples and writes to a stream.
-       * The source block also provides API calls for receiver settings.
-       *
-       * RX Stream tagging:
-       *
-       * The following tag keys will be produced by the work function:
-       *  - pmt::string_to_symbol("rx_time")
-       *
-       * The timestamp tag value is a pmt tuple of the following:
-       * (uint64 seconds, and double fractional seconds).
-       * A timestamp tag is produced at start() and after overflows.
-       *
-       * \section uhd_rx_command_iface Command interface
-       *
-       * This block has a message port, which consumes UHD PMT commands.
-       * For a description of the command syntax, see Section \ref 
uhd_command_syntax.
-       *
-       * For a more general description of the gr-uhd components, see \ref 
page_uhd.
-       *
        * \param device_addr the address to identify the hardware
        * \param stream_args the IO format and channel specification
        * \return a new USRP source block object