GNU Radio Manual and C++ API Reference  3.7.9.2
The Free & Open Software Radio Ecosystem
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
usrp_sink.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2010-2015 Free Software Foundation, Inc.
4  *
5  * This file is part of GNU Radio
6  *
7  * GNU Radio is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation; either version 3, or (at your option)
10  * any later version.
11  *
12  * GNU Radio is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with GNU Radio; see the file COPYING. If not, write to
19  * the Free Software Foundation, Inc., 51 Franklin Street,
20  * Boston, MA 02110-1301, USA.
21  */
22 
23 #ifndef INCLUDED_GR_UHD_USRP_SINK_H
24 #define INCLUDED_GR_UHD_USRP_SINK_H
25 
27 
28 // TODO In 3.8, UHD 3.4 will be required and we can remove all these ifdefs
29 #ifndef INCLUDED_UHD_STREAM_HPP
30 namespace uhd {
32  {
33  stream_args_t(const std::string &cpu = "",
34  const std::string &otw = "")
35  {
36  cpu_format = cpu;
37  otw_format = otw;
38  }
39  std::string cpu_format;
40  std::string otw_format;
41  device_addr_t args;
42  std::vector<size_t> channels;
43  };
44 }
45 # define INCLUDED_UHD_STREAM_HPP
46 #else
47 # define GR_UHD_USE_STREAM_API
48 #endif
49 
50 namespace gr {
51  namespace uhd {
52 
53  class uhd_usrp_sink;
54 
55  /*! USRP Sink -- Radio Transmitter
56  * \ingroup uhd_blk
57  *
58  *
59  * The USRP sink block reads a stream and transmits the samples.
60  * The sink block also provides API calls for transmitter settings.
61  * See also gr::uhd::usrp_block for more public API calls.
62  *
63  * \section uhd_tx_tagging TX Stream tagging
64  *
65  * The following tag keys will be consumed by the work function:
66  * - pmt::string_to_symbol("tx_sob")
67  * - pmt::string_to_symbol("tx_eob")
68  * - pmt::string_to_symbol("tx_time")
69  * - pmt::string_to_symbol("tx_freq")
70  * - pmt::string_to_symbol("tx_command")
71  * - pmt::string_to_symbol(tsb_tag_name)
72  *
73  * Any other tag will be ignored.
74  *
75  * \section uhd_tx_burstys Bursty Transmission
76  *
77  * There are multiple ways to do bursty transmission without triggering
78  * underruns:
79  * - Using SOB/EOB tags
80  * - Using tagged streams (See \ref page_tagged_stream_blocks)
81  *
82  * The sob and eob (start and end of burst) tag values are pmt booleans.
83  * When present, burst tags should be set to true (pmt::PMT_T).
84  *
85  * If `tsb_tag_name` is not an empty string, all "tx_sob" and "tx_eob"
86  * tags will be ignored, and the input is assumed to a tagged stream.
87  *
88  * If sob/eob tags or length tags are used, this block understands that
89  * the data is bursty, and will configure the USRP to make sure there's
90  * no underruns after transmitting the final sample of a burst.
91  *
92  * \section uhd_tx_time Timestamps
93  *
94  * The timestamp tag value is a PMT tuple of the following:
95  * (uint64 seconds, double fractional seconds).
96  *
97  * The tx_freq tag has to be a double or a pair of form (channel, frequency),
98  * with frequency being a double and channel being an integer.
99  * This tag will trigger a tune command to the USRP
100  * to the given frequency, if possible. Note that oscillators need some time
101  * to stabilize after this! Don't expect clean data to be sent immediately after this command.
102  * If channel is omitted, and only a double is given, it will set this frequency to all
103  * channels.
104  *
105  * The command tag can carry a PMT command. See the following section.
106  *
107  * \section uhd_tx_commands Command interface
108  *
109  * There are two ways of passing commands to this block:
110  * 1. tx_command tag. The command is attached to a sample, and will executed
111  * before the sample is transmitted, and after the previous sample.
112  * 2. The 'command' message port. The command is executed asynchronously,
113  * as soon as possible.
114  *
115  * In both cases, the payload of the command is a PMT command, as described
116  * in Section \ref uhd_command_syntax.
117  *
118  * For a more general description of the gr-uhd components, see \ref page_uhd.
119  */
120  class GR_UHD_API usrp_sink : virtual public usrp_block
121  {
122  public:
123  // gr::uhd::usrp_sink::sptr
124  typedef boost::shared_ptr<usrp_sink> sptr;
125 
126  /*!
127  * \brief DEPRECATED Make a new USRP sink block using the deprecated io_type_t.
128  * \ingroup uhd_blk
129  *
130  * This function will be removed in the future. Please use the other make function,
131  * gr::uhd::usrp_sink::make(const ::uhd::device_addr_t, const ::uhd::stream_args_t, const std::string).
132  */
133  static sptr make(const ::uhd::device_addr_t &device_addr,
134  const ::uhd::io_type_t &io_type,
135  size_t num_channels);
136 
137  /*!
138  * \param device_addr the address to identify the hardware
139  * \param stream_args the IO format and channel specification
140  * \param tsb_tag_name the name of the tag identifying tagged stream length
141  * \return a new USRP sink block object
142  */
143  static sptr make(const ::uhd::device_addr_t &device_addr,
144  const ::uhd::stream_args_t &stream_args,
145  const std::string &tsb_tag_name = "");
146 
147  /*!
148  * Set the start time for outgoing samples.
149  * To control when samples are transmitted,
150  * set this value before starting the flow graph.
151  * The value is cleared after each run.
152  * When not specified, the start time will be:
153  * - Immediately for the one channel case
154  * - in the near future for multi-channel
155  *
156  * \param time the absolute time for transmission to begin
157  */
158  virtual void set_start_time(const ::uhd::time_spec_t &time) = 0;
159 
160  /*!
161  * Returns identifying information about this USRP's configuration.
162  * Returns motherboard ID, name, and serial.
163  * Returns daughterboard TX ID, subdev name and spec, serial, and antenna.
164  * \param chan channel index 0 to N-1
165  * \return TX info
166  */
167  virtual ::uhd::dict<std::string, std::string> get_usrp_info(size_t chan = 0) = 0;
168 
169  /*!
170  * Set a constant DC offset value.
171  * The value is complex to control both I and Q.
172  * \param offset the dc offset (1.0 is full-scale)
173  * \param chan the channel index 0 to N-1
174  */
175  virtual void set_dc_offset(const std::complex<double> &offset,
176  size_t chan = 0) = 0;
177 
178  /*!
179  * Set the RX frontend IQ imbalance correction.
180  * Use this to adjust the magnitude and phase of I and Q.
181  *
182  * \param correction the complex correction (1.0 is full-scale)
183  * \param chan the channel index 0 to N-1
184  */
185  virtual void set_iq_balance(const std::complex<double> &correction,
186  size_t chan = 0) = 0;
187 
188  };
189 
190  } /* namespace uhd */
191 } /* namespace gr */
192 
193 #endif /* INCLUDED_GR_UHD_USRP_SINK_H */
Definition: usrp_block.h:41
Definition: usrp_sink.h:120
std::string otw_format
Definition: usrp_sink.h:40
Definition: usrp_sink.h:30
std::string cpu_format
Definition: usrp_sink.h:39
boost::shared_ptr< usrp_sink > sptr
Definition: usrp_sink.h:124
Include this header to use the message passing features.
Definition: logger.h:131
stream_args_t(const std::string &cpu="", const std::string &otw="")
Definition: usrp_sink.h:33
device_addr_t args
Definition: usrp_sink.h:41
Definition: usrp_sink.h:31
#define GR_UHD_API
Definition: gr-uhd/include/gnuradio/uhd/api.h:30
std::vector< size_t > channels
Definition: usrp_sink.h:42