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