3 * Copyright 2008 Free Software Foundation, Inc.
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
19 #ifndef INCLUDED_USRP2_H
20 #define INCLUDED_USRP2_H
22 #include <boost/shared_ptr.hpp>
23 #include <boost/utility.hpp>
26 #include <usrp2/rx_sample_handler.h>
27 #include <usrp2/tune_result.h>
31 * N.B., The interfaces described here are still in flux.
33 * We will keep all the code in the tree up-to-date with regard to changes
34 * here, but reserve the right to change this on a whim.
40 * Structure to hold properties of USRP2 hardware devices.
47 uint8_t fpga_md5sum[16];
48 uint8_t sw_md5sum[16];
51 typedef std::vector<props> props_vector_t;
54 * \brief Search the ethernet for all USRP2s or for a specific USRP2.
56 * \param ifc is the name of the OS ethernet interface (e.g., "eth0")
57 * \param mac_addr is the MAC address of the desired USRP2, or "" to search for all.
58 * mac_addr must be either a zero length string, "", or must be of the form
59 * "01:02:03:04:05:06" or "05:06".
61 * \returns a vector of properties, 1 entry for each matching USRP2 found.
63 props_vector_t find(const std::string &ifc, const std::string &mac_addr="");
67 class usrp2 : boost::noncopyable
70 static const unsigned int MAX_CHAN = 30;
73 * Shared pointer to this class
75 typedef boost::shared_ptr<usrp2> sptr;
78 * Static function to return an instance of usrp2 as a shared pointer
80 * \param ifc Network interface name, e.g., "eth0"
81 * \param addr Network mac address, e.g., "01:23:45:67:89:ab", "89:ab" or "".
82 * If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
83 * "" will autoselect a USRP2 if there is only a single one on the local ethernet.
85 static sptr make(const std::string &ifc, const std::string &addr="");
93 * Returns the MAC address associated with this USRP
95 std::string mac_addr();
98 * ----------------------------------------------------------------
99 * Rx configuration and control
100 * ----------------------------------------------------------------
105 * \param gain in dB (more or less)
107 bool set_rx_gain(double gain);
109 //! return minimum Rx gain
110 double rx_gain_min();
112 //! return maximum Rx gain
113 double rx_gain_max();
115 //! return Rx gain db_per_step
116 double rx_gain_db_per_step();
119 * Set receiver center frequency
121 bool set_rx_center_freq(double frequency, tune_result *result);
123 //! return minimum Rx center frequency
124 double rx_freq_min();
126 //! return maximum Rx center frequency
127 double rx_freq_max();
130 * Set receiver sample rate decimation
132 bool set_rx_decim(int decimation_factor);
134 //! Return current decimation factor
138 * Set receiver IQ magnitude scaling
140 bool set_rx_scale_iq(int scale_i, int scale_q);
143 * Set received sample format
145 * domain: complex or real
146 * type: floating, fixed point, or raw
147 * depth: bits per sample
149 * Sets format over the wire for samples from USRP2.
151 // bool set_rx_format(...);
154 * Start streaming receive mode. USRP2 will send a continuous stream of
155 * DSP pipeline samples to host. Call rx_samples(...) to access.
157 * \param channel Stream channel number (0-30)
158 * \param items_per_frame Number of 32-bit items per frame.
160 bool start_rx_streaming(unsigned int channel=0, unsigned int items_per_frame=0);
163 * Stop streaming receive mode.
165 bool stop_rx_streaming(unsigned int channel=0);
168 * \brief Receive data from the specified channel
169 * This method is used to receive all data: streaming or discrete.
171 bool rx_samples(unsigned int channel, rx_sample_handler *handler);
174 * Returns number of times receive overruns have occurred
176 unsigned int rx_overruns();
179 * Returns total number of missing frames from overruns.
181 unsigned int rx_missing();
184 * ----------------------------------------------------------------
185 * Tx configuration and control
186 * ----------------------------------------------------------------
190 * Set transmitter gain
192 bool set_tx_gain(double gain);
194 //! return minimum Tx gain
195 double tx_gain_min();
197 //! return maximum Tx gain
198 double tx_gain_max();
200 //! return Tx gain db_per_step
201 double tx_gain_db_per_step();
204 * Set transmitter center frequency
206 bool set_tx_center_freq(double frequency, tune_result *result);
208 //! return minimum Tx center frequency
209 double tx_freq_min();
211 //! return maximum Tx center frequency
212 double tx_freq_max();
215 * Set transmitter sample rate interpolation
217 bool set_tx_interp(int interpolation_factor);
219 //! Return current interpolation factor
223 * Set transmit IQ magnitude scaling
225 bool set_tx_scale_iq(int scale_i, int scale_q);
228 * Set transmit sample format
230 * domain: complex or real
231 * type: floating, fixed point, or raw
232 * depth: bits per sample
234 * Sets format over the wire for samples to USRP2.
236 // bool set_tx_format(...);
239 * \brief transmit complex<float> samples to USRP2
241 * \param channel specifies the channel to send them to
242 * \param samples are the samples to transmit. They should be in the range [-1.0, +1.0]
243 * \param nsamples is the number of samples to transmit
244 * \param metadata provides the timestamp and flags
246 * The complex<float> samples are converted to the appropriate
247 * "on the wire" representation, depending on the current USRP2
248 * configuration. Typically, this is big-endian 16-bit I & Q.
250 bool tx_32fc(unsigned int channel,
251 const std::complex<float> *samples,
253 const tx_metadata *metadata);
256 * \brief transmit complex<int16_t> samples to USRP2
258 * \param channel specifies the channel to send them to
259 * \param samples are the samples to transmit
260 * \param nsamples is the number of samples to transmit
261 * \param metadata provides the timestamp and flags
263 * The complex<int16_t> samples are converted to the appropriate
264 * "on the wire" representation, depending on the current USRP2
265 * configuration. Typically, this is big-endian 16-bit I & Q.
267 bool tx_16sc(unsigned int channel,
268 const std::complex<int16_t> *samples,
270 const tx_metadata *metadata);
273 * \brief transmit raw uint32_t data items to USRP2
275 * The caller is responsible for ensuring that the items are
276 * formatted appropriately for the USRP2 and its configuration.
277 * This method is used primarily by the system itself. Users
278 * should call tx_32fc or tx_16sc instead.
280 * \param channel specifies the channel to send them to
281 * \param items are the data items to transmit
282 * \param nitems is the number of items to transmit
283 * \param metadata provides the timestamp and flags
285 bool tx_raw(unsigned int channel,
286 const uint32_t *items,
288 const tx_metadata *metadata);
291 * ----------------------------------------------------------------
292 * miscellaneous methods
293 * ----------------------------------------------------------------
297 * \brief MIMO configuration
299 * \param flags from usrp2_mimo_config.h
308 * and optionally this:
310 * MC_PROVIDE_CLK_TO_MIMO
313 bool config_mimo(int flags);
316 //! Get frequency of master oscillator in Hz
317 bool fpga_master_clock_freq(long *freq);
319 // Get Sampling rate of A/D converter in Hz
320 bool adc_rate(long *rate);
322 // Get Sampling rate of D/A converter in Hz
323 bool dac_rate(long *rate);
326 * \brief Get Tx daughterboard ID
328 * \param[out] dbid returns the daughterboard id.
330 * daughterboard id >= 0 if successful, -1 if no daugherboard installed,
331 * -2 if invalid EEPROM on daughterboard.
333 bool tx_daughterboard_id(int *dbid);
336 * \brief Get Rx daughterboard ID
338 * \param[out] dbid returns the daughterboard id.
340 * daughterboard id >= 0 if successful, -1 if no daugherboard installed,
341 * -2 if invalid EEPROM on daughterboard.
343 bool rx_daughterboard_id(int *dbid);
346 * ----------------------------------------------------------------
348 * ----------------------------------------------------------------
352 * Burn new mac address into EEPROM on USRP2
354 * \param new_addr Network mac address, e.g., "01:23:45:67:89:ab" or "89:ab".
355 * If \p addr is HH:HH, it's treated as if it were 00:50:c2:85:HH:HH
357 bool burn_mac_addr(const std::string &new_addr);
360 * Reset master time to 0 at next PPS rising edge
365 * Read memory from Wishbone bus
367 * \param addr 32-bit aligned address. Only the lower 16-bits are significant.
368 * \param len Number of bytes to read, must be positive and multiple of 4.
370 * \returns Vector of 8-bit read values
372 * WARNING: Attempts to read memory from addresses that do not correspond to RAM or
373 * memory-mapped peripherals may cause the USRP2 to hang, requiring a power cycle.
376 std::vector<uint8_t> peek(uint32_t addr, uint32_t len);
379 #if 0 // not yet implemented
381 * \brief Write EEPROM on motherboard or any daughterboard.
382 * \param i2c_addr I2C bus address of EEPROM
383 * \param eeprom_offset byte offset in EEPROM to begin writing
384 * \param buf the data to write
385 * \returns true iff sucessful
387 bool write_eeprom (int i2c_addr, int eeprom_offset, const std::string &buf);
390 * \brief Read EEPROM on motherboard or any daughterboard.
391 * \param i2c_addr I2C bus address of EEPROM
392 * \param eeprom_offset byte offset in EEPROM to begin reading
393 * \param len number of bytes to read
394 * \returns the data read if successful, else a zero length string.
396 std::string read_eeprom (int i2c_addr, int eeprom_offset, int len);
399 * \brief Write to I2C peripheral
400 * \param i2c_addr I2C bus address (7-bits)
401 * \param buf the data to write
402 * \returns true iff successful
403 * Writes are limited to a maximum of of 64 bytes.
405 bool write_i2c (int i2c_addr, const std::string &buf);
408 * \brief Read from I2C peripheral
409 * \param i2c_addr I2C bus address (7-bits)
410 * \param len number of bytes to read
411 * \returns the data read if successful, else a zero length string.
412 * Reads are limited to a maximum of 64 bytes.
414 std::string read_i2c (int i2c_addr, int len);
417 * \brief Write data to SPI bus peripheral.
419 * \param optional_header 0,1 or 2 bytes to write before buf.
420 * \param enables bitmask of peripherals to write. See usrp_spi_defs.h
421 * \param format transaction format. See usrp_spi_defs.h SPI_FMT_*
422 * \param buf the data to write
423 * \returns true iff successful
424 * Writes are limited to a maximum of 64 bytes.
426 * If \p format specifies that optional_header bytes are present, they are
427 * written to the peripheral immediately prior to writing \p buf.
429 bool write_spi (int optional_header, int enables, int format, const std::string &buf);
432 * \brief Read data from SPI bus peripheral.
434 * \param optional_header 0,1 or 2 bytes to write before buf.
435 * \param enables bitmask of peripheral to read. See usrp_spi_defs.h
436 * \param format transaction format. See usrp_spi_defs.h SPI_FMT_*
437 * \param len number of bytes to read. Must be in [0,64].
438 * \returns the data read if sucessful, else a zero length string.
440 * Reads are limited to a maximum of 64 bytes.
442 * If \p format specifies that optional_header bytes are present, they
443 * are written to the peripheral first. Then \p len bytes are read from
444 * the peripheral and returned.
446 std::string read_spi (int optional_header, int enables, int format, int len);
450 class impl; // implementation details
453 // Static function to retrieve or create usrp2 instance
454 static sptr find_existing_or_make_new(const std::string &ifc, props *p);
456 // Only class members can instantiate this class
457 usrp2(const std::string &ifc, props *p);
459 // All private state is held in opaque pointer
460 std::auto_ptr<impl> d_impl;
465 std::ostream& operator<<(std::ostream &os, const usrp2::props &x);
468 #endif /* INCLUDED_USRP2_H */