diff options
| author | Martin Braun <martin.braun@ettus.com> | 2015-04-29 13:46:35 -0700 |
|---|---|---|
| committer | Martin Braun <martin.braun@ettus.com> | 2015-04-30 15:43:00 -0700 |
| commit | 0e60616cb0435c084d9ec85972e94e3141003074 (patch) | |
| tree | 201aa2bddaf28dea39e1091006e9b95dc2f4d9e9 | |
| parent | abd0b89f1cd73f93511514270a9b6a657e769fb3 (diff) | |
uhd: Updated USRP block documentation
| -rw-r--r-- | gr-uhd/doc/uhd.dox | 13 | ||||
| -rw-r--r-- | gr-uhd/include/gnuradio/uhd/usrp_block.h | 9 | ||||
| -rw-r--r-- | gr-uhd/include/gnuradio/uhd/usrp_sink.h | 123 | ||||
| -rw-r--r-- | 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 da6d9d45f5..2a2658dde6 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 656bb8ae96..5605ab82fb 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 405922b790..4ccb83f595 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 5a9c81a041..19b3feb61f 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 |