SoapySDR  0.4.4-gdb459f4f
Vendor and platform neutral SDR interface library
Public Member Functions | Static Public Member Functions | List of all members
SoapySDR::Device Class Reference

#include <Device.hpp>

Public Member Functions

virtual ~Device (void)
 virtual destructor for inheritance More...
 
virtual std::string getDriverKey (void) const
 
virtual std::string getHardwareKey (void) const
 
virtual Kwargs getHardwareInfo (void) const
 
virtual void setFrontendMapping (const int direction, const std::string &mapping)
 
virtual std::string getFrontendMapping (const int direction) const
 
virtual size_t getNumChannels (const int direction) const
 
virtual bool getFullDuplex (const int direction, const size_t channel) const
 
virtual std::vector< std::string > getStreamFormats (const int direction, const size_t channel) const
 
virtual std::string getNativeStreamFormat (const int direction, const size_t channel, double &fullScale) const
 
virtual ArgInfoList getStreamArgsInfo (const int direction, const size_t channel) const
 
virtual Stream * setupStream (const int direction, const std::string &format, const std::vector< size_t > &channels=std::vector< size_t >(), const Kwargs &args=Kwargs())
 
virtual void closeStream (Stream *stream)
 
virtual size_t getStreamMTU (Stream *stream) const
 
virtual int activateStream (Stream *stream, const int flags=0, const long long timeNs=0, const size_t numElems=0)
 
virtual int deactivateStream (Stream *stream, const int flags=0, const long long timeNs=0)
 
virtual int readStream (Stream *stream, void *const *buffs, const size_t numElems, int &flags, long long &timeNs, const long timeoutUs=100000)
 
virtual int writeStream (Stream *stream, const void *const *buffs, const size_t numElems, int &flags, const long long timeNs=0, const long timeoutUs=100000)
 
virtual int readStreamStatus (Stream *stream, size_t &chanMask, int &flags, long long &timeNs, const long timeoutUs=100000)
 
virtual size_t getNumDirectAccessBuffers (Stream *stream)
 
virtual int getDirectAccessBufferAddrs (Stream *stream, const size_t handle, void **buffs)
 
virtual int acquireReadBuffer (Stream *stream, size_t &handle, const void **buffs, int &flags, long long &timeNs, const long timeoutUs=100000)
 
virtual void releaseReadBuffer (Stream *stream, const size_t handle)
 
virtual int acquireWriteBuffer (Stream *stream, size_t &handle, void **buffs, const long timeoutUs=100000)
 
virtual void releaseWriteBuffer (Stream *stream, const size_t handle, const size_t numElems, int &flags, const long long timeNs=0)
 
virtual std::vector< std::string > listAntennas (const int direction, const size_t channel) const
 
virtual void setAntenna (const int direction, const size_t channel, const std::string &name)
 
virtual std::string getAntenna (const int direction, const size_t channel) const
 
virtual bool hasDCOffsetMode (const int direction, const size_t channel) const
 
virtual void setDCOffsetMode (const int direction, const size_t channel, const bool automatic)
 
virtual bool getDCOffsetMode (const int direction, const size_t channel) const
 
virtual bool hasDCOffset (const int direction, const size_t channel) const
 
virtual void setDCOffset (const int direction, const size_t channel, const std::complex< double > &offset)
 
virtual std::complex< double > getDCOffset (const int direction, const size_t channel) const
 
virtual bool hasIQBalance (const int direction, const size_t channel) const
 
virtual void setIQBalance (const int direction, const size_t channel, const std::complex< double > &balance)
 
virtual std::complex< double > getIQBalance (const int direction, const size_t channel) const
 
virtual std::vector< std::string > listGains (const int direction, const size_t channel) const
 
virtual bool hasGainMode (const int direction, const size_t channel) const
 
virtual void setGainMode (const int direction, const size_t channel, const bool automatic)
 
virtual bool getGainMode (const int direction, const size_t channel) const
 
virtual void setGain (const int direction, const size_t channel, const double value)
 
virtual void setGain (const int direction, const size_t channel, const std::string &name, const double value)
 
virtual double getGain (const int direction, const size_t channel) const
 
virtual double getGain (const int direction, const size_t channel, const std::string &name) const
 
virtual Range getGainRange (const int direction, const size_t channel) const
 
virtual Range getGainRange (const int direction, const size_t channel, const std::string &name) const
 
virtual void setFrequency (const int direction, const size_t channel, const double frequency, const Kwargs &args=Kwargs())
 
virtual void setFrequency (const int direction, const size_t channel, const std::string &name, const double frequency, const Kwargs &args=Kwargs())
 
virtual double getFrequency (const int direction, const size_t channel) const
 
virtual double getFrequency (const int direction, const size_t channel, const std::string &name) const
 
virtual std::vector< std::string > listFrequencies (const int direction, const size_t channel) const
 
virtual RangeList getFrequencyRange (const int direction, const size_t channel) const
 
virtual RangeList getFrequencyRange (const int direction, const size_t channel, const std::string &name) const
 
virtual ArgInfoList getFrequencyArgsInfo (const int direction, const size_t channel) const
 
virtual void setSampleRate (const int direction, const size_t channel, const double rate)
 
virtual double getSampleRate (const int direction, const size_t channel) const
 
virtual std::vector< double > listSampleRates (const int direction, const size_t channel) const
 
virtual void setBandwidth (const int direction, const size_t channel, const double bw)
 
virtual double getBandwidth (const int direction, const size_t channel) const
 
virtual std::vector< double > listBandwidths (const int direction, const size_t channel) const
 
virtual void setMasterClockRate (const double rate)
 
virtual double getMasterClockRate (void) const
 
virtual RangeList getMasterClockRates (void) const
 
virtual std::vector< std::string > listClockSources (void) const
 
virtual void setClockSource (const std::string &source)
 
virtual std::string getClockSource (void) const
 
virtual std::vector< std::string > listTimeSources (void) const
 
virtual void setTimeSource (const std::string &source)
 
virtual std::string getTimeSource (void) const
 
virtual bool hasHardwareTime (const std::string &what="") const
 
virtual long long getHardwareTime (const std::string &what="") const
 
virtual void setHardwareTime (const long long timeNs, const std::string &what="")
 
virtual void setCommandTime (const long long timeNs, const std::string &what="")
 
virtual std::vector< std::string > listSensors (void) const
 
virtual ArgInfo getSensorInfo (const std::string &name) const
 
virtual std::string readSensor (const std::string &name) const
 
virtual std::vector< std::string > listSensors (const int direction, const size_t channel) const
 
virtual ArgInfo getSensorInfo (const int direction, const size_t channel, const std::string &name) const
 
virtual std::string readSensor (const int direction, const size_t channel, const std::string &name) const
 
virtual void writeRegister (const unsigned addr, const unsigned value)
 
virtual unsigned readRegister (const unsigned addr) const
 
virtual ArgInfoList getSettingInfo (void) const
 
virtual void writeSetting (const std::string &key, const std::string &value)
 
virtual std::string readSetting (const std::string &key) const
 
virtual std::vector< std::string > listGPIOBanks (void) const
 
virtual void writeGPIO (const std::string &bank, const unsigned value)
 
virtual void writeGPIO (const std::string &bank, const unsigned value, const unsigned mask)
 
virtual unsigned readGPIO (const std::string &bank) const
 
virtual void writeGPIODir (const std::string &bank, const unsigned dir)
 
virtual void writeGPIODir (const std::string &bank, const unsigned dir, const unsigned mask)
 
virtual unsigned readGPIODir (const std::string &bank) const
 
virtual void writeI2C (const int addr, const std::string &data)
 
virtual std::string readI2C (const int addr, const size_t numBytes)
 
virtual unsigned transactSPI (const int addr, const unsigned data, const size_t numBits)
 
virtual std::vector< std::string > listUARTs (void) const
 
virtual void writeUART (const std::string &which, const std::string &data)
 
virtual std::string readUART (const std::string &which, const long timeoutUs=100000) const
 

Static Public Member Functions

static KwargsList enumerate (const Kwargs &args=Kwargs())
 
static KwargsList enumerate (const std::string &args)
 
static Devicemake (const Kwargs &args=Kwargs())
 
static Devicemake (const std::string &args)
 
static void unmake (Device *device)
 

Detailed Description

Abstraction for an SDR tranceiver device - configuration and streaming.

Constructor & Destructor Documentation

virtual SoapySDR::Device::~Device ( void  )
virtual

virtual destructor for inheritance

Member Function Documentation

virtual int SoapySDR::Device::acquireReadBuffer ( Stream *  stream,
size_t &  handle,
const void **  buffs,
int &  flags,
long long &  timeNs,
const long  timeoutUs = 100000 
)
virtual

Acquire direct buffers from a receive stream. This call is part of the direct buffer access API.

The buffs array will be filled with a stream pointer for each channel. Each pointer can be read up to the number of return value elements.

The handle will be set by the implementation so that the caller may later release access to the buffers with releaseReadBuffer(). Handle represents an index into the internal scatter/gather table such that handle is between 0 and num direct buffers - 1.

Parameters
streamthe opaque pointer to a stream handle
handlean index value used in the release() call
buffsan array of void* buffers num chans in size
flagsoptional flag indicators about the result
timeNsthe buffer's timestamp in nanoseconds
timeoutUsthe timeout in microseconds
Returns
the number of elements read per buffer or error code
virtual int SoapySDR::Device::acquireWriteBuffer ( Stream *  stream,
size_t &  handle,
void **  buffs,
const long  timeoutUs = 100000 
)
virtual

Acquire direct buffers from a transmit stream. This call is part of the direct buffer access API.

The buffs array will be filled with a stream pointer for each channel. Each pointer can be written up to the number of return value elements.

The handle will be set by the implementation so that the caller may later release access to the buffers with releaseWriteBuffer(). Handle represents an index into the internal scatter/gather table such that handle is between 0 and num direct buffers - 1.

Parameters
streamthe opaque pointer to a stream handle
handlean index value used in the release() call
buffsan array of void* buffers num chans in size
flagsoptional input flags and output flags
timeNsthe buffer's timestamp in nanoseconds
timeoutUsthe timeout in microseconds
Returns
the number of available elements per buffer or error
virtual int SoapySDR::Device::activateStream ( Stream *  stream,
const int  flags = 0,
const long long  timeNs = 0,
const size_t  numElems = 0 
)
virtual

Activate a stream. Call activate to prepare a stream before using read/write(). The implementation control switches or stimulate data flow.

The timeNs is only valid when the flags have SOAPY_SDR_HAS_TIME. The numElems count can be used to request a finite burst size. The SOAPY_SDR_END_BURST flag can signal end on the finite burst. Not all implementations will support the full range of options. In this case, the implementation returns SOAPY_SDR_NOT_SUPPORTED.

Parameters
streamthe opaque pointer to a stream handle
flagsoptional flag indicators about the stream
timeNsoptional activation time in nanoseconds
numElemsoptional element count for burst control
Returns
0 for success or error code on failure
virtual void SoapySDR::Device::closeStream ( Stream *  stream)
virtual

Close an open stream created by setupStream The implementation may change switches or power-down components.

Parameters
streamthe opaque pointer to a stream handle
virtual int SoapySDR::Device::deactivateStream ( Stream *  stream,
const int  flags = 0,
const long long  timeNs = 0 
)
virtual

Deactivate a stream. Call deactivate when not using using read/write(). The implementation control switches or halt data flow.

The timeNs is only valid when the flags have SOAPY_SDR_HAS_TIME. Not all implementations will support the full range of options. In this case, the implementation returns SOAPY_SDR_NOT_SUPPORTED.

Parameters
streamthe opaque pointer to a stream handle
flagsoptional flag indicators about the stream
timeNsoptional deactivation time in nanoseconds
Returns
0 for success or error code on failure
static KwargsList SoapySDR::Device::enumerate ( const Kwargs args = Kwargs())
static

Enumerate a list of available devices on the system.

Parameters
argsdevice construction key/value argument filters
Returns
a list of argument maps, each unique to a device
static KwargsList SoapySDR::Device::enumerate ( const std::string &  args)
static

Enumerate a list of available devices on the system. Markup format for args: "keyA=valA, keyB=valB".

Parameters
argsa markup string of key/value argument filters
Returns
a list of argument maps, each unique to a device
virtual std::string SoapySDR::Device::getAntenna ( const int  direction,
const size_t  channel 
) const
virtual

Get the selected antenna on a chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
the name of an available antenna
virtual double SoapySDR::Device::getBandwidth ( const int  direction,
const size_t  channel 
) const
virtual

Get the baseband filter width of the chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
the baseband filter width in Hz
virtual std::string SoapySDR::Device::getClockSource ( void  ) const
virtual

Get the clock source of the device

Returns
the name of a clock source
virtual std::complex<double> SoapySDR::Device::getDCOffset ( const int  direction,
const size_t  channel 
) const
virtual

Get the frontend DC offset correction.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
the relative correction (1.0 max)
virtual bool SoapySDR::Device::getDCOffsetMode ( const int  direction,
const size_t  channel 
) const
virtual

Get the automatic DC offset corrections mode.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true for automatic offset correction
virtual int SoapySDR::Device::getDirectAccessBufferAddrs ( Stream *  stream,
const size_t  handle,
void **  buffs 
)
virtual

Get the buffer addresses for a scatter/gather table entry. When the underlying DMA implementation uses scatter/gather then this call provides the user addresses for that table.

Example: The caller may query the DMA memory addresses once after stream creation to pre-allocate a re-usable ring-buffer.

Parameters
streamthe opaque pointer to a stream handle
handlean index value between 0 and num direct buffers - 1
buffsan array of void* buffers num chans in size
Returns
0 for success or error code when not supported
virtual std::string SoapySDR::Device::getDriverKey ( void  ) const
virtual

A key that uniquely identifies the device driver. This key identifies the underlying implementation. Serveral variants of a product may share a driver.

virtual double SoapySDR::Device::getFrequency ( const int  direction,
const size_t  channel 
) const
virtual

Get the overall center frequency of the chain.

  • For RX, this specifies the down-conversion frequency.
  • For TX, this specifies the up-conversion frequency.
    Parameters
    directionthe channel direction RX or TX
    channelan available channel on the device
    Returns
    the center frequency in Hz
virtual double SoapySDR::Device::getFrequency ( const int  direction,
const size_t  channel,
const std::string &  name 
) const
virtual

Get the frequency of a tunable element in the chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of a tunable element
Returns
the tunable element's frequency in Hz
virtual ArgInfoList SoapySDR::Device::getFrequencyArgsInfo ( const int  direction,
const size_t  channel 
) const
virtual

Query the argument info description for tune args.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
a list of argument info structures
virtual RangeList SoapySDR::Device::getFrequencyRange ( const int  direction,
const size_t  channel 
) const
virtual

Get the range of overall frequency values.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
a list of frequency ranges in Hz
virtual RangeList SoapySDR::Device::getFrequencyRange ( const int  direction,
const size_t  channel,
const std::string &  name 
) const
virtual

Get the range of tunable values for the specified element.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of a tunable element
Returns
a list of frequency ranges in Hz
virtual std::string SoapySDR::Device::getFrontendMapping ( const int  direction) const
virtual

Get the mapping configuration string.

Parameters
directionthe channel direction RX or TX
thevendor-specific mapping string
virtual bool SoapySDR::Device::getFullDuplex ( const int  direction,
const size_t  channel 
) const
virtual

Find out if the specified channel is full or half duplex.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true for full duplex, false for half duplex
virtual double SoapySDR::Device::getGain ( const int  direction,
const size_t  channel 
) const
virtual

Get the overall value of the gain elements in a chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
the value of the gain in dB
virtual double SoapySDR::Device::getGain ( const int  direction,
const size_t  channel,
const std::string &  name 
) const
virtual

Get the value of an individual amplification element in a chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of an amplification element
Returns
the value of the gain in dB
virtual bool SoapySDR::Device::getGainMode ( const int  direction,
const size_t  channel 
) const
virtual

Get the automatic gain mode on the chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true for automatic gain setting
virtual Range SoapySDR::Device::getGainRange ( const int  direction,
const size_t  channel 
) const
virtual

Get the overall range of possible gain values.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
a list of gain ranges in dB
virtual Range SoapySDR::Device::getGainRange ( const int  direction,
const size_t  channel,
const std::string &  name 
) const
virtual

Get the range of possible gain values for a specific element.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of an amplification element
Returns
a list of gain ranges in dB
virtual Kwargs SoapySDR::Device::getHardwareInfo ( void  ) const
virtual

Query a dictionary of available device information. This dictionary can any number of values like vendor name, product name, revisions, serials... This information can be displayed to the user to help identify the instantiated device.

virtual std::string SoapySDR::Device::getHardwareKey ( void  ) const
virtual

A key that uniquely identifies the hardware. This key should be meaningful to the user to optimize for the underlying hardware.

virtual long long SoapySDR::Device::getHardwareTime ( const std::string &  what = "") const
virtual

Read the time from the hardware clock on the device. The what argument can refer to a specific time counter.

Parameters
whatoptional argument
Returns
the time in nanoseconds
virtual std::complex<double> SoapySDR::Device::getIQBalance ( const int  direction,
const size_t  channel 
) const
virtual

Get the frontend IQ balance correction.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
the relative correction (1.0 max)
virtual double SoapySDR::Device::getMasterClockRate ( void  ) const
virtual

Get the master clock rate of the device.

Returns
the clock rate in Hz
virtual RangeList SoapySDR::Device::getMasterClockRates ( void  ) const
virtual

Get the range of available master clock rates.

Returns
a list of clock rate ranges in Hz
virtual std::string SoapySDR::Device::getNativeStreamFormat ( const int  direction,
const size_t  channel,
double &  fullScale 
) const
virtual

Get the hardware's native stream format for this channel. This is the format used by the underlying transport layer, and the direct buffer access API calls (when available).

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
[out]fullScalethe maximum possible value
Returns
the native stream buffer format string
virtual size_t SoapySDR::Device::getNumChannels ( const int  direction) const
virtual

Get a number of channels given the streaming direction

virtual size_t SoapySDR::Device::getNumDirectAccessBuffers ( Stream *  stream)
virtual

How many direct access buffers can the stream provide? This is the number of times the user can call acquire() on a stream without making subsequent calls to release(). A return value of 0 means that direct access is not supported.

Parameters
streamthe opaque pointer to a stream handle
Returns
the number of direct access buffers or 0
virtual double SoapySDR::Device::getSampleRate ( const int  direction,
const size_t  channel 
) const
virtual

Get the baseband sample rate of the chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
the sample rate in samples per second
virtual ArgInfo SoapySDR::Device::getSensorInfo ( const std::string &  name) const
virtual

Get meta-information about a sensor. Example: displayable name, type, range.

Parameters
namethe name of an available sensor
Returns
meta-information about a sensor
virtual ArgInfo SoapySDR::Device::getSensorInfo ( const int  direction,
const size_t  channel,
const std::string &  name 
) const
virtual

Get meta-information about a channel sensor. Example: displayable name, type, range.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of an available sensor
Returns
meta-information about a sensor
virtual ArgInfoList SoapySDR::Device::getSettingInfo ( void  ) const
virtual

Describe the allowed keys and values used for settings.

Returns
a list of argument info structures
virtual ArgInfoList SoapySDR::Device::getStreamArgsInfo ( const int  direction,
const size_t  channel 
) const
virtual

Query the argument info description for stream args.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
a list of argument info structures
virtual std::vector<std::string> SoapySDR::Device::getStreamFormats ( const int  direction,
const size_t  channel 
) const
virtual

Query a list of the available stream formats.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
a list of allowed format strings
virtual size_t SoapySDR::Device::getStreamMTU ( Stream *  stream) const
virtual

Get the stream's maximum transmission unit (MTU) in number of elements. The MTU specifies the maximum payload transfer in a stream operation. This value can be used as a stream buffer allocation size that can best optimize throughput given the underlying stream implementation.

Parameters
streamthe opaque pointer to a stream handle
Returns
the MTU in number of stream elements (never zero)
virtual std::string SoapySDR::Device::getTimeSource ( void  ) const
virtual

Get the time source of the device

Returns
the name of a time source
virtual bool SoapySDR::Device::hasDCOffset ( const int  direction,
const size_t  channel 
) const
virtual

Does the device support frontend DC offset correction?

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true if DC offset corrections are supported
virtual bool SoapySDR::Device::hasDCOffsetMode ( const int  direction,
const size_t  channel 
) const
virtual

Does the device support automatic DC offset corrections?

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true if automatic corrections are supported
virtual bool SoapySDR::Device::hasGainMode ( const int  direction,
const size_t  channel 
) const
virtual

Does the device support automatic gain control?

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true for automatic gain control
virtual bool SoapySDR::Device::hasHardwareTime ( const std::string &  what = "") const
virtual

Does this device have a hardware clock?

Parameters
whatoptional argument
Returns
true if the hardware clock exists
virtual bool SoapySDR::Device::hasIQBalance ( const int  direction,
const size_t  channel 
) const
virtual

Does the device support frontend IQ balance correction?

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true if IQ balance corrections are supported
virtual std::vector<std::string> SoapySDR::Device::listAntennas ( const int  direction,
const size_t  channel 
) const
virtual

Get a list of available antennas to select on a given chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
a list of available antenna names
virtual std::vector<double> SoapySDR::Device::listBandwidths ( const int  direction,
const size_t  channel 
) const
virtual

Get the range of possible baseband filter widths.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
a list of possible bandwidths in Hz
virtual std::vector<std::string> SoapySDR::Device::listClockSources ( void  ) const
virtual

Get the list of available clock sources.

Returns
a list of clock source names
virtual std::vector<std::string> SoapySDR::Device::listFrequencies ( const int  direction,
const size_t  channel 
) const
virtual

List available tunable elements in the chain. Elements should be in order RF to baseband.

Parameters
directionthe channel direction RX or TX
channelan available channel
Returns
a list of tunable elements by name
virtual std::vector<std::string> SoapySDR::Device::listGains ( const int  direction,
const size_t  channel 
) const
virtual

List available amplification elements. Elements should be in order RF to baseband.

Parameters
directionthe channel direction RX or TX
channelan available channel
Returns
a list of gain string names
virtual std::vector<std::string> SoapySDR::Device::listGPIOBanks ( void  ) const
virtual

Get a list of available GPIO banks by name.

virtual std::vector<double> SoapySDR::Device::listSampleRates ( const int  direction,
const size_t  channel 
) const
virtual

Get the range of possible baseband sample rates.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
a list of possible rates in samples per second
virtual std::vector<std::string> SoapySDR::Device::listSensors ( void  ) const
virtual

List the available global readback sensors. A sensor can represent a reference lock, RSSI, temperature.

Returns
a list of available sensor string names
virtual std::vector<std::string> SoapySDR::Device::listSensors ( const int  direction,
const size_t  channel 
) const
virtual

List the available channel readback sensors. A sensor can represent a reference lock, RSSI, temperature.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
Returns
a list of available sensor string names
virtual std::vector<std::string> SoapySDR::Device::listTimeSources ( void  ) const
virtual

Get the list of available time sources.

Returns
a list of time source names
virtual std::vector<std::string> SoapySDR::Device::listUARTs ( void  ) const
virtual

Enumerate the available UART devices.

Returns
a list of names of available UARTs
static Device* SoapySDR::Device::make ( const Kwargs args = Kwargs())
static

Make a new Device object given device construction args. The device pointer will be stored in a table so subsequent calls with the same arguments will produce the same device. For every call to make, there should be a matched call to unmake.

Note
This call is not thread safe. Implementations calling into make from multiple threads should protect this call with a mutex.
Parameters
argsdevice construction key/value argument map
Returns
a pointer to a new Device object
static Device* SoapySDR::Device::make ( const std::string &  args)
static

Make a new Device object given device construction args. The device pointer will be stored in a table so subsequent calls with the same arguments will produce the same device. For every call to make, there should be a matched call to unmake.

Note
This call is not thread safe. Implementations calling into make from multiple threads should protect this call with a mutex.
Parameters
argsa markup string of key/value arguments
Returns
a pointer to a new Device object
virtual unsigned SoapySDR::Device::readGPIO ( const std::string &  bank) const
virtual

Readback the value of a GPIO bank.

Parameters
bankthe name of an available bank
Returns
an integer representing GPIO bits
virtual unsigned SoapySDR::Device::readGPIODir ( const std::string &  bank) const
virtual

Read the data direction of a GPIO bank. 1 bits represent outputs, 0 bits represent inputs.

Parameters
bankthe name of an available bank
Returns
an integer representing data direction bits
virtual std::string SoapySDR::Device::readI2C ( const int  addr,
const size_t  numBytes 
)
virtual

Read from an available I2C slave. If the device contains multiple I2C masters, the address bits can encode which master.

Parameters
addrthe address of the slave
numBytesthe number of bytes to read
Returns
an array of bytes read from the slave
virtual unsigned SoapySDR::Device::readRegister ( const unsigned  addr) const
virtual

Read a register on the device.

Parameters
addrthe register address
Returns
the register value
virtual std::string SoapySDR::Device::readSensor ( const std::string &  name) const
virtual

Readback a global sensor given the name. The value returned is a string which can represent a boolean ("true"/"false"), an integer, or float.

Parameters
namethe name of an available sensor
Returns
the current value of the sensor
virtual std::string SoapySDR::Device::readSensor ( const int  direction,
const size_t  channel,
const std::string &  name 
) const
virtual

Readback a channel sensor given the name. The value returned is a string which can represent a boolean ("true"/"false"), an integer, or float.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of an available sensor
Returns
the current value of the sensor
virtual std::string SoapySDR::Device::readSetting ( const std::string &  key) const
virtual

Read an arbitrary setting on the device.

Parameters
keythe setting identifier
Returns
the setting value
virtual int SoapySDR::Device::readStream ( Stream *  stream,
void *const *  buffs,
const size_t  numElems,
int &  flags,
long long &  timeNs,
const long  timeoutUs = 100000 
)
virtual

Read elements from a stream for reception. This is a multi-channel call, and buffs should be an array of void *, where each pointer will be filled with data from a different channel.

Client code compatibility: The readStream() call should be well defined at all times, including prior to activation and after deactivation. When inactive, readStream() should implement the timeout specified by the caller and return SOAPY_SDR_TIMEOUT.

Parameters
streamthe opaque pointer to a stream handle
buffsan array of void* buffers num chans in size
numElemsthe number of elements in each buffer
flagsoptional flag indicators about the result
timeNsthe buffer's timestamp in nanoseconds
timeoutUsthe timeout in microseconds
Returns
the number of elements read per buffer or error code
virtual int SoapySDR::Device::readStreamStatus ( Stream *  stream,
size_t &  chanMask,
int &  flags,
long long &  timeNs,
const long  timeoutUs = 100000 
)
virtual

Readback status information about a stream. This call is typically used on a transmit stream to report time errors, underflows, and burst completion.

Client code compatibility: Client code may continually poll readStreamStatus() in a loop. Implementations of readStreamStatus() should wait in the call for a status change event or until the timeout expiration. When stream status is not implemented on a particular stream, readStreamStatus() should return SOAPY_SDR_NOT_SUPPORTED. Client code may use this indication to disable a polling loop.

Parameters
streamthe opaque pointer to a stream handle
chanMaskto which channels this status applies
flagsoptional input flags and output flags
timeNsthe buffer's timestamp in nanoseconds
timeoutUsthe timeout in microseconds
Returns
0 for success or error code like timeout
virtual std::string SoapySDR::Device::readUART ( const std::string &  which,
const long  timeoutUs = 100000 
) const
virtual

Read bytes from a UART until timeout or newline. Its up to the implementation to set the baud rate, carriage return settings, flushing on newline.

Parameters
whichthe name of an available UART
timeoutUsa timeout in microseconds
Returns
an array of bytes read from the UART
virtual void SoapySDR::Device::releaseReadBuffer ( Stream *  stream,
const size_t  handle 
)
virtual

Release an acquired buffer back to the receive stream. This call is part of the direct buffer access API.

Parameters
streamthe opaque pointer to a stream handle
handlethe opaque handle from the acquire() call
virtual void SoapySDR::Device::releaseWriteBuffer ( Stream *  stream,
const size_t  handle,
const size_t  numElems,
int &  flags,
const long long  timeNs = 0 
)
virtual

Release an acquired buffer back to the transmit stream. This call is part of the direct buffer access API.

Stream meta-data is provided as part of the release call, and not the acquire call so that the caller may acquire buffers without committing to the contents of the meta-data, which can be determined by the user as the buffers are filled.

Parameters
streamthe opaque pointer to a stream handle
handlethe opaque handle from the acquire() call
numElemsthe number of elements written to each buffer
flagsoptional input flags and output flags
timeNsthe buffer's timestamp in nanoseconds
virtual void SoapySDR::Device::setAntenna ( const int  direction,
const size_t  channel,
const std::string &  name 
)
virtual

Set the selected antenna on a chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of an available antenna
virtual void SoapySDR::Device::setBandwidth ( const int  direction,
const size_t  channel,
const double  bw 
)
virtual

Set the baseband filter width of the chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
bwthe baseband filter width in Hz
virtual void SoapySDR::Device::setClockSource ( const std::string &  source)
virtual

Set the clock source on the device

Parameters
sourcethe name of a clock source
virtual void SoapySDR::Device::setCommandTime ( const long long  timeNs,
const std::string &  what = "" 
)
virtual

Set the time of subsequent configuration calls. The what argument can refer to a specific command queue. Implementations may use a time of 0 to clear.

Parameters
timeNstime in nanoseconds
whatoptional argument
virtual void SoapySDR::Device::setDCOffset ( const int  direction,
const size_t  channel,
const std::complex< double > &  offset 
)
virtual

Set the frontend DC offset correction.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
offsetthe relative correction (1.0 max)
virtual void SoapySDR::Device::setDCOffsetMode ( const int  direction,
const size_t  channel,
const bool  automatic 
)
virtual

Set the automatic DC offset corrections mode.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
automatictrue for automatic offset correction
virtual void SoapySDR::Device::setFrequency ( const int  direction,
const size_t  channel,
const double  frequency,
const Kwargs args = Kwargs() 
)
virtual

Set the center frequency of the chain.

  • For RX, this specifies the down-conversion frequency.
  • For TX, this specifies the up-conversion frequency.

The default implementation of setFrequency() will tune the "RF" component as close as possible to the requested center frequency. Tuning inaccuracies will be compensated for with the "BB" component.

The args can be used to augment the tuning algorithm.

  • Use "OFFSET" to specify an "RF" tuning offset, usually with the intention of moving the LO out of the passband. The offset will be compensated for using the "BB" component.
  • Use the name of a component for the key and a frequency in Hz as the value (any format) to enforce a specific frequency. The other components will be tuned with compensation to achieve the specified overall frequency.
  • Use the name of a component for the key and the value "IGNORE" so that the tuning algorithm will avoid altering the component.
  • Vendor specific implementations can also use the same args to augment tuning in other ways such as specifying fractional vs integer N tuning.
Parameters
directionthe channel direction RX or TX
channelan available channel on the device
frequencythe center frequency in Hz
argsoptional tuner arguments
virtual void SoapySDR::Device::setFrequency ( const int  direction,
const size_t  channel,
const std::string &  name,
const double  frequency,
const Kwargs args = Kwargs() 
)
virtual

Tune the center frequency of the specified element.

  • For RX, this specifies the down-conversion frequency.
  • For TX, this specifies the up-conversion frequency.

Recommended names used to represent tunable components:

  • "CORR" - freq error correction in PPM
  • "RF" - frequency of the RF frontend
  • "BB" - frequency of the baseband DSP
Parameters
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of a tunable element
frequencythe center frequency in Hz
argsoptional tuner arguments
virtual void SoapySDR::Device::setFrontendMapping ( const int  direction,
const std::string &  mapping 
)
virtual

Set the frontend mapping of available DSP units to RF frontends. This mapping controls channel mapping and channel availability.

Parameters
directionthe channel direction RX or TX
mappinga vendor-specific mapping string
virtual void SoapySDR::Device::setGain ( const int  direction,
const size_t  channel,
const double  value 
)
virtual

Set the overall amplification in a chain. The gain will be distributed automatically across available element.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of an amplification element
valuethe new amplification value in dB
virtual void SoapySDR::Device::setGain ( const int  direction,
const size_t  channel,
const std::string &  name,
const double  value 
)
virtual

Set the value of a amplification element in a chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of an amplification element
valuethe new amplification value in dB
virtual void SoapySDR::Device::setGainMode ( const int  direction,
const size_t  channel,
const bool  automatic 
)
virtual

Set the automatic gain mode on the chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
automatictrue for automatic gain setting
virtual void SoapySDR::Device::setHardwareTime ( const long long  timeNs,
const std::string &  what = "" 
)
virtual

Write the time to the hardware clock on the device. The what argument can refer to a specific time counter.

Parameters
timeNstime in nanoseconds
whatoptional argument
virtual void SoapySDR::Device::setIQBalance ( const int  direction,
const size_t  channel,
const std::complex< double > &  balance 
)
virtual

Set the frontend IQ balance correction.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
balancethe relative correction (1.0 max)
virtual void SoapySDR::Device::setMasterClockRate ( const double  rate)
virtual

Set the master clock rate of the device.

Parameters
ratethe clock rate in Hz
virtual void SoapySDR::Device::setSampleRate ( const int  direction,
const size_t  channel,
const double  rate 
)
virtual

Set the baseband sample rate of the chain.

Parameters
directionthe channel direction RX or TX
channelan available channel on the device
ratethe sample rate in samples per second
virtual void SoapySDR::Device::setTimeSource ( const std::string &  source)
virtual

Set the time source on the device

Parameters
sourcethe name of a time source
virtual Stream* SoapySDR::Device::setupStream ( const int  direction,
const std::string &  format,
const std::vector< size_t > &  channels = std::vector< size_t >(),
const Kwargs args = Kwargs() 
)
virtual

Initialize a stream given a list of channels and stream arguments. The implementation may change switches or power-up components. All stream API calls should be usable with the new stream object after setupStream() is complete, regardless of the activity state.

Format string markup guidelines:

  • C means complex
  • F means floating point
  • S means signed integer
  • U means unsigned integer
  • number float/int size in bytes (complex is 2x this size)

Example format strings:

  • CF32 complex float32 (8 bytes per element)
  • CS16 complex int16 (4 bytes per element)
  • CS12 complex int12 (3 bytes per element)
  • CS4 complex int4 (1 byte per element)
  • S32 int32 (4 bytes per element)
  • U8 uint8 (1 byte per element)

Recommended keys to use in the args dictionary:

  • "WIRE" - format of the samples between device and host
Parameters
directionthe channel direction RX or TX
formatthe desired buffer format in read/writeStream()
channelsa list of channels for empty for automatic
argsstream args or empty for defaults
Returns
an opaque pointer to a stream handle
virtual unsigned SoapySDR::Device::transactSPI ( const int  addr,
const unsigned  data,
const size_t  numBits 
)
virtual

Perform a SPI transaction and return the result. Its up to the implementation to set the clock rate, and read edge, and the write edge of the SPI core. SPI slaves without a readback pin will return 0.

If the device contains multiple SPI masters, the address bits can encode which master.

Parameters
addran address of an available SPI slave
datathe SPI data, numBits-1 is first out
numBitsthe number of bits to clock out
Returns
the readback data, numBits-1 is first in
static void SoapySDR::Device::unmake ( Device device)
static

Unmake or release a device object handle.

Note
This call is not thread safe. Implementations calling into unmake from multiple threads should protect this call with a mutex.
Parameters
devicea pointer to a device object
virtual void SoapySDR::Device::writeGPIO ( const std::string &  bank,
const unsigned  value 
)
virtual

Write the value of a GPIO bank.

Parameters
bankthe name of an available bank
valuean integer representing GPIO bits
virtual void SoapySDR::Device::writeGPIO ( const std::string &  bank,
const unsigned  value,
const unsigned  mask 
)
virtual

Write the value of a GPIO bank with modification mask.

Parameters
bankthe name of an available bank
valuean integer representing GPIO bits
maska modification mask where 1 = modify
virtual void SoapySDR::Device::writeGPIODir ( const std::string &  bank,
const unsigned  dir 
)
virtual

Write the data direction of a GPIO bank. 1 bits represent outputs, 0 bits represent inputs.

Parameters
bankthe name of an available bank
diran integer representing data direction bits
virtual void SoapySDR::Device::writeGPIODir ( const std::string &  bank,
const unsigned  dir,
const unsigned  mask 
)
virtual

Write the data direction of a GPIO bank with modification mask. 1 bits represent outputs, 0 bits represent inputs.

Parameters
bankthe name of an available bank
diran integer representing data direction bits
maska modification mask where 1 = modify
virtual void SoapySDR::Device::writeI2C ( const int  addr,
const std::string &  data 
)
virtual

Write to an available I2C slave. If the device contains multiple I2C masters, the address bits can encode which master.

Parameters
addrthe address of the slave
dataan array of bytes write out
virtual void SoapySDR::Device::writeRegister ( const unsigned  addr,
const unsigned  value 
)
virtual

Write a register on the device. This can represent a register on a soft CPU, FPGA, IC; the interpretation is up the implementation to decide.

Parameters
addrthe register address
valuethe register value
virtual void SoapySDR::Device::writeSetting ( const std::string &  key,
const std::string &  value 
)
virtual

Write an arbitrary setting on the device. The interpretation is up the implementation.

Parameters
keythe setting identifier
valuethe setting value
virtual int SoapySDR::Device::writeStream ( Stream *  stream,
const void *const *  buffs,
const size_t  numElems,
int &  flags,
const long long  timeNs = 0,
const long  timeoutUs = 100000 
)
virtual

Write elements to a stream for transmission. This is a multi-channel call, and buffs should be an array of void *, where each pointer will be filled with data for a different channel.

Client code compatibility: Client code relies on writeStream() for proper back-pressure. The writeStream() implementation must enforce the timeout such that the call blocks until space becomes available or timeout expiration.

Parameters
streamthe opaque pointer to a stream handle
buffsan array of void* buffers num chans in size
numElemsthe number of elements in each buffer
flagsoptional input flags and output flags
timeNsthe buffer's timestamp in nanoseconds
timeoutUsthe timeout in microseconds
Returns
the number of elements written per buffer or error
virtual void SoapySDR::Device::writeUART ( const std::string &  which,
const std::string &  data 
)
virtual

Write data to a UART device. Its up to the implementation to set the baud rate, carriage return settings, flushing on newline.

Parameters
whichthe name of an available UART
dataan array of bytes to write out

The documentation for this class was generated from the following file: