MATLAB Testing Tools

Overview

This tutorial explains the main features of srsRAN-matlab, a MATLAB-based project for testing srsRAN Project. More specifically, this tutorial will show how to generate a new set of test vectors for the srsRAN Project tests, how to analyze the uplink IQ samples recorded by srsRAN gNB, and how to run end-to-end, link-level simulations for testing PHY components of srsRAN Project. 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 the srsRAN Project. This tutorial will show how to generate the set of vectors used for unit testing inside the srsRAN 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:

Note

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

Installation

Assuming that srsRAN Project 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

Note

This tutorial assumes that srsRAN Project 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 srsRAN Project are tested by feeding each component with vectors of input data and comparing the resulting output with their expected values. In srsRAN Project, 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 the srsRAN Project 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 the srsRAN Project 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)