Skip to main content

MATLAB Testing Tools

Overview​

This tutorial explains the main features of OCUDU 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.

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

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 OCUDU MATLAB testing suite requires a working and licensed 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 OCUDU MATLAB.

This can be done with the following command:

git clone https://gitlab.com/ocudu/ocudu_elements/ocudu-matlab
info

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

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

cd ~/ocudu-matlab
addpath .

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

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

If successful, the final section of the output should look similar to:

ans =

  1x131 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   131 Passed, 0 Failed, 0 Incomplete.
   242.2176 seconds testing time.

The PHY components of OCUDU can be tested by feeding each component with vectors of input data and comparing the resulting output with their expected values. In this section of the tutorial we will learn how to generate these test vectors with OCUDU MATLAB and add the corresponding tests to the OCUDU main code.

Test vector generation

The files ocudu<ComponentName>Unittest.m in the main directory of OCUDU 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 OCUDU MATLAB.

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

runOCUDUunittest('all', 'testvector')

This will generate a .h file, with the vector descriptions, and a .tar.gz file, with the actual test vectors, for each of the PHY components and place them in the folder ~/ocudu-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 ~/ocudu/include/ocudu/. For example, the test vectors for the channel estimator, whose interface is declared in ~/ocudu/include/ocudu/phy/upper/signal_processors/port_channel_estimator.h, can be generated with the following command:

runOCUDUunittest('port_channel_estimator', 'testvector')

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

ocuduTest.copyOCUDUtestvectors('testvector_outputs', 'ocuduVectorTests')

By default, executing runOCUDUunittest will always generate the same test vectors. To generate a random set of vectors, we simply add the RandomShuffle option:

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

Build and run the vector tests

The folder ocuduVectorTests contains C++ code that, together with the test vectors generated above, can be imported into OCUDU as a plugin:

cd ~/ocudu
mkdir plugins
cd plugins
ln -s ~/ocudu-matlab/ocuduVectorTests ocudu_vectortests
cd ..

Next, make sure that plugins are imported in OCUDU when building the project:

cmake -B buildplugins -DENABLE_PLUGINS:BOOL=ON

CMake will notify the inclusion of the vector tests with the message

-- Adding plugin: plugins/ocudu_vectortests

Finally, compile and run the tests with

cmake --build buildplugins -j $(nproc) --target all_vector_tests
ctest --test-dir buildplugins -j $(nproc) -L vectortest