GNU Radio 3.6.2-18 C++ API
|
00001 /* 00002 * Copyright 2010-2012 Free Software Foundation, Inc. 00003 * 00004 * This file is part of GNU Radio 00005 * 00006 * GNU Radio is free software; you can redistribute it and/or modify 00007 * it under the terms of the GNU General Public License as published by 00008 * the Free Software Foundation; either version 3, or (at your option) 00009 * any later version. 00010 * 00011 * GNU Radio is distributed in the hope that it will be useful, 00012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00014 * GNU General Public License for more details. 00015 * 00016 * You should have received a copy of the GNU General Public License 00017 * along with GNU Radio; see the file COPYING. If not, write to 00018 * the Free Software Foundation, Inc., 51 Franklin Street, 00019 * Boston, MA 02110-1301, USA. 00020 */ 00021 00022 #ifndef INCLUDED_GR_UHD_USRP_SOURCE_H 00023 #define INCLUDED_GR_UHD_USRP_SOURCE_H 00024 00025 #include <gr_uhd_api.h> 00026 #include <gr_sync_block.h> 00027 #include <uhd/usrp/multi_usrp.hpp> 00028 00029 #ifndef INCLUDED_UHD_STREAM_HPP 00030 namespace uhd{ 00031 struct GR_UHD_API stream_args_t{ 00032 stream_args_t( 00033 const std::string &cpu = "", 00034 const std::string &otw = "" 00035 ){ 00036 cpu_format = cpu; 00037 otw_format = otw; 00038 } 00039 std::string cpu_format; 00040 std::string otw_format; 00041 device_addr_t args; 00042 std::vector<size_t> channels; 00043 }; 00044 } 00045 # define INCLUDED_UHD_STREAM_HPP 00046 #else 00047 # define GR_UHD_USE_STREAM_API 00048 #endif 00049 00050 class uhd_usrp_source; 00051 00052 /*! 00053 * \brief Make a new USRP source block. 00054 * \ingroup uhd_blk 00055 * 00056 * The USRP source block receives samples and writes to a stream. 00057 * The source block also provides API calls for receiver settings. 00058 * 00059 * RX Stream tagging: 00060 * 00061 * The following tag keys will be produced by the work function: 00062 * - pmt::pmt_string_to_symbol("rx_time") 00063 * - pmt::pmt_string_to_symbol("rx_rate") 00064 * - pmt::pmt_string_to_symbol("rx_freq") 00065 * 00066 * The timstamp tag value is a pmt tuple of the following: 00067 * (uint64 seconds, and double fractional seconds). 00068 * A timestamp tag is produced at start() and after overflows. 00069 * 00070 * The sample rate and center frequency tags are doubles, 00071 * representing the sample rate in Sps and frequency in Hz. 00072 * These tags are produced upon the user changing parameters. 00073 * 00074 * See the UHD manual for more detailed documentation: 00075 * http://code.ettus.com/redmine/ettus/projects/uhd/wiki 00076 * 00077 * \param device_addr the address to identify the hardware 00078 * \param io_type the desired output data type 00079 * \param num_channels number of stream from the device 00080 * \return a new USRP source block object 00081 */ 00082 GR_UHD_API boost::shared_ptr<uhd_usrp_source> uhd_make_usrp_source( 00083 const uhd::device_addr_t &device_addr, 00084 const uhd::io_type_t &io_type, 00085 size_t num_channels 00086 ); 00087 00088 /*! 00089 * \brief Make a new USRP source block. 00090 * 00091 * The USRP source block receives samples and writes to a stream. 00092 * The source block also provides API calls for receiver settings. 00093 * 00094 * RX Stream tagging: 00095 * 00096 * The following tag keys will be produced by the work function: 00097 * - pmt::pmt_string_to_symbol("rx_time") 00098 * 00099 * The timstamp tag value is a pmt tuple of the following: 00100 * (uint64 seconds, and double fractional seconds). 00101 * A timestamp tag is produced at start() and after overflows. 00102 * 00103 * See the UHD manual for more detailed documentation: 00104 * http://code.ettus.com/redmine/ettus/projects/uhd/wiki 00105 * 00106 * \param device_addr the address to identify the hardware 00107 * \param stream_args the IO format and channel specification 00108 * \return a new USRP source block object 00109 */ 00110 GR_UHD_API boost::shared_ptr<uhd_usrp_source> uhd_make_usrp_source( 00111 const uhd::device_addr_t &device_addr, 00112 const uhd::stream_args_t &stream_args 00113 ); 00114 00115 class GR_UHD_API uhd_usrp_source : virtual public gr_sync_block{ 00116 public: 00117 00118 /*! 00119 * Set the start time for incoming samples. 00120 * To control when samples are received, 00121 * set this value before starting the flow graph. 00122 * The value is cleared after each run. 00123 * When not specified, the start time will be: 00124 * - Immediately for the one channel case 00125 * - in the near future for multi-channel 00126 * 00127 * \param time the absolute time for reception to begin 00128 */ 00129 virtual void set_start_time(const uhd::time_spec_t &time) = 0; 00130 00131 /*! 00132 * Returns identifying information about this USRP's configuration. 00133 * Returns motherboard ID, name, and serial. 00134 * Returns daughterboard RX ID, subdev name and spec, serial, and antenna. 00135 * \param chan channel index 0 to N-1 00136 * \return RX info 00137 */ 00138 virtual uhd::dict<std::string, std::string> get_usrp_info(size_t chan = 0) = 0; 00139 00140 /*! 00141 * Set the frontend specification. 00142 * \param spec the subdev spec markup string 00143 * \param mboard the motherboard index 0 to M-1 00144 */ 00145 virtual void set_subdev_spec(const std::string &spec, size_t mboard = 0) = 0; 00146 00147 /*! 00148 * Get the RX frontend specification. 00149 * \param mboard the motherboard index 0 to M-1 00150 * \return the frontend specification in use 00151 */ 00152 virtual std::string get_subdev_spec(size_t mboard = 0) = 0; 00153 00154 /*! 00155 * Set the sample rate for the usrp device. 00156 * \param rate a new rate in Sps 00157 */ 00158 virtual void set_samp_rate(double rate) = 0; 00159 00160 /*! 00161 * Get the sample rate for the usrp device. 00162 * This is the actual sample rate and may differ from the rate set. 00163 * \return the actual rate in Sps 00164 */ 00165 virtual double get_samp_rate(void) = 0; 00166 00167 /*! 00168 * Get the possible sample rates for the usrp device. 00169 * \return a range of rates in Sps 00170 */ 00171 virtual uhd::meta_range_t get_samp_rates(void) = 0; 00172 00173 /*! 00174 * Tune the usrp device to the desired center frequency. 00175 * \param tune_request the tune request instructions 00176 * \param chan the channel index 0 to N-1 00177 * \return a tune result with the actual frequencies 00178 */ 00179 virtual uhd::tune_result_t set_center_freq( 00180 const uhd::tune_request_t tune_request, size_t chan = 0 00181 ) = 0; 00182 00183 /*! 00184 * Tune the usrp device to the desired center frequency. 00185 * This is a wrapper around set center freq so that in this case, 00186 * the user can pass a single frequency in the call through swig. 00187 * \param freq the desired frequency in Hz 00188 * \param chan the channel index 0 to N-1 00189 * \return a tune result with the actual frequencies 00190 */ 00191 uhd::tune_result_t set_center_freq(double freq, size_t chan = 0){ 00192 return set_center_freq(uhd::tune_request_t(freq), chan); 00193 } 00194 00195 /*! 00196 * Get the center frequency. 00197 * \param chan the channel index 0 to N-1 00198 * \return the frequency in Hz 00199 */ 00200 virtual double get_center_freq(size_t chan = 0) = 0; 00201 00202 /*! 00203 * Get the tunable frequency range. 00204 * \param chan the channel index 0 to N-1 00205 * \return the frequency range in Hz 00206 */ 00207 virtual uhd::freq_range_t get_freq_range(size_t chan = 0) = 0; 00208 00209 /*! 00210 * Set the gain for the dboard. 00211 * \param gain the gain in dB 00212 * \param chan the channel index 0 to N-1 00213 */ 00214 virtual void set_gain(double gain, size_t chan = 0) = 0; 00215 00216 /*! 00217 * Set the named gain on the dboard. 00218 * \param gain the gain in dB 00219 * \param name the name of the gain stage 00220 * \param chan the channel index 0 to N-1 00221 */ 00222 virtual void set_gain(double gain, const std::string &name, size_t chan = 0) = 0; 00223 00224 /*! 00225 * Get the actual dboard gain setting. 00226 * \param chan the channel index 0 to N-1 00227 * \return the actual gain in dB 00228 */ 00229 virtual double get_gain(size_t chan = 0) = 0; 00230 00231 /*! 00232 * Get the actual dboard gain setting of named stage. 00233 * \param name the name of the gain stage 00234 * \param chan the channel index 0 to N-1 00235 * \return the actual gain in dB 00236 */ 00237 virtual double get_gain(const std::string &name, size_t chan = 0) = 0; 00238 00239 /*! 00240 * Get the actual dboard gain setting of named stage. 00241 * \param chan the channel index 0 to N-1 00242 * \return the actual gain in dB 00243 */ 00244 virtual std::vector<std::string> get_gain_names(size_t chan = 0) = 0; 00245 00246 /*! 00247 * Get the settable gain range. 00248 * \param chan the channel index 0 to N-1 00249 * \return the gain range in dB 00250 */ 00251 virtual uhd::gain_range_t get_gain_range(size_t chan = 0) = 0; 00252 00253 /*! 00254 * Get the settable gain range. 00255 * \param name the name of the gain stage 00256 * \param chan the channel index 0 to N-1 00257 * \return the gain range in dB 00258 */ 00259 virtual uhd::gain_range_t get_gain_range(const std::string &name, size_t chan = 0) = 0; 00260 00261 /*! 00262 * Set the antenna to use. 00263 * \param ant the antenna string 00264 * \param chan the channel index 0 to N-1 00265 */ 00266 virtual void set_antenna(const std::string &ant, size_t chan = 0) = 0; 00267 00268 /*! 00269 * Get the antenna in use. 00270 * \param chan the channel index 0 to N-1 00271 * \return the antenna string 00272 */ 00273 virtual std::string get_antenna(size_t chan = 0) = 0; 00274 00275 /*! 00276 * Get a list of possible antennas. 00277 * \param chan the channel index 0 to N-1 00278 * \return a vector of antenna strings 00279 */ 00280 virtual std::vector<std::string> get_antennas(size_t chan = 0) = 0; 00281 00282 /*! 00283 * Set the bandpass filter on the RF frontend. 00284 * \param bandwidth the filter bandwidth in Hz 00285 * \param chan the channel index 0 to N-1 00286 */ 00287 virtual void set_bandwidth(double bandwidth, size_t chan = 0) = 0; 00288 00289 /*! 00290 * Enable/disable the automatic DC offset correction. 00291 * The automatic correction subtracts out the long-run average. 00292 * 00293 * When disabled, the averaging option operation is halted. 00294 * Once halted, the average value will be held constant 00295 * until the user re-enables the automatic correction 00296 * or overrides the value by manually setting the offset. 00297 * 00298 * \param enb true to enable automatic DC offset correction 00299 * \param chan the channel index 0 to N-1 00300 */ 00301 virtual void set_auto_dc_offset(const bool enb, size_t chan = 0) = 0; 00302 00303 /*! 00304 * Set a constant DC offset value. 00305 * The value is complex to control both I and Q. 00306 * Only set this when automatic correction is disabled. 00307 * \param offset the dc offset (1.0 is full-scale) 00308 * \param chan the channel index 0 to N-1 00309 */ 00310 virtual void set_dc_offset(const std::complex<double> &offset, size_t chan = 0) = 0; 00311 00312 /*! 00313 * Set the RX frontend IQ imbalance correction. 00314 * Use this to adjust the magnitude and phase of I and Q. 00315 * 00316 * \param correction the complex correction value 00317 * \param chan the channel index 0 to N-1 00318 */ 00319 virtual void set_iq_balance(const std::complex<double> &correction, size_t chan = 0) = 0; 00320 00321 /*! 00322 * Get a RF frontend sensor value. 00323 * \param name the name of the sensor 00324 * \param chan the channel index 0 to N-1 00325 * \return a sensor value object 00326 */ 00327 virtual uhd::sensor_value_t get_sensor(const std::string &name, size_t chan = 0) = 0; 00328 00329 /*! 00330 * Get a list of possible RF frontend sensor names. 00331 * \param chan the channel index 0 to N-1 00332 * \return a vector of sensor names 00333 */ 00334 virtual std::vector<std::string> get_sensor_names(size_t chan = 0) = 0; 00335 00336 //! DEPRECATED use get_sensor 00337 uhd::sensor_value_t get_dboard_sensor(const std::string &name, size_t chan = 0){ 00338 return this->get_sensor(name, chan); 00339 } 00340 00341 //! DEPRECATED use get_sensor_names 00342 std::vector<std::string> get_dboard_sensor_names(size_t chan = 0){ 00343 return this->get_sensor_names(chan); 00344 } 00345 00346 /*! 00347 * Get a motherboard sensor value. 00348 * \param name the name of the sensor 00349 * \param mboard the motherboard index 0 to M-1 00350 * \return a sensor value object 00351 */ 00352 virtual uhd::sensor_value_t get_mboard_sensor(const std::string &name, size_t mboard = 0) = 0; 00353 00354 /*! 00355 * Get a list of possible motherboard sensor names. 00356 * \param mboard the motherboard index 0 to M-1 00357 * \return a vector of sensor names 00358 */ 00359 virtual std::vector<std::string> get_mboard_sensor_names(size_t mboard = 0) = 0; 00360 00361 /*! 00362 * Set the clock configuration. 00363 * DEPRECATED for set_time/clock_source. 00364 * \param clock_config the new configuration 00365 * \param mboard the motherboard index 0 to M-1 00366 */ 00367 virtual void set_clock_config(const uhd::clock_config_t &clock_config, size_t mboard = 0) = 0; 00368 00369 /*! 00370 * Set the time source for the usrp device. 00371 * This sets the method of time synchronization, 00372 * typically a pulse per second or an encoded time. 00373 * Typical options for source: external, MIMO. 00374 * \param source a string representing the time source 00375 * \param mboard which motherboard to set the config 00376 */ 00377 virtual void set_time_source(const std::string &source, const size_t mboard = 0) = 0; 00378 00379 /*! 00380 * Get the currently set time source. 00381 * \param mboard which motherboard to get the config 00382 * \return the string representing the time source 00383 */ 00384 virtual std::string get_time_source(const size_t mboard) = 0; 00385 00386 /*! 00387 * Get a list of possible time sources. 00388 * \param mboard which motherboard to get the list 00389 * \return a vector of strings for possible settings 00390 */ 00391 virtual std::vector<std::string> get_time_sources(const size_t mboard) = 0; 00392 00393 /*! 00394 * Set the clock source for the usrp device. 00395 * This sets the source for a 10 Mhz reference clock. 00396 * Typical options for source: internal, external, MIMO. 00397 * \param source a string representing the clock source 00398 * \param mboard which motherboard to set the config 00399 */ 00400 virtual void set_clock_source(const std::string &source, const size_t mboard = 0) = 0; 00401 00402 /*! 00403 * Get the currently set clock source. 00404 * \param mboard which motherboard to get the config 00405 * \return the string representing the clock source 00406 */ 00407 virtual std::string get_clock_source(const size_t mboard) = 0; 00408 00409 /*! 00410 * Get a list of possible clock sources. 00411 * \param mboard which motherboard to get the list 00412 * \return a vector of strings for possible settings 00413 */ 00414 virtual std::vector<std::string> get_clock_sources(const size_t mboard) = 0; 00415 00416 /*! 00417 * Get the master clock rate. 00418 * \param mboard the motherboard index 0 to M-1 00419 * \return the clock rate in Hz 00420 */ 00421 virtual double get_clock_rate(size_t mboard = 0) = 0; 00422 00423 /*! 00424 * Set the master clock rate. 00425 * \param rate the new rate in Hz 00426 * \param mboard the motherboard index 0 to M-1 00427 */ 00428 virtual void set_clock_rate(double rate, size_t mboard = 0) = 0; 00429 00430 /*! 00431 * Get the current time registers. 00432 * \param mboard the motherboard index 0 to M-1 00433 * \return the current usrp time 00434 */ 00435 virtual uhd::time_spec_t get_time_now(size_t mboard = 0) = 0; 00436 00437 /*! 00438 * Get the time when the last pps pulse occured. 00439 * \param mboard the motherboard index 0 to M-1 00440 * \return the current usrp time 00441 */ 00442 virtual uhd::time_spec_t get_time_last_pps(size_t mboard = 0) = 0; 00443 00444 /*! 00445 * Sets the time registers immediately. 00446 * \param time_spec the new time 00447 * \param mboard the motherboard index 0 to M-1 00448 */ 00449 virtual void set_time_now(const uhd::time_spec_t &time_spec, size_t mboard = 0) = 0; 00450 00451 /*! 00452 * Set the time registers at the next pps. 00453 * \param time_spec the new time 00454 */ 00455 virtual void set_time_next_pps(const uhd::time_spec_t &time_spec) = 0; 00456 00457 /*! 00458 * Sync the time registers with an unknown pps edge. 00459 * \param time_spec the new time 00460 */ 00461 virtual void set_time_unknown_pps(const uhd::time_spec_t &time_spec) = 0; 00462 00463 /*! 00464 * Set the time at which the control commands will take effect. 00465 * 00466 * A timed command will back-pressure all subsequent timed commands, 00467 * assuming that the subsequent commands occur within the time-window. 00468 * If the time spec is late, the command will be activated upon arrival. 00469 * 00470 * \param time_spec the time at which the next command will activate 00471 * \param mboard which motherboard to set the config 00472 */ 00473 virtual void set_command_time(const uhd::time_spec_t &time_spec, size_t mboard = 0) = 0; 00474 00475 /*! 00476 * Clear the command time so future commands are sent ASAP. 00477 * 00478 * \param mboard which motherboard to set the config 00479 */ 00480 virtual void clear_command_time(size_t mboard = 0) = 0; 00481 00482 /*! 00483 * Get access to the underlying uhd dboard iface object. 00484 * \return the dboard_iface object 00485 */ 00486 virtual uhd::usrp::dboard_iface::sptr get_dboard_iface(size_t chan = 0) = 0; 00487 00488 /*! 00489 * Get access to the underlying uhd device object. 00490 * \return the multi usrp device object 00491 */ 00492 virtual uhd::usrp::multi_usrp::sptr get_device(void) = 0; 00493 00494 /*! 00495 * Perform write on the user configuration register bus. These only exist if 00496 * the user has implemented custom setting registers in the device FPGA. 00497 * \param addr 8-bit register address 00498 * \param data 32-bit register value 00499 * \param mboard which motherboard to set the user register 00500 */ 00501 virtual void set_user_register(const uint8_t addr, const uint32_t data, size_t mboard = 0) = 0; 00502 00503 /*! 00504 * Convenience function for finite data acquisition. 00505 * This is not to be used with the scheduler; rather, 00506 * one can request samples from the USRP in python. 00507 * //TODO assumes fc32 00508 * \param nsamps the number of samples 00509 * \return a vector of complex float samples 00510 */ 00511 virtual std::vector<std::complex<float> > finite_acquisition(const size_t nsamps) = 0; 00512 00513 /*! 00514 * Convenience function for finite data acquisition. 00515 * This is the multi-channel version of finite_acquisition; 00516 * This is not to be used with the scheduler; rather, 00517 * one can request samples from the USRP in python. 00518 * //TODO assumes fc32 00519 * \param nsamps the number of samples per channel 00520 * \return a vector of buffers, where each buffer represents a channel 00521 */ 00522 virtual std::vector<std::vector<std::complex<float> > > finite_acquisition_v(const size_t nsamps) = 0; 00523 }; 00524 00525 #endif /* INCLUDED_GR_UHD_USRP_SOURCE_H */