SCOPE: An Open and Softwarized Prototyping Platform for NextG Systems
GitHub - wineslab/colosseum-scope: Source code for the paper L. Bonati, S. D'Oro, S. Basagni, and T. Melodia, "SCOPE: An Open and Softwarized Prototyping Platform for NextG Systems," in Proceedings of ACM MobiSys, June 2021.
SCOPE
SCOPE is a development environment for softwarized and virtualized NextG cellular networks based on srsLTE (now srsRAN).
It provides: (i) A ready-to-use portable open-source cellular container with flexible 5G-oriented functionalities; (ii) data collection tools, such as dataset generation functions for recording cellular performance and metrics, and for facilitating data analysis; (iii) a set of APIs to control and reprogram key functionalities of the full cellular stack at run time, without requiring redeploying the network, and (iv) an emulation environment with diverse cellular scenarios closely matching real-world deployments for precise prototyping NextG network solutions.
SCOPE has been prototyped and benchmarked on the Colosseum wireless network emulator, where an LXC container of SCOPE has been made available, and it is portable to LXC-enabled testbeds.
If you use SCOPE, its APIs or scenarios, please reference the following paper:

L. Bonati, S. D'Oro, S. Basagni, and T. Melodia, "SCOPE: An Open and Softwarized Prototyping Platform for NextG Systems,"
 in Proceedings of ACM MobiSys, June 2021.
[pdf] [bibtex]

This work was partially supported by the U.S. National Science Foundation under Grant CNS-1923789 and the U.S. Office of Naval Research, Grants N00014-19-1-2409 and N00014-20-1-2132.
Structure
SCOPE directory structure is organized as follows
root 
|
└──radio_api
|   
└──radio_code
|  |
|  └──scope_config
|  |
|  └──srsGUI
|  |
|  └──srsLTE
|  |
|  └──srslte_config

radio_api
The radio_api directory contains SCOPE API script, examplary scripts, configuration files, and support files for Colosseum.
Quick start on Colosseum with base configuration:


python3 scope_start.py --config-file radio_interactive.conf


Cellular applications will be started in a new tmux session named scope, attach with tmux a -t scope


Main SCOPE API scripts:

constants.py: Constant parameters used by the remaining scripts
scope_api.py: APIs to interact with cellular base station
scope_start.py: Quick start script for running on Colosseum testbed: Parse configuration file, configure and start cellular applications (i.e., base station and core network, or user). If using the quick start script outside Colosseum some pieces might require minor adaptation, e.g., manually supplying the node list instead of leveraging the automatic node discovery. Note that this script generates runtime logs in the /logs directory. If running it on your local machine, please make sure that such directory exists, and that your user can write inside it
support_functions.py: Additional support functions



Exemplary scripts (to be run at the base station):

heuristic.py: Read performance metrics from dataset and implement arbitrary heuristic policy. In this example, read downlink buffer and throughput relative to served users from performance dataset. Then assign more resources to slices if buffers are above threshold (policy slice 0), and throughput is above threshold (policy for slice 2). If more users are served in a single slice, also change the slice scheduling policy from round-robin to waterfilling.
slice_heuristic.py: Periodically modify number of PRBs allocated to the network slices.



Configuration files:

radio.conf: Dummy configuration file replaced by Colosseum when running batch jobs
radio_interactive.conf: Exemplary configuration file to use with scope_start.py script
heuristic.conf: Exemplary configuration file to use with heuristic.py script
slice_heuristic.conf: Exemplary configuration file to use with slice_heuristic.py script



Colosseum support files:

start.sh: Used by Colosseum to start a batch job
statistics.sh: Used by Colosseum to check on the radio performance
status.sh: Used by Colosseum to check on the radio state
stop.sh: Used by Colosseum to stop a batch job



SCOPE API configuration parameters
A list of the configuration parameters accepted by SCOPE APIs follows.

bs-config/ue-config: Base station/UE configuration parameters to override those specified on srsLTE configuration files. Format as json, e.g., {'n_prb': 50, 'dl_freq': 2655000000, 'ul_freq': 2535000000}
capture-pkts: Enable packet capture and dumps them on .pcap files through tcpdump. By default, the monitored interfaces are srs_spgw_sgi, tun_srsue, and Colosseum tr0
colcli: Use colosseumcli APIs to get list of active nodes. This parameter is specific to Colosseum and it is only available in interactive mode
config-file: JSON-formatted configuration file where to read these parameters from. The other arguments are ignored if a configuration file is passed
custom-ue-slice: Use UE-slice associations passed in the configuration file
dl-freq/ul-freq: Downlink/uplink frequency for base station and users [Hz]
dl-prb: Number of downlink PRBs to use at the base station
force-dl-modulation/force-ul-modulation: Force downlink/uplink modulation of base station/users
global-scheduling-policy: Global MAC-layer scheduling policy. Used at base station side, overruled by slice-dependent scheduling if network slicing is enabled. Possible values are: 0: Round-robin, 1: Waterfilling, 2: Proportionally fair
iperf: Generate traffic through iperf3, downlink only
network-slicing: Enable network slicing. Used at base station side
slice-allocation: Base station slice allocation.1 This is passed in the form of {slice_num: [lowest_allowed_rbg, highest_allowed_rbg], ...} (inclusive). E.g., {0: [0, 3], 1: [5, 7]} assigns RBGs 0-3 to slice 0 and 5-7 to slice 1
slice-scheduling-policy: Slicing policy for each slice in a list format.1 E.g., [2, 0, 1, ...] assigns policy 2 to slice 0, policy 0 to slice 1 and policy 1 to slice 2. Possible values are: 0: Round-robin, 1: Waterfilling, 2: Proportionally fair
slice-users: Slice UEs in the form of {slice_num: [ue1, ue2, ...], ...}, e.g., {0: [2, 6], 1: [3, 4, 5]} associates UEs 2, 6 to slice 0 and UEs 3, 4, 5 to slice 1. The UE IDs correspond to the SRNs of the reservation (the first base station has ID equal to 1). E.g., if SRNs 3, 5, 7, 8 are reserved and users-bs is set to 3, the base station is SRN 3, while SRNs 5, 7 and 8 are the 1st, 2nd and 3rd users, respectively
tenant-number: Number of network slicing tenants. By default, a maximum of 10 tenants is supported. In case more than 10 tenants are needed, also modify MAX_SLICING_TENANTS in radio_code/srsLTE/srsenb/hdr/global_variables.h
users-bs: Maximum number of users per base station. This parameter is used to "elect" the base stations in the network. E.g., if users-bs is set to 3 and there are 8 nodes in the reservation, nodes 1 and 5 are elected as base station and nodes 2, 3, 4, 6, 7, 8 are UEs
write-config-parameters: If enabled, writes configuration parameters on file (e.g., scheduling/slicing policies). Done at the base station-side

radio_code
The radio_code directory contains a modified version of srsLTE (now srsRAN) that implements the 5G-oriented functionalities enabled by SCOPE, configuration files and support applications.

srsLTE: This is a modified version of srsLTE with the 5G-oriented functionalities enabled by SCOPE (see Section 3 of [1])
scope_config: Configuration files used by SCOPE base station. A template version of these files is stored in ../srsLTE/config_files/scope_config

scope_cfg.txt: Global configuration file to enable/disable SCOPE functionalities. All parameters are disabled if not found in the file. Loaded parameters:

colosseum_testbed: Enables Colosseum-specific configuration of radio parameters
force_dl_modulation/force_ul_modulation: Enables forcing of downlink/uplink modulation for selected users. The actual modulation can be specified in slicing/ue_imsi_modulation_dl.txt/ue_imsi_modulation_ul.txt
global_scheduling_policy: Specifies scheduling policy for the whole network.2 Available choices are:

0: Round-robin scheduling policy
1: Waterfilling scheduling policy
2: Proportionally fair scheduling policy


network_slicing_enabled: Enables network slicing loading slicing-related configuration files in the slicing directory


remove_experiment_data.sh: Removes collected data from old runs
config: This directory gets populated at run time with user-related parameters (e.g., downlink power scaling factor)
metrics/csv: CSV files on user performance are automatically logged in this directory at run time
slicing: Contains slicing- and user- related configuration files:

slice_allocation_mask_tenant_*.txt: 25-bit RBG allocation mask for tenant. This is a binary mask in which a 1 denotes that the RBG is permitted for use in the specific slice, a 0 that it is not permitted. The number of PRBs contained in a RBG, and the number of RBGs read depend on the configuration of the base station, i.e., by the total number of PRBs used (see 3GPP TS 36.213, Table 7.1.6.1-1)
slice_scheduling_policy.txt: Specifies the scheduling policy to use for each network slice. Available choices are:

0: Round-robin scheduling policy
1: Waterfilling scheduling policy
2: Proportionally fair scheduling policy


ue_imsi_modulation_dl.txt/ue_imsi_modulation_ul.txt: Configuration file to force downlink/uplink modulation for specific users3
ue_imsi_slice.txt: Slice-users associations3




srslte_config: Configuration files for cellular applications used by srsLTE, adapted for use in Colosseum. Generic configuration templates for use in different environments are stored in ../srsLTE/config_files/general_config

SCOPE Cellular Scenarios for Colosseum Network Emulator
These are a set of RF cellular scenarios to use with the Colosseum wireless network emulator (see Section 4 of [1]). Scenarios have been designed in three different urban setups: (i) Rome, Italy; (ii) Boston, MA, US, and (iii) Salt Lake City, UT, US (POWDER scenario).
For the Rome and Boston scenarios, the locations of the base station reflect real cell tower deployments taken from the OpenCelliD database.
For the POWDER scenario, locations mirror the coordinates of the rooftop base stations deployed in the POWDER testbed in Salt Lake City.
Different versions of the above scenarios have been created for different number of base stations and users, different distance from the base stations users are deployed, and different mobility speed of the users.
The available distances between users and base stations are: close, users are deployed within 20 m from the base stations, medium, within 50 m, and far, within 100 m. The available user mobility speeds are: static, users do not move for the whole duration of the scenario, moderate, users move at 3 m/s, and fast, users move at 5 m/s.



Terrain
UE-BS Distance
UE Mobility
BS #
UEs/BS
Node #
Duration [s]
Scenario ID
Available on Colosseum




Rome
close
static
10
4
50
600
1017
✔️


Rome
close
moderate
10
4
50
600
1018
✔️


Rome
close
fast
10
4
50
600
1028
❌


Rome
medium
static
10
4
50
600
1035
✔️


Rome
far
static
10
4
50
600
1019
✔️


Boston
close
static
10
4
50
600
1031
✔️


Boston
close
moderate
10
4
50
600
1033
✔️


Boston
close
fast
10
4
50
600
1034
❌


Boston
medium
static
10
4
50
600
1036
✔️


Boston
far
static
10
4
50
600
1024
✔️


POWDER
close
static
8
4
40
600
1025
✔️


POWDER
close
moderate
8
4
40
600
1026
✔️


POWDER
close
fast
8
4
40
600
1030
❌


POWDER
medium
static
8
4
40
600
1041
✔️


POWDER
far
static
8
4
40
600
1027
✔️



Due to space limitations, only a selection of these scenarios is currently available on Colosseum. The remaining scenarios can be built and installed upon request.
Running on Testbeds External to Colosseum
The command line option --generic-testbed should facilitate running SCOPE outside the Colosseum environment.
Troubleshooting

Command-line options are not applied: Sometimes it may look like the CLI options are not applied. These options are overridden by the configuration file, if passed.

References
[1]
L. Bonati, S. D'Oro, S. Basagni, and T. Melodia,
"SCOPE: An Open and Softwarized Prototyping Platform for NextG Systems,"
in Proceedings of ACM MobiSys, June 2021.
[pdf]
[bibtex]

1. These parameters are periodically reloaded from file. The frequency at which they are reloaded can be modified through the variable line_change_frequency_ms in ../radio_code/srsLTE/srsenb/src/stack/mac/scheduler_metric.cc, function dl_metric_rr::sched_users. 
2. This parameter is ignored if network slicing is enabled (network_slicing_enabled). In such case, the scheduling policy can be specified through the slicing/slice_scheduling_policy.txt configuration file. 
3. When adding a new user to the core network database, the relative IMSI needs to be added to this configuration files as well.
