GNU Radio Manual and C++ API Reference  3.7.7
The Free & Open Software Radio Ecosystem
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
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 
26 #include <gnuradio/uhd/api.h>
27 #include <gnuradio/sync_block.h>
28 #include <uhd/usrp/multi_usrp.hpp>
29 
30 // TODO In 3.8, UHD 3.4 will be required and we can remove all these ifdefs
31 #ifndef INCLUDED_UHD_STREAM_HPP
32 namespace uhd {
33  struct GR_UHD_API stream_args_t
34  {
35  stream_args_t(const std::string &cpu = "",
36  const std::string &otw = "")
37  {
38  cpu_format = cpu;
39  otw_format = otw;
40  }
41  std::string cpu_format;
42  std::string otw_format;
43  device_addr_t args;
44  std::vector<size_t> channels;
45  };
46 }
47 # define INCLUDED_UHD_STREAM_HPP
48 #else
49 # define GR_UHD_USE_STREAM_API
50 #endif
51 
52 namespace gr {
53  namespace uhd {
54 
55  class uhd_usrp_source;
56 
57  class GR_UHD_API usrp_source : virtual public sync_block
58  {
59  public:
60  // gr::uhd::usrp_source::sptr
62 
63  /*!
64  * \brief DEPRECATED Make a new USRP source block using the deprecated io_type_t.
65  * \ingroup uhd_blk
66  *
67  * This function will be removed in the future. Please use the other make function,
68  * gr::uhd::make(const ::uhd::device_addr_t, const ::uhd::stream_args_t, const std::string).
69  */
70  static sptr make(const ::uhd::device_addr_t &device_addr,
71  const ::uhd::io_type_t &io_type,
72  size_t num_channels);
73 
74  /*!
75  * \brief Make a new USRP source block (usually a radio receiver).
76  *
77  * The USRP source block receives samples and writes to a stream.
78  * The source block also provides API calls for receiver settings.
79  *
80  * RX Stream tagging:
81  *
82  * The following tag keys will be produced by the work function:
83  * - pmt::string_to_symbol("rx_time")
84  *
85  * The timestamp tag value is a pmt tuple of the following:
86  * (uint64 seconds, and double fractional seconds).
87  * A timestamp tag is produced at start() and after overflows.
88  *
89  * \section uhd_rx_command_iface Command interface
90  *
91  * This block has a message port, which consumes UHD PMT commands.
92  * For a description of the command syntax, see Section \ref uhd_command_syntax.
93  *
94  * For a more general description of the gr-uhd components, see \ref page_uhd.
95  *
96  * \param device_addr the address to identify the hardware
97  * \param stream_args the IO format and channel specification
98  * \return a new USRP source block object
99  */
100  static sptr make(const ::uhd::device_addr_t &device_addr,
101  const ::uhd::stream_args_t &stream_args);
102 
103  /*!
104  * Set the start time for incoming samples.
105  * To control when samples are received,
106  * set this value before starting the flow graph.
107  * The value is cleared after each run.
108  * When not specified, the start time will be:
109  * - Immediately for the one channel case
110  * - in the near future for multi-channel
111  *
112  * \param time the absolute time for reception to begin
113  */
114  virtual void set_start_time(const ::uhd::time_spec_t &time) = 0;
115 
116  /*!
117  * *Advanced use only:*
118  * Issue a stream command to all channels in this source block.
119  *
120  * This method is intended to override the default "always on"
121  * behavior. After starting the flow graph, the user should
122  * call stop() on this block, then issue any desired arbitrary
123  * stream_cmd_t structs to the device. The USRP will be able to
124  * enqueue several stream commands in the FPGA.
125  *
126  * \param cmd the stream command to issue to all source channels
127  */
128  virtual void issue_stream_cmd(const ::uhd::stream_cmd_t &cmd) = 0;
129 
130  /*!
131  * Returns identifying information about this USRP's configuration.
132  * Returns motherboard ID, name, and serial.
133  * Returns daughterboard RX ID, subdev name and spec, serial, and antenna.
134  * \param chan channel index 0 to N-1
135  * \return RX info
136  */
137  virtual ::uhd::dict<std::string, std::string> get_usrp_info(size_t chan = 0) = 0;
138 
139  /*!
140  * Set the frontend specification.
141  * \param spec the subdev spec markup string
142  * \param mboard the motherboard index 0 to M-1
143  */
144  virtual void set_subdev_spec(const std::string &spec, size_t mboard = 0) = 0;
145 
146  /*!
147  * Get the RX frontend specification.
148  * \param mboard the motherboard index 0 to M-1
149  * \return the frontend specification in use
150  */
151  virtual std::string get_subdev_spec(size_t mboard = 0) = 0;
152 
153  /*!
154  * Set the sample rate for the usrp device.
155  * \param rate a new rate in Sps
156  */
157  virtual void set_samp_rate(double rate) = 0;
158 
159  /*!
160  * Get the sample rate for the usrp device.
161  * This is the actual sample rate and may differ from the rate set.
162  * \return the actual rate in Sps
163  */
164  virtual double get_samp_rate(void) = 0;
165 
166  /*!
167  * Get the possible sample rates for the usrp device.
168  * \return a range of rates in Sps
169  */
170  virtual ::uhd::meta_range_t get_samp_rates(void) = 0;
171 
172  /*!
173  * Tune the usrp device to the desired center frequency.
174  * \param tune_request the tune request instructions
175  * \param chan the channel index 0 to N-1
176  * \return a tune result with the actual frequencies
177  */
178  virtual ::uhd::tune_result_t set_center_freq
179  (const ::uhd::tune_request_t tune_request, size_t chan = 0) = 0;
180 
181  /*!
182  * Tune the usrp device to the desired center frequency.
183  * This is a wrapper around set center freq so that in this case,
184  * the user can pass a single frequency in the call through swig.
185  * \param freq the desired frequency in Hz
186  * \param chan the channel index 0 to N-1
187  * \return a tune result with the actual frequencies
188  */
189  ::uhd::tune_result_t set_center_freq(double freq, size_t chan = 0)
190  {
191  return set_center_freq(::uhd::tune_request_t(freq), chan);
192  }
193 
194  /*!
195  * Get the center frequency.
196  * \param chan the channel index 0 to N-1
197  * \return the frequency in Hz
198  */
199  virtual double get_center_freq(size_t chan = 0) = 0;
200 
201  /*!
202  * Get the tunable frequency range.
203  * \param chan the channel index 0 to N-1
204  * \return the frequency range in Hz
205  */
206  virtual ::uhd::freq_range_t get_freq_range(size_t chan = 0) = 0;
207 
208  /*!
209  * Set the gain for the dboard.
210  * \param gain the gain in dB
211  * \param chan the channel index 0 to N-1
212  */
213  virtual void set_gain(double gain, size_t chan = 0) = 0;
214 
215  /*!
216  * Set the named gain on the dboard.
217  * \param gain the gain in dB
218  * \param name the name of the gain stage
219  * \param chan the channel index 0 to N-1
220  */
221  virtual void set_gain(double gain,
222  const std::string &name,
223  size_t chan = 0) = 0;
224 
225  /*!
226  * Set the normalized gain.
227  *
228  * The normalized gain is always in [0, 1], regardless of the device.
229  * 0 corresponds to minimum gain (usually 0 dB, but make sure to read the device
230  * notes in the UHD manual) and 1 corresponds to maximum gain.
231  * This will work for any UHD device. Use get_gain() to see which dB value
232  * the normalized gain value corresponds to.
233  *
234  * Note that it is not possible to specify a gain name for this function.
235  *
236  * \throws A runtime_error if \p norm_gain is not within the valid range.
237  *
238  * \param norm_gain the gain in fractions of the gain range (must be 0 <= norm_gain <= 1)
239  * \param chan the channel index 0 to N-1
240  */
241  virtual void set_normalized_gain(double norm_gain, size_t chan = 0) = 0;
242 
243  /*!
244  * Get the actual dboard gain setting.
245  * \param chan the channel index 0 to N-1
246  * \return the actual gain in dB
247  */
248  virtual double get_gain(size_t chan = 0) = 0;
249 
250  /*!
251  * Get the actual dboard gain setting of named stage.
252  * \param name the name of the gain stage
253  * \param chan the channel index 0 to N-1
254  * \return the actual gain in dB
255  */
256  virtual double get_gain(const std::string &name,
257  size_t chan = 0) = 0;
258 
259  /*!
260  * Returns the normalized gain.
261  *
262  * The normalized gain is always in [0, 1], regardless of the device.
263  * See also set_normalized_gain().
264  *
265  * Note that it is not possible to specify a gain name for this function,
266  * the result is over the entire gain chain.
267  *
268  * \param chan the channel index 0 to N-1
269  */
270  virtual double get_normalized_gain(size_t chan = 0) = 0;
271 
272  /*!
273  * Get the actual dboard gain setting of named stage.
274  * \param chan the channel index 0 to N-1
275  * \return the actual gain in dB
276  */
277  virtual std::vector<std::string> get_gain_names(size_t chan = 0) = 0;
278 
279  /*!
280  * Get the settable gain range.
281  * \param chan the channel index 0 to N-1
282  * \return the gain range in dB
283  */
284  virtual ::uhd::gain_range_t get_gain_range(size_t chan = 0) = 0;
285 
286  /*!
287  * Get the settable gain range.
288  * \param name the name of the gain stage
289  * \param chan the channel index 0 to N-1
290  * \return the gain range in dB
291  */
292  virtual ::uhd::gain_range_t get_gain_range(const std::string &name,
293  size_t chan = 0) = 0;
294 
295  /*!
296  * Set the antenna to use.
297  * \param ant the antenna string
298  * \param chan the channel index 0 to N-1
299  */
300  virtual void set_antenna(const std::string &ant,
301  size_t chan = 0) = 0;
302 
303  /*!
304  * Get the antenna in use.
305  * \param chan the channel index 0 to N-1
306  * \return the antenna string
307  */
308  virtual std::string get_antenna(size_t chan = 0) = 0;
309 
310  /*!
311  * Get a list of possible antennas.
312  * \param chan the channel index 0 to N-1
313  * \return a vector of antenna strings
314  */
315  virtual std::vector<std::string> get_antennas(size_t chan = 0) = 0;
316 
317  /*!
318  * Set the bandpass filter on the RF frontend.
319  * \param bandwidth the filter bandwidth in Hz
320  * \param chan the channel index 0 to N-1
321  */
322  virtual void set_bandwidth(double bandwidth, size_t chan = 0) = 0;
323 
324  /*!
325  * Get the bandpass filter setting on the RF frontend.
326  * \param chan the channel index 0 to N-1
327  * \return bandwidth of the filter in Hz
328  */
329  virtual double get_bandwidth(size_t chan = 0) = 0;
330 
331  /*!
332  * Get the bandpass filter range of the RF frontend.
333  * \param chan the channel index 0 to N-1
334  * \return the range of the filter bandwidth in Hz
335  */
336  virtual ::uhd::freq_range_t get_bandwidth_range(size_t chan = 0) = 0;
337 
338  /*!
339  * Enable/disable the automatic DC offset correction.
340  * The automatic correction subtracts out the long-run average.
341  *
342  * When disabled, the averaging option operation is halted.
343  * Once halted, the average value will be held constant until
344  * the user re-enables the automatic correction or overrides the
345  * value by manually setting the offset.
346  *
347  * \param enb true to enable automatic DC offset correction
348  * \param chan the channel index 0 to N-1
349  */
350  virtual void set_auto_dc_offset(const bool enb, size_t chan = 0) = 0;
351 
352  /*!
353  * Set a constant DC offset value.
354  * The value is complex to control both I and Q.
355  * Only set this when automatic correction is disabled.
356  * \param offset the dc offset (1.0 is full-scale)
357  * \param chan the channel index 0 to N-1
358  */
359  virtual void set_dc_offset(const std::complex<double> &offset, size_t chan = 0) = 0;
360 
361  /*!
362  * Enable/Disable the RX frontend IQ imbalance correction.
363  *
364  * \param enb true to enable automatic IQ imbalance correction
365  * \param chan the channel index 0 to N-1
366  */
367  virtual void set_auto_iq_balance(const bool enb, size_t chan = 0) = 0;
368 
369  /*!
370  * Set the RX frontend IQ imbalance correction.
371  * Use this to adjust the magnitude and phase of I and Q.
372  *
373  * \param correction the complex correction value
374  * \param chan the channel index 0 to N-1
375  */
376  virtual void set_iq_balance(const std::complex<double> &correction,
377  size_t chan = 0) = 0;
378 
379  /*!
380  * Get a RF frontend sensor value.
381  * \param name the name of the sensor
382  * \param chan the channel index 0 to N-1
383  * \return a sensor value object
384  */
385  virtual ::uhd::sensor_value_t get_sensor(const std::string &name,
386  size_t chan = 0) = 0;
387 
388  /*!
389  * Get a list of possible RF frontend sensor names.
390  * \param chan the channel index 0 to N-1
391  * \return a vector of sensor names
392  */
393  virtual std::vector<std::string> get_sensor_names(size_t chan = 0) = 0;
394 
395  //! DEPRECATED use get_sensor
396  ::uhd::sensor_value_t get_dboard_sensor(const std::string &name,
397  size_t chan = 0)
398  {
399  return this->get_sensor(name, chan);
400  }
401 
402  //! DEPRECATED use get_sensor_names
403  std::vector<std::string> get_dboard_sensor_names(size_t chan = 0)
404  {
405  return this->get_sensor_names(chan);
406  }
407 
408  /*!
409  * Get a motherboard sensor value.
410  * \param name the name of the sensor
411  * \param mboard the motherboard index 0 to M-1
412  * \return a sensor value object
413  */
414  virtual ::uhd::sensor_value_t get_mboard_sensor(const std::string &name,
415  size_t mboard = 0) = 0;
416 
417  /*!
418  * Get a list of possible motherboard sensor names.
419  * \param mboard the motherboard index 0 to M-1
420  * \return a vector of sensor names
421  */
422  virtual std::vector<std::string> get_mboard_sensor_names(size_t mboard = 0) = 0;
423 
424  /*!
425  * Set the clock configuration.
426  * DEPRECATED for set_time/clock_source.
427  * \param clock_config the new configuration
428  * \param mboard the motherboard index 0 to M-1
429  */
430  virtual void set_clock_config(const ::uhd::clock_config_t &clock_config,
431  size_t mboard = 0) = 0;
432 
433  /*!
434  * Set the time source for the usrp device.
435  * This sets the method of time synchronization,
436  * typically a pulse per second or an encoded time.
437  * Typical options for source: external, MIMO.
438  * \param source a string representing the time source
439  * \param mboard which motherboard to set the config
440  */
441  virtual void set_time_source(const std::string &source,
442  const size_t mboard = 0) = 0;
443 
444  /*!
445  * Get the currently set time source.
446  * \param mboard which motherboard to get the config
447  * \return the string representing the time source
448  */
449  virtual std::string get_time_source(const size_t mboard) = 0;
450 
451  /*!
452  * Get a list of possible time sources.
453  * \param mboard which motherboard to get the list
454  * \return a vector of strings for possible settings
455  */
456  virtual std::vector<std::string> get_time_sources(const size_t mboard) = 0;
457 
458  /*!
459  * Set the clock source for the usrp device.
460  * This sets the source for a 10 Mhz reference clock.
461  * Typical options for source: internal, external, MIMO.
462  * \param source a string representing the clock source
463  * \param mboard which motherboard to set the config
464  */
465  virtual void set_clock_source(const std::string &source,
466  const size_t mboard = 0) = 0;
467 
468  /*!
469  * Get the currently set clock source.
470  * \param mboard which motherboard to get the config
471  * \return the string representing the clock source
472  */
473  virtual std::string get_clock_source(const size_t mboard) = 0;
474 
475  /*!
476  * Get a list of possible clock sources.
477  * \param mboard which motherboard to get the list
478  * \return a vector of strings for possible settings
479  */
480  virtual std::vector<std::string> get_clock_sources(const size_t mboard) = 0;
481 
482  /*!
483  * Get the master clock rate.
484  * \param mboard the motherboard index 0 to M-1
485  * \return the clock rate in Hz
486  */
487  virtual double get_clock_rate(size_t mboard = 0) = 0;
488 
489  /*!
490  * Set the master clock rate.
491  * \param rate the new rate in Hz
492  * \param mboard the motherboard index 0 to M-1
493  */
494  virtual void set_clock_rate(double rate, size_t mboard = 0) = 0;
495 
496  /*!
497  * Get the current time registers.
498  * \param mboard the motherboard index 0 to M-1
499  * \return the current usrp time
500  */
501  virtual ::uhd::time_spec_t get_time_now(size_t mboard = 0) = 0;
502 
503  /*!
504  * Get the time when the last pps pulse occured.
505  * \param mboard the motherboard index 0 to M-1
506  * \return the current usrp time
507  */
508  virtual ::uhd::time_spec_t get_time_last_pps(size_t mboard = 0) = 0;
509 
510  /*!
511  * Sets the time registers immediately.
512  * \param time_spec the new time
513  * \param mboard the motherboard index 0 to M-1
514  */
515  virtual void set_time_now(const ::uhd::time_spec_t &time_spec,
516  size_t mboard = 0) = 0;
517 
518  /*!
519  * Set the time registers at the next pps.
520  * \param time_spec the new time
521  */
522  virtual void set_time_next_pps(const ::uhd::time_spec_t &time_spec) = 0;
523 
524  /*!
525  * Sync the time registers with an unknown pps edge.
526  * \param time_spec the new time
527  */
528  virtual void set_time_unknown_pps(const ::uhd::time_spec_t &time_spec) = 0;
529 
530  /*!
531  * Set the time at which the control commands will take effect.
532  *
533  * A timed command will back-pressure all subsequent timed
534  * commands, assuming that the subsequent commands occur within
535  * the time-window. If the time spec is late, the command will
536  * be activated upon arrival.
537  *
538  * \param time_spec the time at which the next command will activate
539  * \param mboard which motherboard to set the config
540  */
541  virtual void set_command_time(const ::uhd::time_spec_t &time_spec,
542  size_t mboard = 0) = 0;
543 
544  /*!
545  * Clear the command time so future commands are sent ASAP.
546  *
547  * \param mboard which motherboard to set the config
548  */
549  virtual void clear_command_time(size_t mboard = 0) = 0;
550 
551  /*!
552  * Get access to the underlying uhd dboard iface object.
553  * \return the dboard_iface object
554  */
555  virtual ::uhd::usrp::dboard_iface::sptr get_dboard_iface(size_t chan = 0) = 0;
556 
557  /*!
558  * Get access to the underlying uhd device object.
559  *
560  * NOTE: This function is only available in C++.
561  * \return the multi usrp device object
562  */
563  virtual ::uhd::usrp::multi_usrp::sptr get_device(void) = 0;
564 
565  /*!
566  * Perform write on the user configuration register bus. These
567  * only exist if the user has implemented custom setting
568  * registers in the device FPGA.
569  * \param addr 8-bit register address
570  * \param data 32-bit register value
571  * \param mboard which motherboard to set the user register
572  */
573  virtual void set_user_register(const uint8_t addr,
574  const uint32_t data,
575  size_t mboard = 0) = 0;
576 
577  /*!
578  * Update the stream args for this device.
579  *
580  * This update will only take effect after a restart of the
581  * streaming, or before streaming and after construction.
582  * This will also delete the current streamer.
583  * Note you cannot change the I/O signature of this block using
584  * this function, or it will throw.
585  *
586  * It is possible to leave the 'channels' fields of \p stream_args
587  * unset. In this case, the previous channels field is used.
588  *
589  * \param stream_args New stream args.
590  * \throws std::runtime_error if new settings are invalid.
591  */
592  virtual void set_stream_args(const ::uhd::stream_args_t &stream_args) = 0;
593 
594  /*!
595  * Convenience function for finite data acquisition.
596  * This is not to be used with the scheduler; rather,
597  * one can request samples from the USRP in python.
598  * //TODO assumes fc32
599  * \param nsamps the number of samples
600  * \return a vector of complex float samples
601  */
602  virtual std::vector<std::complex<float> >
603  finite_acquisition(const size_t nsamps) = 0;
604 
605  /*!
606  * Convenience function for finite data acquisition. This is the
607  * multi-channel version of finite_acquisition; This is not to
608  * be used with the scheduler; rather, one can request samples
609  * from the USRP in python.
610  * //TODO assumes fc32
611  * \param nsamps the number of samples per channel
612  * \return a vector of buffers, where each buffer represents a channel
613  */
614  virtual std::vector<std::vector<std::complex<float> > >
615  finite_acquisition_v(const size_t nsamps) = 0;
616  };
617 
618  } /* namespace uhd */
619 } /* namespace gr */
620 
621 #endif /* INCLUDED_GR_UHD_USRP_SOURCE_H */
::uhd::sensor_value_t get_dboard_sensor(const std::string &name, size_t chan=0)
DEPRECATED use get_sensor.
Definition: usrp_source.h:396
Definition: usrp_source.h:57
unsigned char uint8_t
Definition: stdint.h:78
shared_ptr documentation stub
Definition: shared_ptr_docstub.h:15
::uhd::tune_result_t set_center_freq(double freq, size_t chan=0)
Definition: usrp_source.h:189
Definition: usrp_sink.h:32
unsigned int uint32_t
Definition: stdint.h:80
Include this header to use the message passing features.
Definition: logger.h:129
stream_args_t(const std::string &cpu="", const std::string &otw="")
Definition: usrp_source.h:35
synchronous 1:1 input to output with historyOverride work to provide the signal processing implementa...
Definition: sync_block.h:37
#define GR_UHD_API
Definition: gr-uhd/include/gnuradio/uhd/api.h:30
VOLK_API $kern pname $kern name
A function pointer to the dispatcher implementation.
std::vector< std::string > get_dboard_sensor_names(size_t chan=0)
DEPRECATED use get_sensor_names.
Definition: usrp_source.h:403
boost::shared_ptr< usrp_source > sptr
Definition: usrp_source.h:61