Skip to main content

MATLAB Testing Tools

Overview​

This tutorial explains the main features of srsRAN-matlab, a MATLAB-based project for testing OCUDU. More specifically, this tutorial will show how to generate a new set of test vectors for the OCUDU tests, how to analyze the uplink IQ samples recorded by the OCUDU gNB, and how to run end-to-end, link-level simulations for testing PHY components of OCUDU. This will be done across three independent sections.

srsRAN-matlab offers three main tools: the test vector generators, the uplink analyzers and the link-level simulators.

Test Vector Generation​

Test vectors are mainly used to test, develop and debug the PHY components of OCUDU. This tutorial will show how to generate the set of vectors used for unit testing inside the OCUDU repository. As well as outlining how to generate a new set of random vectors for broadening the extent of the tests.

Signal Analyzers​

The signal analyzers are useful for testing the uplink chain of the gNB. Specifically, they provide visual hints about the signal quality in the uplink slots.

Simulators​

The simulators can be used to estimate the performance of the PHY uplink channels under different configurations and channel conditions provided by MATLAB’s 3GPP-compliant models.

Set-Up Considerations​

For this application note, the following hardware and software are used:

info

Running the srsRAN-matlab testing suite requires a working copy of MATLAB and its 5G Toolbox

Installation​

Assuming that OCUDU and MATLAB have both been downloaded and installed, the next step is to download srsRAN-matlab.

This can be done with the following command:

git clone https://github.com/srsran/srsRAN_matlab.git
info

This tutorial assumes that OCUDU is installed in the users come directory.

Once it has been downloaded, the working directory for srsRAN-matlab should be added to MATLAB’s search path. This can be done from the MATLAB console with the following command:

cd ~/srsRAN_matlab
addpath .

To verify you have added srsRAN-matlab successfully to MATLAB’s search path, run the following command (again from the MATLAB console):

runtests('unitTests', Tag='matlab code')

If successful, the following output should be shown at the end of the console output:

ans =

  1x94 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   94 Passed, 0 Failed, 0 Incomplete.
   42.2176 seconds testing time.

The PHY components of OCUDU are tested by feeding each component with vectors of input data and comparing the resulting output with their expected values. In OCUDU, the test vectors for a PHY component usually consist of a number of binary files with input and output data, and a single shared header file that describes the test set-up and the content of the binary files. The binary files are packed in a single tarball. For example, the test vectors of the channel estimator are provided by the files port_channel_estimator_test_data.h and port_channel_estimator_test_data.tar.gz in ~/ocudu/tests/unittests/phy/upper/signal_processors.

The files srs<ComponentName>Unittest.m in the main directory of srsRAN-matlab provide the classes for generating such PHY input-output test vectors. This is done by leveraging MATLAB 5G Toolbox. These classes inherit from the MATLAB matlab.unittest.TestCase class, meaning all of the tools within MATLAB’s unit testing framework can be used with them. To facilitate the generation of test vectors, a simplified interface is provided with srsRAN-matlab.

To generate the test vectors for all PHY components the following code needs to be run from the MATLAB console:

runSRSRANUnittest('all', 'testvector')

This will generate a .h and .tar.gz file for each of the PHY components and place them in the folder ~/srsRAN_matlab/testvector_outputs..

The test vectors for a single PHY component can also be generated. This is done by replacing all with the name of the desired component, as per its declaration in ~/srsRAN_Project/include/srsran/. For example, the test vectors for the channel estimator, whose interface is declared in ~/srsRAN_Project/include/srsran/phy/upper/signal_processors/port_channel_estimator.h, can be generated with the following command:

runSRSRANUnittest('port_channel_estimator', 'testvector')

Once the test vectors have been generated, the pairs of .h and tar.gz files in the testvector_outputs folder can be transferred to OCUDU folder with the MATLAB command:

srsTest.copySRStestvectors('testvector_outputs', '~/srsRAN_Project/')

This command will automatically copy all test vectors to the proper subdirectory inside ~/srsRAN_Project/tests/unittests/phy.

By default, executing runSRSRANUnittest will reproduce the same test vectors as the ones provided with OCUDU repository. To generate a random set of vectors, we simply need to add the RandomShuffle option. This can be done with the following command:

runSRSRANUnittest('all', 'testvector', RandomShuffle=true)

The PHY components of OCUDU are tested by feeding each component with vectors of input data and comparing the resulting output with their expected values. In OCUDU, the test vectors for a PHY component usually consist of a number of binary files with input and output data, and a single shared header file that describes the test set-up and the content of the binary files. The binary files are packed in a single tarball. For example, the test vectors of the channel estimator are provided by the files port_channel_estimator_test_data.h and port_channel_estimator_test_data.tar.gz in ~/srsRAN_Project/tests/unittests/phy/upper/signal_processors.

The files srs<ComponentName>Unittest.m in the main directory of srsRAN-matlab provide the classes for generating such PHY input-output test vectors. This is done by leveraging MATLAB 5G Toolbox. These classes inherit from the MATLAB matlab.unittest.TestCase class, meaning all of the tools within MATLAB’s unit testing framework can be used with them. To facilitate the generation of test vectors, a simplified interface is provided with srsRAN-matlab.

To generate the test vectors for all PHY components the following code needs to be run from the MATLAB console:

runSRSRANUnittest('all', 'testvector')

This will generate a .h and .tar.gz file for each of the PHY components and place them in the folder ~/srsRAN_matlab/testvector_outputs..

The test vectors for a single PHY component can also be generated. This is done by replacing all with the name of the desired component, as per its declaration in ~/srsRAN_Project/include/srsran/. For example, the test vectors for the channel estimator, whose interface is declared in ~/srsRAN_Project/include/srsran/phy/upper/signal_processors/port_channel_estimator.h, can be generated with the following command:

runSRSRANUnittest('port_channel_estimator', 'testvector')

Once the test vectors have been generated, the pairs of .h and tar.gz files in the testvector_outputs folder can be transferred to OCUDU folder with the MATLAB command:

srsTest.copySRStestvectors('testvector_outputs', '~/srsRAN_Project/')

This command will automatically copy all test vectors to the proper subdirectory inside ~/srsRAN_Project/tests/unittests/phy.

By default, executing runSRSRANUnittest will reproduce the same test vectors as the ones provided with OCUDU repository. To generate a random set of vectors, we simply need to add the RandomShuffle option. This can be done with the following command:

runSRSRANUnittest('all', 'testvector', RandomShuffle=true)