uhd: Updated docs, in particular for the command interface

author: Martin Braun <martin.braun@ettus.com> 2014-07-02 18:35:37 +0200
committer: Martin Braun <martin.braun@ettus.com> 2014-07-07 23:12:08 +0200
commit: 1eaa96b61b495dc669a69fa660a44ec86cf057cc (patch)
tree: ae5fb6197dae5e84d7a1a11b898c9ab2e66cb6aa /gr-uhd
parent: 78f56e07e24e0820a73ba2b24f4b8293bb3b3393 (diff)
3 files changed, 83 insertions, 61 deletions
diff --git a/gr-uhd/doc/uhd.dox b/gr-uhd/doc/uhd.dox
index 538c98c438..7a71b240b4 100644
--- a/gr-uhd/doc/uhd.dox
+++ b/gr-uhd/doc/uhd.dox
@@ -1,4 +1,3 @@
-// vim: set ft=doxygen:
 /*! \page page_uhd UHD Interface
 
 \section Introduction
@@ -22,15 +21,61 @@ by using:
 \endcode
 
 
-\section External Documentation
+\section uhd_external_docs External Documentation
 
-Ettus Research keeps the comprehensive documentation to the underlying UHD driver, which can be found:
+Ettus Research maintains the comprehensive documentation to the underlying UHD driver, which can be found at:
 
-    http://files.ettus.com/uhd_docs/manual/html/
+http://files.ettus.com/uhd_docs/manual/html/
 
 The UHD Doxygen page is located at:
 
-    http://files.ettus.com/uhd_docs/doxygen/html/index.html
+http://files.ettus.com/uhd_docs/doxygen/html/index.html
+
+
+\section uhd_command_syntax Command Syntax
+
+The UHD sink and source can be controlled by a message port. These message ports
+take commands, which are PMTs formatted as such:
+
+    (command, value, [channel])
+
+A command PMT is either a pair or a tuple. If it's a tuple, it must have either 2 or 3 elements.
+Any other type of PMT will throw an error.
+
+The `command` part is a string, which defines the command. `value` is a PMT whose format depends
+on the command issued. Finally, `channel` is an integer PMT value that specifies which channel
+this command shall be specified on. If this value is omitted, then it either applies this command
+to all channels or channel zero, depending on which command is used.
+
+Example:
+\code{.cpp}
+pmt::pmt_t command = pmt::cons( // We make a pair, but pmt::make_tuple() is also valid!
+    pmt::mp("freq"), // Use the 'freq' command, which sets the frequency
+    pmt::mp(1.1e9) // Set the frequency to 1.1 GHz
+);
+\endcode
+
+This PMT would set the frequency to 1.1 GHz on all channels. We make use of the pmt::mp() function
+which automatically sets the PMT types. Assume we only want to set the frequency on channel 1
+(i.e. the second channel). In this case, we must construct a tuple:
+\code{.cpp}
+pmt::pmt_t command = pmt::make_tuple(
+    pmt::mp("freq"), // Use the 'freq' command, which sets the frequency
+    pmt::mp(1.1e9) // Set the frequency to 1.1 GHz
+    pmt::mp(1) // Select channel 1
+);
+\endcode
+
+
+\subsection uhd_command_syntax_cmds Common commands
+
+The following commands are understood by both UHD Source and Sink:
+
+Command name | Value Type | Description
+-------------|------------|-------------------------------------------------------------
+`freq`       | double     | Sets the Tx or Rx frequency. Defaults to all channels.
+`lo_offset`  | double     | Sets an LO offset. Defaults to all channels.
+`gain`       | double     | Sets the Tx or Rx gain (in dB). Defaults to all channels.
 
 
 \section Configuring a UHD object
@@ -100,3 +145,4 @@ resampler to take care of the difference.
 \endcode
 
 */
+// vim: set ft=doxygen:
diff --git a/gr-uhd/include/gnuradio/uhd/usrp_sink.h b/gr-uhd/include/gnuradio/uhd/usrp_sink.h
index 35bb2e4384..2afe634865 100644
--- a/gr-uhd/include/gnuradio/uhd/usrp_sink.h
+++ b/gr-uhd/include/gnuradio/uhd/usrp_sink.h
@@ -62,18 +62,17 @@ namespace gr {
 
       /*!
        * \brief DEPRECATED Make a new USRP sink block using the deprecated io_type_t.
+       * \ingroup uhd_blk
        *
        * This function will be removed in the future. Please use the other make function,
-       * gr::uhd::make(const ::uhd::device_addr_t, const ::uhd::stream_args_t, const std::string).
-       *
-       * \ingroup uhd_blk
+       * 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);
 
       /*!
-       * \brief Make a new USRP sink block.
+       * \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.
@@ -86,60 +85,55 @@ namespace gr {
        *  - pmt::string_to_symbol("tx_time")
        *  - pmt::string_to_symbol("tx_freq")
        *  - pmt::string_to_symbol("tx_command")
-       *  - pmt::string_to_symbol(length_tag_name)
+       *  - 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 length_tag_name is not an empty string, all "tx_sob" and "tx_eob"
+       * 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.
-       * The length tag value should be a PMT long specifying the number
-       * of samples contained in the corresponding 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 etc.
+       * no underruns after transmitting the final sample of a burst.
        *
        * The timestamp tag value is a PMT tuple of the following:
-       * (uint64 seconds, and double fractional seconds).
+       * (uint64 seconds, double fractional seconds).
        *
-       * The tx_freq tag has to be a double, and will issue a tune command to the USRP
+       * 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_commands Command interface
+       * \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
+       * 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,
+       * 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 pair, with the first
-       * item ('car') being the command name, and second ('cdr') the command value.
-       *
-       * Command name | Command value
-       * -------------|--------------------------------------------------------------------------
-       * `freq`       | Tuple: (chan, new_freq). Requests a tune to `new_freq` on channel `chan`.
-       * `lo_offset`  | Tuple: (chan, lo_offset). Adds a LO offset on channel `chan`.
-       * `gain`       | Tuple: (chan, gain). Requests a gain change to `gain` on channel `chan`.
+       * In both cases, the payload of the command is a PMT command, as described
+       * in Section \ref uhd_command_syntax.
        *
-       * See the UHD manual for more detailed documentation:
-       * http://code.ettus.com/redmine/ettus/projects/uhd/wiki
+       * 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 length_tag_name the name of the tag identifying tagged stream length
+       * \param tsb_tag_name the name of the tag identifying tagged stream length
        * \return a new USRP sink block object
        */
       static sptr make(const ::uhd::device_addr_t &device_addr,
                        const ::uhd::stream_args_t &stream_args,
-                       const std::string &length_tag_name = "");
+                       const std::string &tsb_tag_name = "");
 
       /*!
        * Set the start time for outgoing samples.
diff --git a/gr-uhd/include/gnuradio/uhd/usrp_source.h b/gr-uhd/include/gnuradio/uhd/usrp_source.h
index f330ee0901..699d028969 100644
--- a/gr-uhd/include/gnuradio/uhd/usrp_source.h
+++ b/gr-uhd/include/gnuradio/uhd/usrp_source.h
@@ -27,6 +27,7 @@
 #include <gnuradio/sync_block.h>
 #include <uhd/usrp/multi_usrp.hpp>
 
+// TODO In 3.8, UHD 3.4 will be required and we can remove all these ifdefs
 #ifndef INCLUDED_UHD_STREAM_HPP
 namespace uhd {
   struct GR_UHD_API stream_args_t
@@ -60,41 +61,18 @@ namespace gr {
       typedef boost::shared_ptr<usrp_source> sptr;
 
       /*!
-       * \brief Make a new USRP source block.
+       * \brief DEPRECATED Make a new USRP source block using the deprecated io_type_t.
        * \ingroup uhd_blk
        *
-       * 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")
-       *  - pmt::string_to_symbol("rx_rate")
-       *  - pmt::string_to_symbol("rx_freq")
-       *
-       * The timstamp 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.
-       *
-       * The sample rate and center frequency tags are doubles,
-       * representing the sample rate in Sps and frequency in Hz.
-       * These tags are produced upon the user changing parameters.
-       *
-       * See the UHD manual for more detailed documentation:
-       * http://code.ettus.com/redmine/ettus/projects/uhd/wiki
-       *
-       * \param device_addr the address to identify the hardware
-       * \param io_type the desired output data type
-       * \param num_channels number of stream from the device
-       * \return a new USRP source block object
+       * This function will be removed in the future. Please use the other make function,
+       * gr::uhd::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);
 
       /*!
-       * \brief Make a new USRP source block.
+       * \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.
@@ -104,12 +82,16 @@ namespace gr {
        * The following tag keys will be produced by the work function:
        *  - pmt::string_to_symbol("rx_time")
        *
-       * The timstamp tag value is a pmt tuple of the following:
+       * 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.
        *
-       * See the UHD manual for more detailed documentation:
-       * http://code.ettus.com/redmine/ettus/projects/uhd/wiki
+       * \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
author	Martin Braun <martin.braun@ettus.com>	2014-07-02 18:35:37 +0200
committer	Martin Braun <martin.braun@ettus.com>	2014-07-07 23:12:08 +0200
commit	1eaa96b61b495dc669a69fa660a44ec86cf057cc (patch)
tree	ae5fb6197dae5e84d7a1a11b898c9ab2e66cb6aa /gr-uhd
parent	78f56e07e24e0820a73ba2b24f4b8293bb3b3393 (diff)