NR SSB Precoding

This tutorial show you how to apply precoding to SSB. Actually, the precoding in this context is to multiply a specific number (a real or complex number) to a SSB burst from each antenna. We configure the multiplier in the form of matrix since there can be multiple SSB burst and multiple antenna, but strictly speaking the matrix is not applied to SSB burst as in MIMO precoding. In MIMO precoding, the precoding matrix is applied by matrix multiplication, but in SSB precoding the matrix is applied to SSB by element by element multiplication (more like scaler multiplication). Basically what we call SSB precoding matrix is just to adjust the power and phase of each SSB birst. It may not sound clear, but it would be clearer if you see real examples in this note.

The only thing I want you to remember is that you can change the power and phase of each SSB burst using SSB precoding. You may use this method to test Initial Beam Selection of beam management. In case of live network, the gNB active antenna module changes the direction of each SSB beams with the same power to test P1 process, but it is difficult to create such a beam transmitting in different directions in test equipment. Instead of changing the direction of SSB beam, you may simulate SSB burst in different beams direction by setting different power to each SSB burst. This would works because UE does not directly measuring the beam angle/direction when it detects an SSB burst, it just measures the signal quality(e.g, RSRP) of all the SSB it detected and pick the one with the best signal quality. This can be a typical application of SSB precoding in Amarisoft gNB.

Table of Contents

• NR SSB Precoding
• Introduction
• Summary of the Tutorial
• Test Setup
• Key Configuration Parameters
• Test 1 :  SSB Precoding for 1 TX Antenna
• Configuration
• Run and Check
• Analysis
• Test 2 :  SSB Precoding for 2 TX Antenna
• Configuration
• Run and Check
• Analysis
• Tips
• Confirmation on the Selected SSB
• How to Apply it to UE test ?

Introduction

Precoding in the context of Synchronization Signal Blocks (SSBs) is a foundational technique in modern wireless communication systems, particularly within 5G New Radio (NR) architectures. Unlike traditional Multiple Input Multiple Output (MIMO) precoding, where a matrix operation is executed across spatial streams, SSB precoding involves element-wise multiplication—typically by real or complex scalars—applied to each SSB burst from each transmitting antenna. This approach allows for fine-grained control over the power level and phase of individual SSB bursts, which is crucial for simulating and managing beamforming behavior, especially during initial access procedures such as beam sweeping and selection. In commercial networks, active antenna systems in a gNB (next-generation NodeB) dynamically steer SSB beams for optimal coverage and efficient initial user equipment (UE) attachment. However, in test and simulation environments—such as those using Amarisoft gNB—directional beamforming can be emulated by adjusting the power and phase of SSB bursts via the SSB precoding matrix. This enables the evaluation of UE-side beam management algorithms, particularly for testing how UEs select the best beam based on signal quality metrics like Reference Signal Received Power (RSRP). By understanding and applying SSB precoding effectively, engineers and researchers can replicate real-world beam management scenarios, analyze network performance, and accelerate the development and optimization of 5G NR deployments.

• Context and Background
  • SSB precoding is a specialized technique in 5G NR, distinct from conventional MIMO precoding, enabling manipulation of SSB burst characteristics on a per-antenna basis.
  • It is instrumental in simulating beam management processes during initial access, where UEs detect and select optimal SSB beams for network attachment.
  • The approach is especially valuable in environments where hardware constraints prevent the generation of physically distinct beam directions, as often encountered in test setups.
• Relevance and Importance of This Tutorial
  • The tutorial addresses the need for practical methods to emulate beam behavior and evaluate UE beam selection mechanisms in non-live network environments.
  • Mastery of SSB precoding facilitates accurate simulation of power and phase variations across SSB bursts, supporting advanced testing and validation of beam management algorithms.
  • These capabilities are critical for network engineers, researchers, and developers aiming to ensure robust initial access and mobility management in 5G NR systems.
• Outcomes and Learning Objectives
  • Gain a comprehensive understanding of SSB precoding concepts and their application within 5G NR architectures.
  • Learn how to configure and apply SSB precoding matrices for test and simulation purposes, especially using platforms like Amarisoft gNB.
  • Develop the capability to emulate beam directionality through scalar modifications to SSB bursts, enabling effective UE beam management testing.
  • Acquire practical skills to analyze and interpret UE behavior during initial beam selection based on SSB signal quality measurements.
• Prerequisite Knowledge and Skills
  • Familiarity with basic 5G NR architecture, including the roles of gNB, SSB, and UE.
  • Understanding of fundamental beamforming and precoding concepts.
  • Experience with wireless communication testing tools or simulation environments (such as Amarisoft gNB) is recommended for hands-on exercises.
  • Basic knowledge of signal quality metrics (e.g., RSRP) and their relevance in initial access procedures.

Summary of the Tutorial

This tutorial presents procedures for testing SSB (Synchronization Signal Block) precoding with different TX (transmit) antenna configurations using Amarisoft callbox and SDR-based spectrum analysis. The focus is on configuration, execution, and analysis of SSB precoding settings for both 1 TX and 2 TX antenna cases, without the use of a commercial UE.

• Test Setup
  • The test does not utilize a UE, as commercial UEs do not support the required non-3GPP bands and EARFCNs.
  • The setup involves Amarisoft gNB configuration and a spectrum analyzer (sdr_spectrum) for SSB burst verification.

• Key Configuration Parameters
  • ssb_pos_bitmap: Indicates which SSB bursts are enabled.
  • ssb_precoding: Specifies the power/phase settings for each enabled SSB burst.

• Test 1: SSB Precoding for 1 TX Antenna
  • Configuration Steps:
    • Start with the gnb-sa-1x1-ssb-precoding.cfg configuration, based on gnb-sa.cfg.
    • Set the TDD flag and custom frequency in the TDD options.
    • Set N_ANTENNA_DL to 1 for single TX operation.
    • Assign ssb_pos_bitmap to enable the desired SSB bursts (e.g., "11111111" for all 8 bursts).
    • Define ssb_precoding as an array of vectors (one per enabled SSB). In the 1 TX case, each vector has one element (e.g., [[1],[1],[1],[1],[1],[1],[1],[1]]).
    • Ensure the number of vectors in ssb_precoding matches the number of '1's in ssb_pos_bitmap.
  • Test Execution:
    • Use sdr_spectrum as the analysis tool. Identify the absolute frequency either from the enb command line printout or by running rf_info.
    • Run the following sample command:

      ./sdr_spectrum -args "dev0=/dev/sdr0" -rx_freq 3489.420e6 -rate 50.0e6
      

  • Analysis:
    • Verification is conducted using spectrum analyzer output (waterfall/spectrogram).
    • The mapping between ssb_pos_bitmap and ssb_precoding is visually confirmed. For example:
      • All-ones in both parameters yield 8 visible, equal-power SSB bursts.
      • Adjusting elements in ssb_precoding to zero for certain bursts disables them in the spectrum output.
      • Using fractional values in ssb_precoding produces bursts with different power levels, visible as alternating color patterns.

• Test 2: SSB Precoding for 2 TX Antennas
  • Configuration Steps:
    • Use gnb-sa-2x2-ssb-precoding.cfg (based on gnb-sa.cfg).
    • Set the TDD flag and custom frequency; set N_ANTENNA_DL to 2.
    • Set ssb_pos_bitmap to enable the SSB bursts (e.g., "11111111").
    • Configure ssb_precoding as an array of vectors (one per enabled SSB), each vector with two elements (e.g., [[1,1],[1,1],[1,1],[1,1],[1,1],[1,1],[1,1],[1,1]]). Each element corresponds to one TX antenna.
  • Test Execution:
    • Use sdr_spectrum for analysis; determine the absolute frequency as before.
    • Example execution command with two channels:

      ./sdr_spectrum -args "dev0=/dev/sdr0" -rx_freq 3489.420e6 -rate 50.0e6 –channels 2
      

  • Analysis:
    • Waterfall plots display two tracks, one per antenna.
    • Variations in ssb_precoding across antennas are reflected as differences in the spectrograms for each antenna.
    • Settings such as alternating [1,0] and [0,1] per burst allow visual confirmation of antenna-specific SSB transmission.

• Tips and Additional Notes
  • Confirmation on Selected SSB:
    • In a live UE scenario, the selected SSB index can be confirmed via PRACH log prints in the gNB logs, indicating which SSB the UE used for PRACH mapping.
  • Application to UE Testing:
    • The described configuration can be used to test initial beam selection by manipulating SSB transmission power instead of direction, simulating different beams for the UE.
    • For laboratory environments lacking many antennas, external horn antennas can be positioned in different directions to create spatial diversity, but fast port switching is not currently supported.
    • Power variation among SSBs can be a practical method for beam selection tests, though it does not replace directionality-based tests for panel or codebook selection.

Test Setup

I would not use the UE here since commercial UE would not support non-3GPP band and earfcn.

Key Configuration Parameters

Followings are important configuration parameters for this tutorial. You may click on the items for the descriptions from Amarisoft documents.

• ssb_pos_bitmap
• ssb_precoding

Test 1 :  SSB Precoding for 1 TX Antenna

This test is to show how to ssb precoding for 1 TX antenna (1 Downlink Antenna) and verify it.

Configuration

I am using gnb-sa-1x1-ssb-precoding.cfg which is copied and modified from gnb-sa.cfg  

I added a new TDD flag option as shown below.  I added an option for custom frequency to TDD option. Since this test is for single TX case, I set N_ANTENNA_DL to 1.

Then specify the value of ssb_pos_bitmap and ssb_precoding. You wouldn't need any explanation of ssb_pos_bitmap. In this test, ssb_pos_bitmap indicates 8 SSB burst is enabled. Then take a look at the structure of ssb_precoding. It has an array that is consists of 8 vectors and each of the vector has 1 elements. Each of the vector corresponds to the bit position of the value '1' in ssb_pos_bitmap. The number of element vector in ssb_precoding should be same as the number of '1's in ssb_pos_bitmap.

For example, for ssb_pos_bitmap = "11111111", the number of element vector of ssb_precoding should be 8.  For ssb_pos_bitmap = "10101010", the number of element vector of ssb_precoding should be 4 (e.g, ssb_precoding=[[1],[1],[1],[1],])

NOTE : Verbal description of the mapping between ssb_precoding and ssb_pos_bitmap may not sound clear. I myself found it a little tricky to explain in writing. But if you take a look at the examples in Analysis section, it may look clearer than the writing.

Run and Check

In this test, I would not use any UE for verification. I will use a spectrum analyzer(sdr_spectrum) to verify the power of each SSB bursts.

In order to configure, sdr_spectrum the only important information is frequency (the absolute frequency, not arfcn). You can figure out the absolute frequency from the initial print of (enb) command line or you can get the frequency by running the command rf_info as shown below.

Once you figure out the frequency, you can run the following command for the sdr card that is connected to the callbox TX port that is transmitting the SSB (NOTE : If you are not familiar with sdr_spectrum, refer to this tutorial).

./sdr_spectrum -args "dev0=/dev/sdr0" -rx_freq 3489.420e6 -rate 50.0e6

Analysis

For verification of this configuration, trace log would not help much. Spectrum Analyzer would be the better solution for verification. If you have vector signal analyzer with NR analysis capability, it would be the best. I used Amarisoft sdr_spectrum for the verification.  (NOTE : If you are not familiar with sdr_spectrum, refer to this tutorial).

This is an example configuration and the resulting spectrum. In this example, ssb_pos_bitmap is set to "11111111" which indicates 8 contiguous SSB index are enabled and ssb_precoding is set to [[1],[1],[1],[1],[1],[1],[1],[1]] which indicates the ssb power/phase are all set to 1. As a result, in spectrogram (waterfall) you see all 8 SSBs with almost same color code.

In this example, ssb_pos_bitmap is set to "11111111" which indicates 8 contiguous SSB index are enabled and ssb_precoding is set to [[1],[1],[1],[1],[1],[0],[1],[0]] which indicates the ssb power/phase of index 5 and 7 are all set to 0. As a result, in spectrogram (waterfall) you see no detection for SSB index 5 and 7 (NOTE : ssb index start from 0) .

In this example, ssb_pos_bitmap is set to "11111010" which indicates 6 SSB index are enabled and ssb_precoding is set to [[1],[1],[1],[1],[1],[1]] which indicates the ssb power/phase of all the transmitted ssb index are all set to 1. As a result, in spectrogram (waterfall) you see no detection for SSB index 5 and 7 (NOTE : ssb index start from 0) .

In this example, ssb_pos_bitmap is set to "11111111" which indicates 8 SSB index are enabled and ssb_precoding is set to [[1],[0.5],[1],[0.5],[1],[0.25],[1],[0.25]] which indicates the ssb power/phase of all the transmitted ssb index are alternating between high power and low power. As a result, in spectrogram (waterfall) you see the alternating pattern of color code .

Test 2 :  SSB Precoding for 2 TX Antenna

This test is to show how to ssb precoding for 2 TX antenna (2 Downlink Antenna) and verify it.

Configuration

I am using gnb-sa-2x2-ssb-precoding.cfg which is copied and modified from gnb-sa.cfg  

I added a new TDD flag option as shown below.  I added an option for custom frequency to TDD option. Since this test is for single TX case, I set N_ANTENNA_DL to 2.

Then specify the value of ssb_pos_bitmap and ssb_precoding. You wouldn't need any explanation of ssb_pos_bitmap. In this test, ssb_pos_bitmap indicates 8 SSB burst is enabled. Then take a look at the structure of ssb_precoding. It has an array that is consists of 8 vectors and each of the vector has 1 elements. Each of the vector corresponds to the bit position of the value '1' in ssb_pos_bitmap. The number of element vector in ssb_precoding should be same as the number of '1's in ssb_pos_bitmap. Here you see each of the vector in the precoding matrix has two elements like [1,1]. Each elements of the vector is mapped to each TX antenna. The first one is mapped to the first TX antenna and the second one is mapped to the second TX antenna.

For example, for ssb_pos_bitmap = "11111111", the number of element vector of ssb_precoding should be 8.  For ssb_pos_bitmap = "10101010", the number of element vector of ssb_precoding should be 4 (e.g, ssb_precoding=[[1,1],[1,1],[1,1],[1,1],])

NOTE : Verbal description of the mapping between ssb_precoding and ssb_pos_bitmap may not sound clear. I myself found it a little tricky to explain in writing. But if you take a look at the examples in Analysis section, it may look clearer than the writing.

Run and Check

In this test, I would not use any UE for verification. I will use a spectrum analyzer(sdr_spectrum) to verify the power of each SSB bursts.

In order to configure, sdr_spectrum the only important information is frequency (the absolute frequency, not arfcn). You can figure out the absolute frequency from the initial print of (enb) command line or you can get the frequency by running the command rf_info as shown below.

Once you figure out the frequency, you can run the following command for the sdr card that is connected to the callbox TX port that is transmitting the SSB (NOTE : If you are not familiar with sdr_spectrum, refer to this tutorial).

./sdr_spectrum -args "dev0=/dev/sdr0" -rx_freq 3489.420e6 -rate 50.0e6 –channels 2

Analysis

For verification of this configuration, trace log would not help much. Spectrum Analyzer would be the better solution for verification. If you have vector signal analyzer with NR analysis capability, it would be the best. I used Amarisoft sdr_spectrum for the verification.  (NOTE : If you are not familiar with sdr_spectrum, refer to this tutorial).

This is an example configuration and the resulting spectrum. In this example, ssb_pos_bitmap is set to "11111111" which indicates 8 contiguous SSB index are enabled and ssb_precoding is set to [[1,1],[1,1],[1,1],[1,1],[1,1],[1,1],[1,1],[1,1]] which indicates the ssb power/phase are all set to 1. As a result, in spectrogram (waterfall) you see all 8 SSBs with almost same color code. Here you see two tracks of spectrogram(waterfall plot). The upper track plots the signal captured from the first antenna and the lower track plots the signal captured from the second antenna.

In this example, ssb_pos_bitmap is set to "11111111" which indicates 8 contiguous SSB index are enabled and ssb_precoding is set to [[1,1],[0,0],[1,1],[0,0],[1,1],[0,0],[1,1],[0,0]] which indicates the ssb power/phase of index 1,3,5,7 are all set to 0 for both antenna. As a result, in spectrogram (waterfall) you see no detection for SSB index 1,3,5 and 7 (NOTE : ssb index start from 0) .

In this example, ssb_pos_bitmap is set to "10101010" which indicates 4 SSB index are enabled and ssb_precoding is set to [[1,1],[1,1],[1,1],[1,1]] which indicates the ssb power/phase of all the transmitted ssb index are all set to 1. As a result, in spectrogram (waterfall) you see no detection for SSB index 1,3, 5 and 7 (NOTE : ssb index start from 0) .

In this example, ssb_pos_bitmap is set to "11111111" which indicates 8 SSB index are enabled and ssb_precoding is set to [[1,0],[0,1],[1,0],[0,1],[1,0],[0,1],[1,0],[0,1]]. Here, for ssb0 TX0 is set to 1 and TX1 is set to 0. For ssb1 TX0 is set to 0 and TX1 is set to 1, and this kind of alternation repeats . As a result, in spectrogram (waterfall) you see the alternating pattern of color code .

Tips

Confirmation on the Selected SSB

When gNB is transmitting multiple SSB burst(index), UE is expected to detect the best one and send PRACH mapped to the selected SSB. This association between the selected SSB and corresponding PRACH plays the fundamental role of the beam management process named Initial Beam Selection. In gNB log, you can confirm which SSB index is selected by the UE by checking out the ssb_index value in PRACH log print as shown below. (NOTE : You don't see this information when only 1 SSB is enabled).

How to Apply it to UE test ?

One simplest approach to apply this configuration for UE test would be to use it for initial beam selection test. When a UE is powered on, it is expected that UE detect and measure the power of SSB within a certain period and pick the SSB with highest percieved power and trigger PRACH using the physical resources mapped to the selected SSB. In live gNB antenna module which has a huge number of antenna elements (e.g, 64TX64RX), gNB can create different beam(i.e, beam in different directions) for each SSB and transmit them at same power. Even though the transmitted power from the live gNB antenna are same, the percieved/measured power on UE would be different depending on the angle of the beam.

In most case, test equipment does not have such a large number of antenna to create such a fine tuned beams. A typical approach for the lab test with test equipment is to place multiple external horn antenna pointing to UE in different direction as shown here. If you want to point the each SSB beam different direction with external horn antenna, the test equipment should provide such a functionality to switch TX port with interval of only a few OFDM symbol. For now, this kind of TX port switching is not suppored in Amarisoft callbox.

An alternative approach that we can take would be to transmit all the beam with the same direction but different TX power for each SSB. With this approach, it can create a situation which can roughly simulate the multiple beams with same power and different direction and test criteria for initial beam selection. (NOTE : This can be a quick and handy approach for Initial Beam Selection test but there is limitation as well. Without physically changing the direction of the beam, it would be challenging to test pannel and/or codebook selection on UE antenna module. If you want to verify the pannel and/or codebook selection in slow varying situation, you can do it by changing the angular position of the DUT without changing the direction of the beam from test equipment, but this approach cannot be used in fast varying situation like OFDM symbol level granularity)