Team-1G: SmartFactory 5G Slicing Control Center

A reproducible 5G Standalone (SA) smart-factory network slicing lab built with Open5GS, UERANSIM, Docker Compose, and a custom web dashboard for control, observability, transport policy, and automated validation.

This project is designed to make 5G slicing visible, measurable, and explainable. It provides a local environment where multiple slices run simultaneously, each with distinct user-plane behavior, QoS shaping, subscriber mappings, and test thresholds.

1. Project Summary
2. Smart Factory Use Cases and Why 5G Fits
3. System Architecture
4. Key Features
5. Repository Structure
6. Prerequisites
7. Quick Start
8. Running the Dashboard
9. How the Demo Works End to End
10. Configuration and Data Model
11. UI Dashboard Guide
12. Automated Test and Validation Pipeline
13. API Overview
14. Metrics and Report Outputs
15. Troubleshooting
16. Final Deliverables
17. Acknowledgements
18. Glossary
19. Authors

1. Project Summary

This repository implements a smart-factory-oriented 5G SA slicing demo with the following capabilities:

Multi-slice topology with dedicated SMF and UPF instances per slice.
UERANSIM gNB and multiple UEs mapped to slices.
Per-slice QoS shaping using tc inside UPF containers.
Per-slice transport filtering using iptables inside UPF containers.
Subscriber provisioning workflows through open5gs-dbctl and MongoDB.
Live dashboard with topology, status, metrics, logs, transport controls, and configuration editors.
Automated ping and iPerf based validation with test history and generated HTML reports.

Primary runtime scenario for the dashboard:

compose-files/network-slicing/docker-compose.yaml

2. Smart Factory Use Cases and Why 5G Fits

2.1 Smart factory problem context

A smart factory typically carries multiple traffic classes over the same physical infrastructure. Those traffic classes have conflicting requirements:

Robot control traffic needs low latency and predictable behavior.
Vision inspection and AR/video traffic need sustained throughput.
Large fleets of sensors produce many low-bandwidth flows that can tolerate delay.
Enterprise and engineering traffic needs reliable connectivity but should not disturb critical control traffic.
Experimental workloads need a safe space to test policy changes.

A single best-effort network profile is usually a poor fit for all of these at the same time.

2.2 Why 5G network slicing aligns with smart factory needs

5G slicing is a strong fit because it allows one shared infrastructure to host multiple logical service profiles with independent policy and traffic treatment.

This project demonstrates that alignment by mapping each slice to a factory-like service class:

Slice	Category	Example smart-factory role	Why it fits 5G slicing
Slice A	eMBB	Video inspection, AR guidance, high-volume telemetry dashboards	High throughput focus with lower added latency and higher bandwidth caps
Slice B	URLLC	Robot coordination, safety interlocks, control signaling	Lower latency targets and tighter QoS settings
Slice C	mMTC	Dense sensors, meters, machine state reporting	Lower throughput expectations and higher latency tolerance
Slice D	Enterprise	Engineering workstations, HMIs, admin services	Balanced performance with moderate latency and throughput
Slice E	Experimental	Testing new QoS/transport policies	Safe sandbox for tuning and demonstrating policy impact

2.3 Smart-factory use case presets in the dashboard

The dashboard includes named presets in dashboard/data/use-cases.json that apply slice-wide QoS values and validation thresholds:

2.3.1 Factory Balanced

Objective: Balanced throughput and latency across all factory zones with clear differentiation between slices.
Slice configuration: 5 slices (eMBB, URLLC, mMTC, Enterprise, Experimental) mapped to dedicated SMF/UPF pairs.
QoS setup:
- Slice A: 120 Mbps, +0 ms
- Slice B: 60 Mbps, +10 ms
- Slice C: 20 Mbps, +40 ms
- Slice D: 80 Mbps, +15 ms
- Slice E: 30 Mbps, +25 ms
Expected behavior: eMBB throughput dominates; URLLC remains low latency; mMTC tolerates higher latency.
Automated verification:
- UEs attached and PDU sessions established
- Subnet correctness per slice
- Latency, loss, throughput within thresholds
- QoS enforcement vs max rate
Expected KPIs: Latency and throughput thresholds defined in use-cases.json per slice.

2.3.2 Mission Critical

Objective: Prioritize URLLC and Enterprise slices with strict latency targets.
Slice configuration: Same mapping, but with tighter URLLC/Enterprise thresholds.
QoS setup:
- Slice A: 150 Mbps, +0 ms
- Slice B: 80 Mbps, +5 ms
- Slice C: 15 Mbps, +60 ms
- Slice D: 100 Mbps, +8 ms
- Slice E: 25 Mbps, +30 ms
Expected behavior: URLLC and Enterprise achieve lower latency; mMTC is de-prioritized.
Automated verification: Same checks as Factory Balanced, evaluated with stricter thresholds.
Expected KPIs: Lower latency targets for Slice B and Slice D.

2.3.3 IoT Flood

Objective: mMTC-heavy traffic with tolerance for higher latency while protecting eMBB throughput.
Slice configuration: Same mapping, with QoS emphasizing Slice A throughput.
QoS setup:
- Slice A: 140 Mbps, +0 ms
- Slice B: 50 Mbps, +15 ms
- Slice C: 25 Mbps, +80 ms
- Slice D: 70 Mbps, +20 ms
- Slice E: 35 Mbps, +35 ms
Expected behavior: High tolerance on Slice C, stable throughput for Slice A.
Automated verification: Same checks as Factory Balanced, evaluated with IoT-focused thresholds.
Expected KPIs: Higher acceptable latency for Slice C, preserved throughput for Slice A.

These presets help answer practical questions such as:

What happens if the factory shifts from balanced operation to a control-priority mode?
Can the current slice QoS still satisfy latency and throughput thresholds?
Which slices degrade first under stricter policies?

3. System Architecture

3.1 High level architecture

This project combines four layers:

5G Core and RAN simulation (Open5GS + UERANSIM)
Container orchestration and networking (Docker Compose)
Control and automation (Python backend + Bash scripts)
Visualization and operations UI (SPA dashboard)

High-level traffic path:

UE containers -> gNB (UERANSIM) -> Open5GS Core (AMF/SMF/UPF...) -> Data plane / transport path

System Architecture Overview

3.2 Control plane in this project

There is no separate external SDN controller in this implementation.

Instead, the dashboard backend acts as the control plane by:

Orchestrating Docker Compose services
Rewriting Open5GS and UERANSIM YAML configs
Applying tc QoS inside UPF containers
Applying iptables transport rules inside UPF containers
Running test scripts and evaluating results

3.3 Runtime components

The table below describes the role of each runtime component. For the corresponding on-disk directory layout, see Section 5 (Repository Structure).

Component	Implementation	Role
5G Core	Open5GS containers	Core network functions (AMF, SMF, UPF, NRF, NSSF)
RAN/UE simulation	UERANSIM containers	gNB and UE behavior
Dashboard backend	`dashboard/server.py`	API server, SSE snapshots, orchestration, config application
Test engine	`dashboard/backend/test_engine.py`	Test run orchestration, evaluation, report generation
Frontend UI	`dashboard/index.html`, `dashboard/app.js`, `dashboard/styles.css`	Control center and visualization
Metrics collection	`scripts/collect-metrics.sh`, `scripts/run-iperf.sh`	Ping and iPerf automation
Persistence	JSON files under `dashboard/data` and metrics under `metrics/`	UI config/state and test artifacts

3.4 Data and Control Flow

The system handles two distinct types of flows:

Control Plane Flow: User → Dashboard → API → Backend → Docker → Config/QoS/Testing
Data Plane Flow: UE → gNB → 5G Core → UPF (QoS) → Network

System Data & Control Flow Diagram

3.5 Live update model

The backend builds a periodic snapshot that includes:

Stack status
Topology
Slices
Parsed metrics
UE states
Test history revision metadata

This snapshot is streamed to the UI using Server-Sent Events (SSE) at /api/stream, with a polling fallback in the frontend if SSE becomes unhealthy.

4. Key Features

Slice-aware topology and service monitoring
Live UE attach/PDU/IP status
Slice configuration editor (IDs, QoS, mapping, UE assignments)
Subscriber provisioning and subscriber profile templates
PLMN / S-NSSAI profile application across configs
Transport controls (tc + iptables) per slice
Automated validation (ping + iPerf + threshold checks)
Historical test runs and generated HTML reports
Dashboard-driven demo initialization and shutdown

5. Repository Structure

The directories below map directly to the runtime components listed in Section 3.3 (Runtime Components).

.
├── build-files/
│   └── images/
│       ├── amf-open5gs/
│       ├── ausf-open5gs/
│       ├── base-open5gs/
│       ├── base-ueransim/
│       ├── bsf-open5gs/
│       ├── gnb-ueransim/
│       ├── mongodb/
│       ├── nrf-open5gs/
│       ├── nssf-open5gs/
│       ├── packetrusher/
│       ├── pcf-open5gs/
│       ├── scp-open5gs/
│       ├── sepp-open5gs/
│       ├── smf-open5gs/
│       ├── udm-open5gs/
│       ├── udr-open5gs/
│       ├── ue-ueransim/
│       ├── upf-open5gs/
│       └── webui-open5gs/
├── compose-files/
│   ├── basic/
│   │   ├── packetrusher/
│   │   └── ueransim/
│   ├── network-slicing/        # Primary runtime scenario
│   ├── roaming/
│   ├── scp/
│   │   ├── model-c/
│   │   └── model-d/
│   └── speed-test/
├── configs/
│   ├── basic/
│   │   ├── packetrusher/
│   │   └── ueransim/
│   ├── network-slicing/        # Open5GS + UERANSIM YAML configs
│   ├── roaming/
│   ├── scp/
│   │   ├── model-c/
│   │   └── model-d/
│   └── speed-test/
├── dashboard/
│   ├── backend/                # test_engine.py and orchestration helpers
│   └── data/                   # Persistent JSON state (slices, subscribers, profiles, history)
├── docs/
│   ├── diagrams/
│   ├── images/
│   └── team-1g/
│       ├── research-papers/
│       ├── terminal-screenschots/
│       ├── wireshark-captures/
│       └── wireshark-screenshots/
├── explain/
├── metrics/
│   └── runs/                   # Per-run test artifacts (CSV, JSON, HTML reports)
└── scripts/                    # Bash automation (start-demo, collect-metrics, run-iperf)

6. Prerequisites

6.1 Host environment

Requirement	Minimum / Tested version	Notes
OS	Ubuntu 24.04 LTS (Noble Numbat)	Kernel must support `tc`, `netem`, and `iptables`
Docker Engine	Latest stable	User must have permission to run Docker commands
Docker Compose	v2 (`docker compose` subcommand)	The `docker-compose` v1 standalone binary is not supported
Python	3.x	Required to run `dashboard/server.py`
Bash	Any modern version	Required for all scripts under `scripts/`

6.2 Component versions

These versions are defined in build-files/open5gs.env and are used when building or pulling images:

Component	Version
Open5GS	v2.7.6
UERANSIM	v3.2.7
MongoDB	6.0
Node.js	20
Ubuntu (base image)	jammy (22.04)
PacketRusher	main
PacketRusher Go	1.21.3
PacketRusher Ubuntu	focal (20.04)

6.3 Notes

The dashboard backend serves the frontend and API together. Do not open dashboard/index.html via file://.
tc and iptables commands are executed inside UPF containers, so no additional host-level kernel modules need to be manually loaded beyond what Docker provides.

7. Quick Start

7.1 Host IP configuration note

In the default Docker Compose setup in this repo, it's not needed to manually put personal machine IP into the configs because the containers use Docker network aliases such as gnb.ueransim.org and amf.open5gs.org.

If UERANSIM is run with custom networking (or without the provided Docker aliases), the place where the machine/reachable IP must be set is:

configs/network-slicing/gnb.yaml
- linkIp
- ngapIp
- gtpIp

And if the UE cannot resolve gnb.ueransim.org, update the gNB target in:

configs/network-slicing/ue*.yaml
- gnbSearchList (replace gnb.ueransim.org with the reachable gNB IP/hostname)

If only the dashboard is accessed from another device on LAN, no config file change is needed; just open:

http://<your-machine-ip>:8088

7.2 Start the slicing stack and seed subscribers

./scripts/start-demo.sh

This script bootstraps the full stack — starting services, seeding subscribers, and verifying UE tunnel assignment. For a detailed description of what each stage does and how the dashboard interacts with the result, see Section 9 (How the Demo Works End to End).

7.3 Run the dashboard backend

python3 dashboard/server.py

Expected output:

The server prints the URL (default http://localhost:8088)
If port 8088 is busy and DASHBOARD_PORT is not set, it tries nearby ports and prints the fallback port.

7.4 Open the dashboard

Open the URL printed by the backend, typically:

http://localhost:8088

7.5 Stop the stack

From the UI:

Click Shutdown Stack
The stop action runs asynchronously and the UI tracks completion in the background.

Or manually:

docker compose -f compose-files/network-slicing/docker-compose.yaml --env-file build-files/open5gs.env down

8. Running the Dashboard

The dashboard is a single-page application (SPA) served by the Python backend.

Startup sequence:

Loads initial topology and slice definitions from /api/topology
Loads use cases and PLMN profiles from /api/profiles/list
Loads subscribers, metrics, QoS status, slice config, subscriber profiles, transport state, and test history
Opens an SSE connection to /api/stream
Falls back to periodic polling if SSE health degrades

9. How the Demo Works End to End

This section explains what happens at each stage of a demo session. The startup commands themselves are in Section 7 (Quick Start).

9.1 Bootstrap phase (`scripts/start-demo.sh`)

Running the start script performs the following in sequence:

Starts the network slicing Docker Compose stack.
Force-recreates AMF/NSSF/SMF/UPF services so latest config edits are loaded.
Waits for MongoDB readiness.
Seeds (and refreshes) 12 subscribers with slice assignments.
Ensures access_restriction_data=0 for those subscribers.
Restarts or recreates gNB and UE containers.
Waits for UE tunnel IP assignment (uesimtun*) and validates expected slice-subnet prefixes.
Verifies per-UE gateway reachability and performs one automatic UE restart if recovery is needed.

9.2 Dashboard initialization phase

Once the backend is running and the dashboard is open:

Verify the API/JS status chips are healthy.
Click Initialize Demo.
Wait for the backend to run scripts/start-demo.sh to completion.
The UI refreshes topology, subscribers, QoS, and transport state.
The UI automatically launches a baseline all-UE test.

Note: scripts/start-demo.sh starts and seeds the stack. The baseline automated test is a separate step triggered by the dashboard only after Initialize Demo completes.

9.3 Validation and iteration phase

View live progress in the Tests page and slice-specific pages.
Apply a use-case preset or manual QoS changes.
Re-run tests and compare results in Test History and Metrics pages.
Export/view the generated HTML report for documentation or grading evidence.

10. Configuration and Data Model

10.1 Slice definitions (`dashboard/data/slices.json`)

This file is the central dashboard-facing slice model. Each slice includes:

identity (id, name, category)
S-NSSAI values (sst, sd)
data network (dnn)
core mapping (smf, upf, upf_device)
addressing (subnet, gateway)
state and QoS (active, priority, qos.max_rate_mbit, qos.additional_latency_ms)
UE assignment (ues)

Default slice set in this project:

Slice ID	Category	SMF	UPF	Subnet	Default UE mapping
`slice-a`	eMBB	`smf1`	`upf1`	`10.45.0.0/16`	`ue1`, `ue2`, `ue3`
`slice-b`	URLLC	`smf2`	`upf2`	`10.46.0.0/16`	`ue4`, `ue5`
`slice-c`	mMTC	`smf3`	`upf3`	`10.47.0.0/16`	`ue6`, `ue7`, `ue8`, `ue9`
`slice-d`	Enterprise	`smf4`	`upf4`	`10.48.0.0/16`	`ue10`, `ue11`
`slice-e`	Experimental	`smf5`	`upf5`	`10.49.0.0/16`	`ue12`

10.2 Use-case presets (`dashboard/data/use-cases.json`)

Each use case defines two things:

qos_presets: Desired max rate and added latency per slice.
thresholds: Validation thresholds used by the test engine (latency, P95, loss, throughput).

This separation is important:

QoS presets configure behavior.
Thresholds define pass criteria for validation.

10.3 PLMN / S-NSSAI profiles (`dashboard/data/profiles.json`)

These profiles let MCC/MNC be applied and SD values across multiple config files in one action.

The backend profile apply flow updates:

amf.yaml
nssf.yaml
smf1.yaml to smf5.yaml
gnb.yaml
ue1.yaml to ue12.yaml
dashboard/data/slices.json SD values

10.4 Subscriber templates (`dashboard/data/subscriber-profiles.json`)

This file stores reusable provisioning templates (key, OPC, AMF, DNN, SST, SD) for the Subscribers page.

10.5 Transport rules (`dashboard/data/transport-rules.json`)

This file stores per-slice rule definitions used to generate iptables rules inside each UPF container.

10.6 Test history (`dashboard/data/test-history.json`)

This file stores a compact history of prior runs and is augmented by scanning actual test artifacts in metrics/runs/<run_id>/.

10.7 Config application flow from the UI

When slices in the dashboard are saved/applied:

The frontend sends the slice list to /api/slices/save.
The backend sanitizes fields (e.g., sd, numeric values, booleans, gateway fallback).
/api/slices/apply rewrites Open5GS/UERANSIM YAML files for active slices.
Config sync normalizes SMF dnn list format and removes stale nssf.slice blocks before restart.
The backend restarts/starts/stops relevant services (amf, nssf, gnb, slice SMFs/UPFs/UEs).

11. UI Dashboard Guide

This section documents the dashboard at the page-group level and focuses on operational purpose and impact on the smart-factory slicing workflow, rather than a field-by-field UI transcription.

11.1 UI Structure and Operating Model

11.1.1 Navigation Grouping

The dashboard navbar is organized into four groups that align with the lifecycle of a slicing demonstration:

Navbar group	Operational function	Typical usage stage
`Control`	System state awareness and runtime traffic behavior control	Startup, monitoring, live adjustments
`Validation`	Measurement, verification, and evidence generation	Before/after policy changes, final demonstration
`Configuration`	Persistent slice/subscriber/profile definition management	Initial setup, scenario changes
`Slice Pages`	Slice-scoped operational views	Focused debugging and per-slice comparison

11.1.2 Runtime Data and Control Model

The dashboard is not a static visual layer. It is the operational front end for the backend orchestrator in dashboard/server.py.

At runtime, the UI:

Consumes a periodic live snapshot via SSE (/api/stream) for status, topology, metrics, UE state, and test revision signals
Invokes targeted REST endpoints for configuration changes and control actions
Updates views after state-changing operations (QoS apply, slice apply, tests, subscriber changes)

This model ensures the UI reflects actual system state rather than only intended settings.

11.1.3 Operator Workflow Alignment

The grouped pages support a standard demonstration workflow:

Use Control pages to confirm the system is online and inspect current slice behavior.
Use Configuration pages to define slices, subscriber data, and profiles.
Apply transport/QoS changes in Control and scenario presets in Configuration.
Use Validation pages to measure and verify expected behavior.
Use Slice Pages for slice-specific analysis when a single slice needs focused inspection or retesting.

11.2 Control Pages

These pages support real-time operation of the slicing environment and provide the shortest path to understanding current network state.

11.2.1 Overview Page

Purpose:

Provide an operational summary of demo readiness, slice health, and recent control activity.

Impact on the smart-factory use case:

This page supports rapid go/no-go decisions before a demonstration or experiment run
It is the fastest place to verify whether the slices are behaving differently enough to represent distinct industrial traffic classes
It reduces time spent switching pages during live presentations by aggregating readiness, KPI trends, and recent actions

11.2.2 Topology Page

Purpose:

Present the current slice-aware deployment structure, container roles, service status, and logical data paths.

Impact on the smart-factory use case:

This page provides architectural evidence that the demo is implemented as multiple coordinated network functions rather than a single traffic-shaping script.
It helps explain to reviewers or instructors how slice isolation is represented in the deployed topology (SMF/UPF mapping, RAN/core relationships, transport presence).
It accelerates root-cause analysis when a use-case outcome looks incorrect but the issue is actually a stopped service or broken service dependency.

11.2.3 Transport Page

Purpose:

Apply and inspect per-slice transport behavior using tc and iptables on the UPF side.

Impact on the smart-factory use case:

This page is the operational mechanism for demonstrating differentiated treatment of traffic classes across slices.
It provides direct evidence that traffic behavior changes are implemented in the data path (through live tc and iptables state), not only in high-level configuration metadata.
It enables controlled experiments where the team can adjust shaping or filtering and immediately validate the effect through the Validation pages.

11.3 Validation Pages

These pages produce and inspect the measurable evidence used to show that slice behavior matches the intended use-case design.

11.3.1 Tests Page

Purpose:

Run automated validation workflows and review historical results with report artifacts.

Impact on the smart-factory use case:

This page converts the demonstration from a visual claim into a repeatable validation process using latency, loss, throughput, subnet, and session checks.
It supports scenario-level and targeted validation (all, slice, ue), which is critical when demonstrating both full-system behavior and focused slice behavior.
It provides report outputs suitable for grading, documentation, and reproducibility.

11.3.2 Metrics Page

Purpose:

Present the latest parsed ping and iPerf measurements in a direct UE-level view.

Impact on the smart-factory use case:

This page provides the raw KPI view needed to confirm whether automated test outcomes are reasonable.
It supports comparative interpretation across slices (for example, throughput-oriented vs latency-oriented slices) without requiring report generation for every iteration.
It is the primary reference for manual performance inspection during QoS tuning.

11.3.3 Logs Page

Purpose:

Provide service-level log access for runtime diagnosis and fault isolation.

Impact on the smart-factory use case:

This page is essential when a failed validation result is caused by control-plane or registration issues rather than QoS policy.
It shortens debugging cycles by keeping operational troubleshooting inside the same dashboard workflow used for configuration and validation.
It supports demonstration robustness by enabling fast recovery when a service misbehaves during live runs.

11.4 Configuration Pages

These pages define the persistent inputs that shape the behavior of the network slicing environment.

11.4.1 Slices Page

Purpose:

Manage the canonical slice model (dashboard/data/slices.json) and apply it to the Open5GS/UERANSIM runtime configuration.

Impact on the smart-factory use case:

This page controls the mapping from industrial traffic categories to concrete network behavior (slice IDs, SMF/UPF mapping, UE assignment, IP plan, QoS defaults).
It allows the team to evolve the demonstration design without manually editing multiple YAML files for each change.
It provides the configuration bridge between scenario definition and executable network topology.

11.4.2 Subscribers Page

Purpose:

Provision and inspect Open5GS subscriber records used by the UEs in the slicing scenario.

Impact on the smart-factory use case:

Subscriber provisioning is a prerequisite for attach and PDU session establishment, so this page directly affects whether any use-case validation can run.
It enables rapid correction of subscriber/slice mismatches without leaving the dashboard workflow.
It supports repeatability when resetting or re-seeding the environment between experiments.

11.4.3 Profiles Page

Purpose:

Manage reusable scenario presets for QoS behavior and PLMN/S-NSSAI identity values.

Impact on the smart-factory use case:

QoS presets allow fast switching between demonstration narratives (for example balanced operation vs mission-critical prioritization) without manual per-slice edits.
PLMN/S-NSSAI profiles support controlled reconfiguration of identity-related values across the stack and UEs.
This page improves repeatability by making common scenario transitions explicit and reusable.

11.5 Slice Pages

These pages are generated dynamically from the configured slice set and provide a slice-scoped operational perspective.

11.5.1 Dynamic Slice Pages

Purpose:

Provide a focused view of one slice, combining slice-scoped operational state, KPIs, and validation actions.

Impact on the smart-factory use case:

These pages support targeted demonstrations where one industrial traffic class must be analyzed in isolation (for example URLLC latency behavior or eMBB throughput behavior).
They reduce cognitive load during debugging by filtering the system view to the slice under investigation.
They are particularly useful for iterative tuning, where QoS changes and slice-specific tests are repeated until the observed behavior matches the intended use-case profile.

12. Automated Test and Validation Pipeline

This section explains how tests work behind the UI.

12.1 Test trigger paths

Tests can be started from:

Tests page (Run Test)
Dynamic slice page (Run Slice Test)
Dashboard Initialize Demo flow (baseline all-UE test after bootstrap)

12.2 Backend orchestration flow

The backend test engine (dashboard/backend/test_engine.py) performs these steps:

Create a unique run_id and register a running test in memory.
Resolve test scope (all, slice, ue) to a UE list.
Build environment variables for the scripts.
Run scripts/collect-metrics.sh (ping collector).
Run scripts/run-iperf.sh (iPerf collector).
Parse latest CSV outputs from the run directory.
Evaluate validation checks against the selected use-case thresholds.
Generate an HTML report file.
Update in-memory run state and persisted test history.

Key environment variables passed from the test engine to the collectors:

Variable	Purpose
`OUTPUT_DIR`	Per-run artifact folder (`metrics/runs/<run_id>/`)
`UE_LIST`	Scope-limited list of UEs to test
`UE_SLICE_MAP`	UE-to-slice key mapping used by collectors
`SLICE_UPF_MAP`	Slice key to UPF service mapping
`SLICE_GW_MAP`	Slice key to gateway IP mapping
`SLICE_MAX_RATE_MAP`	Slice key to QoS cap mapping (used for iPerf rate limits/QoS checks)
`PING_TARGET`	Ping target (`auto` by default for per-slice gateway) or explicit host/IP
`PING_TARGET_FALLBACK`	Fallback ping target when `auto` cannot resolve a per-slice gateway
`PING_COUNT`	Ping packets per UE
`PING_EXEC_TIMEOUT`	Max per-UE ping command runtime
`DURATION`	iPerf duration in seconds
`IPERF_CONNECT_TIMEOUT_MS`	iPerf client connect timeout (ms)
`IPERF_EXTRA_TIMEOUT`	Extra iPerf runtime buffer (seconds)
`RUN_UPLINK_IPERF`	Enable uplink iPerf (default `0`, downlink-only validation)

Runtime budget behavior:

The test engine computes ping/iPerf command timeouts dynamically from UE count, ping count, and iPerf duration.

12.3 Ping collector (`scripts/collect-metrics.sh`)

What it does:

Runs ping inside each selected UE container
Parses packet counts and RTT stats
Computes a P95 RTT estimate from raw ping replies
Writes slice-metrics-<timestamp>.csv

Default values and overrides:

Target defaults to auto (per-slice gateway via SLICE_GW_MAP), then falls back to PING_TARGET_FALLBACK (default 8.8.8.8)
Ping count defaults to 10 unless overridden via CLI arg or PING_COUNT
Per-UE execution timeout defaults to PING_COUNT + 15 seconds unless PING_EXEC_TIMEOUT is set

Collector robustness behavior:

Pings are sent through the detected UE tunnel interface (uesimtun*) with bounded command timeout.
If a UE returns zero replies, the collector restarts that UE once and retries.
If ping cannot run, the script still writes a failed CSV row (100% loss) instead of dropping data.

12.4 iPerf collector (`scripts/run-iperf.sh`)

What it does:

Groups UEs by slice using UE_SLICE_MAP
Resolves each slice to its UPF and gateway IP
Starts an iPerf3 server inside the slice's UPF container
Runs required downlink iPerf for each UE and optional uplink when RUN_UPLINK_IPERF=1
Writes per-UE JSON files and an aggregate CSV file
Tracks success/fail/skip counts and returns a meaningful exit code

Important implementation detail:

This script does not use one external iPerf server container.
It starts iPerf servers inside the corresponding UPF containers to keep tests slice-aware.

Collector robustness behavior:

Attempts to install iperf3 in containers if missing (using common package managers, with bounded timeout attempts)
Starts/verifies iPerf servers in UPFs and cleans up iPerf processes on exit
Retries failed downlink runs once (and can restart UE once for recovery)
Records 0.000 Mbps rows for unavailable UEs/services instead of silently dropping samples
Uplink is marked skipped by default unless explicitly enabled

12.5 Validation checks in the test engine

Per-slice checks include:

UE Attach
PDU Session
Subnet Match
Latency Avg
Latency P95
Packet Loss
Throughput
QoS Enforcement

How QoS Enforcement is evaluated:

The engine compares downlink throughput samples to the configured/preset QoS cap.
It expects observed throughput to stay within approximately 120% of the configured max rate.

12.6 Test scope and threshold behavior

all: evaluates all slices with their associated UEs
slice: evaluates one slice and its mapped UEs
ue: evaluates the slice containing the selected UE, filtered to that UE

Threshold source:

The selected use case from dashboard/data/use-cases.json
If no use case is selected, report labeling may show no use case and some checks may effectively become permissive/fallback depending on data availability
If PING_TARGET=auto, reports label the target as slice-gateway

12.7 Test result statuses and report semantics

Backend and UI statuses commonly displayed:

PASS
PASS (WARN)
RUNNING

Current report behavior:

The generated HTML report always summarizes validation and tool status.
A run becomes PASS only when validation checks pass and both collectors succeed.
Otherwise it is surfaced as PASS (WARN) with an issue breakdown.

12.8 HTML report contents

Generated report includes:

Run metadata (run id, scope, target, use case)
Overall and validation status
Tool status (ping and iPerf)
Issue breakdown list
Test conditions (ping target/count, iPerf duration)
Per-slice evaluation table with checks, metrics, thresholds, and QoS cap

13. API Overview

The backend exposes a REST-style API plus SSE for the dashboard.

13.1 Core status and telemetry endpoints

Method	Endpoint	Purpose
GET	`/api/health`	Basic backend health check
GET	`/api/status`	Stack status summary and service details
GET	`/api/topology`	Topology nodes and slice definitions
GET	`/api/ues`	UE states with slice mapping and metrics
GET	`/api/metrics/latest`	Latest parsed ping and iPerf metrics (empty when no UE runtime is online)
GET	`/api/stream`	Live SSE snapshot stream
GET	`/api/logs`	Service logs tail (`service`, `tail`)

13.2 Control and configuration endpoints

Method	Endpoint	Purpose
POST	`/api/stack/start`	Start stack (`docker compose up -d`)
POST	`/api/stack/stop`	Initiate async stack stop (`docker compose down`)
GET	`/api/stack/stop/status`	Read async stack-stop task state/result
POST	`/api/service/restart`	Restart one service
POST	`/api/service/action`	Start/stop one service
POST	`/api/ues/restart`	Restart one UE or all UEs
GET	`/api/slices`	Load slice definitions
POST	`/api/slices/save`	Save sanitized slice definitions
POST	`/api/slices/apply`	Apply slice config to YAML + restart/start/stop services
GET	`/api/profiles/list`	Load PLMN profiles and use-case presets
POST	`/api/profiles/save`	Save a PLMN profile
POST	`/api/profiles/apply`	Apply PLMN/SD profile across config files

13.3 Transport and subscriber endpoints

Method	Endpoint	Purpose
GET	`/api/qos/status`	Read `tc` qdisc state per slice
POST	`/api/qos/apply`	Apply QoS (`tc`) to a slice UPF
GET	`/api/transport/status`	Read `tc` and `iptables` state per slice
GET	`/api/transport/rules`	Load persisted transport rules
POST	`/api/transport/iptables`	Add/delete/flush per-slice `iptables` rules
GET	`/api/subscribers`	List subscribers from MongoDB (`db_not_running` hint when DB is offline)
POST	`/api/subscribers/add`	Add subscriber via `open5gs-dbctl`
POST	`/api/subscribers/remove`	Remove subscriber via IMSI
GET	`/api/subscriber-profiles`	Load subscriber profile templates
POST	`/api/subscriber-profiles/save`	Save subscriber profile templates

13.4 Test endpoints

Method	Endpoint	Purpose
POST	`/api/tests/run`	Start a background test run
GET	`/api/tests/<run_id>`	Poll test run status and logs
GET	`/api/tests/history`	List known historical test runs
GET	`/api/tests/export`	Export run metadata/details
GET	`/api/tests/report`	View generated HTML report
GET	`/api/start-demo/status`	Track `Initialize Demo` backend command state
POST	`/api/start-demo`	Run `scripts/start-demo.sh` asynchronously

14. Metrics and Report Outputs

Generated artifacts are written under metrics/ and are treated as runtime outputs.

Common outputs:

metrics/slice-metrics-<timestamp>.csv
metrics/iperf-<timestamp>.csv
metrics/iperf-<timestamp>-<ue>-<direction>.json
metrics/runs/<run_id>/slice-metrics-*.csv
metrics/runs/<run_id>/iperf-*.csv
metrics/runs/<run_id>/report-<run_id>.html

Repository hygiene note:

metrics/ is ignored in .gitignore so generated artifacts do not get committed.

15. Troubleshooting

15.1 Dashboard startup issues

Dashboard opens but buttons do nothing

Likely cause: opened dashboard/index.html directly via file://.

Fix: run python3 dashboard/server.py and open http://localhost:8088 (or the port printed by the server).

Port 8088 is busy

If DASHBOARD_PORT is not set, the backend tries nearby ports and prints the selected port. To set an explicit port:

DASHBOARD_PORT=8089 python3 dashboard/server.py

15.2 Initialize Demo fails or hangs

Check:

Docker daemon is running
images can be pulled (first run may take time)
MongoDB container starts successfully
user has permission to run Docker commands

Helpful pages:

Topology (service status)
Logs (container logs)
Tests activity log (if failure occurs after bootstrap)

15.3 UEs do not attach or do not receive tunnel IPs

Check:

Subscribers were seeded correctly
gNB and UEs were restarted/recreated
slice IDs (SST/SD) and DNN values are consistent
amf, nssf, smf*, upf*, and gnb are running

Useful logs:

amf
smf1 to smf5
gnb
affected ueX

15.4 Ping metrics fail

Possible causes:

Ping target not reachable from UE containers
No UE PDU session
Container networking not ready yet

Fix options:

retry after UE attach is stable
set a reachable PING_TARGET
run a smaller scoped test first

15.5 iPerf metrics fail or are skipped

Possible causes:

iperf3 missing in UE or UPF container
target UPF not running
slice mappings missing or inconsistent

Notes:

The script attempts to install iperf3 automatically in several common container package-manager environments.
If all runs are skipped, the collector returns a non-success code and the UI/report will surface warnings.

15.6 Transport changes do not appear to apply

Check:

correct slice selected
UPF container is running
upf_device in slice config matches the actual tunnel device
tc/iptables command output in Transport page status panes

15.7 Test shows PASS WARN instead of PASS

This usually means one or more of the following happened:

validation threshold was not satisfied (latency, loss, throughput, subnet, etc.)
ping collector failed or was incomplete
iPerf collector failed or was skipped

Use:

Tests page run log
Test History View HTML report
Metrics page raw values
Slice page checklist and charts

15.8 Shutdown Stack appears to hang

Expected behavior:

Stack shutdown is asynchronous; API can briefly disconnect while containers stop.

Check:

Run GET /api/stack/stop/status and inspect running, last.code, and error text.
Use Topology refresh after shutdown completes to confirm all services are down.

15.9 Subscribers list is empty with `unavailable_reason=db_not_running`

Meaning:

MongoDB (db service) is not currently running, so subscriber reads are intentionally returned as unavailable.

Fix:

Start the stack or explicitly start the db service, then reload subscribers.

15.10 Metrics page shows empty data while stack is stopped

Expected behavior:

The backend returns an empty metrics payload when no UE containers are running to avoid showing stale telemetry.

16. Final Deliverables

17. Acknowledgements

This project was developed in an academic and applied systems context, and it benefited from multiple forms of support.

17.1 Academic guidance

We thank Prof. Dr. Armin Lehmann for guidance, feedback, and teaching support throughout the project.
We thank the Frankfurt University of Applied Sciences for the learning environment, curriculum, and technical foundation that made this work possible.

17.2 Acknowledgement of AI-assisted work

This project acknowledges the responsible use of AI-assisted tools during research and implementation, including support in:

technical research and concept clarification,
implementation planning and iteration,
frontend and backend development assistance,
integration troubleshooting (including Docker image and container workflow integration),
documentation drafting and refinement.

All AI-assisted outputs were reviewed, adapted, and validated by the project team before inclusion.

18. Glossary

18.1 5G and telecom terms

5G SA: 5G Standalone architecture using a 5G Core, not LTE EPC.
RAN: Radio Access Network. In this project, simulated by UERANSIM gNB and UEs.
gNB: Next-generation base station in 5G.
UE: User Equipment (device). Here, simulated devices in containers (ue1 to ue12).
Core (5GC): The 5G Core network functions (AMF, SMF, UPF, etc.).
AMF: Access and Mobility Management Function.
SMF: Session Management Function.
UPF: User Plane Function.
NRF: Network Repository Function (service registry/discovery).
NSSF: Network Slice Selection Function.
AUSF: Authentication Server Function.
UDM: Unified Data Management.
UDR: Unified Data Repository.
PCF: Policy Control Function.
BSF: Binding Support Function.
PDU Session: Data session that provides a UE with IP connectivity through the core.
DNN: Data Network Name (similar to APN concept in practice).
PLMN: Public Land Mobile Network identifier (MCC + MNC).
MCC: Mobile Country Code.
MNC: Mobile Network Code.
IMSI: International Mobile Subscriber Identity.
S-NSSAI: Single Network Slice Selection Assistance Information (slice identifier).
SST: Slice/Service Type component of S-NSSAI.
SD: Slice Differentiator component of S-NSSAI.

18.2 Network slicing and QoS terms

eMBB: Enhanced Mobile Broadband (throughput-oriented service class).
URLLC: Ultra-Reliable Low-Latency Communications (latency-sensitive service class).
mMTC: Massive Machine-Type Communications (high-density, typically low-bandwidth devices).
QoS: Quality of Service, used to shape/limit traffic behavior.
Priority: In this project, the tc/HTB class priority used for slice traffic treatment.
Latency: Time delay experienced by packets, commonly measured as RTT in milliseconds.
P95 latency: 95th percentile latency (95% of samples are at or below this value).
Packet loss: Percentage of packets that do not reach the destination.
Throughput: Data transfer rate, usually shown in Mbps.
Jitter: Variation in packet delay over time.

18.3 Linux networking and container terms

Docker Compose: Tool for defining and running multi-container applications.
tc: Linux traffic control utility used for shaping and queueing.
HTB: Hierarchical Token Bucket, a tc qdisc/class discipline for rate control.
netem: Linux traffic emulator used to add delay/loss/jitter-like effects (delay is used here).
iptables: Linux packet filtering and NAT rule tool.
Chain: A named list of packet filtering rules in iptables.
SSE: Server-Sent Events, a one-way streaming mechanism from server to browser used for live snapshots.

18.4 Software and project terms

SPA: Single-Page Application. The dashboard frontend operates as an SPA.
API: Application Programming Interface. The dashboard backend exposes /api/* endpoints.
KPI: Key Performance Indicator (for example latency and throughput summaries).
CSV: Comma-Separated Values file used for collected metrics data.
JSON: JavaScript Object Notation file format used for UI config/state.
Open5GS: Open-source implementation of 5G Core network functions.
UERANSIM: Open-source 5G RAN/UE simulator.
open5gs-dbctl: Helper script used to add/remove subscribers in the Open5GS MongoDB.

19. Authors

Member	Name	GitHub ID
1	`Aditya Praveen Shidhaye`	@axiomsbane
2	`Priyanshu Bandyopadhyay`	@prnshubn
3	`Pradeep Buddhiram Patwa`	@pradeeppatwa
4	`Akshay Ganesh Gudekar`	@Akshay-Gudekar
5	`Vikas Rathore`	@vikasrathore7229
6	`Taibaz Pathan`	@Taibaz-Pathan

Name		Name	Last commit message	Last commit date
build-files		build-files
compose-files		compose-files
configs		configs
dashboard		dashboard
docs		docs
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
open5gs-dbctl		open5gs-dbctl

Latest commit

History

Folders and files

Repository files navigation

Team-1G: SmartFactory 5G Slicing Control Center

Table of Contents

1. Project Summary

2. Smart Factory Use Cases and Why 5G Fits

2.1 Smart factory problem context

2.2 Why 5G network slicing aligns with smart factory needs

2.3 Smart-factory use case presets in the dashboard

2.3.1 Factory Balanced

2.3.2 Mission Critical

2.3.3 IoT Flood

3. System Architecture

3.1 High level architecture

System Architecture Overview

3.2 Control plane in this project

3.3 Runtime components

3.4 Data and Control Flow

System Data & Control Flow Diagram

3.5 Live update model

4. Key Features

5. Repository Structure

6. Prerequisites

6.1 Host environment

6.2 Component versions

6.3 Notes

7. Quick Start

7.1 Host IP configuration note

7.2 Start the slicing stack and seed subscribers

7.3 Run the dashboard backend

7.4 Open the dashboard

7.5 Stop the stack

8. Running the Dashboard

9. How the Demo Works End to End

9.1 Bootstrap phase (scripts/start-demo.sh)

9.2 Dashboard initialization phase

9.3 Validation and iteration phase

10. Configuration and Data Model

10.1 Slice definitions (dashboard/data/slices.json)

10.2 Use-case presets (dashboard/data/use-cases.json)

10.3 PLMN / S-NSSAI profiles (dashboard/data/profiles.json)

10.4 Subscriber templates (dashboard/data/subscriber-profiles.json)

10.5 Transport rules (dashboard/data/transport-rules.json)

10.6 Test history (dashboard/data/test-history.json)

10.7 Config application flow from the UI

11. UI Dashboard Guide

11.1 UI Structure and Operating Model

11.1.1 Navigation Grouping

11.1.2 Runtime Data and Control Model

11.1.3 Operator Workflow Alignment

11.2 Control Pages

11.2.1 Overview Page

11.2.2 Topology Page

11.2.3 Transport Page

11.3 Validation Pages

11.3.1 Tests Page

11.3.2 Metrics Page

11.3.3 Logs Page

11.4 Configuration Pages

11.4.1 Slices Page

11.4.2 Subscribers Page

11.4.3 Profiles Page

11.5 Slice Pages

11.5.1 Dynamic Slice Pages

12. Automated Test and Validation Pipeline

12.1 Test trigger paths

12.2 Backend orchestration flow

12.3 Ping collector (scripts/collect-metrics.sh)

12.4 iPerf collector (scripts/run-iperf.sh)

12.5 Validation checks in the test engine

12.6 Test scope and threshold behavior

12.7 Test result statuses and report semantics

12.8 HTML report contents

13. API Overview

13.1 Core status and telemetry endpoints

13.2 Control and configuration endpoints

13.3 Transport and subscriber endpoints

13.4 Test endpoints

9.1 Bootstrap phase (`scripts/start-demo.sh`)

10.1 Slice definitions (`dashboard/data/slices.json`)

10.2 Use-case presets (`dashboard/data/use-cases.json`)

10.3 PLMN / S-NSSAI profiles (`dashboard/data/profiles.json`)

10.4 Subscriber templates (`dashboard/data/subscriber-profiles.json`)

10.5 Transport rules (`dashboard/data/transport-rules.json`)

10.6 Test history (`dashboard/data/test-history.json`)

12.3 Ping collector (`scripts/collect-metrics.sh`)

12.4 iPerf collector (`scripts/run-iperf.sh`)

15.9 Subscribers list is empty with `unavailable_reason=db_not_running`