Application Programming Interface (API)
Avnet RFSoC Explorer 2.0 introduces an API for programmatic control of all RF-ADC and RF-DAC parameters, signal generation, acquisition and Otava DTRX2 mmwave functions.
To get started, use the MATLAB R2021a built in help:
>> help Avnet_RFSoC_Explorer
For a full listing of API functions and their usage, use the API itself:
>> Avnet_RFSoC_Explorer('help')
Use the API to search help:
>> Avnet_RFSoC_Explorer('help', 'ADC')
API_functions related to 'ADC':
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_tile_enable', <tile>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_tile_disable', <tile>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_tile_open', <tile>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_calibration_status', <tile>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_program', <tile>, <calibrate>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_memory_type' <tile>, <memtype>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_sample_rate', <tile>, <sample_rate_MHz>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_channel_enable', <tile>, <chan>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_channel_disable', <tile>, <chan>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_read', <tile>, <chan>, <nSamples>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_setDSA', <tile>, <chan>, <dB-attenuation>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_decimation', <tile>, <chan>, <rate_change>)
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_mixer', <tile>, <chan>, <params>)
Main API help
Avnet_RFSoC_Explorer Application programmer interface (API) created by Avnet, Inc.
to connect Xilinx Zynq® UltraScale+™ RFSoC gigasample data converters to MATLAB®
and Simulink®.
[STATUS, DATA, MSG] = Avnet_RFSoC_Explorer(API_FUNCTION, VARARGIN)
executes the command string defined by API_FUNCTION and returns a
STATUS boolean pass/fail (true/false) , any DATA values, and
error/warning MSG. Use VARARGIN to provide relevant additional
paramters.
For help with syntax and VARARGIN:
Avnet_RFSoC_Explorer('help', API_FUNCTION); % Search function string
Avnet_RFSoC_Explorer('help', <string>); % Search partial string
API_FUNCTION strings for RFSoC:
-- Global --
'help' % Also try ('help', <string>)
'startup' % Use alone or with board_id
'shutdown' % Close GUI and release the application
'ipconfig' % Board IP address
'Memory_type' % RFSoC Gen1/ZCU111 memory type is global
'DTRX2' % RFSoC Gen3/ZCU208 with Otava DTRX2 mmW card
'Program_CLK104_LMK' % Program CLK104 module LMK PLL (ZCU208 only)
-- RF-ADC --
'ADC_tile_enable' % RFSoC Explorer parameter != RFDC IP setting
'ADC_tile_disable' % RFSoC Explorer parameter != RFDC IP setting
'ADC_tile_open' % Opens tile tab in the GUI
'ADC_channel_enable' % Performs tile enable if required
'ADC_channel_disable' % Resets channel parameters
'ADC_memory_type' % RFSoC Gen3/ZCU208 memory type is per tile
'ADC_setDSA' % Digital Step Attenuator (Gen3)
'ADC_sample_rate' % Tile internal PLL in MHz
'ADC_decimation' % Available integer factors depend on RFSoC Gen
'ADC_mixer' % Requires struct of mixer parameters
'ADC_calibration_status'% Calibration of interleaved ADC required?
'ADC_program' % Program target board with user settings
'ADC_read' % Transfer samples from ADC buffer to PC
-- RF-DAC --
'DAC_tile_enable' % RFSoC Explorer parameter != RFDC IP setting
'DAC_tile_disable' % RFSoC Explorer parameter != RFDC IP setting
'DAC_tile_open' % Opens tile tab in the GUI
'DAC_channel_enable' % Performs tile enable if required
'DAC_channel_disable' % Resets channel parameters
'DAC_memory_type' % RFSoC Gen3/ZCU208 memory type is per tile
'DAC_setVOP' % Variable Output Power (Gen3)
'DAC_sample_rate' % Tile internal PLL in MHz
'DAC_interpolation' % Available integer factors depend on RFSoC Gen
'DAC_mixer' % Requires struct of mixer parameters
'DAC_DUC_mode' % Image Rejection Modes (RFSoC Gen3)
'DAC_VOP' % Variable Output Power (RFSoC Gen3)
'DAC_signal_source' % Setup DAC signal type and parameter structure
'DAC_program' % Program target board with user settings
'DAC_write' % Transfer waveform from PC to DAC buffer for replay
'DAC_signal_level' % dBFS only
Examples:
Enable DAC tile 3 chan 0:
[error_flag, data, msg] = Avnet_RFSoC_Explorer('DAC_channel_enable', 3, 0);
Set ADC tile 0 sample rate to 4915.2 MHz :
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_sample_rate', 0, 4915.2);
Program ADC tile 0 and read 8192 samples :
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_program', 0);
[error_flag, data, msg] = Avnet_RFSoC_Explorer('ADC_read', 0, 8192);
Program DAC tile 1 chan 2 mixer:
% Create structure with mixer parameters
params.Freq = +4700; % MHz
params.PhaseOffset = 0; % Degrees
params.MixerMode = 'IQ->Real'; % 'Real->Real'|'IQ->Real'
params.MixerType = 'Fine'; % 'Fine'|'Coarse'
% Set mixer parameters and program the board
[error_flag, data, msg] = Avnet_RFSoC_Explorer('DAC_mixer', 1, 2, params);
[error_flag, data, msg] = Avnet_RFSoC_Explorer('DAC_program', 1);
More examples are located in the /scripts folder.
Otava DTRX2 mmWave API Help (ZCU208 only)
Avnet_RFSoC_Explorer API to Otava DTRx2 mmWave Daughtercard for ZCU208
Usage :
Avnet_RFSoC_Explorer('DTRX2', <dtrx2_cmd>) sends the command defined by 'dtrx2_cmd' to DTRx mmWave Daughtercard for ZCU208
ex. Avnet_RFSoC_Explorer('DTRX2','TX_power_up')
Available dtrx2_cmd API strings :
TX_power_up % TX power up: DSA is enabled; TX channels remain disabled until call to TX_Ch1_IfAmp/2_Enable
TX_power_down % TX power down
TX_VCO_OutA_Enable % turn on TX VCO A
TX_VCO_OutB_Enable % turn on TX VCO B
TX_IF_AMP_Ch1_Enable % turn on TX Channel 1
TX_IF_AMP_Ch1_Disable % turn off TX Channel 1
TX_IF_AMP_Ch2_Enable % turn on TX Channel 2
TX_IF_AMP_Ch2_Disable % turn off TX Channel 2
TX_Update_GC_Button % Update Gain Control (DSA) in TX chain; programmatic equivalent of user pressing GUI 'Update TX Gain Control' Button
TX_Update_PLL_Button
RX_power_up % RX power up: RF/IF DSAs are enabled; RX channels remain disabled until calls to RX_Ch1_RfAmp/2_Enable & RX_Ch1_IfAmp/2_Enable
RX_power_down
RX_Ch1_RfAmp_Enable % turn on RX Channel 1 RF LNA
RX_Ch1_IfAmp_Enable % turn on RX Channel 1 IF LNA -> Both LNA switches On -> will turn on RX Channel 1
RX_Ch1_RfAmp_Disable % turn off RX Channel 1 RF LNA
RX_Ch1_IfAmp_Disable % turn off RX Channel 1 IF LNA -> When both switches Off -> disable RX channel 1, leaving DSAs at current attenutation settings
RX_Ch2_RfAmp_Enable
RX_Ch2_IfAmp_Enable
RX_Ch2_RfAmp_Disable
RX_Ch2_IfAmp_Disable
RX_Update_GC_ch1_Button % Update Gain Control (DSA) in RX chain; programmatic equivalent of user pressing GUI 'Update RX Gain Control' Button
RX_Update_GC_ch2_Button
RX_Update_PLL_Button
Avnet_RFSoC_Explorer('DTRX2', <dtrx2_cmd>, <parameter>)
ex. Avnet_RFSoC_Explorer('DTRX2', 'TX_RF_DSA_Attenuation', 10) => set TX RF DSA Attenuation = 10 dB
Available dtrx2_cmd strings with parameter :
TX_VCO_Pwr_OutA, parameter = TX VCO A power code (0 ... 50) incl. (Note: by default VCO power is dependant on PLL frequency, but it can be forced / over-ridden by this property)
TX_VCO_Pwr_OutB, parameter = TX VCO B power code (0 ... 50) incl. " " ...
TX_RF_DSA_Attenuation, parameter = TX RF DSA Attenuation (dB), range 0 ... 15.5 dB of positive attenuation (- gain) in 1/2 dB step
TX_mmWave_Fc, parameter = TX output mmWave center frequency (GHz)
TX_IF_signal_BW, parameter = TX signal bandwidth (MHz)
RX_VCO_Pwr_OutA, parameter = RX VCO A power code (0 ... 50) incl. (Note: by default VCO power is dependant on PLL frequency, but it can be over-ridden by this property)
RX_VCO_Pwr_OutB, parameter = RX VCO B power code (0 ... 50) incl. " " ...
RX_mmWave_Fc, parameter = RX input mmWave center frequency (GHz)
RX_IF_signal_BW, parameter = RX signal bandwidth (MHz)
RX_RF_DSA_Ch1_Attenuation, parameter = RX RF DSA Channel 1 Attenuation (dB), range 0 ... 14 dB of positive attenuation (- gain) in 2 dB step
RX_IF_DSA_Ch1_Attenuation, parameter = RX I/F DSA Channel 1 Attenuation (dB), range 0 ... 32 dB of positive attenuation (- gain) in 1/2 dB step
RX_RF_DSA_Ch2_Attenuation, parameter = RX RF DSA Channel 2 Attenuation (dB)
RX_IF_DSA_Ch2_Attenuation, parameter = RX I/F DSA Channel 2 Attenuation (dB)