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