Remote API - IQ Dump

The purpose of this tutorial is to show how to collect IQ data that are saved in separate files for each slot. For this purpose, Amarisoft provide a special java script called 'trx-iq-dump.js'.  There are several different ways to capture I/Q data, but this method is special in a few ways as below

• Save the I/Q for each slot in separate files with specified SFN
• Can save both downlink and uplink simulteneously (Three different options to save : DL only, UL only, DL and UL simulteneously)

NOTE : This method is supported from the release 2024-03-21.

NOTE : For now, this is supported only on Callbox, not UEsim yet.

Table of Contents

• Remote API - IQ Dump
• Introduction
• Summary of the Tutorial
• Test Setup
• Script Location
• Usage
• Test 1 : IQ dump on Callbox
• Run LTE Service
• Run IQ dump
• Post Processing

Introduction

Intelligent collection and analysis of IQ (In-phase and Quadrature) data is a pivotal aspect of modern wireless communications testing and validation, particularly in the context of 4G and 5G networks. IQ data represents the raw baseband signal information prior to modulation or after demodulation, providing critical insight into the integrity and performance of radio transmissions. Amarisoft, a leading provider of software-defined radio (SDR) solutions, facilitates advanced IQ data capture through specialized scripting interfaces. The 'trx-iq-dump.js' JavaScript tool enhances the granularity of IQ data acquisition by enabling per-slot data segmentation, thereby allowing users to save IQ samples for each slot in separate files indexed by System Frame Number (SFN). This approach is highly beneficial for debugging, performance analysis, and compliance testing, as it allows precise isolation and examination of specific radio frames. Architecturally, this method leverages Amarisoft’s flexible SDR platform, interfacing with the physical layer (PHY) to extract both downlink (DL) and uplink (UL) IQ samples in real-time. The ability to concurrently capture DL and UL data, with configurable options for selective or simultaneous acquisition, ensures comprehensive visibility into radio link dynamics. Such capabilities are essential for network engineers, protocol developers, and researchers aiming to verify signal fidelity, troubleshoot issues, or develop advanced radio algorithms. As part of the Amarisoft Callbox ecosystem, this feature integrates seamlessly with other network emulation and testing tools, reinforcing its significance within the broader wireless development and testing landscape.

• Context and Background
  • IQ data is fundamental for physical layer analysis in wireless communications, enabling detailed scrutiny of signal quality, interference, and protocol compliance.
  • Amarisoft’s software-defined radio platform provides extensible scripting support, allowing customized data capture workflows tailored to advanced testing scenarios.
  • The 'trx-iq-dump.js' script introduces a specialized mechanism to capture and organize IQ samples per slot, indexed by SFN, which is crucial for frame-level analysis.
• Relevance and Importance of the Tutorial
  • Slot-based IQ data capture is particularly valuable for diagnosing transient issues, verifying scheduling algorithms, and correlating protocol events with physical layer signals.
  • This tutorial empowers users to harness Amarisoft’s advanced data collection capabilities, enhancing their ability to conduct precise and repeatable RF testing.
  • Understanding this process is critical for professionals engaged in network equipment development, conformance testing, and research on next-generation wireless technologies.
• Learning Outcomes
  • Gain practical experience with Amarisoft’s scripting environment and IQ data capture tools.
  • Learn how to configure and execute slot-based IQ data dumps, including options for DL, UL, or both simultaneously.
  • Acquire skills to organize, analyze, and interpret slot-indexed IQ data for troubleshooting and optimization purposes.
  • Understand the integration of this workflow within the Amarisoft Callbox platform and its implications for broader testing and development activities.
• Prerequisite Knowledge and Skills
  • Familiarity with wireless communication fundamentals, particularly LTE/NR physical layer concepts.
  • Basic knowledge of Amarisoft Callbox architecture and operation.
  • Experience with scripting or command-line interfaces is advantageous for efficient use of the provided tools.
  • Understanding of IQ data structure and its relevance to signal analysis will enhance the value derived from the tutorial.

Summary of the Tutorial

This tutorial explains the procedure for capturing and post-processing I/Q data per slot using a dedicated script on the Callbox platform, focusing on NR SA scenarios.

• Test Setup:
  • No specific requirements for the test setup; the tool can be used in any Callbox configuration.
  • The I/Q data capture script, trx-iq-dump.js, is located in the /root/enb directory.
• Script Usage:
  • The script is executed as ./trx-iq-dump.js [--tx|--rx] <host:[port]> <path> [duration in ms, default=1000].
  • For capturing both downlink and uplink data, use the command ./trx-iq-dump.js enb --tx --rx /tmp/iqs 10000, which captures I/Q data for 10 seconds and stores it in /tmp/iqs.
  • Ensure the target directory for saving I/Q data exists prior to running the script.
• Test Procedure (IQ Dump on Callbox):
  • Configure a NR SA cell and start the LTE service, preparing the environment for I/Q capture.
  • Start the I/Q dump script just before powering on the UE or at any desired capture start time.
  • Immediately after starting the script, power on the UE. The timing of UE power-on can be adjusted based on test requirements.
  • After the capture duration, the specified directory (/tmp/iqs) will contain:
    • JSON files (rf_port#.json) holding meta data and configuration information.
    • Binary files (*.bin) for I/Q data, one per slot, with filenames indicating SFN and slot number.
• Post Processing:
  • No official post-processing script is provided due to varying user requirements, but a sample Python script is shared as an example.
  • The example script (tested on Python 3.11.5 and Windows 11) provides a GUI for browsing and visualizing captured I/Q data.
  • Users select the directory containing the I/Q files; the GUI lists all files and displays meta data from the JSON file.
  • Upon selecting a file, the script generates four plots:
    • Waveform - Spectrum: FFT result for the entire slot (14 OFDM symbols).
    • Waveform - Power vs Time: Magnitude of each sample point for the slot.
    • Spectrogram - OFDM Symbols vs Spectrum: Data split into 14 blocks (one per OFDM symbol), FFT applied to each, and results shown in 2D dB scale.
    • Spectrogram - Power vs Time: Data split into 14 blocks; magnitude plotted as a 2D image without FFT.
  • Plots default to dB (log) scale; users can switch to linear scale via a combobox for alternate visualization.
  • No advanced post-processing (e.g., synchronization, equalization, or CP removal) is performed in the provided script—only basic plotting is implemented.

Test Setup

You can use this tool in any test setup on Callbox. No specific requirement for test setup.

Script Location

For the purpose of capturing and saving I/Q for each slot in separate file, we provided a special script named trx-iq-dump.js which are located in the directory /root/enb

The script is trx-iq-dump.js, 5289 bytes. It sits next to ws.js, the general remote API tool, so you run it from /root/enb.

Usage

The usage of this script is simple as ./trx-iq-dump.js [--tx|--rx] <host:[port]> <path> [duration is ms, default=1000]

Run ./trx-iq-dump.js --help to print this usage. In this installation the script is /root/lteenb-linux-2024-03-18/trx-iq-dump.js.

--tx selects the DL I/Q and --rx selects the UL I/Q. You can give both. host:[port] is the remote API address, and path is the output directory. The duration is in ms. Without it, the script records for 1000 ms.

Test 1 : IQ dump on Callbox

In this test, I will show you how to collect IQ data both for DL and UL in NR SA.

Run LTE Service

Configure a NR SA cell in any way you like and run LTE service. In my case, I wanted to capture the I/Q data for the entire period from UE power-on through the completion of initial attach.

Run IQ dump

Right before UE power on (or at any time you want to start the capture), run IQ dump script as ./trx-iq-dump.js enb --tx --rx  /tmp/iqs 10000. By this command, it will capture the IQ on 'enb' for both DL(--tx) and UL(--rx) for 10 seconds (10000 ms) and save the file in the directory /tmp/iqs. (NOTE : It is assumed that the directory /tmp/iqs exists already. If not, create the directory before running the script)

Right after the script run, power on UE. (NOTE :  In my test, I powered on UE right after the script run, but the timing of UE power on can vary depending on your use case).

The script prints its steps while it runs. Clean directory comes first, so the files already in /tmp/iqs are removed. Then Start capture runs for the 10000 ms.

Split by slot then divides the data into one file per slot. Process /tmp/iqs/rx00 and Process /tmp/iqs/tx00 handle the UL and DL data of rf_port 0. If you want to keep the files of an earlier run, move them out of /tmp/iqs first.

Once the data is captured, you would see the list of files stored in the specified directory (/tmp/iqs in this case). You would see rf_port#.json file where # indicates rf_port number). This json file contains meta data (fundamental configurations). *.bin file is the IQ data file. One file is created for every slot. The digits at the end of file name -abcd-nm indicates the SFN and slot number. 'abcd' indicates SFN and 'mn' indicates slot number.

I listed the first 20 entries with ll /tmp/iqs | head -n 20. The metadata file is rf_port0.json, 1239 bytes.

The IQ data files follow it, e.g, rf_port0-rx0-0463.19.bin to rf_port0-rx0-0480.19.bin. In these names, rx0 is the UL of rf_port 0, 0463 is the SFN and 19 is the slot. Each slot file is 78912 bytes. ll reports total 1964560 for the directory.

Post Processing

Once you capture the channel data that you wanted, you can write your own script to post process it as you desire. We don't provide any post processing script in installation because the technical requirement for the post process would be different for every users. Instead, I would share an example of post processing script written in python for this tutorial. You can download it here. (I would not explain about the script itself). The Python version that I used is 'Python 3.11.5' and I tested this script on Windows 11.  You may use this script as a template and extend it in anyway you like.

Once you run the script, you will get the initial GUI as shown below.

The Directory field at the top is empty until you select a folder with the [...] button. The File List on the left is also empty.

The row above the plots has fields for Frequency (TX), Frequency (RX), NRB(DL), the second NRB field, Sample Rate and Numerology. These are filled from the meta data. The Scale combobox is set to dB, and there is a [Plot] button next to it. The four empty areas below are for the four plots.

Hit [...] button to popup file browser dialog box. Select the directory that contains the IQ files (NOTE : You just need to select a directory name, not a specific file within the directory) and hit [Select Folder] button.

In this run, the IQ folders are on the Windows PC under C:\RyuCloud\Amarisoft\Software\IQViewer\bin. I selected the folder iqs_nr_sa_20Mhz_InitialAttach_10RB_rxgain_auto_r02. The other folders in the list are from earlier LTE and NR runs.

Then the File List box (listbox on the left) is populated with all the files in the selected directory and some basic information from the meta data file(*.json) is displayed in labels highlighted in blue rectangle.

The File List shows the tx0 files, e.g, rf_port0-tx0-0952.06.bin to rf_port0-tx0-0953.19.bin. These are the DL slots of rf_port 0.

From the meta data, Frequency (TX) and Frequency (RX) are both 3489420000. Both NRB fields are 51. The Sample Rate is 23040000 and the Numerology is 1.

If you select one of the file name in the File List, four different plots for the I/Q data will be displayed. By default all the data is plotted in dB scale. I didn't do any other post processing like synchronization, equalization , CP removal etc. I just plotted the data in different ways. This is a brief description on each plot.

• Waveform - Spectrum : This is the result of FFT for the entire slot (i.e, I/Q data of 14 OFDM symbols).
• Waveform - Power vs Time : This is the result of magnitude of each sample point for the entire slot (i.e, I/Q data of 14 OFDM symbols).
• Spectrogram - OFDM Symbols vs Spectrum : Splitted the data into 14 blocks (each block corresponds to one OFDM symbol) , do FFT for each and every block and plot the result of the 14 FFT blocks in dB scale on 2D image. (NOTE : Just splitting the data into 14 blocks with the same szie is not 100% accurate because the first OFDM symbol has a little bit longer CP than other OFDM symbol, but just for the spectrum analysis the current implementation would be good enough)
• Spectrogram - Power vs Time : Splitted the data into 14 blocks (each block corresponds to one OFDM symbol) as above  but does not do FFT for each block. Just calculate the magnitude of each sample point(a complex number) and plot the result  on 2D image. (NOTE : Just splitting the data into 14 blocks with the same size is not 100% accurate because the first OFDM symbol has a little bit longer CP than other OFDM symbol, but just for the spectrum analysis the current implementation would be good enough)

In this example I selected rf_port0-tx0-0956.00.bin, which is SFN 956 and slot 0 of the DL.

In Waveform - Power vs Time, the power drops to about -200 dB for a short period near the start of the slot. The same period appears as a low power line at OFDM symbol 1 in Spectrogram - Power vs Time.

In Spectrogram - OFDM Symbol vs Spectrum, symbol 0 has energy in two separate frequency ranges. Symbols 2 to 5 have a separate block in the middle. A narrow frequency range at the left has energy in all 14 symbols. The Waveform - Spectrum ranges from about -40 dB to 35 dB.

If you want to plot them in linear scale instead of log(dB) scale, select the 'Linear' from the [Scale] combobox.

The Scale combobox has two options, dB and Linear. dB is the default.

Then it plots the data in the same way as described above but in linear scale (i.e, not converting into dB (log) scale).

This is the same file, rf_port0-tx0-0956.00.bin, with Scale set to Linear. The Waveform - Spectrum now peaks at about 62, and the Waveform - Power vs Time peaks at about 0.42.

The short zero power period near the start of the slot is still visible in Waveform - Power vs Time. In Spectrogram - Power vs Time, the low power line at symbol 1 is much less visible in linear scale.