Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tramex project

logo_telecom_ipparis.png

Tramex is a university project conducted in Télécom Paris supervised by Philippe Martins

Tramex is a project that serves the goal of allowing users to analyze and visualize frames in a 4G and 5G network.

Tramex is a project derived from:

  • VIGIE
  • Amarisoft web interface

VIGIE

One of the functionalities of the VIGIE software is to analyze the frames of a 2G/3G network. For more information on this topic, please visit https://hal.science/hal-02141173.

Tramex can be seen as an upgrade of the VIGIE software because it allows the user to analyze the frames of a 4G and 5G network.

VIGIE Citation
@article{oyedapo:hal-02141173,
  TITLE = {{VIGIE : A learning tool for cellular air interfaces (GSM, GPRS, UMTS, WiFi)}},
  AUTHOR = {Oyedapo, Olufemi and Martins, Philippe and Lagrange, Xavier},
  URL = {https://hal.science/hal-02141173},
  JOURNAL = {{The IPSI BgD Transactions on Internet Research}},
  HAL_LOCAL_REFERENCE = {1097},
  VOLUME = {1},
  NUMBER = {2},
  PAGES = {65 - 69},
  YEAR = {2005},
  KEYWORDS = {UMTS},
  HAL_ID = {hal-02141173},
  HAL_VERSION = {v1},
}

Amarisoft web interface

Amarisoft is a software company that provides a 4G LTE and 5G NR software suite. The web interface of Amarisoft lets the user visualize the frames of a 4G and 5G network. This tool uses a Websocket API to retrieve the frames transmitted within the network.

Tramex

Tramex stands for Trame Exploration. As it is a French project, “Trame” is the French word for “Frame” and “Exploration” can be read either in French or in English.

Based on the Amarisoft software, Tramex uses the same WebSocket method to retrieve the frames transmitted within the network, but it displays them in a more user-friendly manner, similarly to the VIGIE software.

User Guide

This section is meant to help get started with Tramex.

Tramex in a nutshell

Tramex is a 4G/5G network analyzer. With Tramex, it is possible to analyze each message of a 4G (LTE) or 5G (NR) communication. Those messages are called traces. Tramex allows users to read protocol traces and display content data such as the channels followed during the communication, the RRC state, resource block allocations, and HARQ processes. Tramex was developed to be accessible from several platforms:

  • Browser mode: the user only needs to go on the tramex website
  • Binary mode: the user needs to download the binary file of tramex from the releases page and run it
  • Crates mode: the user can download and install Tramex with the command: cargo install tramex and then run tramex in the terminal

Get started with Tramex

The Tramex interface is always alike, no matter the mode used. In this section, the various functionalities will be described.

Documentation access

General information is accessible with a click on the Menu button on the left of the top bar then About.

Tramex repository is also accessible from the Tramex interface with a click on the About button on the left of the top bar then Tramex repository.

From the Tramex interface, it is possible to access different documentations:

  • User documentation: Click on the About button on the left of the top bar then User documentation.
  • Tramex code documentation: Click on the About button on the left of the top bar then tramex type.
  • Tramex tools code documentation: Click on the About button on the left of the top bar then tramex-tools types.

Processing modes

In order to analyze frames, Tramex offers two processing modes:

  • File reader: read recorded data from a .log file.
  • Websocket: read real-time data from a server.

The user can choose the processing mode using the buttons Choose ws or file on the top of the left vertical panel. This panel collapses automatically once a file is loaded or a websocket is connected; use the ◀ / ▶ button on the left edge to show or hide it at any time.

File reader mode

When using the file reader mode, the user is asked to provide the file to read which can be done in two ways:

  • With the file explorer by clicking on the Open file... button in the left vertical panel.
  • From the files list in the left vertical panel by clicking on the arrow on the left of each directory name until reaching the desired file.

When done with the file, it is possible to close it by clicking on the Close button on the left vertical panel. It is necessary to close the current file to open another one or switch to the websocket mode.

Websocket mode

When using the websocket mode, the user is asked to provide the IP address as well as the port number of the distant server. The information must be provided in the format ws://127.0.0.1:9001 where 127.0.0.1 is the example IP address and 9001 is the example port number in the typebar below the processing mode choosing buttons. Then click on the Connect button.

The connection might take a few moments and if Tramex cannot connect to the server using the websocket, an error message should appear in the Errors panel. From this window, it is possible to read the description of the error, copy it and report it to the tramex repository if necessary.


Analyze frames with Tramex

Regardless of the chosen mode, the display of the frame analysis using Tramex is always the same. The layout is made of fixed areas (navigation toolbar, Messages panel, status bar) and of floating windows called panels, each of them providing specific information.

This section will define the layout and the various panels available.


Layout overview

┌ Menu bar ─────────────────────────────────────────────────────────┐
├ Toolbar: ◀ Previous  ▶ Next  | Event 12 / 4567 | Time 12:03:01.234 │
│                                             [ RRC ] [ NAS ] [ Radio ] │
├────────┬──────────────────────────────────────────────────────────┤
│ Source │  Messages (always visible)                               │
│        │                     + floating panels of the active group │
├────────┴──────────────────────────────────────────────────────────┤
└ Status bar: source | Loaded N / total | auto-loading | Fully loaded ┘

The navigation toolbar is fixed at the top of the main area and is always visible once a source is active.

Navigation controls:

  • ◀ Previous / ▶ Next buttons: Navigate sequentially through events. Next is shown as Start before the first event is selected. While searching for the next event with an enabled layer, the button shows a spinner and Searching…; click it again to stop the search (events already loaded stay loaded).
  • Clickable index: Click on the event index (Event 12 / 4567) to type an event number and jump directly to it
  • Time: The timestamp of the current event

WebSocket mode controls:

  • ⏸ Pause / ▶ Resume: Control auto-loading of new events from the WebSocket connection

Panel groups (right side of the toolbar): the RRC, NAS and Radio buttons open a set of panels in one click, see Panel groups.


Status Bar

The status bar at the bottom of the window shows:

  • The active source (file path or websocket URL)
  • Loaded: number of events in memory, with the total number of events in the file when known
  • The auto-loading state in websocket mode (● auto-loading / ● paused)
  • Fully loaded once the whole source has been read

Panel groups

The analysis panels are floating windows grouped by topic. Selecting a group with the toolbar buttons opens its panels, closes the panels of the other groups and enables the matching protocol layers:

GroupPanelsLayers enabled
RRCRAN Config, RRC Status, Bearer Status, Logical Channels, ChronographRRC
NASChronograph RAN, Identity, GTPU TunnelRRC, NAS, NGAP, GTPU
RadioResource Blocks, HARQ, Chronograph MAC-RLC-PDCP, PowerPHY
  • The RRC group is selected automatically when a file is opened or a websocket is connected.
  • The Chronograph belongs to the NAS group (it is listed there in the Windows menu) but is also opened by the RRC shortcut, as it is useful in both contexts.
  • The Chronograph belongs to the NAS group (it is listed there in the Windows menu) but is also opened by the RRC shortcut, as it is useful in both contexts.
  • Clicking the active group closes its panels.
  • To mix panels from several groups, or to show a single panel, use the Windows menu in the top bar: Show all / Hide all and one checkbox per panel. The menu stays open while you tick panels; click outside to close it.
  • The layer selection can be refined afterwards in Settings → Layers.

Message Panel

The Message panel is fixed in the center of the window and displays the detailed content of the currently selected trace.

Information displayed:

  • Layer badge: The protocol layer (RRC, NAS, NGAP, PHY, etc.) shown as a colored badge
  • Additional information: Direction (UL/DL), channel type, and message name

Features:

  • Show full message checkbox: Toggle to display the raw text content of the message
  • Copy to clipboard button: When the full message is shown, copy the entire message text to clipboard

AI Explain feature (when enabled):

  • AI Explain button: Sends the current trace to a configured AI provider (e.g., Mistral) for an explanation
  • The AI returns a human-readable explanation of the protocol message, displayed as formatted Markdown
  • Useful for understanding complex RRC, NAS, or NGAP messages without consulting external documentation

RRC Status Panel

The RRC Status panel visualizes the Radio Resource Control (RRC) connection state machine.

State machine visualization:

  • Displays the current RRC state: IDLE, INACTIVE (5G only), or CONNECTED
  • Shows the direction of the current RRC message with arrows between BASE STATION and USER EQUIPMENT
  • Highlights the current state with distinct colors

State transitions:

  • IDLE → CONNECTED: Triggered by RRC Connection Setup Complete (LTE) or RRC Setup Complete (NR)
  • CONNECTED → IDLE: Triggered by RRC Connection Release (LTE) or RRC Release (NR)
  • CONNECTED ↔ INACTIVE: 5G NR specific transitions via RRC Suspend/Resume messages

Technology awareness:

  • Automatically detects LTE or NR technology and applies the correct state transition rules
  • Maintains state history for accurate state reconstruction when navigating backward through events

Bearer Status Panel

The Bearer Status panel visualizes the radio bearers established between the base station and the UE, as two state machines:

  • SRB (signaling): SRB1, SRB2 or SRB3, highlighted in orange
  • DRB (traffic): DRB1, DRB2 or DRB3, highlighted in green

State transitions:

MessageContent (radioBearerConfig)New state
RRC setupsrb-ToAddModList → srb-Identity 1SRB1, no DRB
RRC reconfigurationsrb-ToAddModList → srb-Identity 2SRB2
RRC reconfigurationdrb-ToAddModList → drb-Identity 1DRB1
RRC release—no SRB, no DRB

SRB3, DRB2 and DRB3 are displayed but not triggered yet.

Behavior:

  • The state does not change until a message updating the SRB or DRB is passed
  • The arrows between BASE STATION and USER EQUIPMENT light up when the focused message changes the bearers
  • Maintains state history for accurate state reconstruction when navigating backward through events

Logical Channels Panel

The Logical Channels panel visualizes the mapping between logical, transport, and physical channels for the current message.

Grid layout:

  • Rows: Logical channels (top), Transport channels (middle), Physical channels (bottom)
  • Columns: Downlink (left) and Uplink (right)

Channel highlighting: When an RRC message is focused, the panel highlights the channels that carried that message:

ColorChannel TypeDescription
RedBroadcastMessage intended for all UEs in the network
BlueCommon/SharedMessage intended for a group of UEs
OrangeDedicatedMessage intended for a specific UE
GreenTrafficData channel

Technology indicator:

  • Displays the detected technology (LTE or NR) at the top of the panel

Hover tooltips:

  • Hover over any channel label to see a description of its type and purpose

RAN Config Panel (BST Config)

The RAN Config panel displays parsed configuration fields from RRC System Information Blocks (SIBs) and NAS messages.

Sections displayed:

General:

  • Technology (LTE/NR)
  • PCI (Physical Cell Identity)
  • Mode (FDD/TDD)
  • ARFCN (Absolute Radio Frequency Channel Number)
  • I/O Mode (MIMO/SISO)

SIB1 fields (when SIB1 message is encountered):

  • MCC/MNC (Mobile Country/Network Code)
  • Cell ID
  • Tracking Area Code
  • q-RxLevMin, q-QualMin (cell selection parameters)
  • Frequency band, subcarrier spacing, carrier bandwidth (5G NR)

SIB2/SIB3 fields (cell reselection parameters):

  • q-Hyst (hysteresis)
  • s-IntraSearch, t-ReselectionNR
  • Neighbor cell lists

NSSAI section (5G NR only):

  • Displays configured and allowed S-NSSAI (Network Slice Selection Assistance Information)
  • Shows SST (Slice/Service Type) with descriptions: eMBB, URLLC, mMTC, V2X
  • Indicates which slices are allowed for the UE

Behavior:

  • Fields persist until a new SIB message updates them
  • Supports both 4G LTE and 5G NR message formats

Identity Panel

The Identity panel displays parsed identity information from NAS messages.

4G LTE fields (from Attach Accept):

  • PDN Address: PDN type, IPv4/IPv6 addresses
  • Network: APN (Access Point Name), DNS servers
  • GUTI (MME): MCC, MNC, MME Group ID, MME Code, M-TMSI
  • TAI List: Tracking Area Codes with decoded MCC/MNC

5G NR fields (from Registration Accept / PDU Session Establishment Accept):

  • PDU Address: Session type, IPv4/IPv6 addresses
  • Network: DNN (Data Network Name), DNS servers
  • 5G-GUTI: MCC, MNC, AMF Region ID, AMF Set ID, AMF Pointer, 5G-TMSI
  • TAI List: Tracking Area Codes
  • QoS Rules: Rule identifier, DQR, precedence, QFI
  • Session AMBR: Downlink/Uplink maximum bit rates
  • 5QI: 5G QoS Identifier

Behavior:

  • Automatically switches between 4G and 5G display based on detected technology
  • Values persist until a new NAS message updates them

Chronograph RAN Panel

The Chronograph RAN panel displays a visual timeline of message exchanges between network elements.

Layout:

  • Three vertical lifelines: UE (User Equipment), BST (Base Station), CN (Core Network)
  • Horizontal arrows represent messages flowing between elements
  • Messages are displayed chronologically from top to bottom

Arrow mapping:

LayerDirectionArrow
RRCULUE → BST
RRCDLBST → UE
NASULUE → CN
NASDLCN → UE
NGAPTOBST → CN
NGAPFROMCN → BST
GTPUTOBST → CN
GTPUFROMCN → BST

Highlighting:

  • Current event: Bright blue, thicker arrow
  • Related events (parent/child traces): Lighter blue
  • Other events: Theme-aware default color

Features:

  • Auto-scrolls to center on the focused event
  • Displays layer type and message name on each arrow
  • Layer checkboxes (RRC, NAS, NGAP, GTPU) filter the displayed arrows
  • Click an arrow to navigate to the corresponding trace
  • Navigating back to an event older than the kept buffer rebuilds the arrows around it

GTPU Tunnel Panel

The GTPU Tunnel panel displays the user-plane tunnel parsed from GTPU traces, such as:

13:20:45.574 [GTPU] TO 127.0.1.100:2152 G-PDU TEID=0x5315caa3 QFI=1 SDU_len=1452: IP/TCP 192.168.3.2:51158 > 172.217.18.202:443

Layout:

  • Two lifelines: BST (Base Station) on the left and UPF on the right, with the GTP-U peer IP and port under the UPF label (e.g. 127.0.1.100:2152)
  • One arrow per tunnel and direction, labeled with its TEID (Tunnel Endpoint Identifier) and QFI (QoS Flow Identifier):
DirectionArrow
UL (TO)BST → UPF
DL (FROM)UPF → BST

Behavior:

  • Each new TEID adds a new arrow; previous tunnels are kept, ordered by first appearance
  • An existing arrow shows the QFI of the latest GTPU message on its TEID
  • Focusing a GTPU trace highlights the arrow of its tunnel in blue
  • Click an arrow to navigate to the latest trace of that tunnel

GTPU Tunnel Panel

The GTPU Tunnel panel displays the user-plane tunnel parsed from GTPU traces, such as:

13:20:45.574 [GTPU] TO 127.0.1.100:2152 G-PDU TEID=0x5315caa3 QFI=1 SDU_len=1452: IP/TCP 192.168.3.2:51158 > 172.217.18.202:443

Layout:

  • Two lifelines: BST (Base Station) on the left and UPF on the right, with the GTP-U peer IP and port under the UPF label (e.g. 127.0.1.100:2152)
  • One arrow per tunnel and direction, labeled with its TEID (Tunnel Endpoint Identifier) and QFI (QoS Flow Identifier):
DirectionArrow
UL (TO)BST → UPF
DL (FROM)UPF → BST

Behavior:

  • Each new TEID adds a new arrow; previous tunnels are kept, ordered by first appearance
  • An existing arrow shows the QFI of the latest GTPU message on its TEID
  • Focusing a GTPU trace highlights the arrow of its tunnel in blue
  • Click an arrow to navigate to the latest trace of that tunnel

Chronograph MAC-RLC-PDCP Panel

This panel follows the same timeline, highlighting, auto-scroll, buffer rebuild, and click-to-navigate principles as the Chronograph RAN Panel. Its key differences are:

  • Two lifelines only: UE and BST
  • Displays MAC, RLC, and PDCP traces
  • UL arrows flow from UE to BST; DL arrows flow from BST to UE
  • Arrow labels contain the layer and full log message; hover an arrow to read the full message in a tooltip
  • Layer checkboxes (MAC, RLC, PDCP) filter the displayed arrows

Layout:

The window is split horizontally:

  • Left: the message timeline (scrollable, resizable)
  • Right: a bearer status column showing which SRB/DRB channels are used by the focused trace, styled like the Bearer Status panel

Bearer detection:

  • RLC / PDCP: the bearer name is read directly from the log line (e.g. [RLC] DL 0001 DRB1 ... → DRB1)
  • MAC: every LCID:N in the line is mapped to a channel (a MAC trace can activate several at once):
LCID01234567
ChannelNASRB0SRB1SRB2SRB3DRB1DRB2DRB3

Highlighting:

  • Channels carried by the focused trace light up in orange (SRB) or green (DRB)
  • Several channels can be highlighted simultaneously for multi-LCID MAC traces

Refer to the Chronograph RAN Panel for the common chronograph behavior.


Resource Blocks Panel

The Resource Blocks panel visualizes the 5G NR Physical Resource Block (PRB) allocations over time.

Grid axes:

  • Y-axis (Frequency): Physical Resource Blocks (PRBs), typically 51 PRBs
  • X-axis (Time): Symbols (detailed) or Slots (aggregated)

View modes:

  • Symbol view: 14 symbols per slot, detailed allocation visualization
  • Slot view: Aggregated view showing highest-priority resource per PRB per slot

Resource types and colors:

TypeColorDescription
PDCCHDark greenDownlink control channel
PUCCHLight greenUplink control channel
PDSCHBlueDownlink data channel
PUSCHCyanUplink data channel
PRACHYellowRandom access channel
SSBMagentaSynchronization Signal Block
DMRSRedDemodulation Reference Signal

Navigation:

  • Frame navigation: ◀◀ / ▶▶ buttons to move by frames (10ms)
  • Subframe navigation: ◀ / ▶ buttons to move by subframes (1ms)
  • Cell size slider: Adjust the size of grid cells for visibility

Features:

  • Auto-centers on focused PHY event
  • Highlights cells belonging to the focused event
  • Displays frame range at the top
  • Hover over cells for detailed PHY allocation info
  • Grays out slots outside the received event range

HARQ Panel

The HARQ panel provides a chronograph-style visualization of PHY layer events, showing the HARQ (Hybrid Automatic Repeat Request) process flow.

Layout:

  • Two vertical lifelines: UE and BST
  • Arrows colored by HARQ process number (0-15)
  • Legend shows active HARQ processes with their colors

Supported channels:

ChannelDirectionRole
PDCCHDLControl channel carrying DCI grants
PDSCHDLDownlink data
PUSCHULUplink data
PUCCHULUplink control (ACK/NACK feedback)

Arrow labels:

  • PDCCH: PDCCH dci={format} ndi={} rv_idx={}
  • PDSCH: PDSCH harq={} retx={} rv_idx={}
  • PUSCH: PUSCH harq={} retx={} rv_idx={} crc={OK/KO} {ACK/NACK}
  • PUCCH: PUCCH format={} {ACK/NACK}

Filtering:

  • Automatically filters out non-HARQ events (MIB/SIB broadcasts, CSI-only PUCCH)
  • It is possible to filter by HARQ process to better understand the sequence

Features:

  • Color-coded HARQ processes for easy tracking
  • Focused event highlighted with background bar
  • Click an arrow to navigate to the corresponding trace
  • Auto-scrolls to centered on focused event
  • Track retransmissions via retx and rv_idx fields

Power Panel

The Power panel displays three point graphs sharing a common SFN (System Frame Number) X axis, built from uplink measurements reported on PUSCH and PUCCH PHY traces:

MetricDescription
EPREEnergy Per Resource Element (dB)
TATiming Advance (µs)
CSIChannel State Information (decoded from binary, e.g. 0101 → 5)

Layout:

  • Three stacked graphs, each with its own Y axis auto-scaled to visible data
  • Shared X axis labeled with frame numbers at frame boundaries
  • Points only (no lines) since events do not arrive in SFN order

Controls:

  • Window slider: Adjust the number of frames displayed (5–500)
  • ◀◀ / ▶▶: Navigate by one frame
  • PUSCH / PUCCH toggles: Show or hide samples from each channel type
  • Drag: Pan the X window left/right

Features:

  • Focused event highlighted with an accent ring and a vertical marker across all graphs
  • Hover over a point to see all measurements in a tooltip (including raw CSI bits)
  • Click a point to navigate to the corresponding trace
  • Window automatically re-centers on the focused event

Options and Settings

All options are grouped in the Settings window, opened from the Settings menu in the top bar. The window has four tabs: AI, Layers, File options and Parameters.

Layer Filtering

The Layers tab allows filtering which protocol layers are displayed. Selecting a panel group in the toolbar applies a preset (see Panel groups); this tab lets you adjust it.

Radio layers:

  • PHY (Physical)
  • MAC (Medium Access Control)
  • RLC (Radio Link Control)
  • PDCP (Packet Data Convergence Protocol)
  • SDAP (Service Data Adaptation Protocol) - 5G only
  • RRC (Radio Resource Control)
  • NAS (Non-Access Stratum)

Core Network layers:

  • S72, S1AP (4G LTE)
  • NGAP (5G NR)
  • GTPU (User plane tunneling)
  • X2AP, XnAP (inter-eNB/gNB interfaces)
  • M2AP, LPPa, NRPPa (positioning)
  • TRX (transceiver)

Toggle checkboxes to enable/disable display of specific layers. In file mode, disabled layers are skipped when navigating with Previous / Next; in websocket mode, only the enabled layers are requested from the server.


File options

The File options tab (file mode only) sets the URL of the index of files used to populate the files list in the left panel, with a Reload list button.


Parameters

The Parameters tab exposes runtime values that used to be hard-coded constants. All values are saved between sessions, and Reset to defaults restores them.

ParameterDefaultEffect
HARQ max arrows100Arrows kept in the HARQ panel buffer
Chronograph RAN max arrows100Arrows kept in the Chronograph RAN panel buffer; dropped arrows are rebuilt around the focused event when navigating back
Chronograph MAC max arrows100Arrows kept in the Chronograph MAC-RLC-PDCP panel buffer; dropped arrows are rebuilt around the focused event when navigating back
File batch size100Events parsed per batch when loading a file
WebSocket max request size1024Max events per log_get request (64–4096)
WebSocket history12 hHow far back the server is asked for logs — applies to the next request

AI Settings

The AI tab configures the AI-powered trace explanation feature.

Configuration options:

  • Provider: Select AI provider (e.g., Mistral)
  • Model: Select specific model (e.g., mistral-medium-latest)
  • API Key: Enter your API key directly or load from environment variable
  • Environment variable: Configure the variable name (default: TRAMEX_AI_API_KEY)

Usage:

  1. Set TRAMEX_AI_API_KEY environment variable before running Tramex, or enter the key in settings
  2. Navigate to any trace in the Message panel
  3. Click “AI Explain” to get a human-readable explanation

Security:

  • API keys are not saved to disk (must be re-entered or loaded from environment each session)

Proceed through the frames

To browse through the frames, use the Previous and Next buttons in the navigation toolbar.

Jump to specific event:

  • Click on the event index number in the navigation toolbar
  • Enter the desired event number
  • Press Enter to jump directly to that event

Panel management

  • Use the RRC / NAS / Radio buttons in the toolbar to switch between panel groups
  • Click on Windows in the top menu to show/hide individual panels
  • Panels can be resized and repositioned; Menu → Organize windows resets their positions
  • Open panels are saved between sessions
  • The light/dark theme switch is on the left of the top bar

Developer Guide

This guide covers the development environment, common commands, documentation, CI/CD pipelines, and troubleshooting notes for Tramex.

Development Setup

Install rustup, the recommended installer for the Rust compiler (rustc) and the Cargo package manager.

Add the WebAssembly target:

rustup target add wasm32-unknown-unknown

Install cargo-hack and trunk. Trunk builds, bundles, and optimizes the WebAssembly application.

cargo install cargo-hack
cargo install trunk

Clone the repository:

git clone git@github.com:tramex/tramex.git

Development Commands

Run the web application:

trunk serve

Run the desktop application:

cargo run

Check the code with Clippy:

cargo clippy

Run the application with the debug features enabled in tramex and tramex-tools:

cargo run --features debug

Enable backtraces and more detailed logs:

RUST_BACKTRACE=1 RUST_LOG=debug cargo run --features debug

Documentation

The project uses mdBook to generate HTML documentation from Markdown files.

Install mdBook:

cargo install mdbook

Start the documentation development server from the repository root:

mdbook serve docs/

The latest generated crate documentation is available at:

CI/CD

Continuous Integration and Continuous Delivery automate tests and deployment throughout the application lifecycle. Tramex uses GitHub Actions for deployment and testing. The principal workflows are:

Each YAML workflow defines its execution context and a sequence of named actions or commands.

Deployment

The deployment workflow runs for pushes to the main branch and can also be started manually from the Actions tab. It configures GitHub Pages, Cargo caching, and mdBook before building coverage, the application, and the documentation.

The web application is built with Trunk in release mode. The --public-url option accounts for the application being hosted below the /tramex/ path, and all generated files are collected in dist.

Coverage is generated and moved into dist. mdBook transforms the Markdown files under docs according to docs/book.toml, and its output is also placed in dist. The entire directory is then deployed to GitHub Pages.

Deployment outputs are available at:

Tests

The tests workflow runs for pushes and pull requests targeting the main branch. It configures the Cargo cache, builds the workspace, and runs its test suite with verbose output to make failures easier to diagnose.

WebAssembly

The WASM workflow runs for pushes and pull requests targeting the main branch. In addition to the native workspace checks, it verifies that the Rust WebAssembly target builds successfully with Trunk.

Spelling

typos.yml checks documentation spelling for pushes and pull requests targeting the main branch. False positives can be added to typos.toml at the repository root.

Troubleshooting and Knowledge Base

Browser Copy and Paste

Older versions of eframe required --cfg=web_sys_unstable_apis to enable browser clipboard access. This was fixed in eframe 0.29: https://github.com/emilk/egui/pull/4980#pullrequestreview-2260129833.

Related resources:

Coverage

Code coverage generated by cargo-llvm-cov is available at https://tramex.github.io/tramex/coverage/.

Secure WebSocket Connections

When the website runs over HTTPS, browsers block connections to insecure endpoints such as ws://. Possible solutions include:

  • Add an SSL certificate to the WebSocket server.
  • Use a WebSocket proxy to translate ws connections to wss.
  • Use a local WebSocket proxy so the application connects through a local address.
  • Disable the browser restriction during local development.

Example local proxy with an origin header:

npx @n4n5/proxy-ws -t ws://10.0.0.1:9001 -h '{"origin":"toto"}'
# Redirects ws://127.0.0.1:9001 to ws://10.0.0.1:9001

Limiting Compilation Resources

Cargo can use all available CPU cores during compilation. Limit the number of parallel jobs from the command line:

cargo build --jobs 10
# or
cargo build -j 10

To make the limit persistent, add the following to ~/.cargo/config.toml:

[build]
jobs = 10

On Linux, nproc reports the number of available CPUs.

Changing the File List from a URL

Use the files_url query parameter to provide a different file list:

https://tramex.github.io/tramex/?files_url=https://example.com/

Development Log

Overview

This document tracks major improvements to Tramex, including the indexed file navigation system, automatic batch continuation, and the fixed layout with a navigation toolbar and grouped panels.


1. Indexed Pre-Scan with Lazy Parsing

Implementation Date

2025-10-10

1.0. Overview

1.0.1 Problem Solved

  • Slow navigation through large log files (900k+ events)
  • Landing on filtered/disabled layers when navigating
  • No visibility into total event count or progress

1.0.1 Solution: File Index System

Implemented a lightweight index that pre-scans the file to identify all log boundaries and extract metadata without full parsing.

1.0.2. Performance Improvements

  • Index building: ~3-4x faster (8s → 2-3s for 900k traces)
  • Navigation: Instant jumps to any event position
  • Memory: Only parsed events are cached
  • Filtering: Can skip disabled layers efficiently

1.1. Key Components

File Index (file_index.rs)

  • Scans file on load to identify all log boundaries
  • Extracts metadata (timestamp and layer) for each log
  • Stores line ranges for efficient random access
  • Provides search methods for finding enabled logs
  • Enables instant total count and progress tracking

Enhanced InterfaceTrait Extended with new methods:

  • supports_preloading() - File: true, WebSocket: false
  • get_total_event_count() - File: Some(count), WebSocket: None
  • is_fully_read() - Check if all data is loaded

Updated File Handler

  • FileIndex field - built on first data request
  • Parse cache - HashMap for caching parsed logs
  • Automatic indexing when file is opened
  • Lazy parsing - only parse events when accessed

WebSocket Compatibility Implemented trait methods without changing core logic:

  • Server still handles parsing and filtering
  • No preloading support (server controls data)
  • Unknown total count (returns None)

1.2. tramex-tools Architecture

The tramex-tools crate provides the data acquisition and parsing layer used by Tramex. Its main entry point is Connector, which reads traces from supported sources and returns Data.

1.2.1. Data Model

Data contains a vector of Trace values and the index of the current trace. Each Trace combines:

  • MessageType: metadata such as the protocol layer, direction, and channel.
  • Hexa: the hexadecimal representation of ASN.1 binary data, which can be decoded according to the message type.

1.2.2. Interfaces

Tramex retrieves 4G traces from an Amarisoft software core through two interfaces:

  • File, which reads multiple traces from a log file.
  • WsConnection, which requests traces through the WebSocket API.

Connector exposes constructors for these sources and two principal data-loading methods:

  • get_more_data requests more traces. For WebSocket sources, it sends a message to the server; for file sources, it reads the next unread part of the file and stores the resulting data.
  • try_recv reads the WebSocket receive buffer and is typically called whenever the UI refreshes.

When a WebSocket connection is open, server messages enter a receive buffer. The application can either poll this buffer or use a callback to wake the UI when a message arrives.

1.2.3. Parsing

Both interfaces serialize their input into the common trace model. File parsing starts in file_handler, with the indexed pre-scan and lazy parsing described above allowing traces to be located before their full payload is decoded.

1.3. Files Modified

New Files:

  • tramex-tools/src/interface/interface_file/file_index.rs

Modified Files:

  • tramex-tools/src/interface/interface_types.rs
  • tramex-tools/src/interface/interface_file/file_handler.rs
  • tramex-tools/src/interface/interface_file/mod.rs
  • tramex-tools/src/interface/websocket/ws_connection.rs
  • tramex/src/handlers/mod.rs
  • tramex/src/handlers/handler_file.rs

2. Automatic Batch Continuation

Implementation Date

2025-10-10

2.0. Overview

2.0.1. Problem Solved

When navigating with layer filters enabled, the “Next” button would sometimes stop after loading 5-6 batches without finding an enabled layer, requiring multiple clicks to continue.

2.0.2. Solution: Loop-Based Batch Loading

Modified the frontend to keep loading batches in a loop until an enabled layer is found or the end of file is reached.

2.0.3. Benefits

  • No more manual clicking: One click finds the next enabled event
  • Faster navigation: Automatic batch loading feels instant
  • Better UX: Users don’t need to understand batching

2.1. Architecture

  1. User clicks “Next”
  2. Search through currently loaded events
  3. If no enabled layer found → load next batch
  4. Search through new batch
  5. If still not found → load another batch
  6. Repeat until: enabled layer found OR end of file OR error

2.1.1. Implementation Details

In frontend.rs:

#![allow(unused)]
fn main() {
while self.trame_manager.should_get_more_log {
    // Load batch
    // Continue navigation
    // Loop continues if more batches needed
}
}

In trame_manager.rs:

  • Sets should_get_more_log = true when reaching end of loaded events
  • Sets continue_navigation_after_load = true to resume search
  • Automatically continues until enabled layer found

2.2. Files Modified

  • tramex/src/frontend.rs - Added while loop for batch continuation
  • tramex/src/panels/trame_manager.rs - Navigation logic with flags

3. Fixed Layout, Navigation Toolbar & Panel Groups

Implementation Date

2025-10-10 : Dedicated Navigation Panel window (Previous/Next, event counter, jump to event) 2026-10-13 : Fixed layout (navigation toolbar, inline Messages, status bar), panel groups with layer presets, Settings window, unified theme 2026-11-05 : Settings → Parameters tab (HARQ max arrows, Chronograph RAN/MAC max arrows, file batch size, WebSocket request size and history window) 2026-11-09 : Incremental next-event search with loading indicator on the Next button

3.0. Overview

3.0.1. Problem Solved

  • Every panel was a floating window: with ten of them open at once the workspace quickly became unusable
  • Navigation and Messages are needed in every context, yet they could be closed or hidden behind other windows
  • Hard-coded colors made the light theme partially unreadable and the look inconsistent
  • Layer filters and file options took permanent space in the sidebar

3.0.2. Solution: Fixed Core UI + Grouped Floating Panels

Navigation and Messages are now fixed parts of the layout. The remaining panels stay floating windows but are organized in three groups that can be switched with a single click, each group also applying a layer-filter preset.

┌ Menu bar: [theme] Menu | Windows | Settings | About ──────────────────────────┐
├ Toolbar: [◀ Previous] [▶ Next] [⏸ Pause] | Event 12 / 4567 | Time 12:03:01.234 │
│                                                        [ RRC ] [ NAS ] [ Radio ] │
├────────┬─────────────────────────────────────────────────────────────────────────┤
│ Source │  Messages (fixed)                                                       │
│ (side  │   [RRC]  AdditionalInfos(...)                                           │
│  bar)  │   [x] Show full message        📋                                       │
│        │   [AI Explain]                                                          │
│        │                       (floating panels of the active group on top)     │
├────────┴─────────────────────────────────────────────────────────────────────────┤
└ Status: File: trace.log | Loaded 1500 / 4567 | ● auto-loading     Fully loaded ─┘

3.0.3. Future Enhancements

  1. Keyboard shortcuts: Arrow keys for Previous/Next
  2. Event markers / bookmarks: Mark and save important event positions
  3. Search: Search through events by content
  4. Dockable panels: Optional egui_tiles/egui_dock layout for split views inside a group
  5. Batch controls: Skip forward/backward by N events
  6. Auto-play: Automatically advance through events

3.1. Navigation Toolbar (navigation_panel.rs)

NavigationPanel::show_toolbar(ui, &NavState) renders a single row inside a fixed egui::Panel::top("nav_toolbar"):

  • ◀ Previous (default style, disabled on the first event)
  • ▶ Start / ▶ Next (accent fill; disabled only when at the end and the source is fully loaded)
  • ⏸ Pause / ▶ Resume (WebSocket only) toggles auto-loading
  • Event N / M: the index is a clickable label that turns into an inline text field to jump to a given event
  • Time: timestamp of the current event (HH:MM:SS.FFF)

The Layer label was removed (the layer is shown in the Messages header) and the Loaded counter moved to the status bar.

The toolbar does not touch the Application directly: it sets flags (should_go_next, should_go_previous, should_goto_event, should_toggle_auto_loading) that FrontEnd::ui consumes after rendering, exactly as the former window did.

3.2. Panel Groups (event_bus.rs, frontend.rs)

EventSubscriber gained two methods:

#![allow(unused)]
fn main() {
pub enum PanelGroup { Main, Rrc, Nas, Radio }

pub trait EventSubscriber: Send {
    fn group(&self) -> PanelGroup;                       // required
    fn show_inline(&mut self, _ui: &mut egui::Ui) {}     // Main-group panels only
    fn show_window(&mut self, ctx: &egui::Context, open: &mut bool) -> Result<(), TramexError>;
    // ...event callbacks unchanged
}
}
GroupPanelsLayer preset
MainMessages (rendered inline in the central panel via show_inline)—
RRCRAN Config, RRC Status, Bearer Status, Logical Channels (+ Chronograph RAN)RRC
NASChronograph RAN, Identity, GTPU TunnelRRC, NAS, NGAP, GTPU
RadioResource Blocks, HARQ, Chronograph MAC-RLC-PDCP, PowerPHY
  • A panel declares a single group(), used for the Windows menu listing. The set of windows actually toggled by a group button is computed by FrontEnd::windows_for_group, which adds a few cross-group panels: the RRC shortcut also opens Chronograph RAN, which stays declared as a NAS panel.
  • EventBus::show_windows skips Main panels; EventBus::show_main renders them inline. The event notifications are unchanged: every panel keeps receiving events whether or not its window is open.
  • The group buttons on the right of the toolbar are exclusive: selecting a group opens its windows, closes the other groups’ windows and applies its layer preset (FrontEnd::select_group / layers_for_group). Clicking the active group closes its windows.
  • RRC is the default group: it is selected as soon as a file is loaded or a WebSocket connects, before the first data request so the server receives the RRC-only filter.
  • The Windows menu stays non-exclusive (Show all / Hide all + one checkbox per panel, listed by group) and stays open while clicking (MenuConfig::close_behavior(CloseOnClickOutside)).
  • open_windows starts empty on first launch; later launches restore the persisted state.

3.3. Messages, Sidebar, Status Bar and Settings

  • Messages (panel_message.rs): rendered inline inside one outer ScrollArea; the “Layer : X” heading became a colored pill badge followed by the additional infos. “Show full message”, copy to clipboard and the AI Explain section are unchanged (the inner scroll areas were removed since the whole view scrolls).
  • Sidebar (ui_connector): reduced to the source selection (File / WebSocket) and the connector UI. It collapses automatically when a source becomes active and reopens when the file is closed or the socket disconnected; the ◀/▶ toggle still works in between.
  • Status bar (egui::Panel::bottom("status_bar")): data source description, Loaded N / total, WebSocket auto-loading state, and Fully loaded on the right.
  • Settings window (app.rs): always available from the Settings menu with tabs AI (feature ai), Layers (FrontEnd::show_layer_options) and File options (FrontEnd::show_file_options, File mode only).

3.4. Theme (theme.rs)

ThemeColors is now the single source of truth for colors and drives egui’s own styling through ThemeColors::apply_style(ctx), called once in TramexApp::new:

  • One palette per mode (dark / light), with new accent_fill / on_accent fields for primary buttons
  • Visuals per theme (ctx.set_visuals_of): panel/window fills, strokes, corner radii, shadows, selection and hyperlink colors, widget states
  • Shared Style (ctx.all_styles_mut): compact spacing (item spacing 6×4, button padding 8×3, interact height 20) and text styles (Heading 15, Body 13, Button 13, Monospace 12, Small 10.5)
  • UI colors that used to be hard-coded (navigation buttons, status labels, error labels, color_label) now come from the palette. Data-encoding palettes (HARQ processes, resource types, channel/arrow colors) are intentionally kept fixed.

Gotcha: egui’s strong_text_color() resolves to widgets.active.fg_stroke.color; it must stay a text color (not the on-accent white) or every .strong() label becomes invisible in light mode.

3.5. Files Modified

Modified Files:

  • tramex/src/panels/navigation_panel.rs - show_nav window replaced by show_toolbar
  • tramex/src/event_system/event_bus.rs - PanelGroup, group(), show_inline(), show_main(), subscriber_groups()
  • tramex/src/event_system/application.rs - panel_groups(), show_main_panel()
  • tramex/src/frontend.rs - Toolbar, status bar, group toggles, select_group, layers_for_group, sidebar auto-hide, Windows menu
  • tramex/src/app.rs - Settings window with tabs, apply_style call
  • tramex/src/theme.rs - Palettes, apply_style
  • tramex/src/panels/panel_message.rs - Inline rendering, layer badge
  • tramex/src/panels/*.rs - group() implementations
  • tramex/src/handlers/handler_file.rs - ui_options without collapsing header
  • tramex/src/parameters.rs - runtime Parameters struct, Settings tab UI

4. RRC Field Viewer & Message Panel Improvements

Implementation Date

2025-10-10

4.0. Overview

4.0.1. Problem Solved

  • No dedicated panel for viewing specific RRC message fields
  • Message panel displayed too much information (timestamp, hex always visible)
  • Array values in JSON were not properly displayed
  • Technology information was not visible in logical channels panel
  • Technology detection relied only on file headers (which could be missing)

4.0.2. Solution: RRC Field Viewer + UI Enhancements

4.0.3. Benefits

For Users:

  • Quick access to important RRC message fields
  • Cleaner message panel with less clutter
  • Technology always visible and correctly detected
  • Easy to understand array values

For Developers:

  • Easy to add new message configurations
  • Flexible JSON path system
  • Centralized technology detection
  • Extensible field mapping system

4.0.4. Future Enhancements

  1. Dynamic field configuration: Load field mappings from config file
  2. More message types: Add configurations for other RRC messages (SIB2, MIB, etc.)
  3. Field filtering: Show/hide specific fields
  4. Export fields: Copy field values to clipboard
  5. Field history: Track field value changes over time
  6. Comparison view: Compare fields across multiple messages

4.1. New RRC Field Viewer Panel (bst_config.rs)

A dedicated panel for displaying extracted fields from RRC messages with configurable field mappings.

Key Features:

  • Configurable field mappings: Define which fields to extract per message type
  • JSON path navigation: Support for nested objects and array indexing with [N] syntax
  • Automatic value formatting:
    • Arrays displayed as [item1, item2, ...]
    • Objects with decimal/hex fields automatically formatted
    • Units can be added to values (e.g., “dB”)
  • Grid layout: Clean table display with field names and values

Default Configurations:

  • SIB1 (4G): mcc, mnc (from plmn-IdentityList[0].plmn-Identity)
  • SIB1 (5G): q-RxLevMin, q-QualMin, mcc, mnc, cellId, trackingAreaCode (from plmn-IdentityInfoList[0])

JSON Path Examples:

#![allow(unused)]
fn main() {
// Simple field
"message.c1.systemInformationBlockType1.cellSelectionInfo.q-RxLevMin"

// Array indexing
"message.c1.systemInformationBlockType1.cellAccessRelatedInfo.plmn-IdentityList[0].plmn-Identity.mcc"

// Nested arrays
"message.c1.systemInformationBlockType1.cellAccessRelatedInfo.plmn-IdentityInfoList[0].plmn-IdentityList[0].mcc"
}

Value Extraction:

  • Arrays: [0, 0, 1] → displayed as [0, 0, 1]
  • Objects with decimal: {"decimal": 101, "hex": "000065"} → displayed as 101
  • Objects with hex: {"hex": "001234501"} → displayed as 0x001234501

4.2. Message Panel Improvements

UI Cleanup:

  • Layer type: Now displayed as large heading
  • Timestamp removed: No longer displayed by default
  • Hex moved: Only shown in “Show full message” section for RRC layers
  • Simplified layout: Less clutter, more focus on important info

Before:

RRC at 12:34:56.789
AdditionalInfos(...)
Hex: [0x12, 0x34, ...]
[Show full message checkbox]

After:

Layer: RRC

AdditionalInfos(...)
[Show full message checkbox]

[When checked:]
  Hex: [0x12, 0x34, ...]
  [ASN.1 text...]

4.3. Technology Detection Enhancement

Two-tier detection system:

  1. Primary: File header parsing (existing)

    • Looks for nr_arfcn (5G) or earfcn (4G) in Cell line
  2. Fallback: RRC canal name inference (new)

    • If technology is Unknown after header parsing
    • Checks first RRC trace canal name:
      • Ends with "-NR" → Technology::NR
      • Otherwise → Technology::LTE
    • Applied during file parsing in file_handler.rs

Benefits:

  • Works even when file headers are missing
  • Propagates to all panels automatically
  • Displayed in Logical Channels panel

4.4. Logical Channels Panel Update

New display:

[----] [----] [----] [Downlink] [----] [----] [----]
[    ] [Techno: LTE (4G)] [    ] [----] [Uplink] [----]

Shows technology (LTE/NR) in the channel grid for quick reference.

4.5. Technical Details

Array Indexing Implementation:

#![allow(unused)]
fn main() {
// Supports syntax like "field[0].nested[1].value"
if let Some(bracket_pos) = part.find('[') {
    let field_name = &part[..bracket_pos];
    let index_str = &part[bracket_pos+1..part.len()-1];
    
    current = current.get(field_name)?;
    
    if let Value::Array(arr) = current {
        let index: usize = index_str.parse().ok()?;
        current = arr.get(index)?;
    }
}
}

Technology Inference:

#![allow(unused)]
fn main() {
// In file_handler.rs during batch processing
if data.metadata.technology == Technology::Unknown {
    for trace in &traces {
        if let AdditionalInfos::RRCInfos(infos) = &trace.additional_infos {
            if infos.canal.ends_with("-NR") {
                data.metadata.technology = Technology::NR;
            } else {
                data.metadata.technology = Technology::LTE;
            }
            break;
        }
    }
}
}

4.5. Files Modified

New Files:

  • tramex/src/panels/bst_config.rs - New RRC field viewer panel

Modified Files:

  • tramex/src/panels/mod.rs - Added bst_config module
  • tramex/src/frontend.rs - Integrated RRC Field Viewer panel
  • tramex/src/panels/panel_message.rs - UI improvements, moved display_log function
  • tramex/src/utils.rs - Removed display_log (moved to panel_message.rs)
  • tramex/src/panels/logical_channels.rs - Added technology display
  • tramex-tools/src/interface/interface_file/file_handler.rs - Technology inference logic
  • tramex-tools/src/interface/parse_config.rs - Technology enum and FileMetadata

5. WebSocket Connection Debugging Guide

Implementation Date

2025-11-27

5.0. Overview

5.0.1. Current Situation

You’re receiving the initial “ready” message from the Amarisoft server but not seeing subsequent log messages.

5.0.2. Root Cause

The Amarisoft WebSocket server uses a REQUEST-RESPONSE pattern, not a push model:

  1. ✅ Server sends “ready” message when you connect
  2. ❌ You must send log_get requests to receive logs (this is not happening automatically)
  3. ❌ Server only sends log data in response to your log_get requests

5.0.3. Next Steps

  1. Run your application and check the logs for the emoji indicators (🔵 📨 📤 ✅)
  2. Click the Next button to trigger a log_get request
  3. Check if you see the request being sent (📤 messages)
  4. Check if you receive a response (🔵 and 📨 messages)
  5. If no response, check the Amarisoft server configuration for screen settings

5.1. How Your Application Works

5.1.1 Message Flow:

1. Connect → Server sends "ready" message
2. User navigates (clicks Next) → Triggers `should_get_more_log = true`
3. `get_more_data()` is called → Sends `log_get` request to server
4. Server responds → `try_recv()` receives the log data

5.1.2. The Problem:

  • try_recv() is called every frame to check for incoming messages ✅
  • get_more_data() sends the request to the server ✅
  • BUT get_more_data() is only called when:
    • You click the “Next” navigation button
    • You’re near the end of loaded events (preloading)
    • should_get_more_log is set to true

5.2. Debugging Steps

5.2.1. Check the Logs

I’ve added comprehensive logging to help you debug. Run your application and look for these log messages:

✅ WebSocket connection opened successfully
✅ Received 'ready' message from server: ENB
💡 Server is ready. You need to click 'Load More' or enable auto-loading to request logs.

5.2.2. Trigger a Request

After connecting, you need to trigger a log_get request. Try one of these:

Option A: Click the Navigation Button

  • Click the “Next” button in your navigation panel
  • This should trigger get_more_data() and you’ll see:
    📤 Sending log_get request: ...
    📤 JSON request: {"timeout":1,"min":64,"max":1024,...}
    

Option B: Check if Auto-Loading Works

  • The code has preloading logic that should automatically request more data
  • But it only works if you have some events already loaded

5.2.3. Watch for Server Response

After sending a request, you should see:

🔵 WebSocket event received: Message(...)
📨 Raw WebSocket text message: {"message":"log_get","logs":[...]}

If you DON’T see the server response, the problem is with the server or network.

5.3. Common Issues

5.3.1. “Screens” on Amarisoft Server

Amarisoft servers often require you to enable “screens” to receive log data:

Check if screens are enabled:

## Connect to your Amarisoft VM
ssh user@137.194.194.35

## Check screen configuration
## Look for screen settings in your ENB configuration file

Typical screen configuration in enb.cfg or mme.cfg:

log_options: {
    // Enable screens
    screens: [
        {
            name: "ENB",
            layers: ["rrc", "nas", "s1ap"],  // Specify which layers to log
        }
    ],
}

5.3.2. Layer Filters

Your log_get request includes layer filters. Make sure:

  1. The layers you’re requesting are enabled on the server
  2. The layers match what the server is configured to send

Check your layer configuration:

  • Open Settings → Layers in your app (or select a panel group in the toolbar to apply a preset)
  • Make sure at least one layer is enabled (e.g., RRC, NAS, S1AP)

5.3.3. Server Not Sending Data

The server might not have any data to send if:

  • No UE (User Equipment) is connected
  • No traffic is being generated
  • The layers you’re requesting have no activity

5.4. Testing with a Simple Request

You can test the WebSocket connection manually using a WebSocket client:

// Connect to the server
const ws = new WebSocket('ws://137.194.194.35:9001');

ws.onopen = () => {
    console.log('Connected');
    
    // Wait for ready message, then send a log_get request
    setTimeout(() => {
        const request = {
            message: "log_get",
            message_id: 1,
            timeout: 1,
            min: 64,
            max: 1024,
            layers: {
                rrc: "Debug",
                nas: "Debug",
                s1ap: "Debug"
            },
            headers: false
        };
        ws.send(JSON.stringify(request));
        console.log('Sent log_get request');
    }, 1000);
};

ws.onmessage = (event) => {
    console.log('Received:', event.data);
};

5.5. Files Modified

I’ve added logging to:

  • tramex-tools/src/interface/websocket/ws_connection.rs
    • Line 115: Log all WebSocket events
    • Line 122: Log all raw text messages
    • Line 74-77: Log all outgoing requests
    • Line 148-149: Log ready message with helpful hint

All logs use log::info!() so they’ll be visible by default.


6. Event-Driven Architecture (Observer Pattern)

Implementation Date

2025-11-09 : Implementation 2026-03-11 : Clean up the legacy system

6.0. Overview

Refactored the application to use an event-driven architecture with the Observer pattern, replacing the legacy polling-based system with a reactive, notification-based approach.

6.1. Architecture

Core Components:

  1. Application Controller - Central orchestrator

    • Owns EventStore (all event data)
    • Owns EventBus (notification dispatcher)
    • Owns DataSource (File/WebSocket I/O)
    • Coordinates event flow and navigation
  2. EventStore - Event data management

    • Single source of truth for all events
    • Maintains current index for navigation
    • Provides O(1) access to events
  3. EventBus - Observer pattern implementation

    • Dispatches notifications to all subscribers
    • Three notification types:
      • on_event_added - New event received
      • on_event_focused - User navigated to event
      • on_events_cleared - Data cleared
  4. EventSubscriber Trait - Panel interface

    • All panels implement this trait
    • Receive notifications automatically
    • No manual polling required

6.2. Data Flow

Loading Events:

DataSource → Application.update()
          → EventStore.add_events()
          → EventBus.notify_event_added()
          → All panels' on_event_added()

Navigation:

User clicks Next → Application.navigate_next()
                → EventStore.go_next()
                → EventBus.notify_event_focused()
                → All panels' on_event_focused()

Auto-Loading (WebSocket):

Frame loop → Application.update()
          → DataSource.poll()
          → New events processed
          → Auto-navigate to latest

6.3. Key Benefits

AspectOld SystemNew System
Event ProcessingLoop through all events on navigationProcess once when added
Data OwnershipScattered across Data, TrameManager, panelsSingle EventStore
NavigationCoupled with processingSeparate: data vs. UI focus
Adding PanelsManually wire in multiple placesImplement EventSubscriber trait
TestingHard to test individual partsEasy to mock components

6.4. API Examples

Basic Usage:

#![allow(unused)]
fn main() {
// Create application
let mut app = Application::new();

// Register panels
app.subscribe(Box::new(Chronograph::new()));
app.subscribe(Box::new(RRCStatusPanel::new()));

// Set data source (File or WebSocket)
app.set_data_source(Box::new(file_source));

// Main loop
loop {
    app.update()?;  // Poll data, process events, notify panels
    
    // Navigation
    if next_clicked {
        app.navigate_next();
    }
}
}

File Loading Strategies:

#![allow(unused)]
fn main() {
// Load entire file immediately
FileSource::new(path, FileLoadingStrategy::Immediate)

// Load in batches on demand
FileSource::new(path, FileLoadingStrategy::OnDemand { batch_size: 1000 })

// Progressive loading with delays
FileSource::new(path, FileLoadingStrategy::Progressive { 
    batch_size: 500, 
    delay_ms: 100 
})
}

6.5. Panel Implementation

Panels implement EventSubscriber:

#![allow(unused)]
fn main() {
impl EventSubscriber for Chronograph {
    fn on_event_added(&mut self, event: &Trace, index: usize, context: &EventContext) {
        // Process event data (extract info, update state)
        if let AdditionalInfos::RRCInfos(infos) = &event.additional_infos {
            self.add_arrow(infos, index);
        }
    }
    
    fn on_event_focused(&mut self, event: &Trace, index: usize, context: &EventContext) {
        // Update UI (scroll, highlight)
        self.current_index = index;
        self.should_scroll = true;
    }
    
    fn on_events_cleared(&mut self) {
        // Clean up
        self.arrows.clear();
    }
}
}

6.6. Performance Characteristics

Memory:

  • Single copy of events in EventStore
  • No duplication across panels
  • Bounded collections (e.g., max 500 arrows in Chronograph)

CPU:

  • O(1) event addition to store
  • O(n) notification where n = number of subscribers
  • O(1) navigation between events

I/O:

  • File: Configurable batch size (1-4096 events)
  • WebSocket: Server-controlled with timeout
  • Non-blocking: poll() never blocks main thread

6.7. Files

  • tramex/src/event_system/mod.rs - Module exports
  • tramex/src/event_system/application.rs - Application controller
  • tramex/src/event_system/event_bus.rs - Observer pattern dispatcher
  • tramex/src/event_system/event_store.rs - Event data management
  • tramex/src/event_system/data_source.rs - DataSource trait
  • tramex/src/event_system/file_source.rs - File DataSource
  • tramex/src/event_system/websocket_source.rs - WebSocket DataSource
  • tramex/src/event_system/integration.rs - create_application_with_panels() factory
  • tramex/src/frontend.rs - Integrated Application controller
  • tramex/src/panels/*.rs - All panels implement EventSubscriber

6.8. Legacy Cleanup (2025-03-11)

Removed legacy migration scaffolding:

  • EventSystemBridge struct and all methods
  • should_use_new_system() env-var toggle
  • add_event() (unused singular method)
  • TRAMEX_USE_NEW_EVENT_SYSTEM env var from .cargo/config.toml
  • Legacy comments throughout application.rs and frontend.rs

Still in place (requires Handler trait refactoring):

  • FrontEnd.data: Data — handlers still write into Data
  • Handler → Data → add_events() → Application transfer pipeline
  • sync_metadata_from_data() bridge

6.9. Future Enhancements

  1. Complete DataSource migration: Replace Handler trait with DataSource, remove Data middleman
  2. Advanced features: Event filtering, search, bookmarks, export/import

7. Trace Association System

Implementation Date

2025-01-11

7.0. Overview

A flexible, rule-based system for linking related protocol messages across layers, enabling visibility into parent/child relationships between traces.

7.1. Key Principles

7.1.1. Parent-Child Relationships

Each Trace contains a TraceRelation that stores its associations:

TraceRelation holds two AssociationStatus fields:

#![allow(unused)]
fn main() {
pub struct TraceRelation {
    pub parent: AssociationStatus,  // Traces that carry this one
    pub child: AssociationStatus,   // Traces carried by this one
}
}

AssociationStatus represents the state of an association search:

#![allow(unused)]
fn main() {
pub enum AssociationStatus {
    NotComputed,           // Not yet processed
    Found(Vec<usize>),     // Found related trace indices
    NotFound,              // Searched but no match found
    NotApplicable,         // Layer doesn't support associations
}
}

Why Vec<usize> for multiple associations?
This is specific to NAS, which is carried by both RRC (radio layer) and NGAP (core network). A NAS message can have two parents simultaneously. For logic convenience and consistency, this multi-parent support has been applied to all layers, and extended to children as well for shared logic and possible evolution.

Associations are found by searching within a configurable window around the source trace:

         ←── window_size ──→            ←── window_size ──→
    [...][candidate][candidate][SOURCE][candidate][candidate][...]
              <-                    ↑                  ->
         search_backward      current trace      search_forward
  • Default window: 10 traces in each direction
  • Efficiency: Avoids scanning entire event list.
  • Configurable: Each rule can override window_size()

7.1.3. Preferred Direction

Rules specify which direction to search first based on the trace’s communication direction:

#![allow(unused)]
fn main() {
pub enum SearchDirection {
    BackwardFirst,   // Search past traces first, then future
    ForwardFirst,    // Search future traces first, then past
    BackwardOnly,    // Only search past traces
    ForwardOnly,     // Only search future traces
}
}

Typical usage:

  • Uplink (UL/TO): Search backward first (carrier came before because the ENB/GNB is reading encapsulation with lower level first)
  • Downlink (DL/FROM): Search forward first (carrier comes after because the ENB/GNB is encapsulating higher level first)

7.1.4. Message Filtering

Rules can filter which messages are eligible for association:

  • valid_source_messages(): Only process source traces with these message names
  • valid_target_messages(): Only consider targets with these message names

This prevents false matches between unrelated message types.

7.1.5. Relationship Direction (source_is_child)

Each rule defines whether the source trace is the child or parent:

source_is_childSource RoleTarget RoleExample
trueChildParentNAS finds its RRC carrier
falseParentChildNGAP finds the NAS it carries

7.2. Architecture

┌─────────────────────────────────────────────────────────┐
│                 AssociationRules                        │
│         (Collection of rule implementations)            │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   TraceMatcher                          │
│  - find_relative(source, rules) → AssociationStatus    │
│  - search_backward() / search_forward()                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   TraceRelation                         │
│  - parent: AssociationStatus (Vec<usize>)              │
│  - child: AssociationStatus (Vec<usize>)               │
└─────────────────────────────────────────────────────────┘

7.3. AssociationRule Trait

#![allow(unused)]
fn main() {
pub trait AssociationRule {
    // Layer configuration
    fn source_layer(&self) -> Layer;
    fn target_layer(&self) -> Layer;
    
    // Core matching logic
    fn matches(&self, source: &Trace, candidate: &Trace) -> bool;
    
    // Search behavior
    fn window_size(&self) -> usize { 10 }
    fn preferred_direction(&self, source: &Trace) -> SearchDirection;
    
    // Filtering
    fn valid_source_messages(&self) -> &[&str] { &[] }
    fn valid_target_messages(&self) -> &[&str] { &[] }
    
    // Relationship direction
    fn source_is_child(&self) -> bool { true }
}
}

7.4. Computation Flow

7.4.1. compute_associations()

Main entry point that processes traces and builds relationships:

#![allow(unused)]
fn main() {
pub fn compute_associations(
    events: &mut [Trace], 
    rules: &AssociationRules, 
    start_index: usize
) {
    for index in start_index..events.len() {
        // 1. Get applicable rules for this trace's layer
        let applicable_rules = rules.rules_for_layer(&layer);
        
        // 2. If no rules apply, mark as NotApplicable
        if applicable_rules.is_empty() {
            trace.relation.set_parent_not_applicable();
            continue;
        }
        
        // 3. Try each rule until match found
        for rule in applicable_rules {
            let status = TraceMatcher::find_relative(index, events, rule);
            
            if let AssociationStatus::Found(targets) = status {
                // 4. Set bidirectional relationship based on source_is_child
                if rule.source_is_child() {
                    trace.add_parent(target);      // source is child
                    target.add_child(index);       // target is parent
                } else {
                    trace.add_child(target);       // source is parent
                    target.add_parent(index);      // target is child
                }
            }
        }
    }
}
}

7.4.2. rules_for_layer()

Returns all rules where the given layer is the source layer:

#![allow(unused)]
fn main() {
pub fn rules_for_layer(&self, layer: &Layer) -> Vec<&dyn AssociationRule> {
    self.rules.iter()
        .filter(|r| r.source_layer() == *layer)
        .collect()
}
}

This means:

  • When processing a NAS trace → NasToRrcRule applies (NAS is source, finds RRC parent)
  • When processing an NGAP trace → NgapToNasRule applies (NGAP is source, finds NAS child)

7.4.3. Lookback Window

When new batches arrive, traces near the batch boundary are re-processed to catch associations that span batches:

#![allow(unused)]
fn main() {
let lookback_window = 20;
let lookback_start = start_index.saturating_sub(lookback_window);
// Reset NotFound status in lookback range to NotComputed
// Then recompute from lookback_start
}

7.5. Chronograph Integration

Related traces are visually highlighted:

  • Current trace: Bright blue
  • Parent/child traces: Lighter blue
  • Other traces: Theme-aware default color

Chronograph arrows are interactive: clicking an arrow writes its trace index under the shared NAVIGATE_REQUEST_ID, which the frontend forwards to Application::navigate_to. HARQ, Power, Chronograph RAN, and Chronograph MAC-RLC-PDCP use the same panel-to-frontend navigation mechanism.

7.6. Implemented Rules

NasToRrcRule

ParameterValue
Source LayerNAS
Target LayerRRC
source_is_childtrue (NAS is child)
Window Size10
MatchingBinary comparison (first 10 bytes)
Valid SourceAll NAS messages
Valid Targetdl information transfer, ul information transfer, rrc setup complete, rrc reconfiguration

NgapToNasRule

ParameterValue
Source LayerNGAP
Target LayerNAS
source_is_childfalse (NGAP is parent)
Window Size10
MatchingBinary comparison (first 14 bytes)
Valid Sourceinitial ue message, downlink nas transport, uplink nas transport, initial context setup request
Valid TargetAll NAS messages

Note on Rule Direction

RuleDirection
NgapToNasRulesource_is_child = false
NasToRrcRulesource_is_child = true

There is no particular reason for this difference. Both orders are valid. The variation was primarily for testing the full logic.

Performance consideration: There is no difference in performance between the two approaches. However, source_is_child = false could be slightly faster if the hex parsing is reused across matches instead of being parsed every time.

7.7. Files

New Files:

  • tramex-tools/src/interface/association/mod.rs - compute_associations()
  • tramex-tools/src/interface/association/relation.rs - TraceRelation, AssociationStatus
  • tramex-tools/src/interface/association/rules.rs - AssociationRule trait, implementations
  • tramex-tools/src/interface/association/matcher.rs - TraceMatcher

8. Resource Blocks Panel - 5G NR Resource Grid Visualization

Implementation Timeline

  • v1.0: 2025-02-11 - Initial grid visualization
  • v2.0: 2025-02-28 - HFN support, view modes, performance optimizations

Overview

A visual resource grid panel displaying 5G NR Physical Resource Block (PRB) allocations over time. Renders a scrollable matrix of PRBs (y-axis) × Time (x-axis) with two view modes: Symbol-level (detailed) and Slot-level (aggregated).

8.1. Key principles

8.1.1. Frequency Axis

The Y axis is the frequency axis. There is no specific name for the unit, it will be referenced as Physical Resource Blocks (PRB), although one PRB is a unit of frequency x time.
One PRB is composed on multiple subcarriers, but this level of precision is not pertinent for the representation as it serves mainly for increasing the data output capacity.

Here, the Y axis is composed of 51 PRBs of 180KHz each. This can vary depending on the bandwidth configuration.

8.1.2. Time Axis

The X axis is the time axis.

  • A frame is 10ms
  • A Subframe is 1ms, 1/10th of a Frame.
  • The number of Slot per Subframe can vary from 2 to 8 depending of the antenna configuration. It is commonly 2 slots per subframe, so 1 slot = 0.5ms
  • There is 14 Symbol per Slot in 5G. This is the smallest allocation duration.

8.1.3. PHY layer

The Traces from Amarisoft provide enough information through the PHY layer to build most part of the resource grid. (Unfortunately his does apply for PDSCH, where positions are more difficult to find)

Example of a PHY event :

10:32:35.169 [PHY] UL 0001 01 4601 476.19 PUSCH: harq=0 prb=15:34 symb=0:14 ...

From there we can extract information to help us fill the grid :

UnitPHYRendering
PRBprb=15:34PRBs 15 → 48
Symbolsymb=0:14Symbols 0 → 13
SFN476.19Frame 476 - Slot 19

The System Frame Number (SFN) takes only into account the Frame and Slot number, but we can construct the SubFrame number through the number of Symbol per Frame (SpF).
This gives us : Frame 476, SubFrame 9, Slot 1, Symbol 0-13

Note: The System Frame Number (SFN) is a 10-bit value that cycles every 1024 frames and does not include the Hyper Frame Number (HFN). Therefore, we must infer the HFN by detecting SFN wraparound:

HFN: N, Frame 1023 → HFN: N+1, Frame 0

8.1.4. SSB

There is another type of event which can be easily displayed but which are not in the traces but in the antenna configuration: SSB

SSB: id=0 arfcn=630336 mu=1 L=8 period=20 offset=0 k_ssb=20 prb=15:21 symb=2

From there we can extract information to help us fill the grid :

UnitSSBRendering
IDid=0–
PRBprb=15:21PRBs 15 → 35
Symbolsymb=2Symbol 2 → 2
SFNperiod=20Every 20ms (2 frames)

8.2. Architecture Principles

8.2.1. Data Pipeline

As for every panel the events are parsed from the data source (File / Websocket) to the Trace format.
This is where we extract the information from the events and store it in the PHYInfos struct based on the rules above. HFN is not present because is cannot be extracted from the PHY event itself.

#![allow(unused)]
fn main() {
pub struct PHYInfos {
    pub direction: Direction, // Direction (UL or DL)
    pub channel_type: PHYChannelType, /// Channel type (PDSCH, PUSCH, etc.)
    pub frame: u16, /// Frame number
    pub slot: u8, /// Slot number within frame
    pub prb_start: u16, /// PRB start position
    pub prb_length: u16, /// PRB length (number of PRBs)
    pub symb_start: u8, /// Symbol start position within slot
    pub symb_length: u8, /// Symbol length (number of symbols)
}
}

When events are added to the trace, we process the PHYInfos and store them in a the CachedPHYEvent with the computed HFN.

8.2.2. Event System Integration

The panel implements EventSubscriber for reactive updates:

#![allow(unused)]
fn main() {
impl EventSubscriber for ResourceBlocks {
    fn on_event_added(&mut self, event: &Trace, index: usize, _ctx: &EventContext) {
        // Cache PHY events with HFN
        if let AdditionalInfos::PHYInfos(phy) = &event.additional_infos {
            self.add_phy_event(index, phy.clone());
        }
    }
    
    fn on_event_focused(&mut self, event: &Trace, index: usize, _ctx: &EventContext) {
        // Track for highlight and auto-center grid
        self.focused_trace_index = Some(index);
        self.center_on_event(event);
    }
    
    fn on_events_cleared(&mut self) {
        self.clear_slots();
        self.start_limit = (0, 0, 0);
        self.end_limit = (0, 0, 0);
    }
}
}

Auto-Centering: When a PHY event is focused in the navigation panel, the Resource Blocks grid automatically scrolls to center on that frame/slot.

8.2.3. Three-Dimensional Grid Model

For performance issues, it is not reasonable to think of building the whole grid :
1s = 100 Frames = 1k SubFrames = 2k Slots = 28k Symbols
One symbol column is one state ID of 8 bits x 51 PRBs = 51 octets
So 1s = 1.39 Mo, 1 hour of trace is over 5Go, and this is without counting for indexing cost and other additional data per symbol.

Therefore, we need to build the grid on demand, only for the visible part of the trace. We render N=10 frames before and after the focused event. With the possibility to navigate 1 Frame or 1 SubFrame. This also allows us to reduce the hell of scrolling headlessly on an infinite time axis.

The grid operates on three axes with distinct addressing strategies:

AxisDimensionAddressingRendering
YFrequency (PRBs)0 to n_rb_dl (e.g., 0-50)Vertical scroll with sticky labels
XTime (Symbols/Slots)Symbol: 0-13 per slot
Slot: aggregated
Horizontal scroll with sticky headers
X“Frame WindowGlobal slot indexVirtual scrolling with 200-slot (10 frames) window

Global Slot Addressing:

We use the absolute slot position for indexing:

#![allow(unused)]
fn main() {
// HFN-aware slot addressing for 1024-frame looping
pub type SlotAddress = (u32, u16, u16);  // (hfn, frame, slot)

// Global slot index for window positioning
let global_slot = (hfn as usize * 1024 + frame as usize) * slots_per_frame + slot;
}

8.2.3 HFN-Aware Event Caching

5G NR frames loop every 1024 frames. Without Hyper Frame Number tracking, frame 0 at startup is indistinguishable from frame 0 after wraparound.

#![allow(unused)]
fn main() {
pub struct CachedPHYEvent {
    pub trace_index: usize,
    pub hfn: u32,  // Hyper Frame Number increments on wraparound
    pub phy_info: PHYInfos,
}

// Limits stored with HFN for correct range checking
pub struct ResourceBlocks {
    pub start_limit: (u32, u16, u16),  // (hfn, frame, slot)
    pub end_limit: (u32, u16, u16),
}
}

Frame Wrap Detection:

#![allow(unused)]
fn main() {
// Detect wraparound by large frame jump (more than -512 frames)
if frame < end_frame && (end_frame - frame) > 512 { // Wrapped: 1023 -> 0
    hfn = hfn.saturating_add(1);  // HFN += 1
}
}

However, because of the precision of the Amarisoft logger, we can have prior events (relative to the SFN) coming after the current event. So we need to be able to detect an anti-wrap.

#![allow(unused)]
fn main() {
// Detect anti-wraparound by large frame jump (more than +512 frames)
if frame > end_frame && (frame - end_frame) > 512 { // Anti-wrapped: 0 -> 1023
    hfn = hfn.saturating_sub(1); // HFN -= 1
}
}

8.3. Data Structures

8.3.1 SlotGrid

#![allow(unused)]
fn main() {
pub struct SlotGrid {
    pub hfn: u32,               // HyperFrame number
    pub frame_number: u16,      // Frame (0-1023, wraps around)
    pub subframe_number: u16,   // Subframe (0-9)
    pub slot_number: u16,       // Slot within frame
    pub symbols: Vec<Vec<ResourceType>>,        // [prb][symbol] -> Resource Type 
    pub event_indices: Vec<Vec<Option<usize>>>, // [prb][symbol] -> trace index
    pub ssb_ids: Vec<Vec<Option<usize>>>,       // [prb][symbol] -> SSB index
}
}

8.3.2 Resource Types

TypeColorPurpose
EmptyWhiteUnallocated
PDCCHDark green 0, 100, 0Downlink control
PUCCHLight green 0, 200, 0Uplink control
PDSCHBlue 0, 100, 200Downlink data
PUSCHCyan 0, 180, 180Uplink data
PRACHYellow 255, 220, 0Random access
SSBMagenta 200, 0, 200Synchronization signal
DMRSRed 200, 0, 0Reference signal
GuardDark gray 100, 100, 100Guard band

8.4. UI Rendering

8.4.1 Dual View Mode Architecture

The panel supports two visualization modes with shared underlying data:

#![allow(unused)]
fn main() {
pub enum ViewMode {
    Symbol,  // Detailed: 14 symbols × PRBs per slot
    Slot,    // Aggregated: 1 column per slot with priority-based color
}
}

View Mode Characteristics:

AspectSymbol ViewSlot View
Use CaseDetailed analysisOverview, pattern detection
Cell Count14 × PRBs × slotsPRBs × slots
Resource DisplayExact symbol allocationHighest priority resource
PerformanceHigher CPU (more cells)Optimized (cached aggregation)

Priority Aggregation for Slot View:

In case many resources are allocated to the same PRB and slot, we need to prioritize the most important one to be displayed.

#![allow(unused)]
fn main() {
// cf
impl ResourceType -> pub fn priority(&self)
}

8.4.2 Sticky Header Rendering

Traditional egui::Grid cannot handle both sticky row headers (PRB labels) and sticky column headers (slot info). The panel uses a custom overlay approach:

Implementation:

  • Single ScrollArea::both() contains the entire grid
  • Headers/labels drawn as overlays using painter with viewport-relative coordinates
  • Content rect calculations account for label/header dimensions

8.4.3. Visible-Range Culling

Only render cells within the visible viewport for performance:

#![allow(unused)]
fn main() {
// Calculate visible ranges from scroll offset
let vis_start_slot = (scroll_offset_x / slot_width) as usize;
let vis_end_slot = ((scroll_offset_x + viewport_width) / slot_width) as usize + 1;
let vis_start_prb = (scroll_offset_y / cell_size) as usize;
let vis_end_prb = ((scroll_offset_y + viewport_height) / cell_size) as usize + 1;

// Clamp to actual data bounds
let vis_start_slot = vis_start_slot.min(total_slots);
let vis_end_slot = vis_end_slot.min(total_slots);
}

8.4.4. Smart Border Drawing

Vertical-only borders with thickness indicating hierarchy:

Border TypeThicknessPurpose
Symbol gap0.5pxVisual separation within slot
Slot boundary1.0pxMajor time unit separation
Subframe gap2.0pxFrame structure boundary

No horizontal borders - visual clarity through vertical separation only.

8.4.5. Auto-Scroll & Focus Highlighting

Recentering the data window (start_slot) on a focused event is not enough: egui::ScrollArea keeps its own independent scroll offset, so the focused slot could still be rendered far outside the visible viewport, and switching ViewMode (Symbol ↔ Slot) changes slot_width drastically, invalidating any previous scroll position.

Fix - explicit scroll request:

#![allow(unused)]
fn main() {
// Set whenever focus changes or the view mode is toggled
self.scroll_pending = true;

// Inside the ScrollArea closure, once per pending request:
if self.scroll_pending {
    if let Some(slot_idx) = focused_global_slot.and_then(|g| g.checked_sub(self.start_slot)) {
        let target_rect = Rect::from_min_size(Pos2::new(slot_x, y_top), Vec2::new(slot_width, y_height));
        ui.scroll_to_rect(target_rect, Some(egui::Align::Center));
        self.scroll_pending = false;
    }
}
}

Ui::scroll_to_rect must be called from within the ScrollArea’s child Ui - it queues an animated scroll to bring the given rect into view regardless of the current offset, which fixes the “wrong X position until manual scroll” issue.

Focus legend: the header (slot/frame label) and PRB label corresponding to the focused event are highlighted with a translucent theme.accent fill + border, so the current position remains identifiable even after scrolling away:

ElementHighlight condition
Slot/Frame headerglobal_slot == focused_global_slot
PRB labelprb within [prb_start, prb_start + prb_length - 1]

8.5. Performance Optimizations

8.5.1. Hot Path Optimizations

OptimizationBeforeAfterImpact
Limit checksPer cell (14×PRBs×slots)Per slot-93% ops
Slot lookups3× per PRB1× cached-85% lookups
Symbol passes3 separate loops1 combined-67% iterations
Coordinate mathPer-cell computationHoisted to loop start-99% redundant math
Tooltip stringsAllocated every frameDeferred to callback-95% idle allocations

Key Techniques:

  1. Hoisted Coordinate Calculations:
#![allow(unused)]
fn main() {
// Before: computed per cell (N × M × 14 times)
let y = content_rect.top() + header_height + (prb as f32 * cell_size);

// After: computed once
let grid_origin_y = content_rect.top() + header_height;
// In loop: just add offset
let y = grid_origin_y + (prb as f32 * cell_size);
}
  1. Early Exit Aggregation:
#![allow(unused)]
fn main() {
// Inlined with early termination
for symb in 0..symbols_per_slot {
    let resource = slot.get(prb, symb);
    if resource.priority() >= 6 {  // PUSCH/PDSCH
        return *resource;  // Early exit, no need to scan remaining
    }
}
}
  1. Deferred Tooltip Allocation:
#![allow(unused)]
fn main() {
// Before: always allocates
response.on_hover_text(format!("Frame {}", frame));

// After: allocates only when shown
response.on_hover_ui(|ui| {
    ui.label(format!("Frame {}", frame)); // Only runs on hover
});
}

8.6. Files

  • tramex/src/panels/resources_blocks.rs - Panel implementation
  • tramex-tools/src/interface/layer.rs - PHY layer visibility (default: on)

8.7. Usage

  1. Load a file with PHY traces (PDSCH, PUSCH, PUCCH, PRACH)
  2. Open Resource Blocks panel from Windows menu
  3. Navigate events - grid auto-centers on focused PHY event
  4. Toggle Symbol/Slot view for detail vs overview
  5. Hover cells for detailed PHY allocation info
  6. Adjust cell size for visibility of dense allocations

9. HARQ Panel - PHY Layer Visualization

Implementation Date

2026-03-12 2026-09-01 - Added filtering by HARQ process and click-to-navigate

9.0. Overview

The HARQ panel provides a chronograph-style visualization of PHY layer events, showing the communication flow between UE (User Equipment) and BST (Base Station). It displays PDCCH grants, PDSCH/PUSCH data transfers, and PUCCH feedback with color-coded HARQ process identification.

9.0.1. Definitions

  • ndi: New Data Indicator, 0 = new data, 1 = redundant transmission
  • retx: Retransmission count, 0 = first transmission, >0 = retransmission
  • rv_idx: Redundancy Version index, 0-3 for different redundancy versions
  • crc: Cyclic Redundancy Check, “OK” or “FAIL” for error detection

9.0.2. Purpose

  • Visualize the HARQ (Hybrid Automatic Repeat Request) process flow
  • Track retransmissions via retx, rv_idx, and crc fields
  • Understand ACK/NACK feedback timing
  • Identify scheduling patterns by HARQ process number

9.0.3. Supported Channels

ChannelDirectionRole in HARQ
PDCCHDLControl channel carrying DCI grants
PDSCHDLDownlink data (carries TB from gNB to UE)
PUSCHULUplink data (carries TB from UE to gNB)
PUCCHULUplink control (ACK/NACK feedback)

9.1. Panel Layout

┌─────────────────────────────────────────────────────────┐
│                    UE              BST                  │
│                    │                │                   │
│  PDCCH dci=1_1     │ ◄──────────────┤  (DL grant)       │
│  PDSCH harq=0      │ ◄──────────────┤  (DL data)        │
│  PUCCH format=1    ├───────────────►│  ACK              │
│  PDCCH dci=0_1     │ ◄──────────────┤  (UL grant)       │
│  PUSCH harq=0      ├───────────────►│  crc=OK           │
│                    │                │                   │
├─────────────────────────────────────────────────────────┤
│  HARQ: [0] [1] [2] ...              (color legend)      │
└─────────────────────────────────────────────────────────┘
  • Vertical lifelines: UE on left, BST on right
  • Arrows: Direction indicates UL (→) or DL (←)
  • Labels: Channel-specific info above each arrow
  • Legend: Shows active HARQ processes with their colors

9.2. Arrow Display

9.2.1. Arrow Labels by Channel

ChannelLabel FormatExample
PDCCHPDCCH dci={format} ndi={} rv_idx={}PDCCH dci=1_1 ndi=1 rv_idx=0
PDSCHPDSCH harq={} retx={} rv_idx={}PDSCH harq=0 retx=0 rv_idx=0
PUSCHPUSCH harq={} retx={} rv_idx={} crc={}PUSCH harq=0 retx=0 rv_idx=0 crc=OK
PUCCHPUCCH format={} {ACK/NACK}PUCCH format=1 ACK

9.2.2. Color Coding

  • HARQ Process Colors : Each Harq gets its own color to help the diferenciation
  • PUCCH: Uses neutral theme color (no HARQ process ID)
  • Focused arrow: Highlighted with semi-transparent background bar
  • Support Theme Colors

9.2.3. Focus & Navigation

  • When an event is focused in the navigation panel the corresponding arrow is highlighted with a colored background
  • Clicking an arrow navigates to its corresponding trace through the shared NAVIGATE_REQUEST_ID mechanism
  • It is possible to click on an arrow to focus on the corresponding event in the navigation panel

9.3. Filtering Logic

The panel automatically filters out non-HARQ events:

Filtered OutReason
harq=siMIB/SIB broadcasts (system info, no HARQ)
PUCCH format!=1CSI (Channel State Info) only, no HARQ feedback
PDCCH without harq_processDCI 1_0 for SIB (no HARQ)
PRACHRandom access, not HARQ

If one harq process has been selected, only the corresponding arrows will appear in the panel.

9.4. PHY Trace Parsing

9.4.1. PHYChannelData Structure

Channel-specific fields are stored in a dedicated enum:

#![allow(unused)]
fn main() {
pub enum PHYChannelData {
    Pdcch { 
        dci: String,                      // "0_1" or "1_1"
        harq_process: Option<u8>, 
        ndi: Option<u8>,                  // New Data Indicator
        rv_idx: Option<u8>,               // Redundancy Version
        harq_feedback_timing: Option<u8>  // DCI 1_1 only
    },
    Pdsch { retx: Option<u8>, rv_idx: Option<u8> },
    Pusch { retx: Option<u8>, rv_idx: Option<u8>, crc: Option<bool>, ack: Option<bool> },
    Pucch { format: Option<u8>, ack: Option<bool> },
    None,
}
}

9.4.2. Multi-Line PDCCH Parsing

PDCCH traces from Amarisoft span multiple lines:

10:32:35.169 [PHY] DL 0001 01 476.19 PDCCH: ss_id=2 cce_index=6 al=2 dci=1_1 k1=4
    harq_process=0
    ndi1=1
    rv_idx1=0
    harq_feedback_timing=1

The parser handles continuation lines with parse_phy_lines().

9.4.3. DCI Format Differences

DCI FormatDirectionSpecific Fields
0_1UL grantNA
0_1UL grant with RNTIndi=, rv_idx=
1_0DL grant with RNTINA
1_1DL grantndi1=, rv_idx1=, harq_feedback_timing=

9.4.4. Format & Inferences from Amarisoft

Because the traces are logged from the BST’s point of view, not all fields in PUSCH/PUCCH traces originate from the UE: Because the traces are logged from the BST’s point of view, not all fields in PUSCH/PUCCH traces originate from the UE:

  • ACK: Sent by the UE to acknowledge a previously received PDSCH.
  • CRC: Computed locally by the BST after decoding the uplink message — it is not transmitted by the UE.

Additionally, an ACK may appear in a PUSCH trace even though it is nominally a data channel. This is called piggybacking: the UE embeds the HARQ feedback in the PUSCH transmission instead of sending a separate PUCCH, reducing latency.

  • ACK: Sent by the UE to acknowledge a previously received PDSCH.
  • CRC: Computed locally by the BST after decoding the uplink message — it is not transmitted by the UE.

Additionally, an ACK may appear in a PUSCH trace even though it is nominally a data channel. This is called piggybacking: the UE embeds the HARQ feedback in the PUSCH transmission instead of sending a separate PUCCH, reducing latency.

9.5. Performance

9.5.1. Arrow Buffer

The panel keeps a sliding buffer of at most MAX_ARROWS arrows for memory efficiency. When the limit is reached, the oldest half is dropped:

#![allow(unused)]
fn main() {
const MAX_ARROWS: usize = 100;

if self.arrows.len() >= MAX_ARROWS {
    self.arrows.drain(0..50);  // Remove oldest 50
}
}

9.5.2. Buffer Regeneration on Navigation

Because arrows outside the buffer are discarded, navigating back to an older event would otherwise show nothing. on_event_focused therefore rebuilds the window on demand:

  • buffered_range() returns the (min, max) trace index currently held in arrows.
  • If the focused index is before that range, the arrows were dropped → rebuild.
  • If it is after the range, a rebuild happens only when a PHY arrow actually exists in between (avoids useless rebuilds while stepping through non-PHY traces).
  • rebuild_window(all_events, index) walks backwards from the focused event until MAX_ARROWS / 2 arrows are collected, then forwards up to MAX_ARROWS, recomputes the HFNs sequentially (anti-wrap state is reset first) and re-sorts by (hfn, frame, slot).

9.5.3. Event System Integration

The panel implements EventSubscriber:

  • on_event_added: Creates arrow if PHY event matches criteria
  • on_event_focused: Updates highlight, triggers auto-scroll, and rebuilds the arrow buffer if the focused event lies outside it
  • on_events_cleared: Clears all arrows and resets the HFN tracking state

9.7. Files

  • tramex/src/panels/harq_panel.rs — Panel implementation
  • tramex-tools/src/interface/parser/parser_phy.rs — PHY parsing with PHYChannelData

9.8. Usage

  1. Load a file containing PHY layer traces
  2. Open HARQ panel from Windows menu
  3. Navigate through events — panel auto-scrolls to focused PHY event
  4. Identify HARQ processes by color
  5. Track retransmissions by watching retx, rv_idx changes
  6. Monitor ACK/NACK feedback in PUCCH/PUSCH arrows

10. AI Explain Feature

Implementation Date

2026-03-20

10.0. Overview

10.0.1. Problem Solved

  • Understanding complex 4G/5G protocol traces requires deep domain knowledge
  • Users need quick explanations of what each trace represents without consulting external documentation
  • No built-in assistance for interpreting RRC, NAS, NGAP, and other protocol layers

10.0.2. Solution: AI-Powered Trace Explanation

Integrated an AI chatbot feature that sends trace context to Mistral AI (with extensible connector architecture) and displays a concise explanation directly in the Messages panel.

10.0.3. Benefits

  • Instant context: Get human-readable explanations of any trace with one click
  • Educational: Learn protocol behavior as you analyze traces
  • Extensible: Connector trait supports multiple AI providers
  • Secure: API key loaded from environment or settings, never committed to git

10.1. Architecture

10.1.1. AI Connector System (tramex-tools crate)

Trait-based design for multiple providers:

#![allow(unused)]
fn main() {
pub trait AIConnector: Send {
    fn build_request(&self, trace: &Trace, api_key: &str) -> Result<AIRequest, TramexError>;
    fn parse_response(&self, response_body: &str) -> Result<String, TramexError>;
}
}

AIProvider enum with factory function:

#![allow(unused)]
fn main() {
pub enum AIProvider {
    Mistral,
    // Future: OpenAI, Anthropic, etc.
}

pub fn create_connector(provider: &AIProvider) -> Box<dyn AIConnector> {
    match provider {
        AIProvider::Mistral => Box::new(MistralConnector::default()),
    }
}
}

10.1.2. Request/Response Flow

User clicks "AI Explain"
    ↓
MessageBox.request_ai_explain()
    ↓
MistralConnector.build_request(trace, api_key)
    ↓
ehttp::fetch() async request
    ↓
poll_promise::Promise polls for response
    ↓
MistralConnector.parse_response()
    ↓
AIExplainStatus::Done(explanation)
    ↓
UI displays explanation in scrollable text area

10.1.3. Prompt Engineering

System prompt (Mistral mistral-medium-latest):

  • Concise telecom expert persona
  • Structured context format with layer, timestamp, direction, channel, and raw text
  • Bullet-point output format
  • Key fields identification
  • Brief 5-7 sentence summary

Request structure:

#![allow(unused)]
fn main() {
AIRequest {
    url: "https://api.mistral.ai/v1/chat/completions",
    headers: {"Authorization": "Bearer {api_key}"},
    body: JSON with system prompt + user context,
}
}

10.2. UI Integration

10.2.1. Settings Menu

New Settings menu added to top bar (next to Menu, Windows, About):

┌─────────────────────────────────────────┐
│ Menu │ Windows │ Settings │ About      │
└─────────────────────────────────────────┘
              ↓
        ┌──────────────────┐
        │ AI Configuration │
        └──────────────────┘
              ↓
        ┌─────────────────────────────┐
        │  AI Configuration             │
        │  ─────────────────────────    │
        │  Provider: [Mistral ▼]        │
        │                               │
        │  API Key: [sk-xxxxxxxxxxxx]   │
        │                               │
        │  [Clear]         [Save]       │
        │                               │
        │  Loaded from env: Yes/No      │
        └─────────────────────────────┘

10.2.2. Messages Panel Integration

AI explain button appears below “Show full message”:

┌─────────────────────────────────────────┐
│ Layer: RRC                              │
│ AdditionalInfos(...)                    │
│ [ ] Show full message                   │
│ ─────────────────────────────────────   │
│ 🤖 AI Explain           ✓              │  ← AI section
└─────────────────────────────────────────┘
              ↓ (after clicking)
┌─────────────────────────────────────────┐
│ 🤖 AI Explain          ✓               │
│ ─────────────────────────────────────   │
│ • Message Type: RRCConnectionRequest      │
│ • Direction: Uplink (UE → eNB)          │
│ • Purpose: UE initiates connection      │
│ • Key Fields: initial UE identity,      │
│   establishment cause                   │
│ • Summary: This is the first message    │
│   the UE sends when trying to connect   │
└─────────────────────────────────────────┘

10.2.3. State Management

AIExplainStatus enum:

#![allow(unused)]
fn main() {
pub enum AIExplainStatus {
    Idle,           // No request made yet
    Loading,        // Request in flight (spinner shown)
    Done(String),   // Successful explanation
    Error(String),  // HTTP or parsing error
}
}

State transitions:

  • Idle → Loading: User clicks button
  • Loading → Done: Response received successfully
  • Loading → Error: HTTP error or invalid response
  • Done/Error → Idle: User navigates to different trace

10.3. Configuration

10.3.1. Environment Variable

Set TRAMEX_AI_API_KEY before running:

export TRAMEX_AI_API_KEY="sk-xxxxxxxxxxxxxxxx"
cargo run

Or in .env file (gitignored):

TRAMEX_AI_API_KEY=sk-xxxxxxxxxxxxxxxx

10.3.2. Runtime Configuration

Settings are passed from TramexApp → FrontEnd → Application → EventBus → all panels:

#![allow(unused)]
fn main() {
// In TramexApp::update()
self.frontend.set_ai_config(&self.ai_settings.api_key, &self.ai_settings.provider);

// EventSubscriber trait method
fn set_ai_config(&mut self, key: &str, provider: &AIProvider) {
    self.ai_api_key = key.to_string();
    self.ai_provider = provider.clone();
}
}

10.4. Feature Flag

The AI feature is enabled by default via default = ["websocket", "ai"] in tramex/Cargo.toml.

To build without AI:

cargo build --no-default-features --features websocket

10.5. Files Modified

New Files:

  • tramex-tools/src/ai/mod.rs — AIConnector trait, types, factory
  • tramex-tools/src/ai/mistral.rs — MistralConnector implementation
  • tramex/src/ai_settings.rs — AISettings with UI and env loading

Modified Files:

  • tramex-tools/Cargo.toml — Added ai feature
  • tramex-tools/src/lib.rs — Registered ai module
  • tramex/Cargo.toml — Added ai to default features, poll-promise dependency
  • tramex/src/lib.rs — Registered ai_settings module
  • tramex/src/app.rs — Settings menu, AI config window, config forwarding
  • tramex/src/frontend.rs — set_ai_config() forwarding
  • tramex/src/event_system/event_bus.rs — set_ai_config trait method + forwarding
  • tramex/src/event_system/application.rs — set_ai_config() forwarding
  • tramex/src/panels/panel_message.rs — AI button, async request, response display
  • .gitignore — Added .env

10.6. Future Enhancements

  1. Multiple providers: OpenAI GPT-4, Anthropic Claude, local LLMs via Ollama
  2. Context history: Include previous traces in prompt for richer explanations
  3. Custom prompts: User-defined system prompts for specific use cases
  4. Caching: Store explanations to avoid duplicate API calls
  5. Offline mode: Pre-trained model on-device for disconnected operation
  6. Multi-language: Translated explanations for international users

11. Power Panel

11.1. Motivation

The gNB PHY layer reports several uplink measurements on PUSCH and PUCCH traces that are useful for diagnosing radio conditions:

  • EPRE (Energy Per Resource Element): received signal power in dB
  • TA (Timing Advance): propagation delay compensation in µs
  • CSI (Channel State Information): feedback from the UE encoded in binary

These values were present in the log but not extracted by the parser or visualized. The Power panel fills this gap by plotting them over time (SFN) so that trends and anomalies are easy to spot.

11.2. Parser Changes

The PHY parser (tramex-tools/src/interface/parser/parser_phy.rs) was extended:

  1. New struct UlMeasurements with optional epre: f32, ta: f32, csi: u32 fields.
  2. PHYChannelData::Pusch and PHYChannelData::Pucch now include a measurements: UlMeasurements field.
  3. parse_ul_measurements() helper extracts epre=, ta= and csi= from the trace line. csi is decoded from binary at parse time (0101 → 5).
  4. Tests updated and a new test added for the sample line epre=-45.4 ta=0.1 csi=0101.

11.3. Panel Implementation

tramex/src/panels/power_panel.rs implements the EventSubscriber trait:

CallbackBehavior
on_event_addedIf the trace is PUSCH/PUCCH with at least one measurement, cache it with computed HFN
on_event_focusedCenter the X window on the focused event (or nearest sample for non-PHY events)
on_events_clearedClear the sample cache and reset state

Rendering:

  • Three stacked graphs (EPRE, TA, CSI) drawn with the egui painter (no external plot crate).
  • Y axis auto-scales to visible data with a minimum span to avoid noise zoom.
  • X axis shows frame numbers at frame boundaries; HFN boundaries are drawn with a stronger line.
  • Points colored by channel type (PUSCH cyan, PUCCH green), reusing ResourceType colors.
  • Focused point highlighted with an accent ring; vertical marker across all graphs.
  • Hover tooltip shows all measurements plus raw CSI bits; click navigates via NAVIGATE_REQUEST_ID.

HFN handling reuses the same anti-wrap logic as the HARQ panel: if a new event’s frame is more than 512 frames behind the current end, it is assigned to the previous HFN; if it jumps forward by more than 512, the HFN is incremented.

11.4. Files Changed

New Files:

  • tramex/src/panels/power_panel.rs — Panel implementation

Modified Files:

  • tramex-tools/src/interface/parser/parser_phy.rs — UlMeasurements, measurements field, parse_ul_measurements()
  • tramex/src/panels/mod.rs — Registered power_panel module
  • tramex/src/panels/harq_panel.rs — Adjusted match arms for new measurements field
  • tramex/src/event_system/integration.rs — Subscribed PowerPanel

12. Chronograph MAC-RLC-PDCP Panel

Implementation

Implementation : 09/09/2026, commit 9ed6dc867c34adc032226cda61e30c702aaf4a42

12.1. Overview

The MAC-RLC-PDCP chronograph reuses the design principles of the Chronograph RAN panel: chronological arrows, focused and related-event highlighting, bounded history, automatic centering, and event-driven updates. Refer to 7.5. Chronograph Integration and the Chronograph RAN implementation for those shared principles.

The panel specializes that model for the radio protocol stack:

  • It has two lifelines, UE and BST, with no Core Network lifeline.
  • It accepts only MAC, RLC, and PDCP traces.
  • UL messages flow from UE to BST and DL messages flow from BST to UE.
  • Labels preserve the layer and full first-line log message; the hover tooltip exposes the full value when the rendered label is truncated.
  • Clicking an arrow sends its trace index through NAVIGATE_REQUEST_ID.

12.2. Shared Click-to-Navigate Contract

Interactive event visualizations do not navigate the event store directly. Chronograph RAN, Chronograph MAC-RLC-PDCP, HARQ, and Power publish a trace index into temporary egui memory using NAVIGATE_REQUEST_ID. After drawing panel windows, FrontEnd consumes that request and calls Application::navigate_to, ensuring every subscriber receives the normal focused-event notification.

12.3. Buffer Management (HARQ-style)

Both chronographs reuse the HARQ buffer model so that navigating backwards still works:

  • buffered_range() returns the trace-index span of the kept arrows.
  • On on_event_added, when the buffer reaches max_arrows the oldest half is drained instead of a single arrow.
  • On on_event_focused, a rebuild is triggered when the focused index is below the buffer (dropped arrows), above it with missing arrows in between, or when the buffer is empty. rebuild_window walks backwards from the focused event until half the buffer is filled, then forwards until it is full — recentered on the focus.
  • set_parameters applies the configurable limit (chronograph_max_arrows / chronograph_mac_max_arrows, Settings → Panels).

12.4. Layer Filters

Each chronograph keeps a layer_filter: Option<BTreeSet<String>> (None = all supported layers, persisted). A checkbox row above the timeline toggles each layer (RRC/NAS/NGAP/GTPU for RAN, MAC/RLC/PDCP for MAC). The filter applies to rendering, hover/click and auto-scroll positioning, but not to the underlying buffer — unchecking then rechecking a layer restores its arrows instantly.

12.5. Bearer Column (MAC-RLC-PDCP only)

The window is split with egui::Panel::right(...).show_inside (bearer column, resizable) + CentralPanel::default().show_inside (timeline) so the timeline keeps the full height. The right column reuses the make_label style of the Bearer Status panel and lists the channels used by the focused arrow:

  • RLC / PDCP: the SRBx/DRBx token is read directly from the first text line.
  • MAC: each LCID:N token is mapped — 1→SRB0, 2→SRB1, 3→SRB2, 4→SRB3, 5→DRB1, 6→DRB2, 7→DRB3 (0 ignored) — and deduplicated, so a multi-SDU MAC trace lights several channels at once.

Hover/click detection uses response.hover_pos() (layer-aware) so tooltips and clicks never trigger while the pointer is outside the panel or above a covering window.


13. GTPU Tunnel Panel

Implementation

Implementation : 23/10/2026

13.1. Motivation

GTPU traces carry the user-plane tunnel parameters between the base station and the core network, but the parser only extracted the direction, the GTP-U peer and the message type. The TEID, the QFI and the encapsulated flow were only visible in the raw text. The GTPU Tunnel panel extracts and displays them for each direction of the tunnel.

Example trace:

13:20:45.574 [GTPU] TO 127.0.1.100:2152 G-PDU TEID=0x5315caa3 QFI=1 SDU_len=1452: IP/TCP 192.168.3.2:51158 > 172.217.18.202:443

13.2. Parser Changes

The GTPU parser (tramex-tools/src/interface/parser/parser_gtpu.rs) was extended:

  1. GTPUInfos gained the optional fields teid: u32, qfi: u8, sdu_len: u32, src_addr and dst_addr, and now derives Default.
  2. parse_payload() is shared by the file path (FileParser::parse_additional_infos) and the WebSocket path (LayerParser::parse_layer). It splits the payload on the first ": ":
    • the GTPU header (G-PDU TEID=0x... QFI=... SDU_len=...) gives the message type and the KEY=VALUE fields (TEID is decoded from hexadecimal);
    • the encapsulated part (IP/TCP src > dst) gives the source/destination addresses. IPv6 addresses and addresses without port (ICMP) are kept as-is.
  3. Helpers remote_addr() and ue_addr() resolve the sides of the inner flow from the direction: for TO (uplink) the remote endpoint is the destination, for FROM (downlink) it is the source.
  4. Tests cover the uplink IPv4/TCP sample, a downlink IPv6/ICMPv6 sample, the WebSocket parse_layer path and a message without encapsulated payload.

13.3. Panel Implementation

tramex/src/panels/gtpu_tunnel.rs implements the EventSubscriber trait and belongs to the NAS panel group (GTPU is already among the layers enabled by this group).

CallbackBehavior
on_event_addedFor GTPU traces, update the arrow keyed by (direction, TEID), or insert a new one if the TEID is unknown
on_event_focusedSame update, then mark the trace’s tunnel as current
on_events_clearedReset the panel state

Tunnel model:

  • Arrows are stored in tunnels: Vec<TunnelArrow>, one per TunnelKey = (uplink, TEID), so a new tunnel adds an arrow instead of replacing the previous one.
  • Each arrow keeps first_index (used to order arrows by first appearance, stable when events are re-added after a filter change) and last_index with the infos of the latest message (QFI shown, click target).

Rendering:

  • Two lifelines: BST on the left and UPF on the right, with the GTP-U peer (connection_info) under the UPF label, taken from the focused tunnel or the most recent one.
  • One row per tunnel arrow: UL (BST → UPF) or DL (UPF → BST), labeled with its TEID and QFI. The diagram height grows with the number of tunnels inside a vertical scroll area.
  • The arrow of the focused tunnel uses ArrowColors::CURRENT; clicking an arrow navigates to its latest trace through NAVIGATE_REQUEST_ID.

13.4. Files Changed

New Files:

  • tramex/src/panels/gtpu_tunnel.rs — Panel implementation

Modified Files:

  • tramex-tools/src/interface/parser/parser_gtpu.rs — New GTPUInfos fields, parse_payload(), remote_addr() / ue_addr(), tests
  • tramex/src/panels/mod.rs — Registered gtpu_tunnel module
  • tramex/src/event_system/integration.rs — Subscribed GtpuTunnel

14. Bearer Status Panel

Implementation

Implementation : 23/10/2026

14.1. Overview

The Bearer Status panel (tramex/src/panels/bearer_status.rs, RRC group) shows the signaling (SRB) and traffic (DRB) radio bearers of the BST as two state machines. It follows the design of the RRC Status panel:

  • process_event advances a build state (build_srb, build_drb) on each added event and appends a StateChange { index, srb, drb } to state_history when a message affects the bearers.
  • refresh_display is the single writer of the displayed state: it binary-searches state_history for the last change at or before the focused index, so navigating backward restores the right state.
  • The BASE STATION / USER EQUIPMENT arrows light up only when the focused message is itself a state change.

14.2. Transitions

Transitions are declared in the TRANSITIONS table (BearerTransition { messages, list, identity_field, identity, target }). A transition applies when the RRC message matches and the ASN.1 block list { ... } of the trace text contains identity_field N:

MessagePathTarget
RRC setupradioBearerConfig > srb-ToAddModList > srb-Identity 1SRB1
RRC reconfigurationradioBearerConfig > srb-ToAddModList > srb-Identity 2SRB2
RRC reconfigurationradioBearerConfig > drb-ToAddModList > drb-Identity 1DRB1
  • RRC setup / RRC connection setup reset both bearers before applying the table (a new connection only has SRB1).
  • RRC release / RRC connection release reset both bearers.
  • identities_in_list tracks the brace depth of the list block and only accepts field N (not field: N), so servedRadioBearer srb-Identity: 1 in the cell group config is ignored.
  • SRB3, DRB2 and DRB3 have no transition yet (no sample message): placeholders with the expected format are left as TODO comments in TRANSITIONS.

14.3. Files Changed

New Files:

  • tramex/src/panels/bearer_status.rs — Panel implementation and tests

Modified Files:

  • tramex/src/panels/mod.rs — Registered bearer_status module
  • tramex/src/event_system/integration.rs — Subscribed BearerStatusPanel

Architecture

ASN.1

ASN.1 (Abstract Syntax Notation One) is a standard interface description language used for defining data structures that can be serialized and deserialized in a cross-platform way. It is used in telecommunications, cryptography, and other fields.

Download ASN.1 from 3gpp docx

Another solution is to access through the ftp server:

Convert docx to asn1

If the document from 3gpp has asn1 inside, it can be extracted with the following command (using the tool docx-asn1):

# download docx from 3gpp

# install python package docx_asn1
python -m pip install docx_asn1

# use docx_asn1 to convert docx to asn1
python -m docx_asn1 file.docx > output.asn1

# the converted asn1 file is then called output.asn1 and can be found in the current directory

asn1c

For raw decoding, the tool asn1c (https://github.com/vlm/asn1c) can be used to generate C code from the ASN.1 file. The generated code can be used to decode the messages.

types_lte_3gpp

The crate types_lte_3gpp (https://github.com/tramex/types_lte_3gpp/) is used to automatically generate Rust code from ASN.1 files (extracted automatically from docx files created by 3gpp). It is used in the Tramex project to generate the code for the LTE protocol.

Amarisoft Resources

Amarisoft File Log Format

From the amarisoft documentation: https://https://tech-academy.amarisoft.com/

LTE Software eNodeB and NR Software gNB

PHY

Format

time layer dir ue_id cell rnti frame.subframe channel:short_content long_content

Doc

time Time using the selected format.

layer Layer ([PHY] here).

dir UL (uplink) or DL (downlink).

ue_id eNodeB UE identifier (hexadecimal, unique among all cells).

cell Low 8 bits of the cell identifier (hexadecimal).

rnti Associated RNTI (hexadecimal) or - if none.

frame.subframe Frame number (0-1023) and either subframe number (0-9) for LTE and NB-IoT cells or slot number for NR cells.

channel PHY channel name (e.g. PUSCH, PUCCH, PRACH, SRS, PSS, PBCH, PCFICH, PDSCH, PHICH, PDCCH, EPDCCH, …).

short_content Single line content.

long_content Hexadecimal dump of the message if phy.max_size > 0.

RLC PDCP NAS

Format

When a message is dumped, the format is:

time layer - ue_id message

When a PDU is dumped (debug level), the format is:

time layer dir ue_id short_content long_content

Doc

time Time using the selected format

layer Layer ([RLC], [PDCP], or [NAS] here).

dir UL (uplink) or DL (downlink).

ue_id eNodeB UE identifier (hexadecimal, unique among all cells).

short_content Single line content.

RLC, PDCP: preceded by the SRB or DRB identifier. long_content NAS: full content of the NAS message if layer.max_size > 0.

MAC RRC

Format

When a message is dumped, the format is:

time layer - ue_id message When a PDU is dumped (debug level), the format is:

time layer dir ue_id short_content long_content

Doc

time Time using the selected format

layer Layer ([MAC] or [RRC] here).

dir UL (uplink) or DL (downlink).

ue_id eNodeB UE identifier (hexadecimal, unique among all cells).

cell_id Primary cell identifier. See cell_id

short_content Single line content.

long_content MAC: hexadecimal dump of the message if layer.max_size > 0. RRC: full ASN.1 content of the RRC message if layer.max_size > 0. long_content MAC, RLC, PDCP: hexadecimal dump of the message if layer.max_size > 0. RRC: full ASN.1 content of the RRC message if layer.max_size > 0.

S1AP NGAP X2AP XnAP M2AP GTP-U

Format

When a message is dumped, the format is:

time layer - message When a PDU is dumped (debug level), the format is:

time layer dir ip_address short_content long_content

Doc

time Time using the selected format.

layer Layer (e.g. [S1AP]).

dir Direction: TO or FROM.

ip_address Source or destination IP address, depending on the dir field.

short_content Single line content.

long_content S1AP, NGAP, X2AP, XnAP, M2AP: full ASN.1 content of the message if layer.max_size > 0. GTPU: hexadecimal dump of the message if layer.max_size > 0.

LTE and NR Core Network

NAS

Format

When a NAS message is dumped, the format is:

time layer - message When a NAS data PDU is dumped (debug level), the format is:

time layer dir MME_UE_ID message_type long_content

Doc

time Time using the selected format

layer Indicate the layer ([NAS] here).

dir UL (uplink) or DL (downlink).

MME_UE_ID MME S1AP UE identifier (hexadecimal).

message_type NAS message type.

long_content Full content of the NAS message if nas.max_size > 0.

IP

Format

When a IP data PDU is dumped (debug level), the format is:

time layer dir short_content long_content

Doc

time Time using the selected format

layer Indicate the layer ([IP] here).

dir UL (uplink) or DL (downlink).

short_content Single line content (at least the IP protocol and the source and destination address).

long_content Optional hexadecimal dump of the PDU if ip.max_size > 0.

S1AP NGAP SBcAP LCSAP GTP-U

Format

When a message is dumped, the format is:

time layer - message When a data PDU is dumped (debug level), the format is:

time layer dir ip_address short_content long_content

Doc

time Time using the selected format.

layer Indicate the layer ([S1AP], [NGAP], [SBCAP], [LCSAP], or [GTPU] here).

dir Direction: TO or FROM.

ip_address source or destination IP address, depending on the dir field.

short_content Single line content.

long_content S1AP, NGAP, SBCAP, LCSAP: full ASN.1 content of the message if layer.max_size > 0. GTPU: hexadecimal dump of the message if layer.max_size > 0.

LTE IMS Server

IMS SIP

Format

time layer dir id message

Doc

time Time using the selected format.

layer Indicate the layer.

dir FROM or TO or - (No direction associated).

id For IMS, represents a unique ID associated with a UE binding. For SIP, represents a unique ID associated to a SIP dialog.

message Log message.

CX RX

Format

time layer dir addr message

Doc

time Time using the selected format.

layer Indicate the layer.

dir FROM or TO or - (No direction associated).

addr Source IP address for incoming messages. Destination IP address for outgoing messages. message Log message.

MEDIA

Format

time layer id dir protocol/media message

Doc

time Time using the selected format.

layer Indicate the layer.

dir FROM or TO or - (No direction associated).

id SIP associated dialog id.

protocol Can be either RTP or RTCP.

media Media type: audio, video or text.

message Log message.

Contributors