GNU Radio Manual and C++ API Reference 3.7.14.0
The Free & Open Software Radio Ecosystem
usrp_source.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_SOURCE_H
24#define INCLUDED_GR_UHD_USRP_SOURCE_H
25
27
28// TODO In 3.8, UHD 3.6 will be required and we can remove all these ifdefs
29#ifndef INCLUDED_UHD_STREAM_HPP
30namespace uhd {
31struct GR_UHD_API stream_args_t {
32 stream_args_t(const std::string& cpu = "", const std::string& otw = "")
33 {
34 cpu_format = cpu;
35 otw_format = otw;
36 }
37 std::string cpu_format;
38 std::string otw_format;
39 device_addr_t args;
40 std::vector<size_t> channels;
41};
42} // namespace uhd
43#define INCLUDED_UHD_STREAM_HPP
44#else
45#define GR_UHD_USE_STREAM_API
46#endif
47
48namespace gr {
49namespace uhd {
50
51class uhd_usrp_source;
52
53/*! USRP Source -- Radio Receiver
54 * \ingroup uhd_blk
55 *
56 * The USRP source block receives samples and writes to a stream.
57 * The source block also provides API calls for receiver settings.
58 * See also gr::uhd::usrp_block for more public API calls.
59 *
60 * RX Stream tagging:
61 *
62 * The following tag keys will be produced by the work function:
63 * - pmt::string_to_symbol("rx_time")
64 *
65 * The timestamp tag value is a pmt tuple of the following:
66 * (uint64 seconds, and double fractional seconds).
67 * A timestamp tag is produced at start() and after overflows.
68 *
69 * \section uhd_rx_command_iface Command interface
70 *
71 * This block has a message port, which consumes UHD PMT commands.
72 * For a description of the command syntax, see Section \ref uhd_command_syntax.
73 *
74 * For a more general description of the gr-uhd components, see \ref page_uhd.
75 *
76 */
77class GR_UHD_API usrp_source : virtual public usrp_block
78{
79public:
80 // gr::uhd::usrp_source::sptr
81 typedef boost::shared_ptr<usrp_source> sptr;
82
83 /*!
84 * \brief DEPRECATED Make a new USRP source block using the deprecated io_type_t.
85 * \ingroup uhd_blk
86 *
87 * This function will be removed in the future. Please use the other make function,
88 * gr::uhd::make(const ::uhd::device_addr_t, const ::uhd::stream_args_t, const
89 * std::string).
90 */
91 static sptr make(const ::uhd::device_addr_t& device_addr,
92 const ::uhd::io_type_t& io_type,
93 size_t num_channels);
94
95 /*!
96 * \param device_addr the address to identify the hardware
97 * \param stream_args the IO format and channel specification
98 * \param issue_stream_cmd_on_start enable or disable continuous streaming when
99 * flowgraph starts (default true) \return a new USRP source block object
100 */
101 static sptr make(const ::uhd::device_addr_t& device_addr,
102 const ::uhd::stream_args_t& stream_args,
103 const bool issue_stream_cmd_on_start = true);
104
105 /*!
106 * Set the start time for incoming samples.
107 * To control when samples are received,
108 * set this value before starting the flow graph.
109 * The value is cleared after each run.
110 * When not specified, the start time will be:
111 * - Immediately for the one channel case
112 * - in the near future for multi-channel
113 *
114 * \param time the absolute time for reception to begin
115 */
116 virtual void set_start_time(const ::uhd::time_spec_t& time) = 0;
117
118 /*!
119 * *Advanced use only:*
120 * Issue a stream command to all channels in this source block.
121 *
122 * This method is intended to override the default "always on"
123 * behavior. After starting the flow graph, the user should
124 * call stop() on this block, then issue any desired arbitrary
125 * stream_cmd_t structs to the device. The USRP will be able to
126 * enqueue several stream commands in the FPGA.
127 *
128 * \param cmd the stream command to issue to all source channels
129 */
130 virtual void issue_stream_cmd(const ::uhd::stream_cmd_t& cmd) = 0;
131
132 /*! Configure the timeout value on the UHD recv() call
133 *
134 * This is an advanced use parameter. Changing the timeout value affects
135 * the latency of this block; a high timeout value can be more optimal
136 * for high-throughput applications (e.g., 1 second) and setting it to
137 * zero will have the best latency. Changing the timeout value may also
138 * be useful for custom FPGA modifications, where traffic might not be
139 * continuously streaming.
140 * For specialized high-performance use cases, twiddling these knobs may
141 * improve performance, but changes are not generally applicable.
142 *
143 * Note that UHD's recv() call may block until the timeout is over, which
144 * means this block might also block for up to the timeout value.
145 *
146 * \param timeout Timeout parameter in seconds. Cf. the UHD manual for
147 * uhd::rx_streamer::recv() for more details. A lower
148 * value will mean lower latency, but higher CPU load.
149 * \param one_packet If true, only receive one packet at a time. Cf. the
150 * UHD manual for uhd::rx_streamer::recv() for more
151 * details. A value of true will mean lower latency,
152 * but higher CPU load.
153 */
154 virtual void set_recv_timeout(const double timeout, const bool one_packet = true) = 0;
155
156 /*!
157 * Returns identifying information about this USRP's configuration.
158 * Returns motherboard ID, name, and serial.
159 * Returns daughterboard RX ID, subdev name and spec, serial, and antenna.
160 * \param chan channel index 0 to N-1
161 * \return RX info
162 */
163 virtual ::uhd::dict<std::string, std::string> get_usrp_info(size_t chan = 0) = 0;
164
165
166 /*!
167 * Get a list of possible LO stage names
168 * \param chan the channel index 0 to N-1
169 * \return a vector of strings for possible LO names
170 */
171 virtual std::vector<std::string> get_lo_names(size_t chan = 0) = 0;
172
173 /*!
174 * Set the LO source for the usrp device.
175 * For usrps that support selectable LOs, this function
176 * allows switching between them.
177 * Typical options for source: internal, external.
178 * \param src a string representing the LO source
179 * \param name the name of the LO stage to update
180 * \param chan the channel index 0 to N-1
181 */
182 virtual void
183 set_lo_source(const std::string& src, const std::string& name, size_t chan = 0) = 0;
184
185 /*!
186 * Get the currently set LO source.
187 * \param name the name of the LO stage to query
188 * \param chan the channel index 0 to N-1
189 * \return the configured LO source
190 */
191 virtual const std::string get_lo_source(const std::string& name, size_t chan = 0) = 0;
192
193 /*!
194 * Get a list of possible LO sources.
195 * \param name the name of the LO stage to query
196 * \param chan the channel index 0 to N-1
197 * \return a vector of strings for possible settings
198 */
199 virtual std::vector<std::string> get_lo_sources(const std::string& name,
200 size_t chan = 0) = 0;
201
202 /*!
203 * Set whether the LO used by the usrp device is exported
204 * For usrps that support exportable LOs, this function
205 * configures if the LO used by chan is exported or not.
206 * \param enabled if true then export the LO
207 * \param name the name of the LO stage to update
208 * \param chan the channel index 0 to N-1 for the source channel
209 */
210 virtual void
211 set_lo_export_enabled(bool enabled, const std::string& name, size_t chan = 0) = 0;
212
213 /*!
214 * Returns true if the currently selected LO is being exported.
215 * \param name the name of the LO stage to query
216 * \param chan the channel index 0 to N-1
217 */
218 virtual bool get_lo_export_enabled(const std::string& name, size_t chan = 0) = 0;
219
220 /*!
221 * Set the RX LO frequency (Advanced).
222 * \param freq the frequency to set the LO to
223 * \param name the name of the LO stage to update
224 * \param chan the channel index 0 to N-1
225 * \return a coerced LO frequency
226 */
227 virtual double set_lo_freq(double freq, const std::string& name, size_t chan = 0) = 0;
228
229 /*!
230 * Get the current RX LO frequency (Advanced).
231 * \param name the name of the LO stage to query
232 * \param chan the channel index 0 to N-1
233 * \return the configured LO frequency
234 */
235 virtual double get_lo_freq(const std::string& name, size_t chan = 0) = 0;
236
237 /*!
238 * Get the LO frequency range of the RX LO.
239 * \param name the name of the LO stage to query
240 * \param chan the channel index 0 to N-1
241 * \return a frequency range object
242 */
243 virtual ::uhd::freq_range_t get_lo_freq_range(const std::string& name,
244 size_t chan = 0) = 0;
245
246 /*!
247 * Enable/disable the automatic DC offset correction.
248 * The automatic correction subtracts out the long-run average.
249 *
250 * When disabled, the averaging option operation is halted.
251 * Once halted, the average value will be held constant until
252 * the user re-enables the automatic correction or overrides the
253 * value by manually setting the offset.
254 *
255 * \param enb true to enable automatic DC offset correction
256 * \param chan the channel index 0 to N-1
257 */
258 virtual void set_auto_dc_offset(const bool enb, size_t chan = 0) = 0;
259
260 /*!
261 * Set a constant DC offset value.
262 * The value is complex to control both I and Q.
263 * Only set this when automatic correction is disabled.
264 * \param offset the dc offset (1.0 is full-scale)
265 * \param chan the channel index 0 to N-1
266 */
267 virtual void set_dc_offset(const std::complex<double>& offset, size_t chan = 0) = 0;
268
269 /*!
270 * Enable/Disable the RX frontend IQ imbalance correction.
271 *
272 * \param enb true to enable automatic IQ imbalance correction
273 * \param chan the channel index 0 to N-1
274 */
275 virtual void set_auto_iq_balance(const bool enb, size_t chan = 0) = 0;
276
277 /*!
278 * Set the RX frontend IQ imbalance correction.
279 * Use this to adjust the magnitude and phase of I and Q.
280 *
281 * \param correction the complex correction value
282 * \param chan the channel index 0 to N-1
283 */
284 virtual void set_iq_balance(const std::complex<double>& correction,
285 size_t chan = 0) = 0;
286
287 /*!
288 * Convenience function for finite data acquisition.
289 * This is not to be used with the scheduler; rather,
290 * one can request samples from the USRP in python.
291 * //TODO assumes fc32
292 * \param nsamps the number of samples
293 * \return a vector of complex float samples
294 */
295 virtual std::vector<std::complex<float> > finite_acquisition(const size_t nsamps) = 0;
296
297 /*!
298 * Convenience function for finite data acquisition. This is the
299 * multi-channel version of finite_acquisition; This is not to
300 * be used with the scheduler; rather, one can request samples
301 * from the USRP in python.
302 * //TODO assumes fc32
303 * \param nsamps the number of samples per channel
304 * \return a vector of buffers, where each buffer represents a channel
305 */
306 virtual std::vector<std::vector<std::complex<float> > >
307 finite_acquisition_v(const size_t nsamps) = 0;
308};
309
310} /* namespace uhd */
311} /* namespace gr */
312
313#endif /* INCLUDED_GR_UHD_USRP_SOURCE_H */
Definition: usrp_block.h:65
Definition: usrp_source.h:78
virtual void set_auto_iq_balance(const bool enb, size_t chan=0)=0
static sptr make(const ::uhd::device_addr_t &device_addr, const ::uhd::stream_args_t &stream_args, const bool issue_stream_cmd_on_start=true)
virtual ::uhd::freq_range_t get_lo_freq_range(const std::string &name, size_t chan=0)=0
virtual ::uhd::dict< std::string, std::string > get_usrp_info(size_t chan=0)=0
virtual std::vector< std::string > get_lo_names(size_t chan=0)=0
virtual void set_lo_export_enabled(bool enabled, const std::string &name, size_t chan=0)=0
virtual void issue_stream_cmd(const ::uhd::stream_cmd_t &cmd)=0
virtual const std::string get_lo_source(const std::string &name, size_t chan=0)=0
virtual void set_recv_timeout(const double timeout, const bool one_packet=true)=0
virtual bool get_lo_export_enabled(const std::string &name, size_t chan=0)=0
virtual std::vector< std::complex< float > > finite_acquisition(const size_t nsamps)=0
virtual void set_start_time(const ::uhd::time_spec_t &time)=0
virtual double set_lo_freq(double freq, const std::string &name, size_t chan=0)=0
virtual std::vector< std::string > get_lo_sources(const std::string &name, size_t chan=0)=0
virtual std::vector< std::vector< std::complex< float > > > finite_acquisition_v(const size_t nsamps)=0
virtual void set_iq_balance(const std::complex< double > &correction, size_t chan=0)=0
virtual double get_lo_freq(const std::string &name, size_t chan=0)=0
virtual void set_auto_dc_offset(const bool enb, size_t chan=0)=0
boost::shared_ptr< usrp_source > sptr
Definition: usrp_source.h:81
virtual void set_lo_source(const std::string &src, const std::string &name, size_t chan=0)=0
virtual void set_dc_offset(const std::complex< double > &offset, size_t chan=0)=0
#define GR_UHD_API
Definition: gr-uhd/include/gnuradio/uhd/api.h:30
static sptr make(const ::uhd::device_addr_t &device_addr, const ::uhd::io_type_t &io_type, size_t num_channels)
DEPRECATED Make a new USRP source block using the deprecated io_type_t.
Include this header to use the message passing features.
Definition: basic_block.h:45
Definition: usrp_sink.h:30
stream_args_t(const std::string &cpu="", const std::string &otw="")
Definition: usrp_source.h:32