LMS API Documentation: High-level control functions

LMS API Documentation v20.10.0

Modules | Data Structures | Typedefs | Enumerations | Functions | Variables
High-level control functions

## Modules
| Advanced control functions

## Data Structures
struct | lms_range_t

## Typedefs
typedef char | lms_name_t[16]

## Enumerations
enum | lms_testsig_t { LMS_TESTSIG_NONE =0 , LMS_TESTSIG_NCODIV8 , LMS_TESTSIG_NCODIV4 , LMS_TESTSIG_NCODIV8F , LMS_TESTSIG_NCODIV4F , LMS_TESTSIG_DC }
enum | { LMS_PATH_NONE = 0 , LMS_PATH_LNAH = 1 , LMS_PATH_LNAL = 2 , LMS_PATH_LNAW = 3 , LMS_PATH_TX1 = 1 , LMS_PATH_TX2 = 2 , LMS_PATH_AUTO = 255 }
| Enumeration of RF ports. More...

## Functions
API_EXPORT int CALL_CONV | LMS_Init (lms_device_t *device)
API_EXPORT int CALL_CONV | LMS_GetNumChannels (lms_device_t *device, bool dir_tx)
API_EXPORT int CALL_CONV | LMS_EnableChannel (lms_device_t *device, bool dir_tx, size_t chan, bool enabled)
API_EXPORT int CALL_CONV | LMS_SetSampleRate (lms_device_t *device, float_type rate, size_t oversample)
API_EXPORT int CALL_CONV | LMS_GetSampleRate (lms_device_t *device, bool dir_tx, size_t chan, float_type *host_Hz, float_type *rf_Hz)
API_EXPORT int CALL_CONV | LMS_GetSampleRateRange (lms_device_t *device, bool dir_tx, lms_range_t *range)
API_EXPORT int CALL_CONV | LMS_SetLOFrequency (lms_device_t *device, bool dir_tx, size_t chan, float_type frequency)
API_EXPORT int CALL_CONV | LMS_GetLOFrequency (lms_device_t *device, bool dir_tx, size_t chan, float_type *frequency)
API_EXPORT int CALL_CONV | LMS_GetLOFrequencyRange (lms_device_t *device, bool dir_tx, lms_range_t *range)
API_EXPORT int CALL_CONV | LMS_GetAntennaList (lms_device_t *dev, bool dir_tx, size_t chan, lms_name_t *list)
API_EXPORT int CALL_CONV | LMS_SetAntenna (lms_device_t *dev, bool dir_tx, size_t chan, size_t index)
API_EXPORT int CALL_CONV | LMS_GetAntenna (lms_device_t *dev, bool dir_tx, size_t chan)
API_EXPORT int CALL_CONV | LMS_GetAntennaBW (lms_device_t *dev, bool dir_tx, size_t chan, size_t index, lms_range_t *range)
API_EXPORT int CALL_CONV | LMS_SetNormalizedGain (lms_device_t *device, bool dir_tx, size_t chan, float_type gain)
API_EXPORT int CALL_CONV | LMS_SetGaindB (lms_device_t *device, bool dir_tx, size_t chan, unsigned gain)
API_EXPORT int CALL_CONV | LMS_GetNormalizedGain (lms_device_t *device, bool dir_tx, size_t chan, float_type *gain)
API_EXPORT int CALL_CONV | LMS_GetGaindB (lms_device_t *device, bool dir_tx, size_t chan, unsigned *gain)
API_EXPORT int CALL_CONV | LMS_SetLPFBW (lms_device_t *device, bool dir_tx, size_t chan, float_type bandwidth)
API_EXPORT int CALL_CONV | LMS_GetLPFBW (lms_device_t *device, bool dir_tx, size_t chan, float_type *bandwidth)
API_EXPORT int CALL_CONV | LMS_GetLPFBWRange (lms_device_t *device, bool dir_tx, lms_range_t *range)
API_EXPORT int CALL_CONV | LMS_SetLPF (lms_device_t *device, bool dir_tx, size_t chan, bool enable)
API_EXPORT int CALL_CONV | LMS_SetGFIRLPF (lms_device_t *device, bool dir_tx, size_t chan, bool enabled, float_type bandwidth)
API_EXPORT int CALL_CONV | LMS_Calibrate (lms_device_t *device, bool dir_tx, size_t chan, double bw, unsigned flags)
API_EXPORT int CALL_CONV | LMS_LoadConfig (lms_device_t *device, const char *filename)
API_EXPORT int CALL_CONV | LMS_SaveConfig (lms_device_t *device, const char *filename)
API_EXPORT int CALL_CONV | LMS_SetTestSignal (lms_device_t *device, bool dir_tx, size_t chan, lms_testsig_t sig, int16_t dc_i, int16_t dc_q)
API_EXPORT int CALL_CONV | LMS_GetTestSignal (lms_device_t *device, bool dir_tx, size_t chan, lms_testsig_t *sig)
API_EXPORT int CALL_CONV | LMS_GetChipTemperature (lms_device_t *dev, size_t ind, float_type *temp)

## Variables
static const bool | LMS_CH_TX = true
| Convenience constants for TX selection. More...
static const bool | LMS_CH_RX = false
| Convenience constants for RX selection. More...

## Detailed Description

The functions in this section provide the ability to easily configure the device for operation. They modify multiple internal device settings.

## Typedef Documentation

## ◆ lms_name_t

typedef char lms_name_t[16]

Convenience type for fixed length name string

Definition at line 132 of file LimeSuite.h.

## Enumeration Type Documentation

## ◆ anonymous enum

anonymous enum

Enumeration of RF ports.

Enumerator
LMS_PATH_NONE | No active path (RX or TX)
LMS_PATH_LNAH | RX LNA_H port.
LMS_PATH_LNAL | RX LNA_L port.
LMS_PATH_LNAW | RX LNA_W port.
LMS_PATH_TX1 | TX port 1.
LMS_PATH_TX2 | TX port 2.
LMS_PATH_AUTO | Automatically select port (if supported)

Definition at line 280 of file LimeSuite.h.

## ◆ lms_testsig_t

enum lms_testsig_t

Enumeration of LMS7 TEST signal types

Enumerator
LMS_TESTSIG_NONE | Disable test signals. Return to normal operation.
LMS_TESTSIG_NCODIV8 | Test signal from NCO half scale.
LMS_TESTSIG_NCODIV4 | Test signal from NCO half scale.
LMS_TESTSIG_NCODIV8F | Test signal from NCO full scale.
LMS_TESTSIG_NCODIV4F | Test signal from NCO full scale.
LMS_TESTSIG_DC | DC test signal.

Definition at line 143 of file LimeSuite.h.

## Function Documentation

## ◆ LMS_Calibrate()

API_EXPORT int CALL_CONV LMS_Calibrate | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | double | bw,
|  | unsigned | flags
| ) |  |

Perform the automatic calibration of specified RX/TX channel. The automatic calibration must be run after device configuration is finished because calibration values are dependant on various configuration settings.

Precondition
  Device should be configured

Parameters

  device | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX
  chan | channel index
  bw | bandwidth
  flags | additional calibration flags (normally should be 0)

Returns
  0 on success, (-1) on failure

## ◆ LMS_EnableChannel()

API_EXPORT int CALL_CONV LMS_EnableChannel | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | bool | enabled
| ) |  |

Enable or disable specified RX or TX channel. Some API functions will fail when performed on disabled channel.

Parameters

  [in] | device | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  | chan | Channel index
  | enabled | true(1) to enable, false(0) to disable.

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetAntenna()

API_EXPORT int CALL_CONV LMS_GetAntenna | ( | lms_device_t * | dev,
|  | bool | dir_tx,
|  | size_t | chan
| ) |  |

Obtain currently selected antenna of the the specified RX or TX channel.

Parameters

  dev | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX
  chan | channel index

Returns
  Index of selected antenna on success, (-1) on failure

## ◆ LMS_GetAntennaBW()

API_EXPORT int CALL_CONV LMS_GetAntennaBW | ( | lms_device_t * | dev,
|  | bool | dir_tx,
|  | size_t | chan,
|  | size_t | index,
|  | lms_range_t * | range
| ) |  |

Obtains recommended bandwidth (lower and upper frequency) for the specified antenna port. The ports can be used outside this range.

Parameters

  | dev | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  | chan | channel index
  | index | Antenna index
  [out] | range | Antenna bandwidth

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetAntennaList()

API_EXPORT int CALL_CONV LMS_GetAntennaList | ( | lms_device_t * | dev,
|  | bool | dir_tx,
|  | size_t | chan,
|  | lms_name_t * | list
| ) |  |

Obtain antenna list with names. First item in the list is the name of antenna index 0.

Parameters

  | dev | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  | chan | channel index
  [out] | list | List of antenna names (can be NULL)

Returns
  number of available antennae, (-1) on failure

## ◆ LMS_GetChipTemperature()

API_EXPORT int CALL_CONV LMS_GetChipTemperature | ( | lms_device_t * | dev,
|  | size_t | ind,
|  | float_type * | temp
| ) |  |

Read LMS7 chip internal temperature sensor

Parameters

  dev | Device handle previously obtained by LMS_Open().
  ind | chip index
  temp | temperature value

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetGaindB()

API_EXPORT int CALL_CONV LMS_GetGaindB | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | unsigned * | gain
| ) |  |

Obtain the current combined gain value in dB

Note
  actual gain depends on LO frequency and analog LPF configuration and resulting output signal level may be different when those values are changed

Attention
  Gain functionality and range will be changed in the future. IAMP and TIA gain element values won't be obtained via this function. To enable new behaviour, turn on ENABLE_NEW_GAIN_BEHAVIOUR CMake option.

Parameters

  | device | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  | chan | Channel index
  [out] | gain | Current gain

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetLOFrequency()

API_EXPORT int CALL_CONV LMS_GetLOFrequency | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | float_type * | frequency
| ) |  |

Obtain the current RF center frequency in Hz.

Parameters

  | device | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  | chan | Channel index
  [out] | frequency | Current RF center frequency in Hz

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetLOFrequencyRange()

API_EXPORT int CALL_CONV LMS_GetLOFrequencyRange | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | lms_range_t * | range
| ) |  |

Obtain the supported RF center frequency range in Hz.

Parameters

  | device | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  [out] | range | Supported RF center frequency in Hz

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetLPFBW()

API_EXPORT int CALL_CONV LMS_GetLPFBW | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | float_type * | bandwidth
| ) |  |

Get the currently configured analog LPF RF bandwidth.

Note
  readback from board is currently not supported, only returns last set value cached by software.

Parameters

  | device | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  | chan | Channel index
  [out] | bandwidth | Current LPF bandwidth in Hz

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetLPFBWRange()

API_EXPORT int CALL_CONV LMS_GetLPFBWRange | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | lms_range_t * | range
| ) |  |

Get the RF bandwidth setting range supported by the analog LPF of LMS chip.

Parameters

  | device | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  [out] | range | Supported RF bandwidth range in Hz

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetNormalizedGain()

API_EXPORT int CALL_CONV LMS_GetNormalizedGain | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | float_type * | gain
| ) |  |

Obtain the current combined gain value

Note
  actual gain depends on LO frequency and analog LPF configuration and resulting output signal level may be different when those values are changed

Attention
  Gain functionality will be changed in the future. IAMP and TIA gain element values won't be obtained via this function. To enable new behaviour, turn on ENABLE_NEW_GAIN_BEHAVIOUR CMake option.

Parameters

  | device | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  | chan | Channel index
  [out] | gain | Current gain, range [0, 1.0], where 1.0 represents the maximum gain

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetNumChannels()

API_EXPORT int CALL_CONV LMS_GetNumChannels | ( | lms_device_t * | device,
|  | bool | dir_tx
| ) |  |

Obtain number of RX or TX channels. Use this to determine the maximum channel index (specifying channel index is required by most API functions). The maximum channel index is N-1, where N is number returned by this function

Parameters

  device | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX

Returns
  Number of channels on success, (-1) on failure

## ◆ LMS_GetSampleRate()

API_EXPORT int CALL_CONV LMS_GetSampleRate | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | float_type * | host_Hz,
|  | float_type * | rf_Hz
| ) |  |

Get the sampling rate of the specified RX or TX channel. The function obtains the sample rate used in data interface with the host and the RF sample rate used by DAC/ADC.

Parameters

  [in] | device | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  | chan | Channel index
  [out] | host_Hz | sampling rate used for data exchange with the host
  [out] | rf_Hz | RF sampling rate in Hz

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetSampleRateRange()

API_EXPORT int CALL_CONV LMS_GetSampleRateRange | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | lms_range_t * | range
| ) |  |

Get the range of supported sampling rates.

Parameters

  | device | Device handle previously obtained by LMS_Open().
  | dir_tx | Select RX or TX
  [out] | range | Allowed sample rate range in Hz.

Returns
  0 on success, (-1) on failure

## ◆ LMS_GetTestSignal()

API_EXPORT int CALL_CONV LMS_GetTestSignal | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | lms_testsig_t * | sig
| ) |  |

Get the currently active test signal

Parameters

  device | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX
  chan | Channel index
  sig | Currently active test signal

Returns
  0 on success, (-1) on failure

## ◆ LMS_Init()

API_EXPORT int CALL_CONV LMS_Init | ( | lms_device_t * | device | ) |

Configure LMS chip with settings that make it ready for operation.

Note
  This configuration differs from default LMS chip configuration which is described in chip datasheet. In order to load default chip configuration use LMS_Reset().

Parameters

  [in] | device | Device handle previously obtained by LMS_Open().

Returns
  0 on success, (-1) on failure

## ◆ LMS_LoadConfig()

API_EXPORT int CALL_CONV LMS_LoadConfig | ( | lms_device_t * | device,
|  | const char * | filename
| ) |  |

Load LMS chip configuration from a file

Note
  this only loads LMS chip configuration, in oder for streaming to work properly FPGA has also to be configured. Use LMS_SetSampleRate() to configure LMS and FPGA for streaming.

Parameters

  device | Device handle
  filename | path to file

Returns
  0 on success, (-1) on failure

## ◆ LMS_SaveConfig()

API_EXPORT int CALL_CONV LMS_SaveConfig | ( | lms_device_t * | device,
|  | const char * | filename
| ) |  |

Save LMS chip configuration to a file

Parameters

  device | Device handle
  filename | path to file with LMS chip configuration

Returns
  0 on success, (-1) on failure

## ◆ LMS_SetAntenna()

API_EXPORT int CALL_CONV LMS_SetAntenna | ( | lms_device_t * | dev,
|  | bool | dir_tx,
|  | size_t | chan,
|  | size_t | index
| ) |  |

Select the antenna for the specified RX or TX channel.

Parameters

  dev | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX
  chan | channel index
  index | Index of antenna to select

Returns
  0 on success, (-1) on failure

## ◆ LMS_SetGaindB()

API_EXPORT int CALL_CONV LMS_SetGaindB | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | unsigned | gain
| ) |  |

Set the combined gain value in dB This function computes and sets the optimal gain values of various amplifiers that are present in the device based on desired gain value in dB.

Note
  actual gain depends on LO frequency and analog LPF configuration and resulting output signal levle may be different when those values are changed

Attention
  Gain functionality and range will be changed in the future. IAMP and TIA gain elements won't configured via this function. To enable new behaviour, turn on ENABLE_NEW_GAIN_BEHAVIOUR CMake option.

Parameters

  device | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX
  chan | Channel index
  gain | Desired gain, range [0, 73]

Returns
  0 on success, (-1) on failure

## ◆ LMS_SetGFIRLPF()

API_EXPORT int CALL_CONV LMS_SetGFIRLPF | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | bool | enabled,
|  | float_type | bandwidth
| ) |  |

Set up digital LPF using LMS chip GFIRS. This is a convenience function to quickly configure GFIRS as LPF with desired RF bandwidth.

Precondition
  sampling rate must be set

Parameters

  device | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX
  chan | channel index
  enabled | Disable (false) or enable (true) GFIRS.
  bandwidth | LPF bandwidth in Hz. Has no effect if enabled is false.

Returns
  0 on success, (-1) on failure

## ◆ LMS_SetLOFrequency()

API_EXPORT int CALL_CONV LMS_SetLOFrequency | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | float_type | frequency
| ) |  |

Set RF center frequency in Hz.

Note
  channels A and B in LMS7 chip share the same clock so ability to set different frequencies for channels A and B is very limited. This function will attempt to achieve different requested frequencies using NCO when possible, however often changing frequency for one (A or B) channel will result in frequency being changed for both (A and B) channels.

Parameters

  device | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX
  chan | Channel index
  frequency | Desired RF center frequency in Hz

Returns
  0 on success, (-1) on failure

## ◆ LMS_SetLPF()

API_EXPORT int CALL_CONV LMS_SetLPF | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | bool | enable
| ) |  |

Disables or enables the analog LPF of LMS chip without reconfiguring it.

Parameters

  device | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX
  chan | Channel index
  enable | true(1) to enable, false(0) to disable

Returns
  0 on success, (-1) on failure

## ◆ LMS_SetLPFBW()

API_EXPORT int CALL_CONV LMS_SetLPFBW | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | float_type | bandwidth
| ) |  |

Configure analog LPF of the LMS chip for the desired RF bandwidth. This function automatically enables LPF.

Parameters

  device | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX
  chan | Channel index
  bandwidth | LPF bandwidth in Hz

Returns
  0 on success, (-1) on failure

## ◆ LMS_SetNormalizedGain()

API_EXPORT int CALL_CONV LMS_SetNormalizedGain | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | float_type | gain
| ) |  |

Set the combined gain value This function computes and sets the optimal gain values of various amplifiers that are present in the device based on desired normalized gain value.

Note
  actual gain depends on LO frequency and analog LPF configuration and resulting output signal level may be different when those values are changed

Attention
  Gain functionality will be changed in the future. IAMP and TIA gain elements won't configured via this function. To enable new behaviour, turn on ENABLE_NEW_GAIN_BEHAVIOUR CMake option.

Parameters

  device | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX
  chan | Channel index
  gain | Desired gain, range [0, 1.0], where 1.0 represents the maximum gain

Returns
  0 on success, (-1) on failure

## ◆ LMS_SetSampleRate()

API_EXPORT int CALL_CONV LMS_SetSampleRate | ( | lms_device_t * | device,
|  | float_type | rate,
|  | size_t | oversample
| ) |  |

Set sampling rate for all RX/TX channels. Sample rate is in complex samples (1 sample = I + Q). The function sets sampling rate that is used for data exchange with the host. It also allows to specify higher sampling rate to be used in RF by setting oversampling ratio. Valid oversampling values are 1, 2, 4, 8, 16, 32 or 0 (use device default oversampling value).

Parameters

  [in] | device | Device handle previously obtained by LMS_Open().
  | rate | sampling rate in Hz to set
  | oversample | RF oversampling ratio.

Returns
  0 on success, (-1) on failure

## ◆ LMS_SetTestSignal()

API_EXPORT int CALL_CONV LMS_SetTestSignal | ( | lms_device_t * | device,
|  | bool | dir_tx,
|  | size_t | chan,
|  | lms_testsig_t | sig,
|  | int16_t | dc_i,
|  | int16_t | dc_q
| ) |  |

Apply the specified test signal

Parameters

  device | Device handle previously obtained by LMS_Open().
  dir_tx | Select RX or TX.
  chan | Channel index.
  sig | Test signal. LMS_TESTSIG_NONE disables test signal.
  dc_i | DC I value for LMS_TESTSIG_DC mode. Ignored in other modes.
  dc_q | DC Q value for LMS_TESTSIG_DC mode. Ignored in other modes.

Returns
  0 on success, (-1) on failure

## Variable Documentation

## ◆ LMS_CH_RX

const bool LMS_CH_RX = false
| static

Convenience constants for RX selection.

Definition at line 129 of file LimeSuite.h.

## ◆ LMS_CH_TX

const bool LMS_CH_TX = true
| static

Convenience constants for TX selection.

Definition at line 128 of file LimeSuite.h.