GNU Radio Manual and C++ API Reference  3.7.8
The Free & Open Software Radio Ecosystem
usrp_block.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 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_BLOCK_H
24 #define INCLUDED_GR_UHD_USRP_BLOCK_H
25 
26 #include <gnuradio/uhd/api.h>
27 #include <gnuradio/sync_block.h>
28 #include <uhd/usrp/multi_usrp.hpp>
29 
30 namespace gr {
31  namespace uhd {
32 
33  /*! Base class for USRP blocks.
34  * \ingroup uhd_blk
35  *
36  * Note that many of the functions defined here differ between
37  * Rx and Tx configurations. As an example, set_center_freq()
38  * will set the Rx frequency for a usrp_source object, and the
39  * Tx frequency on a usrp_sink object.
40  */
42  {
43  protected:
44  usrp_block() {}; // For virtual sub-classing
45  usrp_block(const std::string &name,
46  gr::io_signature::sptr input_signature,
47  gr::io_signature::sptr output_signature);
48  public:
49 
50  /*!
51  * Set the frontend specification.
52  *
53  * \param spec the subdev spec markup string
54  * \param mboard the motherboard index 0 to M-1
55  */
56  virtual void set_subdev_spec(const std::string &spec, size_t mboard = 0) = 0;
57 
58  /*!
59  * Get the frontend specification.
60  *
61  * \param mboard the motherboard index 0 to M-1
62  * \return the frontend specification in use
63  */
64  virtual std::string get_subdev_spec(size_t mboard = 0) = 0;
65 
66  /*!
67  * Set the sample rate for this connection to the USRP.
68  *
69  * \param rate a new rate in Sps
70  */
71  virtual void set_samp_rate(double rate) = 0;
72 
73  /*!
74  * Get the sample rate for this connection to the USRP.
75  * This is the actual sample rate and may differ from the rate set.
76  *
77  * \return the actual rate in Sps
78  */
79  virtual double get_samp_rate(void) = 0;
80 
81  /*!
82  * Get the possible sample rates for this connection.
83  *
84  * \return a range of rates in Sps
85  */
86  virtual ::uhd::meta_range_t get_samp_rates(void) = 0;
87 
88  /*!
89  * Tune the selected channel to the desired center frequency.
90  *
91  * \param tune_request the tune request instructions
92  * \param chan the channel index 0 to N-1
93  * \return a tune result with the actual frequencies
94  */
95  virtual ::uhd::tune_result_t set_center_freq(
96  const ::uhd::tune_request_t tune_request,
97  size_t chan = 0
98  ) = 0;
99 
100  /*!
101  * Tune the the selected channel to the desired center frequency.
102  *
103  * This is a wrapper around set_center_freq() so that in this case,
104  * the user can pass a single frequency in the call instead of
105  * having to generate a tune_request_t object.
106  *
107  * \param freq the desired frequency in Hz
108  * \param chan the channel index 0 to N-1
109  * \return a tune result with the actual frequencies
110  */
111  ::uhd::tune_result_t set_center_freq(double freq, size_t chan = 0)
112  {
113  return set_center_freq(::uhd::tune_request_t(freq), chan);
114  }
115 
116  /*!
117  * Get the center frequency.
118  *
119  * \param chan the channel index 0 to N-1
120  * \return the frequency in Hz
121  */
122  virtual double get_center_freq(size_t chan = 0) = 0;
123 
124  /*!
125  * Get the tunable frequency range.
126  *
127  * \param chan the channel index 0 to N-1
128  * \return the frequency range in Hz
129  */
130  virtual ::uhd::freq_range_t get_freq_range(size_t chan = 0) = 0;
131 
132  /*!
133  * Set the gain for the selected channel.
134  *
135  * \param gain the gain in dB
136  * \param chan the channel index 0 to N-1
137  */
138  virtual void set_gain(double gain, size_t chan = 0) = 0;
139 
140  /*!
141  * Set the named gain on the dboard.
142  *
143  * \param gain the gain in dB
144  * \param name the name of the gain stage
145  * \param chan the channel index 0 to N-1
146  */
147  virtual void set_gain(double gain,
148  const std::string &name,
149  size_t chan = 0) = 0;
150 
151  /*!
152  * Set the normalized gain.
153  *
154  * The normalized gain is always in [0, 1], regardless of the device.
155  * 0 corresponds to minimum gain (usually 0 dB, but make sure to read the device
156  * notes in the UHD manual) and 1 corresponds to maximum gain.
157  * This will work for any UHD device. Use get_gain() to see which dB value
158  * the normalized gain value corresponds to.
159  *
160  * Note that it is not possible to specify a gain name for this function.
161  *
162  * \throws A runtime_error if \p norm_gain is not within the valid range.
163  *
164  * \param norm_gain the gain in fractions of the gain range (must be 0 <= norm_gain <= 1)
165  * \param chan the channel index 0 to N-1
166  */
167  virtual void set_normalized_gain(double norm_gain, size_t chan = 0) = 0;
168 
169  /*!
170  * Get the actual dboard gain setting.
171  *
172  * \param chan the channel index 0 to N-1
173  * \return the actual gain in dB
174  */
175  virtual double get_gain(size_t chan = 0) = 0;
176 
177  /*!
178  * Get the actual dboard gain setting of named stage.
179  *
180  * \param name the name of the gain stage
181  * \param chan the channel index 0 to N-1
182  * \return the actual gain in dB
183  */
184  virtual double get_gain(const std::string &name,
185  size_t chan = 0) = 0;
186 
187  /*!
188  * Returns the normalized gain.
189  *
190  * The normalized gain is always in [0, 1], regardless of the device.
191  * See also set_normalized_gain().
192  *
193  * Note that it is not possible to specify a gain name for
194  * this function, the result is over the entire gain chain.
195  *
196  * \param chan the channel index 0 to N-1
197  */
198  virtual double get_normalized_gain(size_t chan = 0) = 0;
199 
200  /*!
201  * Get the actual dboard gain setting of named stage.
202  *
203  * \param chan the channel index 0 to N-1
204  * \return the actual gain in dB
205  */
206  virtual std::vector<std::string> get_gain_names(size_t chan = 0) = 0;
207 
208  /*!
209  * Get the settable gain range.
210  *
211  * \param chan the channel index 0 to N-1
212  * \return the gain range in dB
213  */
214  virtual ::uhd::gain_range_t get_gain_range(size_t chan = 0) = 0;
215 
216  /*!
217  * Get the settable gain range.
218  *
219  * \param name the name of the gain stage
220  * \param chan the channel index 0 to N-1
221  * \return the gain range in dB
222  */
223  virtual ::uhd::gain_range_t get_gain_range(const std::string &name,
224  size_t chan = 0) = 0;
225 
226  /*!
227  * Set the antenna to use for a given channel.
228  *
229  * \param ant the antenna string
230  * \param chan the channel index 0 to N-1
231  */
232  virtual void set_antenna(const std::string &ant,
233  size_t chan = 0) = 0;
234 
235  /*!
236  * Get the antenna in use.
237  *
238  * \param chan the channel index 0 to N-1
239  * \return the antenna string
240  */
241  virtual std::string get_antenna(size_t chan = 0) = 0;
242 
243  /*!
244  * Get a list of possible antennas on a given channel.
245  *
246  * \param chan the channel index 0 to N-1
247  * \return a vector of antenna strings
248  */
249  virtual std::vector<std::string> get_antennas(size_t chan = 0) = 0;
250 
251  /*!
252  * Set the bandpass filter on the RF frontend.
253  *
254  * \param bandwidth the filter bandwidth in Hz
255  * \param chan the channel index 0 to N-1
256  */
257  virtual void set_bandwidth(double bandwidth, size_t chan = 0) = 0;
258 
259  /*!
260  * Get the bandpass filter setting on the RF frontend.
261  *
262  * \param chan the channel index 0 to N-1
263  * \return bandwidth of the filter in Hz
264  */
265  virtual double get_bandwidth(size_t chan = 0) = 0;
266 
267  /*!
268  * Get the bandpass filter range of the RF frontend.
269  *
270  * \param chan the channel index 0 to N-1
271  * \return the range of the filter bandwidth in Hz
272  */
273  virtual ::uhd::freq_range_t get_bandwidth_range(size_t chan = 0) = 0;
274 
275  /*!
276  * Get an RF frontend sensor value.
277  * \param name the name of the sensor
278  * \param chan the channel index 0 to N-1
279  * \return a sensor value object
280  */
281  virtual ::uhd::sensor_value_t get_sensor(const std::string &name,
282  size_t chan = 0) = 0;
283 
284  /*!
285  * Get a list of possible RF frontend sensor names.
286  * \param chan the channel index 0 to N-1
287  * \return a vector of sensor names
288  */
289  virtual std::vector<std::string> get_sensor_names(size_t chan = 0) = 0;
290 
291  //! DEPRECATED use get_sensor
292  ::uhd::sensor_value_t get_dboard_sensor(const std::string &name,
293  size_t chan = 0)
294  {
295  return this->get_sensor(name, chan);
296  }
297 
298  //! DEPRECATED use get_sensor_names
299  std::vector<std::string> get_dboard_sensor_names(size_t chan = 0)
300  {
301  return this->get_sensor_names(chan);
302  }
303 
304  /*!
305  * Get a motherboard sensor value.
306  *
307  * \param name the name of the sensor
308  * \param mboard the motherboard index 0 to M-1
309  * \return a sensor value object
310  */
311  virtual ::uhd::sensor_value_t get_mboard_sensor(const std::string &name,
312  size_t mboard = 0) = 0;
313 
314  /*!
315  * Get a list of possible motherboard sensor names.
316  *
317  * \param mboard the motherboard index 0 to M-1
318  * \return a vector of sensor names
319  */
320  virtual std::vector<std::string> get_mboard_sensor_names(size_t mboard = 0) = 0;
321 
322  /*!
323  * Get the currently set time source.
324  *
325  * \param mboard which motherboard to get the config
326  * \return the string representing the time source
327  */
328  virtual std::string get_time_source(const size_t mboard) = 0;
329 
330  /*!
331  * Get a list of possible time sources.
332  *
333  * \param mboard which motherboard to get the list
334  * \return a vector of strings for possible settings
335  */
336  virtual std::vector<std::string> get_time_sources(const size_t mboard) = 0;
337 
338  /*!
339  * Set the clock source for the usrp device.
340  *
341  * This sets the source for a 10 MHz reference clock.
342  * Typical options for source: internal, external, MIMO.
343  *
344  * \param source a string representing the clock source
345  * \param mboard which motherboard to set the config
346  */
347  virtual void set_clock_source(const std::string &source,
348  const size_t mboard = 0) = 0;
349 
350  /*!
351  * Get the currently set clock source.
352  *
353  * \param mboard which motherboard to get the config
354  * \return the string representing the clock source
355  */
356  virtual std::string get_clock_source(const size_t mboard) = 0;
357 
358  /*!
359  * Get a list of possible clock sources.
360  *
361  * \param mboard which motherboard to get the list
362  * \return a vector of strings for possible settings
363  */
364  virtual std::vector<std::string> get_clock_sources(const size_t mboard) = 0;
365 
366  /*!
367  * Get the master clock rate.
368  *
369  * \param mboard the motherboard index 0 to M-1
370  * \return the clock rate in Hz
371  */
372  virtual double get_clock_rate(size_t mboard = 0) = 0;
373 
374  /*!
375  * Set the master clock rate.
376  *
377  * \param rate the new rate in Hz
378  * \param mboard the motherboard index 0 to M-1
379  */
380  virtual void set_clock_rate(double rate, size_t mboard = 0) = 0;
381 
382  /*!
383  * Get the current time registers.
384  *
385  * \param mboard the motherboard index 0 to M-1
386  * \return the current usrp time
387  */
388  virtual ::uhd::time_spec_t get_time_now(size_t mboard = 0) = 0;
389 
390  /*!
391  * Get the time when the last pps pulse occured.
392  * \param mboard the motherboard index 0 to M-1
393  * \return the current usrp time
394  */
395  virtual ::uhd::time_spec_t get_time_last_pps(size_t mboard = 0) = 0;
396 
397  /*!
398  * Sets the time registers immediately.
399  * \param time_spec the new time
400  * \param mboard the motherboard index 0 to M-1
401  */
402  virtual void set_time_now(const ::uhd::time_spec_t &time_spec, size_t mboard = 0) = 0;
403 
404  /*!
405  * Set the time registers at the next pps.
406  * \param time_spec the new time
407  */
408  virtual void set_time_next_pps(const ::uhd::time_spec_t &time_spec) = 0;
409 
410  /*!
411  * Sync the time registers with an unknown pps edge.
412  * \param time_spec the new time
413  */
414  virtual void set_time_unknown_pps(const ::uhd::time_spec_t &time_spec) = 0;
415 
416  /*!
417  * Set the time at which the control commands will take effect.
418  *
419  * A timed command will back-pressure all subsequent timed commands,
420  * assuming that the subsequent commands occur within the time-window.
421  * If the time spec is late, the command will be activated upon arrival.
422  *
423  * \param time_spec the time at which the next command will activate
424  * \param mboard which motherboard to set the config
425  */
426  virtual void set_command_time(const ::uhd::time_spec_t &time_spec,
427  size_t mboard = 0) = 0;
428 
429  /*!
430  * Clear the command time so future commands are sent ASAP.
431  *
432  * \param mboard which motherboard to set the config
433  */
434  virtual void clear_command_time(size_t mboard = 0) = 0;
435 
436  /*!
437  * Get access to the underlying uhd dboard iface object.
438  *
439  * \return the dboard_iface object
440  */
441  virtual ::uhd::usrp::dboard_iface::sptr get_dboard_iface(size_t chan = 0) = 0;
442 
443  /*!
444  * Get access to the underlying uhd device object.
445  *
446  * NOTE: This function is only available in C++.
447  * \return the multi usrp device object
448  */
449  virtual ::uhd::usrp::multi_usrp::sptr get_device(void) = 0;
450 
451  /*!
452  * Perform write on the user configuration register bus. These
453  * only exist if the user has implemented custom setting
454  * registers in the device FPGA.
455  *
456  * \param addr 8-bit register address
457  * \param data 32-bit register value
458  * \param mboard which motherboard to set the user register
459  */
460  virtual void set_user_register(const uint8_t addr,
461  const uint32_t data,
462  size_t mboard = 0) = 0;
463 
464  /*!
465  * Set the clock configuration.
466  *
467  * DEPRECATED for set_time/clock_source.
468  * \param clock_config the new configuration
469  * \param mboard the motherboard index 0 to M-1
470  */
471  virtual void set_clock_config(const ::uhd::clock_config_t &clock_config,
472  size_t mboard = 0) = 0;
473 
474  /*!
475  * Set the time source for the USRP device.
476  *
477  * This sets the method of time synchronization,
478  * typically a pulse per second or an encoded time.
479  * Typical options for source: external, MIMO.
480  * \param source a string representing the time source
481  * \param mboard which motherboard to set the config
482  */
483  virtual void set_time_source(const std::string &source,
484  const size_t mboard = 0) = 0;
485 
486  /*!
487  * Update the stream args for this device.
488  *
489  * This update will only take effect after a restart of the
490  * streaming, or before streaming and after construction.
491  * This will also delete the current streamer.
492  * Note you cannot change the I/O signature of this block using
493  * this function, or it will throw.
494  *
495  * It is possible to leave the 'channels' fields of \p stream_args
496  * unset. In this case, the previous channels field is used.
497  *
498  * \param stream_args New stream args.
499  * \throws std::runtime_error if new settings are invalid.
500  */
501  virtual void set_stream_args(const ::uhd::stream_args_t &stream_args) = 0;
502 
503  /*******************************************************************
504  * GPIO methods
505  ******************************************************************/
506  /*!
507  * Enumerate GPIO banks on the current device.
508  * \param mboard the motherboard index 0 to M-1
509  * \return a list of string for each bank name
510  */
511  virtual std::vector<std::string> get_gpio_banks(const size_t mboard) = 0;
512 
513  /*!
514  * Set a GPIO attribute on a particular GPIO bank.
515  * Possible attribute names:
516  * - CTRL - 1 for ATR mode 0 for GPIO mode
517  * - DDR - 1 for output 0 for input
518  * - OUT - GPIO output level (not ATR mode)
519  * - ATR_0X - ATR idle state
520  * - ATR_RX - ATR receive only state
521  * - ATR_TX - ATR transmit only state
522  * - ATR_XX - ATR full duplex state
523  * \param bank the name of a GPIO bank
524  * \param attr the name of a GPIO attribute
525  * \param value the new value for this GPIO bank
526  * \param mask the bit mask to effect which pins are changed
527  * \param mboard the motherboard index 0 to M-1
528  */
529  virtual void set_gpio_attr(
530  const std::string &bank,
531  const std::string &attr,
532  const boost::uint32_t value,
533  const boost::uint32_t mask = 0xffffffff,
534  const size_t mboard = 0
535  ) = 0;
536 
537  /*!
538  * Get a GPIO attribute on a particular GPIO bank.
539  * Possible attribute names:
540  * - CTRL - 1 for ATR mode 0 for GPIO mode
541  * - DDR - 1 for output 0 for input
542  * - OUT - GPIO output level (not ATR mode)
543  * - ATR_0X - ATR idle state
544  * - ATR_RX - ATR receive only state
545  * - ATR_TX - ATR transmit only state
546  * - ATR_XX - ATR full duplex state
547  * - READBACK - readback input GPIOs
548  * \param bank the name of a GPIO bank
549  * \param attr the name of a GPIO attribute
550  * \param mboard the motherboard index 0 to M-1
551  * \return the value set for this attribute
552  */
553  virtual boost::uint32_t get_gpio_attr(
554  const std::string &bank,
555  const std::string &attr,
556  const size_t mboard = 0
557  ) = 0;
558 
559  };
560 
561  } /* namespace uhd */
562 } /* namespace gr */
563 
564 #endif /* INCLUDED_GR_UHD_USRP_BLOCK_H */
boost::shared_ptr< io_signature > sptr
Definition: io_signature.h:45
Definition: usrp_block.h:41
::uhd::tune_result_t set_center_freq(double freq, size_t chan=0)
Definition: usrp_block.h:111
Definition: usrp_sink.h:30
usrp_block()
Definition: usrp_block.h:44
Include this header to use the message passing features.
Definition: basic_block.h:45
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
std::vector< std::string > get_dboard_sensor_names(size_t chan=0)
DEPRECATED use get_sensor_names.
Definition: usrp_block.h:299
::uhd::sensor_value_t get_dboard_sensor(const std::string &name, size_t chan=0)
DEPRECATED use get_sensor.
Definition: usrp_block.h:292