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