SoapySDR  0.5.4-g68d0793c
Vendor and platform neutral SDR interface library
Typedefs | Functions
Device.h File Reference
#include <SoapySDR/Config.h>
#include <SoapySDR/Types.h>
#include <SoapySDR/Constants.h>
#include <SoapySDR/Errors.h>
#include <SoapySDR/Device.h>

Go to the source code of this file.

Typedefs

typedef struct SoapySDRDevice SoapySDRDevice
 Forward declaration of device handle. More...
 
typedef struct SoapySDRStream SoapySDRStream
 Forward declaration of stream handle. More...
 

Functions

SOAPY_SDR_API int SoapySDRDevice_lastStatus (void)
 
SOAPY_SDR_API const char * SoapySDRDevice_lastError (void)
 
SOAPY_SDR_API SoapySDRKwargsSoapySDRDevice_enumerate (const SoapySDRKwargs *args, size_t *length)
 
SOAPY_SDR_API SoapySDRKwargsSoapySDRDevice_enumerateStrArgs (const char *args, size_t *length)
 
SOAPY_SDR_API SoapySDRDeviceSoapySDRDevice_make (const SoapySDRKwargs *args)
 
SOAPY_SDR_API SoapySDRDeviceSoapySDRDevice_makeStrArgs (const char *args)
 
SOAPY_SDR_API void SoapySDRDevice_unmake (SoapySDRDevice *device)
 
SOAPY_SDR_API char * SoapySDRDevice_getDriverKey (const SoapySDRDevice *device)
 
SOAPY_SDR_API char * SoapySDRDevice_getHardwareKey (const SoapySDRDevice *device)
 
SOAPY_SDR_API SoapySDRKwargs SoapySDRDevice_getHardwareInfo (const SoapySDRDevice *device)
 
SOAPY_SDR_API int SoapySDRDevice_setFrontendMapping (SoapySDRDevice *device, const int direction, const char *mapping)
 
SOAPY_SDR_API char * SoapySDRDevice_getFrontendMapping (const SoapySDRDevice *device, const int direction)
 
SOAPY_SDR_API size_t SoapySDRDevice_getNumChannels (const SoapySDRDevice *device, const int direction)
 
SOAPY_SDR_API SoapySDRKwargs SoapySDRDevice_getChannelInfo (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API bool SoapySDRDevice_getFullDuplex (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API char ** SoapySDRDevice_getStreamFormats (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API char * SoapySDRDevice_getNativeStreamFormat (const SoapySDRDevice *device, const int direction, const size_t channel, double *fullScale)
 
SOAPY_SDR_API SoapySDRArgInfoSoapySDRDevice_getStreamArgsInfo (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API int SoapySDRDevice_setupStream (SoapySDRDevice *device, SoapySDRStream **stream, const int direction, const char *format, const size_t *channels, const size_t numChans, const SoapySDRKwargs *args)
 
SOAPY_SDR_API void SoapySDRDevice_closeStream (SoapySDRDevice *device, SoapySDRStream *stream)
 
SOAPY_SDR_API size_t SoapySDRDevice_getStreamMTU (const SoapySDRDevice *device, SoapySDRStream *stream)
 
SOAPY_SDR_API int SoapySDRDevice_activateStream (SoapySDRDevice *device, SoapySDRStream *stream, const int flags, const long long timeNs, const size_t numElems)
 
SOAPY_SDR_API int SoapySDRDevice_deactivateStream (SoapySDRDevice *device, SoapySDRStream *stream, const int flags, const long long timeNs)
 
SOAPY_SDR_API int SoapySDRDevice_readStream (SoapySDRDevice *device, SoapySDRStream *stream, void *const *buffs, const size_t numElems, int *flags, long long *timeNs, const long timeoutUs)
 
SOAPY_SDR_API int SoapySDRDevice_writeStream (SoapySDRDevice *device, SoapySDRStream *stream, const void *const *buffs, const size_t numElems, int *flags, const long long timeNs, const long timeoutUs)
 
SOAPY_SDR_API int SoapySDRDevice_readStreamStatus (SoapySDRDevice *device, SoapySDRStream *stream, size_t *chanMask, int *flags, long long *timeNs, const long timeoutUs)
 
SOAPY_SDR_API size_t SoapySDRDevice_getNumDirectAccessBuffers (SoapySDRDevice *device, SoapySDRStream *stream)
 
SOAPY_SDR_API int SoapySDRDevice_getDirectAccessBufferAddrs (SoapySDRDevice *device, SoapySDRStream *stream, const size_t handle, void **buffs)
 
SOAPY_SDR_API int SoapySDRDevice_acquireReadBuffer (SoapySDRDevice *device, SoapySDRStream *stream, size_t *handle, const void **buffs, int *flags, long long *timeNs, const long timeoutUs)
 
SOAPY_SDR_API void SoapySDRDevice_releaseReadBuffer (SoapySDRDevice *device, SoapySDRStream *stream, const size_t handle)
 
SOAPY_SDR_API int SoapySDRDevice_acquireWriteBuffer (SoapySDRDevice *device, SoapySDRStream *stream, size_t *handle, void **buffs, const long timeoutUs)
 
SOAPY_SDR_API void SoapySDRDevice_releaseWriteBuffer (SoapySDRDevice *device, SoapySDRStream *stream, const size_t handle, const size_t numElems, int *flags, const long long timeNs)
 
SOAPY_SDR_API char ** SoapySDRDevice_listAntennas (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API int SoapySDRDevice_setAntenna (SoapySDRDevice *device, const int direction, const size_t channel, const char *name)
 
SOAPY_SDR_API char * SoapySDRDevice_getAntenna (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API bool SoapySDRDevice_hasDCOffsetMode (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API int SoapySDRDevice_setDCOffsetMode (SoapySDRDevice *device, const int direction, const size_t channel, const bool automatic)
 
SOAPY_SDR_API bool SoapySDRDevice_getDCOffsetMode (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API bool SoapySDRDevice_hasDCOffset (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API int SoapySDRDevice_setDCOffset (SoapySDRDevice *device, const int direction, const size_t channel, const double offsetI, const double offsetQ)
 
SOAPY_SDR_API void SoapySDRDevice_getDCOffset (const SoapySDRDevice *device, const int direction, const size_t channel, double *offsetI, double *offsetQ)
 
SOAPY_SDR_API bool SoapySDRDevice_hasIQBalance (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API int SoapySDRDevice_setIQBalance (SoapySDRDevice *device, const int direction, const size_t channel, const double balanceI, const double balanceQ)
 
SOAPY_SDR_API void SoapySDRDevice_getIQBalance (const SoapySDRDevice *device, const int direction, const size_t channel, double *balanceI, double *balanceQ)
 
SOAPY_SDR_API char ** SoapySDRDevice_listGains (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API bool SoapySDRDevice_hasGainMode (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API int SoapySDRDevice_setGainMode (SoapySDRDevice *device, const int direction, const size_t channel, const bool automatic)
 
SOAPY_SDR_API bool SoapySDRDevice_getGainMode (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API int SoapySDRDevice_setGain (SoapySDRDevice *device, const int direction, const size_t channel, const double value)
 
SOAPY_SDR_API int SoapySDRDevice_setGainElement (SoapySDRDevice *device, const int direction, const size_t channel, const char *name, const double value)
 
SOAPY_SDR_API double SoapySDRDevice_getGain (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API double SoapySDRDevice_getGainElement (const SoapySDRDevice *device, const int direction, const size_t channel, const char *name)
 
SOAPY_SDR_API SoapySDRRange SoapySDRDevice_getGainRange (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API SoapySDRRange SoapySDRDevice_getGainElementRange (const SoapySDRDevice *device, const int direction, const size_t channel, const char *name)
 
SOAPY_SDR_API int SoapySDRDevice_setFrequency (SoapySDRDevice *device, const int direction, const size_t channel, const double frequency, const SoapySDRKwargs *args)
 
SOAPY_SDR_API int SoapySDRDevice_setFrequencyComponent (SoapySDRDevice *device, const int direction, const size_t channel, const char *name, const double frequency, const SoapySDRKwargs *args)
 
SOAPY_SDR_API double SoapySDRDevice_getFrequency (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API double SoapySDRDevice_getFrequencyComponent (const SoapySDRDevice *device, const int direction, const size_t channel, const char *name)
 
SOAPY_SDR_API char ** SoapySDRDevice_listFrequencies (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API SoapySDRRangeSoapySDRDevice_getFrequencyRange (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API SoapySDRRangeSoapySDRDevice_getFrequencyRangeComponent (const SoapySDRDevice *device, const int direction, const size_t channel, const char *name, size_t *length)
 
SOAPY_SDR_API SoapySDRArgInfoSoapySDRDevice_getFrequencyArgsInfo (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API int SoapySDRDevice_setSampleRate (SoapySDRDevice *device, const int direction, const size_t channel, const double rate)
 
SOAPY_SDR_API double SoapySDRDevice_getSampleRate (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API double * SoapySDRDevice_listSampleRates (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API int SoapySDRDevice_setBandwidth (SoapySDRDevice *device, const int direction, const size_t channel, const double bw)
 
SOAPY_SDR_API double SoapySDRDevice_getBandwidth (const SoapySDRDevice *device, const int direction, const size_t channel)
 
SOAPY_SDR_API double * SoapySDRDevice_listBandwidths (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API SoapySDRRangeSoapySDRDevice_getBandwidthRange (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API int SoapySDRDevice_setMasterClockRate (SoapySDRDevice *device, const double rate)
 
SOAPY_SDR_API double SoapySDRDevice_getMasterClockRate (const SoapySDRDevice *device)
 
SOAPY_SDR_API SoapySDRRangeSoapySDRDevice_getMasterClockRates (const SoapySDRDevice *device, size_t *length)
 
SOAPY_SDR_API char ** SoapySDRDevice_listClockSources (const SoapySDRDevice *device, size_t *length)
 
SOAPY_SDR_API int SoapySDRDevice_setClockSource (SoapySDRDevice *device, const char *source)
 
SOAPY_SDR_API char * SoapySDRDevice_getClockSource (const SoapySDRDevice *device)
 
SOAPY_SDR_API char ** SoapySDRDevice_listTimeSources (const SoapySDRDevice *device, size_t *length)
 
SOAPY_SDR_API int SoapySDRDevice_setTimeSource (SoapySDRDevice *device, const char *source)
 
SOAPY_SDR_API char * SoapySDRDevice_getTimeSource (const SoapySDRDevice *device)
 
SOAPY_SDR_API bool SoapySDRDevice_hasHardwareTime (const SoapySDRDevice *device, const char *what)
 
SOAPY_SDR_API long long SoapySDRDevice_getHardwareTime (const SoapySDRDevice *device, const char *what)
 
SOAPY_SDR_API void SoapySDRDevice_setHardwareTime (SoapySDRDevice *device, const long long timeNs, const char *what)
 
SOAPY_SDR_API void SoapySDRDevice_setCommandTime (SoapySDRDevice *device, const long long timeNs, const char *what)
 
SOAPY_SDR_API char ** SoapySDRDevice_listSensors (const SoapySDRDevice *device, size_t *length)
 
SOAPY_SDR_API SoapySDRArgInfo SoapySDRDevice_getSensorInfo (const SoapySDRDevice *device, const char *name)
 
SOAPY_SDR_API char * SoapySDRDevice_readSensor (const SoapySDRDevice *device, const char *name)
 
SOAPY_SDR_API char ** SoapySDRDevice_listChannelSensors (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API SoapySDRArgInfo SoapySDRDevice_getChannelSensorInfo (const SoapySDRDevice *device, const int direction, const size_t channel, const char *name)
 
SOAPY_SDR_API char * SoapySDRDevice_readChannelSensor (const SoapySDRDevice *device, const int direction, const size_t channel, const char *name)
 
SOAPY_SDR_API char ** SoapySDRDevice_listRegisterInterfaces (const SoapySDRDevice *device, size_t *length)
 
SOAPY_SDR_API void SoapySDRDevice_writeNamedRegister (SoapySDRDevice *device, const char *name, const unsigned addr, const unsigned value)
 
SOAPY_SDR_API unsigned SoapySDRDevice_readNamedRegister (const SoapySDRDevice *device, const char *name, const unsigned addr)
 
SOAPY_SDR_API void SoapySDRDevice_writeRegister (SoapySDRDevice *device, const unsigned addr, const unsigned value)
 
SOAPY_SDR_API unsigned SoapySDRDevice_readRegister (const SoapySDRDevice *device, const unsigned addr)
 
SOAPY_SDR_API SoapySDRArgInfoSoapySDRDevice_getSettingInfo (const SoapySDRDevice *device, size_t *length)
 
SOAPY_SDR_API void SoapySDRDevice_writeSetting (SoapySDRDevice *device, const char *key, const char *value)
 
SOAPY_SDR_API char * SoapySDRDevice_readSetting (const SoapySDRDevice *device, const char *key)
 
SOAPY_SDR_API SoapySDRArgInfoSoapySDRDevice_getChannelSettingInfo (const SoapySDRDevice *device, const int direction, const size_t channel, size_t *length)
 
SOAPY_SDR_API void SoapySDRDevice_writeChannelSetting (SoapySDRDevice *device, const int direction, const size_t channel, const char *key, const char *value)
 
SOAPY_SDR_API char * SoapySDRDevice_readChannelSetting (const SoapySDRDevice *device, const int direction, const size_t channel, const char *key)
 
SOAPY_SDR_API char ** SoapySDRDevice_listGPIOBanks (const SoapySDRDevice *device, size_t *length)
 
SOAPY_SDR_API void SoapySDRDevice_writeGPIO (SoapySDRDevice *device, const char *bank, const unsigned value)
 
SOAPY_SDR_API void SoapySDRDevice_writeGPIOMasked (SoapySDRDevice *device, const char *bank, const unsigned value, const unsigned mask)
 
SOAPY_SDR_API unsigned SoapySDRDevice_readGPIO (const SoapySDRDevice *device, const char *bank)
 
SOAPY_SDR_API void SoapySDRDevice_writeGPIODir (SoapySDRDevice *device, const char *bank, const unsigned dir)
 
SOAPY_SDR_API void SoapySDRDevice_writeGPIODirMasked (SoapySDRDevice *device, const char *bank, const unsigned dir, const unsigned mask)
 
SOAPY_SDR_API unsigned SoapySDRDevice_readGPIODir (const SoapySDRDevice *device, const char *bank)
 
SOAPY_SDR_API void SoapySDRDevice_writeI2C (SoapySDRDevice *device, const int addr, const char *data, const size_t numBytes)
 
SOAPY_SDR_API char * SoapySDRDevice_readI2C (SoapySDRDevice *device, const int addr, const size_t numBytes)
 
SOAPY_SDR_API unsigned SoapySDRDevice_transactSPI (SoapySDRDevice *device, const int addr, const unsigned data, const size_t numBits)
 
SOAPY_SDR_API char ** SoapySDRDevice_listUARTs (const SoapySDRDevice *device, size_t *length)
 
SOAPY_SDR_API void SoapySDRDevice_writeUART (SoapySDRDevice *device, const char *which, const char *data)
 
SOAPY_SDR_API char * SoapySDRDevice_readUART (const SoapySDRDevice *device, const char *which, const long timeoutUs)
 

Detailed Description

Interface definition for Soapy SDR devices. This is the C version of the Device interface.

General design rules about the API: The caller must free non-const array results.

Typedef Documentation

Forward declaration of device handle.

Forward declaration of stream handle.

Function Documentation

SOAPY_SDR_API int SoapySDRDevice_acquireReadBuffer ( SoapySDRDevice device,
SoapySDRStream stream,
size_t *  handle,
const void **  buffs,
int *  flags,
long long *  timeNs,
const long  timeoutUs 
)

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
devicea pointer to a device instance
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
SOAPY_SDR_API int SoapySDRDevice_acquireWriteBuffer ( SoapySDRDevice device,
SoapySDRStream stream,
size_t *  handle,
void **  buffs,
const long  timeoutUs 
)

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
devicea pointer to a device instance
streamthe opaque pointer to a stream handle
handlean index value used in the release() call
buffsan array of void* buffers num chans in size
timeoutUsthe timeout in microseconds
Returns
the number of available elements per buffer or error
SOAPY_SDR_API int SoapySDRDevice_activateStream ( SoapySDRDevice device,
SoapySDRStream stream,
const int  flags,
const long long  timeNs,
const size_t  numElems 
)

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
devicea pointer to a device instance
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
SOAPY_SDR_API void SoapySDRDevice_closeStream ( SoapySDRDevice device,
SoapySDRStream stream 
)

Close an open stream created by setupStream

Parameters
devicea pointer to a device instance
streamthe opaque pointer to a stream handle
SOAPY_SDR_API int SoapySDRDevice_deactivateStream ( SoapySDRDevice device,
SoapySDRStream stream,
const int  flags,
const long long  timeNs 
)

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
devicea pointer to a device instance
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
SOAPY_SDR_API SoapySDRKwargs* SoapySDRDevice_enumerate ( const SoapySDRKwargs args,
size_t *  length 
)

Enumerate a list of available devices on the system.

Parameters
argsdevice construction key/value argument filters
[out]lengththe number of elements in the result.
Returns
a list of arguments strings, each unique to a device
SOAPY_SDR_API SoapySDRKwargs* SoapySDRDevice_enumerateStrArgs ( const char *  args,
size_t *  length 
)

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
[out]lengththe number of elements in the result.
Returns
a list of arguments strings, each unique to a device
SOAPY_SDR_API char* SoapySDRDevice_getAntenna ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Get the selected antenna on a chain.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
the name of an available antenna
SOAPY_SDR_API double SoapySDRDevice_getBandwidth ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Get the baseband filter width of the chain.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
the baseband filter width in Hz
SOAPY_SDR_API SoapySDRRange* SoapySDRDevice_getBandwidthRange ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

Get the range of possible baseband filter widths.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]lengththe number of ranges
Returns
a list of bandwidth ranges in Hz
SOAPY_SDR_API SoapySDRKwargs SoapySDRDevice_getChannelInfo ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Get channel info given the streaming direction

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelthe channel number to get info for
Returns
channel information
SOAPY_SDR_API SoapySDRArgInfo SoapySDRDevice_getChannelSensorInfo ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  name 
)

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

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of an available sensor
Returns
meta-information about a sensor
SOAPY_SDR_API SoapySDRArgInfo* SoapySDRDevice_getChannelSettingInfo ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

Describe the allowed keys and values used for channel settings.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]lengththe number of sensor names
Returns
a list of argument info structures
SOAPY_SDR_API char* SoapySDRDevice_getClockSource ( const SoapySDRDevice device)

Get the clock source of the device

Parameters
devicea pointer to a device instance
Returns
the name of a clock source
SOAPY_SDR_API void SoapySDRDevice_getDCOffset ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
double *  offsetI,
double *  offsetQ 
)

Get the frontend DC offset correction.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]offsetIthe relative correction (1.0 max)
[out]offsetQthe relative correction (1.0 max)
SOAPY_SDR_API bool SoapySDRDevice_getDCOffsetMode ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Get the automatic DC offset corrections mode.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true for automatic offset correction
SOAPY_SDR_API int SoapySDRDevice_getDirectAccessBufferAddrs ( SoapySDRDevice device,
SoapySDRStream stream,
const size_t  handle,
void **  buffs 
)

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
devicea pointer to a device instance
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
SOAPY_SDR_API char* SoapySDRDevice_getDriverKey ( const SoapySDRDevice device)

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

Parameters
devicea pointer to a device instance
SOAPY_SDR_API double SoapySDRDevice_getFrequency ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

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
    devicea pointer to a device instance
    directionthe channel direction RX or TX
    channelan available channel on the device
    Returns
    the center frequency in Hz
SOAPY_SDR_API SoapySDRArgInfo* SoapySDRDevice_getFrequencyArgsInfo ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

Query the argument info description for tune args.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]lengththe number of argument infos
Returns
a list of argument info structures
SOAPY_SDR_API double SoapySDRDevice_getFrequencyComponent ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  name 
)

Get the frequency of a tunable element in the chain.

Parameters
devicea pointer to a device instance
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
SOAPY_SDR_API SoapySDRRange* SoapySDRDevice_getFrequencyRange ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

Get the range of overall frequency values.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]lengththe number of ranges
Returns
a list of frequency ranges in Hz
SOAPY_SDR_API SoapySDRRange* SoapySDRDevice_getFrequencyRangeComponent ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  name,
size_t *  length 
)

Get the range of tunable values for the specified element.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of a tunable element
[out]lengththe number of ranges
Returns
a list of frequency ranges in Hz
SOAPY_SDR_API char* SoapySDRDevice_getFrontendMapping ( const SoapySDRDevice device,
const int  direction 
)

Get the mapping configuration string.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
Returns
the vendor-specific mapping string
SOAPY_SDR_API bool SoapySDRDevice_getFullDuplex ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

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

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true for full duplex, false for half duplex
SOAPY_SDR_API double SoapySDRDevice_getGain ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

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

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
the value of the gain in dB
SOAPY_SDR_API double SoapySDRDevice_getGainElement ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  name 
)

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

Parameters
devicea pointer to a device instance
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
SOAPY_SDR_API SoapySDRRange SoapySDRDevice_getGainElementRange ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  name 
)

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

Parameters
devicea pointer to a device instance
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
SOAPY_SDR_API bool SoapySDRDevice_getGainMode ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Get the automatic gain mode on the chain.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true for automatic gain setting
SOAPY_SDR_API SoapySDRRange SoapySDRDevice_getGainRange ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Get the overall range of possible gain values.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
a list of gain ranges in dB
SOAPY_SDR_API SoapySDRKwargs SoapySDRDevice_getHardwareInfo ( const SoapySDRDevice device)

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.

Parameters
devicea pointer to a device instance
SOAPY_SDR_API char* SoapySDRDevice_getHardwareKey ( const SoapySDRDevice device)

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

Parameters
devicea pointer to a device instance
SOAPY_SDR_API long long SoapySDRDevice_getHardwareTime ( const SoapySDRDevice device,
const char *  what 
)

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

Parameters
devicea pointer to a device instance
whatoptional argument
Returns
the time in nanoseconds
SOAPY_SDR_API void SoapySDRDevice_getIQBalance ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
double *  balanceI,
double *  balanceQ 
)

Get the frontend IQ balance correction.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]balanceIthe relative correction (1.0 max)
[out]balanceQthe relative correction (1.0 max)
SOAPY_SDR_API double SoapySDRDevice_getMasterClockRate ( const SoapySDRDevice device)

Get the master clock rate of the device.

Parameters
devicea pointer to a device instance
Returns
the clock rate in Hz
SOAPY_SDR_API SoapySDRRange* SoapySDRDevice_getMasterClockRates ( const SoapySDRDevice device,
size_t *  length 
)

Get the range of available master clock rates.

Parameters
devicea pointer to a device instance
[out]lengththe number of ranges
Returns
a list of clock rate ranges in Hz
SOAPY_SDR_API char* SoapySDRDevice_getNativeStreamFormat ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
double *  fullScale 
)

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
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]fullScalethe maximum possible value
Returns
the native stream buffer format string
SOAPY_SDR_API size_t SoapySDRDevice_getNumChannels ( const SoapySDRDevice device,
const int  direction 
)

Get a number of channels given the streaming direction

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
Returns
the number of channels
SOAPY_SDR_API size_t SoapySDRDevice_getNumDirectAccessBuffers ( SoapySDRDevice device,
SoapySDRStream stream 
)

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
devicea pointer to a device instance
streamthe opaque pointer to a stream handle
Returns
the number of direct access buffers or 0
SOAPY_SDR_API double SoapySDRDevice_getSampleRate ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Get the baseband sample rate of the chain.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
the sample rate in samples per second
SOAPY_SDR_API SoapySDRArgInfo SoapySDRDevice_getSensorInfo ( const SoapySDRDevice device,
const char *  name 
)

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

Parameters
devicea pointer to a device instance
namethe name of an available sensor
Returns
meta-information about a sensor
SOAPY_SDR_API SoapySDRArgInfo* SoapySDRDevice_getSettingInfo ( const SoapySDRDevice device,
size_t *  length 
)

Describe the allowed keys and values used for settings.

Parameters
devicea pointer to a device instance
[out]lengththe number of sensor names
Returns
a list of argument info structures
SOAPY_SDR_API SoapySDRArgInfo* SoapySDRDevice_getStreamArgsInfo ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

Query the argument info description for stream args.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]lengththe number of argument infos
Returns
a list of argument info structures
SOAPY_SDR_API char** SoapySDRDevice_getStreamFormats ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

Query a list of the available stream formats.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]lengththe number of format strings
Returns
a list of allowed format strings
SOAPY_SDR_API size_t SoapySDRDevice_getStreamMTU ( const SoapySDRDevice device,
SoapySDRStream stream 
)

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
devicea pointer to a device instance
streamthe opaque pointer to a stream handle
Returns
the MTU in number of stream elements (never zero)
SOAPY_SDR_API char* SoapySDRDevice_getTimeSource ( const SoapySDRDevice device)

Get the time source of the device

Parameters
devicea pointer to a device instance
Returns
the name of a time source
SOAPY_SDR_API bool SoapySDRDevice_hasDCOffset ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Does the device support frontend DC offset correction?

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true if DC offset corrections are supported
SOAPY_SDR_API bool SoapySDRDevice_hasDCOffsetMode ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Does the device support automatic DC offset corrections?

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true if automatic corrections are supported
SOAPY_SDR_API bool SoapySDRDevice_hasGainMode ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Does the device support automatic gain control?

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true for automatic gain control
SOAPY_SDR_API bool SoapySDRDevice_hasHardwareTime ( const SoapySDRDevice device,
const char *  what 
)

Does this device have a hardware clock?

Parameters
devicea pointer to a device instance
whatoptional argument
Returns
true if the hardware clock exists
SOAPY_SDR_API bool SoapySDRDevice_hasIQBalance ( const SoapySDRDevice device,
const int  direction,
const size_t  channel 
)

Does the device support frontend IQ balance correction?

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
Returns
true if IQ balance corrections are supported
SOAPY_SDR_API const char* SoapySDRDevice_lastError ( void  )

Get the last error message after a device call fails. When an device API call throws, the C bindings catch the exception, store its message in thread-safe storage, and return a non-zero status code to indicate failure. Use lastError() to access the exception's error message.

SOAPY_SDR_API int SoapySDRDevice_lastStatus ( void  )

Get the last status code after a Device API call. The status code is cleared on entry to each Device call. When an device API call throws, the C bindings catch the exception, and set a non-zero last status code. Use lastStatus() to determine success/failure for Device calls without integer status return codes.

SOAPY_SDR_API char** SoapySDRDevice_listAntennas ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

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

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]lengththe number of antenna names
Returns
a list of available antenna names
SOAPY_SDR_API double* SoapySDRDevice_listBandwidths ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

Get the range of possible baseband filter widths.

Deprecated:
replaced by getBandwidthRange()
Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]lengththe number of bandwidths
Returns
a list of possible bandwidths in Hz
SOAPY_SDR_API char** SoapySDRDevice_listChannelSensors ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

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

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]lengththe number of sensor names
Returns
a list of available sensor string names
SOAPY_SDR_API char** SoapySDRDevice_listClockSources ( const SoapySDRDevice device,
size_t *  length 
)

Get the list of available clock sources.

Parameters
devicea pointer to a device instance
[out]lengththe number of sources
Returns
a list of clock source names
SOAPY_SDR_API char** SoapySDRDevice_listFrequencies ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

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

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel
[out]lengththe number names
Returns
a list of tunable elements by name
SOAPY_SDR_API char** SoapySDRDevice_listGains ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

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

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel
[out]lengththe number of gain names
Returns
a list of gain string names
SOAPY_SDR_API char** SoapySDRDevice_listGPIOBanks ( const SoapySDRDevice device,
size_t *  length 
)

Get a list of available GPIO banks by name.

Parameters
[out]lengththe number of GPIO banks
devicea pointer to a device instance
SOAPY_SDR_API char** SoapySDRDevice_listRegisterInterfaces ( const SoapySDRDevice device,
size_t *  length 
)

Get a list of available register interfaces by name.

Parameters
devicea pointer to a device instance
[out]lengththe number of interfaces
Returns
a list of available register interfaces
SOAPY_SDR_API double* SoapySDRDevice_listSampleRates ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
size_t *  length 
)

Get the range of possible baseband sample rates.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
[out]lengththe number of sample rates
Returns
a list of possible rates in samples per second
SOAPY_SDR_API char** SoapySDRDevice_listSensors ( const SoapySDRDevice device,
size_t *  length 
)

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

Parameters
devicea pointer to a device instance
[out]lengththe number of sensor names
Returns
a list of available sensor string names
SOAPY_SDR_API char** SoapySDRDevice_listTimeSources ( const SoapySDRDevice device,
size_t *  length 
)

Get the list of available time sources.

Parameters
devicea pointer to a device instance
[out]lengththe number of sources
Returns
a list of time source names
SOAPY_SDR_API char** SoapySDRDevice_listUARTs ( const SoapySDRDevice device,
size_t *  length 
)

Enumerate the available UART devices.

Parameters
devicea pointer to a device instance
[out]lengththe number of UART names
Returns
a list of names of available UARTs
SOAPY_SDR_API SoapySDRDevice* SoapySDRDevice_make ( const SoapySDRKwargs args)

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.

Parameters
argsdevice construction key/value argument map
Returns
a pointer to a new Device object
SOAPY_SDR_API SoapySDRDevice* SoapySDRDevice_makeStrArgs ( const char *  args)

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.

Parameters
argsa markup string of key/value arguments
Returns
a pointer to a new Device object
SOAPY_SDR_API char* SoapySDRDevice_readChannelSensor ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  name 
)

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
devicea pointer to a device instance
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
SOAPY_SDR_API char* SoapySDRDevice_readChannelSetting ( const SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  key 
)

Read an arbitrary channel setting on the device.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
keythe setting identifier
Returns
the setting value
SOAPY_SDR_API unsigned SoapySDRDevice_readGPIO ( const SoapySDRDevice device,
const char *  bank 
)

Readback the value of a GPIO bank.

Parameters
devicea pointer to a device instance
bankthe name of an available bank
Returns
an integer representing GPIO bits
SOAPY_SDR_API unsigned SoapySDRDevice_readGPIODir ( const SoapySDRDevice device,
const char *  bank 
)

Read the data direction of a GPIO bank.

Parameters
devicea pointer to a device instance 1 bits represent outputs, 0 bits represent inputs.
bankthe name of an available bank
Returns
an integer representing data direction bits
SOAPY_SDR_API char* SoapySDRDevice_readI2C ( SoapySDRDevice device,
const int  addr,
const size_t  numBytes 
)

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

Parameters
devicea pointer to a device instance
addrthe address of the slave
numBytesthe number of bytes to read
Returns
an array of bytes read from the slave
SOAPY_SDR_API unsigned SoapySDRDevice_readNamedRegister ( const SoapySDRDevice device,
const char *  name,
const unsigned  addr 
)

Read a register on the device given the interface name.

Parameters
devicea pointer to a device instance
namethe name of a available register interface
addrthe register address
Returns
the register value
SOAPY_SDR_API unsigned SoapySDRDevice_readRegister ( const SoapySDRDevice device,
const unsigned  addr 
)

Read a register on the device.

Deprecated:
replaced by readRegister(name)
Parameters
devicea pointer to a device instance
addrthe register address
Returns
the register value
SOAPY_SDR_API char* SoapySDRDevice_readSensor ( const SoapySDRDevice device,
const char *  name 
)

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
devicea pointer to a device instance
namethe name of an available sensor
Returns
the current value of the sensor
SOAPY_SDR_API char* SoapySDRDevice_readSetting ( const SoapySDRDevice device,
const char *  key 
)

Read an arbitrary setting on the device.

Parameters
devicea pointer to a device instance
keythe setting identifier
Returns
the setting value
SOAPY_SDR_API int SoapySDRDevice_readStream ( SoapySDRDevice device,
SoapySDRStream stream,
void *const *  buffs,
const size_t  numElems,
int *  flags,
long long *  timeNs,
const long  timeoutUs 
)

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
devicea pointer to a device instance
streamthe opaque pointer to a stream handle
buffsan array of void* buffers num chans in size
numElemsthe number of elements in each buffer
[out]flagsoptional flag indicators about the result
[out]timeNsthe buffer's timestamp in nanoseconds
timeoutUsthe timeout in microseconds
Returns
the number of elements read per buffer or error code
SOAPY_SDR_API int SoapySDRDevice_readStreamStatus ( SoapySDRDevice device,
SoapySDRStream stream,
size_t *  chanMask,
int *  flags,
long long *  timeNs,
const long  timeoutUs 
)

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
devicea pointer to a device instance
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
SOAPY_SDR_API char* SoapySDRDevice_readUART ( const SoapySDRDevice device,
const char *  which,
const long  timeoutUs 
)

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
devicea pointer to a device instance
whichthe name of an available UART
timeoutUsa timeout in microseconds
Returns
a null terminated array of bytes
SOAPY_SDR_API void SoapySDRDevice_releaseReadBuffer ( SoapySDRDevice device,
SoapySDRStream stream,
const size_t  handle 
)

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

Parameters
devicea pointer to a device instance
streamthe opaque pointer to a stream handle
handlethe opaque handle from the acquire() call
SOAPY_SDR_API void SoapySDRDevice_releaseWriteBuffer ( SoapySDRDevice device,
SoapySDRStream stream,
const size_t  handle,
const size_t  numElems,
int *  flags,
const long long  timeNs 
)

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
devicea pointer to a device instance
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
SOAPY_SDR_API int SoapySDRDevice_setAntenna ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  name 
)

Set the selected antenna on a chain.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of an available antenna
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setBandwidth ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const double  bw 
)

Set the baseband filter width of the chain.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
bwthe baseband filter width in Hz
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setClockSource ( SoapySDRDevice device,
const char *  source 
)

Set the clock source on the device

Parameters
devicea pointer to a device instance
sourcethe name of a clock source
Returns
an error code or 0 for success
SOAPY_SDR_API void SoapySDRDevice_setCommandTime ( SoapySDRDevice device,
const long long  timeNs,
const char *  what 
)

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.

Deprecated:
replaced by setHardwareTime()
Parameters
devicea pointer to a device instance
timeNstime in nanoseconds
whatoptional argument
SOAPY_SDR_API int SoapySDRDevice_setDCOffset ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const double  offsetI,
const double  offsetQ 
)

Set the frontend DC offset correction.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
offsetIthe relative correction (1.0 max)
offsetQthe relative correction (1.0 max)
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setDCOffsetMode ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const bool  automatic 
)

Set the automatic DC offset corrections mode.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
automatictrue for automatic offset correction
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setFrequency ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const double  frequency,
const SoapySDRKwargs args 
)

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
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
frequencythe center frequency in Hz
argsoptional tuner arguments
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setFrequencyComponent ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  name,
const double  frequency,
const SoapySDRKwargs args 
)

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
devicea pointer to a device instance
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
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setFrontendMapping ( SoapySDRDevice device,
const int  direction,
const char *  mapping 
)

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

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
mappinga vendor-specific mapping string
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setGain ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const double  value 
)

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

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
valuethe new amplification value in dB
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setGainElement ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  name,
const double  value 
)

Set the value of a amplification element in a chain.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
namethe name of an amplification element
valuethe new amplification value in dB
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setGainMode ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const bool  automatic 
)

Set the automatic gain mode on the chain.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
automatictrue for automatic gain setting
Returns
an error code or 0 for success
SOAPY_SDR_API void SoapySDRDevice_setHardwareTime ( SoapySDRDevice device,
const long long  timeNs,
const char *  what 
)

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

Parameters
devicea pointer to a device instance
timeNstime in nanoseconds
whatoptional argument
SOAPY_SDR_API int SoapySDRDevice_setIQBalance ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const double  balanceI,
const double  balanceQ 
)

Set the frontend IQ balance correction.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
balanceIthe relative correction (1.0 max)
balanceQthe relative correction (1.0 max)
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setMasterClockRate ( SoapySDRDevice device,
const double  rate 
)

Set the master clock rate of the device.

Parameters
devicea pointer to a device instance
ratethe clock rate in Hz
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setSampleRate ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const double  rate 
)

Set the baseband sample rate of the chain.

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
ratethe sample rate in samples per second
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setTimeSource ( SoapySDRDevice device,
const char *  source 
)

Set the time source on the device

Parameters
devicea pointer to a device instance
sourcethe name of a time source
Returns
an error code or 0 for success
SOAPY_SDR_API int SoapySDRDevice_setupStream ( SoapySDRDevice device,
SoapySDRStream **  stream,
const int  direction,
const char *  format,
const size_t *  channels,
const size_t  numChans,
const SoapySDRKwargs args 
)

Initialize a stream given a list of channels and stream arguments. 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
devicea pointer to a device instance
[out]streamthe opaque pointer to a stream handle
directionthe channel direction RX or TX
formatthe desired buffer format in read/writeStream()
channelsa list of channels for empty for automatic
numChansthe number of elements in the channels array
argsstream args or empty for defaults
Returns
0 for success or error code on failure
SOAPY_SDR_API unsigned SoapySDRDevice_transactSPI ( SoapySDRDevice device,
const int  addr,
const unsigned  data,
const size_t  numBits 
)

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
devicea pointer to a device instance
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
SOAPY_SDR_API void SoapySDRDevice_unmake ( SoapySDRDevice device)

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
SOAPY_SDR_API void SoapySDRDevice_writeChannelSetting ( SoapySDRDevice device,
const int  direction,
const size_t  channel,
const char *  key,
const char *  value 
)

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

Parameters
devicea pointer to a device instance
directionthe channel direction RX or TX
channelan available channel on the device
keythe setting identifier
valuethe setting value
SOAPY_SDR_API void SoapySDRDevice_writeGPIO ( SoapySDRDevice device,
const char *  bank,
const unsigned  value 
)

Write the value of a GPIO bank.

Parameters
devicea pointer to a device instance
bankthe name of an available bank
valuean integer representing GPIO bits
SOAPY_SDR_API void SoapySDRDevice_writeGPIODir ( SoapySDRDevice device,
const char *  bank,
const unsigned  dir 
)

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

Parameters
devicea pointer to a device instance
bankthe name of an available bank
diran integer representing data direction bits
SOAPY_SDR_API void SoapySDRDevice_writeGPIODirMasked ( SoapySDRDevice device,
const char *  bank,
const unsigned  dir,
const unsigned  mask 
)

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

Parameters
devicea pointer to a device instance
bankthe name of an available bank
diran integer representing data direction bits
maska modification mask where 1 = modify
SOAPY_SDR_API void SoapySDRDevice_writeGPIOMasked ( SoapySDRDevice device,
const char *  bank,
const unsigned  value,
const unsigned  mask 
)

Write the value of a GPIO bank with modification mask.

Parameters
devicea pointer to a device instance
bankthe name of an available bank
valuean integer representing GPIO bits
maska modification mask where 1 = modify
SOAPY_SDR_API void SoapySDRDevice_writeI2C ( SoapySDRDevice device,
const int  addr,
const char *  data,
const size_t  numBytes 
)

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

Parameters
devicea pointer to a device instance
addrthe address of the slave
dataan array of bytes write out
numBytesthe number of bytes to write
SOAPY_SDR_API void SoapySDRDevice_writeNamedRegister ( SoapySDRDevice device,
const char *  name,
const unsigned  addr,
const unsigned  value 
)

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

Parameters
devicea pointer to a device instance
namethe name of a available register interface
addrthe register address
valuethe register value
SOAPY_SDR_API void SoapySDRDevice_writeRegister ( SoapySDRDevice device,
const unsigned  addr,
const unsigned  value 
)

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.

Deprecated:
replaced by writeRegister(name)
Parameters
devicea pointer to a device instance
addrthe register address
valuethe register value
SOAPY_SDR_API void SoapySDRDevice_writeSetting ( SoapySDRDevice device,
const char *  key,
const char *  value 
)

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

Parameters
devicea pointer to a device instance
keythe setting identifier
valuethe setting value
SOAPY_SDR_API int SoapySDRDevice_writeStream ( SoapySDRDevice device,
SoapySDRStream stream,
const void *const *  buffs,
const size_t  numElems,
int *  flags,
const long long  timeNs,
const long  timeoutUs 
)

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
devicea pointer to a device instance
streamthe opaque pointer to a stream handle
buffsan array of void* buffers num chans in size
numElemsthe number of elements in each buffer
[in,out]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
SOAPY_SDR_API void SoapySDRDevice_writeUART ( SoapySDRDevice device,
const char *  which,
const char *  data 
)

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

Parameters
devicea pointer to a device instance
whichthe name of an available UART
dataa null terminated array of bytes