#include <SoapySDR/Config.h>
#include <SoapySDR/Types.h>
#include <SoapySDR/Constants.h>

Functions
SOAPY_SDR_API SoapySDRKwargs *	SoapySDRDevice_enumerate (const SoapySDRKwargs args, size_t length)

SOAPY_SDR_API SoapySDRKwargs *	SoapySDRDevice_enumerateStrArgs (const char args, size_t length)

SOAPY_SDR_API SoapySDRDevice *	SoapySDRDevice_make (const SoapySDRKwargs *args)

SOAPY_SDR_API SoapySDRDevice *	SoapySDRDevice_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 char *	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 bool	SoapySDRDevice_getFullDuplex (const SoapySDRDevice *device, const int direction, const size_t channel)

SOAPY_SDR_API char *	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 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 char **	SoapySDRDevice_listAntennas (const SoapySDRDevice device, const int direction, const size_t channel, size_t length)

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

SOAPY_SDR_API char *	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 char *	SoapySDRDevice_setFrequency (SoapySDRDevice device, const int direction, const size_t channel, 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 SoapySDRRange *	SoapySDRDevice_getFrequencyRange (const SoapySDRDevice device, const int direction, const size_t channel, size_t length)

SOAPY_SDR_API char *	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 char *	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 char *	SoapySDRDevice_setMasterClockRate (SoapySDRDevice *device, const double rate)

SOAPY_SDR_API double	SoapySDRDevice_getMasterClockRate (const SoapySDRDevice *device)

SOAPY_SDR_API char **	SoapySDRDevice_listClockSources (const SoapySDRDevice device, size_t length)

SOAPY_SDR_API char *	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 char *	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 char *	SoapySDRDevice_readSensor (const SoapySDRDevice device, const char name)

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 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 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 unsigned	SoapySDRDevice_readGPIO (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.

Copyright: Copyright (c) 2014-2014 Josh Blum SPDX-License-Identifier: BSL-1.0

Function Documentation

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

device	a pointer to a device instance
stream	the opaque pointer to a stream handle
flags	optional flag indicators about the stream
timeNs	optional activation time in nanoseconds
numElems	optional 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

device	a pointer to a device instance
stream	the 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

device	a pointer to a device instance
stream	the opaque pointer to a stream handle
flags	optional flag indicators about the stream
timeNs	optional 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

	args	device construction key/value argument filters
[out]	length	the 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

	args	a markup string of key/value argument filters
[out]	length	the 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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an 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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device

Returns: the baseband filter width in Hz

SOAPY_SDR_API char* SoapySDRDevice_getClockSource ( const SoapySDRDevice * device )

Get the clock source of the device

Parameters

device a 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

	device	a pointer to a device instance
	direction	the channel direction RX or TX
	channel	an available channel on the device
[out]	offsetI	the relative correction (1.0 max)
[out]	offsetQ	the 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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device

Returns: true for automatic offset correction

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

device a pointer to a device instance

SOAPY_SDR_API double SoapySDRDevice_getFrequency	(	const SoapySDRDevice *	device,
		const int	direction,
		const size_t	channel
	)

Get the center frequency of the chain.

Parameters

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device

Returns: the center frequency in Hz

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. 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

device a pointer to a device instance

direction the channel direction RX or TX

channel an available channel on the device

name the name of an frequency component

Returns
a dictionary of tunable elements to frequencies 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 possible frequency values.

Parameters

	device	a pointer to a device instance
	direction	the channel direction RX or TX
	channel	an available channel on the device
[out]	length	the 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

device	a pointer to a device instance
direction	the channel direction RX or TX
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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an 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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an 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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
name	the 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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
name	the 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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an 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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an 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

device a 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

device a 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

device	a pointer to a device instance
what	optional 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

	device	a pointer to a device instance
	direction	the channel direction RX or TX
	channel	an available channel on the device
[out]	balanceI	the relative correction (1.0 max)
[out]	balanceQ	the relative correction (1.0 max)

SOAPY_SDR_API double SoapySDRDevice_getMasterClockRate ( const SoapySDRDevice * device )

Get the master clock rate of the device.

Parameters

device a pointer to a device instance

Returns: the clock rate in Hz

SOAPY_SDR_API size_t SoapySDRDevice_getNumChannels	(	const SoapySDRDevice *	device,
		const int	direction
	)

Get a number of channels given the streaming direction

Parameters

device	a pointer to a device instance
direction	the channel direction RX or TX

Returns: the number of channels

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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device

Returns: the sample rate in samples per second

SOAPY_SDR_API char* SoapySDRDevice_getTimeSource ( const SoapySDRDevice * device )

Get the time source of the device

Parameters

device a pointer to a device instance

Returns: the name of a time source

SOAPY_SDR_API bool SoapySDRDevice_hasHardwareTime	(	const SoapySDRDevice *	device,
		const char *	what
	)

Does this device have a hardware clock?

Parameters

device	a pointer to a device instance
what	optional argument

Returns: true if the hardware clock exists

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

	device	a pointer to a device instance
	direction	the channel direction RX or TX
	channel	an available channel on the device
[out]	length	the 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.

Parameters

	device	a pointer to a device instance
	direction	the channel direction RX or TX
	channel	an available channel on the device
[out]	length	the number of bandwidths

Returns: a list of possible bandwidths in Hz

SOAPY_SDR_API char** SoapySDRDevice_listClockSources	(	const SoapySDRDevice *	device,
		size_t *	length
	)

Get the list of available clock sources.

Parameters

	device	a pointer to a device instance
[out]	length	the 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.

Parameters

	device	a pointer to a device instance
	direction	the channel direction RX or TX
	channel	an available channel
[out]	length	the 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.

Parameters

	device	a pointer to a device instance
	direction	the channel direction RX or TX
	channel	an available channel
[out]	length	the 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]	length	the number of GPIO banks
	device	a pointer to a device instance

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

	device	a pointer to a device instance
	direction	the channel direction RX or TX
	channel	an available channel on the device
[out]	length	the 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 readback sensors. A sensor can represent a reference lock, RSSI, temperature.

Parameters

	device	a pointer to a device instance
[out]	length	the 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

	device	a pointer to a device instance
[out]	length	the 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

	device	a pointer to a device instance
[out]	length	the 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.

Note: This call is not thread safe. Implementations calling into make from multiple threads should protect this call with a mutex.

Parameters

args	device 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.

Note: This call is not thread safe. Implementations calling into make from multiple threads should protect this call with a mutex.

Parameters

args	a markup string of key/value arguments

Returns: a pointer to a new Device object

SOAPY_SDR_API unsigned SoapySDRDevice_readGPIO	(	const SoapySDRDevice *	device,
		const char *	bank
	)

Readback the value of a GPIO bank.

Parameters

device	a pointer to a device instance
bank	the name of an available bank

Returns: an integer representing GPIO 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

device	a pointer to a device instance
addr	the address of the slave
numBytes	the number of bytes to read

Returns: an array of bytes read from the slave

SOAPY_SDR_API unsigned SoapySDRDevice_readRegister	(	const SoapySDRDevice *	device,
		const unsigned	addr
	)

Read a register on the device.

Parameters

device	a pointer to a device instance
addr	the register address

Returns: the register value

SOAPY_SDR_API char* SoapySDRDevice_readSensor	(	const SoapySDRDevice *	device,
		const char *	name
	)

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

Parameters

device	a pointer to a device instance
name	the 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

device	a pointer to a device instance
key	the 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.

Parameters

	device	a pointer to a device instance
	stream	the opaque pointer to a stream handle
	buffs	an array of void* buffers num chans in size
	numElems	the number of elements in each buffer
[out]	flags	optional flag indicators about the result
[out]	timeNs	the buffer's timestamp in nanoseconds
	timeoutUs	the timeout in microseconds

Returns: the number of elements read per buffer or error code

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

device	a pointer to a device instance
which	the name of an available UART
timeoutUs	a timeout in microseconds

Returns: a null terminated array of bytes

SOAPY_SDR_API char* SoapySDRDevice_setAntenna	(	SoapySDRDevice *	device,
		const int	direction,
		const size_t	channel,
		const char *	name
	)

Set the selected antenna on a chain.

Parameters

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
name	the name of an available antenna

Returns: an error message or NULL for success

SOAPY_SDR_API char* SoapySDRDevice_setBandwidth	(	SoapySDRDevice *	device,
		const int	direction,
		const size_t	channel,
		const double	bw
	)

Set the baseband filter width of the chain.

Parameters

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
bw	the baseband filter width in Hz

Returns: an error message or NULL for success

SOAPY_SDR_API char* SoapySDRDevice_setClockSource	(	SoapySDRDevice *	device,
		const char *	source
	)

Set the clock source on the device

Parameters

device	a pointer to a device instance
source	the name of a clock source

Returns: an error message or NULL 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.

Parameters

device	a pointer to a device instance
timeNs	time in nanoseconds
what	optional argument

SOAPY_SDR_API char* SoapySDRDevice_setDCOffset	(	SoapySDRDevice *	device,
		const int	direction,
		const size_t	channel,
		const double	offsetI,
		const double	offsetQ
	)

Set the frontend DC offset correction.

Parameters

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
offsetI	the relative correction (1.0 max)
offsetQ	the relative correction (1.0 max)

Returns: an error message or NULL for success

SOAPY_SDR_API char* SoapySDRDevice_setDCOffsetMode	(	SoapySDRDevice *	device,
		const int	direction,
		const size_t	channel,
		const bool	automatic
	)

Set the automatic DC offset corrections mode.

Parameters

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
automatic	true for automatic offset correction

Returns: an error message or NULL for success

SOAPY_SDR_API char* SoapySDRDevice_setFrequency	(	SoapySDRDevice *	device,
		const int	direction,
		const size_t	channel,
		const double	frequency,
		const SoapySDRKwargs *	args
	)

Set the center frequency of the chain. Recommended keys to use in the args dictionary:

"CORR" - freq error correction in PPM
"OFFSET" - offset for the RF frontend
"RF" - frequency of the RF frontend

"BB" - frequency of the baseband DSP

Parameters

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
frequency	the center frequency in Hz
args	optional tuner arguments

Returns: an error message or NULL for success

SOAPY_SDR_API char* 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

device	a pointer to a device instance
direction	the channel direction RX or TX
mapping	a vendor-specific mapping string

Returns: an error message or NULL for success

SOAPY_SDR_API char* 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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
name	the name of an amplification element
value	the new amplification value in dB

Returns: an error message or NULL for success

SOAPY_SDR_API char* 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

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
name	the name of an amplification element
value	the new amplification value in dB

Returns: an error message or NULL for success

SOAPY_SDR_API char* SoapySDRDevice_setGainMode	(	SoapySDRDevice *	device,
		const int	direction,
		const size_t	channel,
		const bool	automatic
	)

Set the automatic gain mode on the chain.

Parameters

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
automatic	true for automatic gain setting

Returns: an error message or NULL 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

device	a pointer to a device instance
timeNs	time in nanoseconds
what	optional argument

SOAPY_SDR_API char* SoapySDRDevice_setIQBalance	(	SoapySDRDevice *	device,
		const int	direction,
		const size_t	channel,
		const double	balanceI,
		const double	balanceQ
	)

Set the frontend IQ balance correction.

Parameters

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
balanceI	the relative correction (1.0 max)
balanceQ	the relative correction (1.0 max)

Returns: an error message or NULL for success

SOAPY_SDR_API char* SoapySDRDevice_setMasterClockRate	(	SoapySDRDevice *	device,
		const double	rate
	)

Set the master clock rate of the device.

Parameters

device	a pointer to a device instance
rate	the clock rate in Hz

Returns: an error message or NULL for success

SOAPY_SDR_API char* SoapySDRDevice_setSampleRate	(	SoapySDRDevice *	device,
		const int	direction,
		const size_t	channel,
		const double	rate
	)

Set the baseband sample rate of the chain.

Parameters

device	a pointer to a device instance
direction	the channel direction RX or TX
channel	an available channel on the device
rate	the sample rate in samples per second

Returns: an error message or NULL for success

SOAPY_SDR_API char* SoapySDRDevice_setTimeSource	(	SoapySDRDevice *	device,
		const char *	source
	)

Set the time source on the device

Parameters

device	a pointer to a device instance
source	the name of a time source

Returns: an error message or NULL for success

SOAPY_SDR_API char* 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.

Format string markup guidelines:

C means complex
F means floating point
U means signed integer
S 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

On failure setup will return NULL and set the error. The error message string must be freed by the caller.

Parameters

	device	a pointer to a device instance
[out]	stream	the opaque pointer to a stream handle
	direction	the channel direction RX or TX
	format	the desired buffer format in read/writeStream()
	channels	a list of channels for empty for automatic
	numChans	the number of elements in the channels array
	args	stream args or empty for defaults
	errorMsg	an error string set on failure

Returns: an error message or NULL for success

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

device	a pointer to a device instance
addr	an address of an available SPI slave
data	the SPI data, numBits-1 is first out
numBits	the 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

device a pointer to a device object

SOAPY_SDR_API void SoapySDRDevice_writeGPIO	(	SoapySDRDevice *	device,
		const char *	bank,
		const unsigned	value
	)

Write the value of a GPIO bank.

Parameters

device	a pointer to a device instance
bank	the name of an available bank
value	an integer representing GPIO bits

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

device	a pointer to a device instance
addr	the address of the slave
data	an array of bytes write out
numBytes	the number of bytes to write

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.

Parameters

device	a pointer to a device instance
addr	the register address
value	the 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

device	a pointer to a device instance
key	the setting identifier
value	the 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.

Parameters

	device	a pointer to a device instance
	stream	the opaque pointer to a stream handle
	buffs	an array of void* buffers num chans in size
	numElems	the number of elements in each buffer
[in,out]	flags	optional input flags and output flags
	timeNs	the buffer's timestamp in nanoseconds
	timeoutUs	the 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

device	a pointer to a device instance
which	the name of an available UART
data	a null terminated array of bytes

Functions

Detailed Description

Function Documentation