Remote API - PHY/MAC

This tutorial shows you how to change configurations for PHY/MAC with Remote API while the lte service is running. (NOTE : If you are new to Remote API or not familiar with it, I would suggest you to go through this tutorial first).

You can do set these configurations in configuration file, but if you use the configuration file you need to stop the lte service and change the value and run again when you want to change those parameter values. But if you are using Remote API, you can change those parameter values without stopping lte service.

I personally use this kind of tricks to figure out the root cause of BLER (low throughput) and troubleshoot the high BLER issue. Whenever I have the case where I am getting high BLER, I usually do as follows:

Step 1 : set full schedulinging force_dl_schedule and force_full_bsr and set very low mcs

Step 2 : check if you still see high bler even at the very low MCS, if you don't see high BLER at low MCS, increase MCS step by step during run time using the Remote API and find the first MCS that is causing high BLER.

Step 3 : Adjust radio link (e.g, cabling, distance between UE and Callbox Antenna etc) and repeat step 2 until you see any improvement.

NOTE : For further details on the factors on High BLER/Throughput issue, I would suggest you to check this tutorial.

Table of Contents

• Remote API - PHY/MAC
• Introduction
• Summary of the Tutorial
• Test Setup
• Key Configuration Parameters
• Configuration
• Test 1 : Changing DL PHY Configurations
• Perform the Test
• Test 2 : Changing UL PHY Configurations
• Perform the Test

Introduction

The ability to dynamically configure PHY (Physical Layer) and MAC (Medium Access Control) parameters in an LTE (Long Term Evolution) environment is a crucial aspect of modern telecom system management, particularly in scenarios where uptime and service continuity are paramount. Traditional approaches require halting the LTE service to modify configuration files, leading to service interruptions and operational inefficiencies. The Remote API framework addresses this limitation by enabling real-time parameter adjustments without necessitating a service restart. Architecturally, the Remote API acts as an abstraction layer, interfacing with the LTE stack and exposing a set of programmable endpoints that allow for the modification of key runtime parameters such as scheduling strategies, MCS (Modulation and Coding Scheme), and buffer settings. This flexibility is vital for troubleshooting and optimizing radio performance metrics like BLER (Block Error Rate) and throughput, especially in live network environments. By leveraging the Remote API, engineers gain granular control over the radio interface, allowing iterative tuning and rapid feedback cycles—a critical capability for diagnosing, mitigating, and resolving radio link issues in both lab and production settings. The Remote API thus plays an integral role in the LTE ecosystem, bridging the gap between static configuration and agile, adaptive network management, and empowering users to maintain optimal service quality with minimal disruption.

• Context of the Tutorial
  • This tutorial focuses on using the Remote API to make real-time adjustments to PHY/MAC configurations in an LTE system while the lte service remains operational.
  • The Remote API provides seamless, programmatic access to runtime parameters, eliminating the need for service restarts and supporting advanced troubleshooting and optimization practices.
  • Dynamic configuration is particularly valuable for diagnosing and resolving radio interface issues, such as high BLER, in both testing and live deployment scenarios.
• Relevance and Importance
  • Enables efficient network performance tuning without downtime, which is essential for continuous service delivery.
  • Supports rapid experimentation and root cause analysis by allowing real-time parameter changes and immediate observation of effects.
  • Facilitates advanced troubleshooting workflows for radio link issues, significantly enhancing diagnostic capabilities.
• Learning Outcomes
  • Understand the architectural principles and operational benefits of the Remote API in LTE environments.
  • Gain practical skills in modifying PHY/MAC parameters on-the-fly without disrupting active LTE services.
  • Develop effective troubleshooting strategies for identifying and resolving BLER and throughput issues using dynamic configuration techniques.
• Prerequisite Knowledge and Skills
  • Familiarity with LTE network architecture, especially PHY and MAC layer concepts.
  • Basic understanding of telecom configuration management and performance diagnostics.
  • Prior exposure to Remote API usage is recommended for seamless progression through this tutorial. New users should first review the introductory tutorial on Remote API fundamentals.

Summary of the Tutorial

This tutorial demonstrates procedures for low-layer LTE testing, focusing on dynamically changing PHY/MAC configurations for both downlink (DL) and uplink (UL) using Amarisoft Remote API commands. The tests are designed to modify resource allocation and scheduling parameters for a connected UE in a controlled callbox environment, with a focus on practical command execution and verification.

• Test 1: Changing DL PHY Configurations
  • Before powering on the UE, the inactivity_timer is extended via Remote API to maintain RRC connection throughout the test. This prevents premature release due to inactivity, as higher-layer traffic is not generated.
    ./ws.js enb '{"message":"config_set","cells":{"1":{"inactivity_timer":6000}}}'
  • Change the pdsch_mcs parameter to modify the DL modulation and coding scheme for the specified cell. This demonstrates the ability to set DL transport block parameters in real time.
    ./ws.js enb '{"message":"config_set","cells":{"1":{"pdsch_mcs":2}}}'
  • Verify parameter changes using the trace log (t command), ensuring the updated configuration is in effect.
  • Enable forced DL scheduling by setting force_dl_schedule to true, resulting in the eNB attempting to schedule PDSCH in every possible subframe.
    ./ws.js enb '{"message":"config_set","cells":{"1":{"force_dl_schedule":true}}}'
  • Adjust the PDSCH resource block (RB) allocation to a fixed range by setting pdsch_fixed_rb_alloc to true, specifying the start and length of the RB allocation.
    ./ws.js enb '{"message":"config_set","cells":{"1":{"pdsch_fixed_rb_alloc":true,"pdsch_fixed_rb_start":0,"pdsch_fixed_rb_l_crb":20}}}'
  • Use the t command on the eNB to confirm the correct application of all configuration changes.
• Test 2: Changing UL PHY Configurations
  • As in Test 1, extend the inactivity_timer before UE power-on to maintain the connection.
    ./ws.js enb '{"message":"config_set","cells":{"1":{"inactivity_timer":6000}}}'
  • Change the pusch_mcs parameter to alter the UL modulation and coding scheme for the specified cell.
    ./ws.js enb '{"message":"config_set","cells":{"1":{"pusch_mcs":2}}}'
  • Confirm the parameter update using the trace log (t command).
  • Enable forced BSR reporting by setting force_full_bsr to true, triggering the eNB to schedule uplink grants more aggressively.
    ./ws.js enb '{"message":"config_set","cells":{"1":{"force_full_bsr":true}}}'
  • Again, verify the updated configuration via the t command on the eNB.

Methodology Overview:

• Key configuration parameters are adjusted live via the Amarisoft Remote API, without modifying the static configuration files.
• Each configuration change is specific to a cell (e.g., cell ID 1) and is applied via JSON-formatted command-line instructions.
• Verification of parameter changes is performed by monitoring the trace output (t command) to ensure the desired settings are active.
• The procedure is modular, allowing for further parameter experimentation once the basic method is understood.

Test Setup

Test setup for this tutorial is as shown below.  This is just for low layer testing, you may not need any complicated IP layer setup.

• SIM Card used in this tutorial is the one delivered with the system as it is.
• If you want to change the configuration, The tutorial Configuration Guide would help

Key Configuration Parameters

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

• force_dl_scheduler
• force_full_bsr
• pdsch_mcs
• pdsch_fixed_rb_alloc
• pdsch_fixed_rb_start
• pdsch_fixed_l_crb
• pusch_fixed_rb_alloc
• pusch_fixed_rb_start
• pusch_fixed_l_crb

Configuration

In this tutorial, the default configuration (the default configuration for LTE) is used without any change. We don't need to change anything in the configuration file since we will change configuration using Remote API while the lte service is running

Test 1 : Changing DL PHY Configurations

In this test, I will change some parameters to change resource allocation and scheduling for LTE DL. This is just an example of changing DL PHY/MAC configuration. You don't need to do exactly as shown here. Once you get familiar with this basic operation, you may use any other parameters in any order as you like.

Perform the Test

Before power on UE, I extended the inactivity_timer as shown below to maitain the call connection during the whole test period.  Since I am not generating any higher layer traffic (e.g, IP traffic), if you don't extend inactivity_timer, RRC will be released soon (10 seconds by default) after the initial attach.

./ws.js enb '{"message":"config_set","cells":{"1":{"inactivity_timer":6000}}}'

Try changing pdsch mcs using the following command. (NOTE : This is a cell specific parameter, make it sure that you set the correct cell ID in the mssage)

./ws.js enb '{"message":"config_set","cells":{"1":{"pdsch_mcs":2}}}'

Check if the command is properly applied using 't' command as shown below. (NOTE : There is no straightfoward way to figure out exactly what the remoteAPI took effect in trace log(t). If you see the phy configuration that you set printed continuously, it would be a good candidates for the timing that the remoteAPI took effect)

Now I am trying to let eNB to schedule pdsch at every possible subframe using the command as shown below. (NOTE : This is a cell specific parameter, make it sure that you set the correct cell ID in the mssage)

./ws.js enb '{"message":"config_set","cells":{"1":{"force_dl_schedule":true}}}'

Then change RB ranges for every pdsch using the command as shown below. (NOTE : These are a cell specific parameters, make it sure that you set the correct cell ID in the mssage)

./ws.js enb '{"message":"config_set","cells":{"1":{"pdsch_fixed_rb_alloc":true,"pdsch_fixed_rb_start":0,"pdsch_fixed_rb_l_crb":20}}}'

Check if the command is properly applied using 't' command as shown below

Test 2 : Changing UL PHY Configurations

In this test, I will change some parameters to change resource allocation and scheduling for LTE UL. This is just an example of changing UL PHY/MAC configuration. You don't need to do exactly as shown here. Once you get familiar with this basic operation, you may use any other parameters in any order as you like.

Perform the Test

Before power on UE, I extended the inactivity_timer as shown below to maitain the call connection during the whole test period.

./ws.js enb '{"message":"config_set","cells":{"1":{"inactivity_timer":6000}}}'  (NOTE : This is a cell specific parameter, make it sure that you set the correct cell ID in the mssage)

Try changing pusch mcs using the following command.

./ws.js enb '{"message":"config_set","cells":{"1":{"pusch_mcs":2}}}' (NOTE : This is a cell specific parameter, make it sure that you set the correct cell ID in the mssage)

Check if the command is properly applied using 't' command as shown below.

Now I am trying to let eNB to schedule pdsch at every possible subframe using the command as shown below.

./ws.js enb '{"message":"config_set","cells":{"1":{"force_full_bsr":true}}}' (NOTE : This is a cell specific parameter, make it sure that you set the correct cell ID in the mssage)

Check if the command is properly applied using 't' command as shown below.