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