diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a0090b4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# macOS +.DS_Store diff --git a/README.md b/README.md new file mode 100644 index 0000000..800c955 --- /dev/null +++ b/README.md @@ -0,0 +1,67 @@ +# Colosseum Master Class 2021 +### November 1-3, 2021 + +

+ + +

+ +Large-scale experimentation is a core component of wireless research. However, experimental capabilities are as effective and useful as their ability of capturing diverse wireless environments and conditions realistically, in a controlled environment that is highly accessible, programmable and where experiments can be repeated for fair and informative comparison among solutions. Up until now, the research community lacked widespread access to testbeds offering such critical capabilities, especially at scale. + +The past few years have seen the emergence of larger facilities with the characteristics required for repeatable wireless experimentation at scale. Examples include the testbeds of the NSF Platform for Advanced Wireless Research (PAWR) program and Colosseum, which, with its capability of emulating over 60k wireless channels, is hailed as the world's largest wireless network emulator. + +Colosseum is a massive RF and computational facility enabling large-scale experiments through a pool of 128 Software-defined Radios (SDRs) controlled by dedicated and remotely-accessible host computers called Standard Radio Nodes (SRNs). It emulates wireless signals traversing space and reflecting off multiple objects and obstacles as they travel from transmitters to receivers, through its Massive Channel Emulator (MCHEM) that consists of an additional array of 128 SDRs and 64 FPGAs. As such, Colosseum can create virtual worlds, as if the radios are operating in an open field, downtown area, shopping mall, or a desert, by generating more than 52 terabytes of data per second. + +Colosseum is hosted at Northeastern University, and is freely accessible by anybody in the research community with an active grant on wireless research. We believe that a tutorial on Colosseum is timely and relevant to the MobiCom community as it will offer to the attendees a clear introduction on how to access the emulator, and how to run repeatable wireless experiments at scale on it, emphasizing its capabilities of modeling a vast variety of scenarios, channel conditions, and traffic and mobility patterns. Particularly, we will show how to use Colosseum in a set of scenario relevant to most wireless research: Local area networking (e.g., WiFi-based networks), cellular networks, and wireless ad hoc scenarios (e.g., aerial or vehicular networking). Out tutorial will further explain how wireless emulated experiments can be ported to other real-world wireless testbeds, including the PAWR platforms, thus facilitating full-cycle experimental wireless research: Design, experiments and tests at scale in a fully controlled and observable environment, and testing in the field. + + +## Colosseum Young Gladiators Master Class + +The Colosseum team at the Institute for the Wireless Internet of Things at Northeastern University is organizing a 3 day in-person master class for PhD students and Postdoc researchers at U.S. institutions who are interested in using the Colosseum channel emulator for their research. The course will include tutorial-like presentations from Colosseum experts, hands-on assignments for the attendees, invited talks by Colosseum lead users, and a site visit to the Colosseum data center facility. + +By the end of this master class the attendees will learn about the wireless emulation, how Colosseum does it, and how to access and use the Colosseum wireless network emulator. We will explain the fundamentals of wireless network emulation, its use for experimental wireless research, and how Colosseum does it at scale and with hardware-in-the-loop. We will describe the Colosseum architecture and its unique emulation system, called MCHEM, and will talk about Radio Frequency (RF) and traffic scenarios in Colosseum and how they capture realistic wireless environments and conditions. + +After the initial overview of Colosseum, attendees will be guided to the usage of the emulator with hands-on experiments on how to access Colosseum and run experiments. The Colosseum containerized system will be explained in detail with hands-on exercises on how to instantiate containers on Colosseum, how to work with them, and how to save them for a later use. We will then show how to run actual experiments using customized containers in Colosseum and its channel emulation system. Practical demonstrations will be given of Colosseum use cases, including WiFi and cellular networking and multi-hop ad hoc networks. + + +## Agenda +### Day 1 +| Time | Topic | +| :---------- | :--------------------------------------------------------------- | +| 9 - 10am | Introduction and Use Cases | +| 10 - 11am | Colosseum Architecture and Emulation System | +| 11am - 12pm | First Time Users – Quick Start Guide | +| 12 - 1pm | Lunch Break | +| 1 - 2pm | Invited Speaker Seminar | +| 2 - 3pm | Hands-on: [Wi-Fi assignment](wifi-assignment/wifi-assignment.md) | + +### Day 2 +| Time | Topic | +| :---------- | :-------------------------------------------------------------------------- | +| 9 - 10am | Colosseum Emulation Scenarios | +| 10 - 11am | LXC Containers (background) and File Proxy Server | +| 11am - 12pm | Interactive Emulations in Colosseum | +| 12 - 1pm | Lunch Break | +| 1 - 2pm | Invited Speaker Seminar | +| 2 - 3pm | Hands-on: [Cellular assignment](cellular-assignment/cellular-assignment.md) | + +### Day 3 +| Time | Topic | +| :----------- | :------------------------------------------ | +| 9 - 10am | Meet at ISEC to Travel to Burlington Campus | +| 10 - 10.30am | Site Visit to Colosseum | +| 10.30 - 11am | Colosseum Evolution | +| 11am - 12pm | Batch Jobs for Extended Offline Emulations | +| 12 - 1pm | Lunch Break | +| 1 - 2pm | Review and Q&A | +| 2 - 3pm | Travel Back to Boston Campus | + + +## Requirements for the attendees + +- The use of Linux-based systems, which is the operating system of most Colosseum components, is advised for hands-on sessions. +Familiarity with basic Linux commands and its command line interface (e.g., ssh, scp/rsync) is recommended. +Basic knowledge of computer networking and wireless concepts is also useful. +- The attendees are required to bring their own laptop for the hands-on sessions. +- The attendees are required to setup in advance their ssh keys (see [Upload SSH Public Keys](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253402-upload-ssh-public-keys)) and ssh proxy (see [SSH Proxy Setup](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253369-ssh-proxy-setup)) +- The attendees are required to verify in advance that they are able to successfully access Colosseum portal and resources (see [Accessing Colosseum Resources](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253362-accessing-colosseum-resources)), e.g., log into the ssh gateway and file-proxy servers. diff --git a/cellular-assignment/cellular-assignment.md b/cellular-assignment/cellular-assignment.md new file mode 100644 index 0000000..196b54b --- /dev/null +++ b/cellular-assignment/cellular-assignment.md @@ -0,0 +1,177 @@ +# Cellular Assignment + +In this assignment, we will use srsLTE (now [srsRAN](https://github.com/srsran/srsRAN)) to instantiate a softwarized cellular network on Colosseum and exchange traffic between the base station and the user(s). + + +## Make a reservation on Colosseum + +1. Connect to Colosseum VPN (instructions [here](https://colosseumneu.freshdesk.com/support/solutions/articles/61000285824-cisco-anyconnect-remote-vpn-access) and login to [Colosseum website](https://experiments.colosseum.net)). +2. Make a reservation with two SRNs with the `srslte-20-04` image (see instructions on [Making a Reservation](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253463-making-a-reservation-interactive-and-batch-mode-)). Call the reservation in a meaningful way (e.g., your name). Two hours should suffice. +3. In the reservation page, you can find the assigned SRNs/nodes and their hostnames by hovering over nodes. At your scheduled reservation time, open four terminals (two for each node). As a convention, the SRN with the lowest ID will be used as a base station; the other SRN as User Equipment (UE). Now, ssh into the assigned Colosseum SRNs[^1],[^2] +(see instructions on [Logging into an SRN](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253366-logging-into-an-srn)): `ssh ` +4. In one of the three terminals, run the following command to start a Colosseum Radio-frequency (RF) scenario through the Colosseum CLI API (see instructions [here](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253397-colosseum-cli)): `colosseumcli rf start 1009 -c`. When the scenario starts, an output similar to the following is returned (time is in UTC): + +``` +Scenario Start Time is 22:30:45 +``` +5. This will engage the Colosseum RF Channel Emulator and make the necessary connections between the USRPs of the reserved nodes based on the parameters set in the specific RF scenario (see the [Scenario Summary List](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000276224-scenarios-summary-list)). In this assignment we will use the [Test Scenario All Paths 0 dB (1009)](https://colosseumneu.freshdesk.com/support/solutions/articles/61000277641-test-scenario-all-paths-0-db-1009). You can check if the RF scenario is active and running by executing the following command: `colosseumcli rf info` + +[^1]: You need to setup your ssh config files by following the instructions in [SSH Proxy Setup](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253369-ssh-proxy-setup). +[^2]: The password for the `srslte-20-04` container is `ChangeMe`. + + +## Configure the cellular nodes + +1. Configure the base station: + - Configure the RF parameters of the base station to match the following parameters. Downlink (DL) and uplink (UL) transmission frequencies need to be compatible with the Colosseum scenario in use. + - `vim /root/radio_code/srslte_config/ue.conf`:

+ + ``` + [rf] + dl_earfcn = 3400 + ul_freq = 1005000000 + dl_freq = 995000000 + tx_gain = 20 + rx_gain = 20 + + time_adv_nsamples = 100 + ``` + +2. Configure the UE: + - On the base station node, read the database configuration of the EPC: `cat /root/radio_code/srslte_config/user_db.csv` + - You will see different entries for different UEs (one per line), for instance:

+ + ``` + ue1,xor,001010123456789,00112233445566778899aabbccddeeff,opc,63bfa50ee6523365ff14c1f45f88737d,8000,0000000012b8,7,dynamic + ue2,mil,001010123456780,00112233445566778899aabbccddeeff,opc,63bfa50ee6523365ff14c1f45f88737d,8000,000000001255,7,dynamic + ``` + + - On the UE node, modify the configuration of the UE. `vim /root/radio_code/srslte_config/ue.conf`: + - Scroll down to the `USIM configuration` section + - Configure the fields to match the configuration of one of the UEs reported in the EPC database. Note that you may need to uncomment the `opc` field. Also, the `imei` field is not registered in the EPC database, feel free to leave it as is. As an example:

+ + ``` + [usim] + mode = soft + algo = mil + opc = 63bfa50ee6523365ff14c1f45f88737d + k = 00112233445566778899aabbccddeeff + imsi = 001010123456780 + imei = 353490069873310 + ``` + + - Check that the APN (found in the `[nas]` section in `ue.conf` file) matches with the one in the `epc.conf` file (`/root/radio_code/srslte_config/epc.conf`), for example:

+ + ``` + apn = colosseum + ``` + + - Configure the RF parameters. DL and UL transmission frequencies need to match those used by the base station (see previous step) and they need to be compatible with the Colosseum scenario in use:

+ + ``` + [rf] + dl_earfcn = 3400 + ul_freq = 1005000000 + dl_freq = 995000000 + freq_offset = 0 + tx_gain = 20 + rx_gain = 20 + + time_adv_nsamples = 100 + ``` + + +## Start the cellular nodes + +1. Start the EPC: + - In the first terminal of the base station/EPC node: + - Move into the directory with the EPC configuration files: `cd /root/radio_code/srslte_config` + - Start the EPC application `srsepc epc.conf` + - The following should appear upon startup of the EPC:

+ + ``` + --- Software Radio Systems EPC --- + + Reading configuration file epc.conf... + HSS Initialized. + MME S11 Initialized + MME GTP-C Initialized + MME Initialized. MCC: 0xf001, MNC: 0xff01 + SPGW GTP-U Initialized. + SPGW S11 Initialized. + SP-GW Initialized. + ``` +2. Start the base station: + - In the second terminal of the base station/EPC node: + - Move into the directory with the base station configuration files: `cd /root/radio_code/srslte_config` + - Start the base station application: `srsenb enb.conf` + - Wait a few moments for the base station to start. In general, the following should be displayed upon startup:

+ + ``` + Setting manual TX/RX offset to 100 samples + Setting frequency: DL=995.0 Mhz, UL=1005.0 MHz for cc_idx=0 + + ==== eNodeB started === + Type to view trace + ``` +3. Start the UE: + - In the terminal of the UE node: + - Move into the directory with the UE configuration files: `cd /root/radio_code/srslte_config` + - Start the UE application: `srsue ue.conf`. Feel free to ignore the following error:

+ + ``` + Waiting PHY to initialize ... /root/radio_code/srsLTE/srsue/src/phy/sync.cc.632: Error stopping AGC: not implemented + ``` + + - Wait a few moments for the UE to start and connect to the base station. An IP address should be returned if the connection is successful. In the remaining of this assignment, we will assume the UE IP is `172.16.0.2` + - The following should appear upon startup of the UE:

+ + ``` + Attaching UE... + Setting manual TX/RX offset to 100 samples + . + Found Cell: Mode=FDD, PCI=1, PRB=15, Ports=1, CFO=-0.3 KHz + Setting manual TX/RX offset to 100 samples + Found PLMN: Id=00101, TAC=7 + Random Access Transmission: seq=51, ra-rnti=0x2 + Random Access Complete. c-rnti=0x46, ta=52 + RRC Connected + Network attach successful. IP: 172.16.0.2 + Software Radio Systems LTE (srsLTE) + ``` + + +## Exchange traffic between base station and UE + +Now that we have instantiated a cellular network on Colosseum, we will exchange traffic between our base station and user. + +1. We will use the `ping` command to confirm reachability of base station and UE: + - Open an additional terminal on the base station and ping the IP address of the UE: `ping 172.16.0.2` + - Optionally open a new terminal on the UE and ping the IP address of the base station: `ping 172.16.0.1` +2. We will use the `iperf3` tool to exchange TCP/UDP traffic between base station and UE: + - On the UE terminal, start an Iperf3 server: `iperf3 -s` + - On the base station terminal, start a TCP client. This client should connect to the UE: `iperf3 -c 172.16.0.2` + - You should see TCP packets being exchanged for 10 seconds. Compare the transmit and receive rates at the base station and UE + - Now do the same but with UDP (parameter `-u` in `iperf3`) and with different source rates (parameter `-b` in `iperf3`) and compare the transmit/receive throughput and packet losses: + - 0.5 Mbps: `iperf3 -c 172.16.0.2 -u -b 0.5M` + - 2 Mbps: `iperf3 -c 172.16.0.2 -u -b 2M` + - 5 Mbps: `iperf3 -c 172.16.0.2 -u -b 5M` + - Compare your findings with the case in which Iperf3 was run in TCP mode. + + +## Terminate the running processes and the Colosseum scenario + +1. In all terminals with running processes on Colosseum, `Ctrl+C` to stop such processes +2. In one of the terminals, stop the Colosseum scenario: `colosseumcli rf stop` +3. Close all open terminals on Colosseum nodes. + + +## Optional + +- Create a new reservation with three nodes and repeat the previous steps. This time connect 2 UEs to the base station and try exchanging traffic between them. +- Create a reservation with two cellular nodes and two Wi-Fi nodes (see [wifi-assignment](../wifi-assignment/wifi-assignment.md)). Configure the Wi-Fi nodes to exchange traffic on the downlink center frequency used by the cellular nodes, while the base station transmits downlink iperf3 traffic to the users. Observe how Wi-Fi and cellular traffic are impacted by the coexistance of these two technologies. + + +## Extra + +Exemplary configurations for base station, EPC and UE can be found in the [example-configurations](example-configurations) directory of this repository. diff --git a/cellular-assignment/example-configurations/drb.conf b/cellular-assignment/example-configurations/drb.conf new file mode 100644 index 0000000..32b6e93 --- /dev/null +++ b/cellular-assignment/example-configurations/drb.conf @@ -0,0 +1,54 @@ + +// All times are in ms. Use -1 for infinity, where available + +qci_config = ( + +{ + qci=7; + pdcp_config = { + discard_timer = 100; + pdcp_sn_size = 12; + } + rlc_config = { + ul_um = { + sn_field_length = 10; + }; + dl_um = { + sn_field_length = 10; + t_reordering = 45; + }; + }; + logical_channel_config = { + priority = 13; + prioritized_bit_rate = -1; + bucket_size_duration = 100; + log_chan_group = 2; + }; +}, +{ + qci=9; + pdcp_config = { + discard_timer = -1; + status_report_required = true; + } + rlc_config = { + ul_am = { + t_poll_retx = 120; + poll_pdu = 64; + poll_byte = 750; + max_retx_thresh = 16; + }; + dl_am = { + t_reordering = 50; + t_status_prohibit = 50; + }; + }; + logical_channel_config = { + priority = 11; + prioritized_bit_rate = -1; + bucket_size_duration = 100; + log_chan_group = 3; + }; +} + +); diff --git a/cellular-assignment/example-configurations/enb.conf b/cellular-assignment/example-configurations/enb.conf new file mode 100644 index 0000000..7aded4e --- /dev/null +++ b/cellular-assignment/example-configurations/enb.conf @@ -0,0 +1,301 @@ +##################################################################### +# srsENB configuration file +##################################################################### + +##################################################################### +# eNB configuration +# +# enb_id: 20-bit eNB identifier. +# mcc: Mobile Country Code +# mnc: Mobile Network Code +# mme_addr: IP address of MME for S1 connnection +# gtp_bind_addr: Local IP address to bind for GTP connection +# s1c_bind_addr: Local IP address to bind for S1AP connection +# n_prb: Number of Physical Resource Blocks (6,15,25,50,75,100) +# tm: Transmission mode 1-4 (TM1 default) +# nof_ports: Number of Tx ports (1 port default, set to 2 for TM2/3/4) +# +##################################################################### +[enb] +enb_id = 0x19B +mcc = 001 +mnc = 01 +mme_addr = 127.0.1.100 +gtp_bind_addr = 127.0.1.1 +s1c_bind_addr = 127.0.1.1 +n_prb = 15 +#tm = 4 +#nof_ports = 2 + +##################################################################### +# eNB configuration files +# +# sib_config: SIB1, SIB2 and SIB3 configuration file +# note: when enabling mbms, use the sib.conf.mbsfn configuration file which includes SIB13 +# rr_config: Radio Resources configuration file +# drb_config: DRB configuration file +##################################################################### +[enb_files] +sib_config = sib.conf +rr_config = rr.conf +drb_config = drb.conf + +##################################################################### +# RF configuration +# +# dl_earfcn: EARFCN code for DL (only valid if a single cell is configured in rr.conf) +# tx_gain: Transmit gain (dB). +# rx_gain: Optional receive gain (dB). If disabled, AGC if enabled +# +# Optional parameters: +# dl_freq: Override DL frequency corresponding to dl_earfcn +# ul_freq: Override UL frequency corresponding to dl_earfcn (must be set if dl_freq is set) +# device_name: Device driver family. Supported options: "auto" (uses first found), "UHD" or "bladeRF" +# device_args: Arguments for the device driver. Options are "auto" or any string. +# Default for UHD: "recv_frame_size=9232,send_frame_size=9232" +# Default for bladeRF: "" +# time_adv_nsamples: Transmission time advance (in number of samples) to compensate for RF delay +# from antenna to timestamp insertion. +# Default "auto". B210 USRP: 100 samples, bladeRF: 27. +##################################################################### +[rf] +dl_earfcn = 3400 +ul_freq = 1005000000 +dl_freq = 995000000 +tx_gain = 20 +rx_gain = 20 + +#device_name = auto +time_adv_nsamples = 100 + +# For best performance in 2x2 MIMO and >= 15 MHz use the following device_args settings: +# USRP B210: num_recv_frames=64,num_send_frames=64 + +# For best performance when BW<5 MHz (25 PRB), use the following device_args settings: +# USRP B210: send_frame_size=512,recv_frame_size=512 + +#device_args = auto +#time_adv_nsamples = auto + +# Example for ZMQ-based operation with TCP transport for I/Q samples +#device_name = zmq +#device_args = fail_on_disconnect=true,tx_port=tcp://*:2000,rx_port=tcp://localhost:2001,id=enb,base_srate=23.04e6 + +##################################################################### +# Packet capture configuration +# +# MAC Packets are captured to file in the compact format decoded by +# the Wireshark mac-lte-framed dissector and with DLT 147. +# To use the dissector, edit the preferences for DLT_USER to +# add an entry with DLT=147, Payload Protocol=mac-lte-framed. +# For more information see: https://wiki.wireshark.org/MAC-LTE +# +# Please note that this setting will by default only capture MAC +# frames on dedicated channels, and not SIB. You have to build with +# WRITE_SIB_PCAP enabled in srsenb/src/stack/mac/mac.cc if you want +# SIB to be part of the MAC pcap file. +# +# S1AP Packets are captured to file in the compact format decoded by +# the Wireshark s1ap dissector and with DLT 150. +# To use the dissector, edit the preferences for DLT_USER to +# add an entry with DLT=150, Payload Protocol=s1ap. +# +# mac_enable: Enable MAC layer packet captures (true/false) +# mac_filename: File path to use for packet captures +# s1ap_enable: Enable or disable the PCAP. +# s1ap_filename: File name where to save the PCAP. +# +##################################################################### +[pcap] +enable = false +filename = /tmp/enb.pcap +s1ap_enable = false +s1ap_filename = /tmp/enb_s1ap.pcap + +##################################################################### +# Log configuration +# +# Log levels can be set for individual layers. "all_level" sets log +# level for all layers unless otherwise configured. +# Format: e.g. phy_level = info +# +# In the same way, packet hex dumps can be limited for each level. +# "all_hex_limit" sets the hex limit for all layers unless otherwise +# configured. +# Format: e.g. phy_hex_limit = 32 +# +# Logging layers: rf, phy, phy_lib, mac, rlc, pdcp, rrc, gtpu, s1ap, all +# Logging levels: debug, info, warning, error, none +# +# filename: File path to use for log output. Can be set to stdout +# to print logs to standard output +# file_max_size: Maximum file size (in kilobytes). When passed, multiple files are created. +# If set to negative, a single log file will be created. +##################################################################### +[log] +all_level = warning +all_hex_limit = 32 +filename = /tmp/enb.log +file_max_size = -1 + +[gui] +enable = false + +##################################################################### +# Scheduler configuration options +# +# max_aggr_level: Optional maximum aggregation level index (l=log2(L) can be 0, 1, 2 or 3) +# pdsch_mcs: Optional fixed PDSCH MCS (ignores reported CQIs if specified) +# pdsch_max_mcs: Optional PDSCH MCS limit +# pusch_mcs: Optional fixed PUSCH MCS (ignores reported CQIs if specified) +# pusch_max_mcs: Optional PUSCH MCS limit +# min_nof_ctrl_symbols: Minimum number of control symbols +# max_nof_ctrl_symbols: Maximum number of control symbols +# +##################################################################### +[scheduler] +#max_aggr_level = -1 +#pdsch_mcs = -1 +#pdsch_max_mcs = -1 +#pusch_mcs = -1 +pusch_max_mcs = 16 +#min_nof_ctrl_symbols = 1 +#max_nof_ctrl_symbols = 3 + +##################################################################### +# eMBMS configuration options +# +# enable: Enable MBMS transmission in the eNB +# m1u_multiaddr: Multicast addres the M1-U socket will register to +# m1u_if_addr: Address of the inteferface the M1-U interface will listen for multicast packets. +# +##################################################################### +[embms] +#enable = false +#m1u_multiaddr = 239.255.0.1 +#m1u_if_addr = 127.0.1.201 + + + +##################################################################### +# Channel emulator options: +# enable: Enable/Disable internal Downlink/Uplink channel emulator +# +# -- AWGN Generator +# awgn.enable: Enable/disable AWGN generator +# awgn.n0: Noise power in dBfs +# +# -- Fading emulator +# fading.enable: Enable/disable fading simulator +# fading.model: Fading model + maximum doppler (E.g. none, epa5, eva70, etu300, etc) +# +# -- Delay Emulator delay(t) = delay_min + (delay_max - delay_min) * (1 + sin(2pi*t/period)) / 2 +# Maximum speed [m/s]: (delay_max - delay_min) * pi * 300 / period +# delay.enable: Enable/disable delay simulator +# delay.period_s: Delay period in seconds. +# delay.init_time_s: Delay initial time in seconds. +# delay.maximum_us: Maximum delay in microseconds +# delay.minumum_us: Minimum delay in microseconds +# +# -- Radio-Link Failure (RLF) Emulator +# rlf.enable: Enable/disable RLF simulator +# rlf.t_on_ms: Time for On state of the channel (ms) +# rlf.t_off_ms: Time for Off state of the channel (ms) +# +# -- High Speed Train Doppler model simulator +# hst.enable: Enable/Disable HST simulator +# hst.period_s: HST simulation period in seconds +# hst.fd_hz: Doppler frequency in Hz +# hst.init_time_s: Initial time in seconds +##################################################################### +[channel.dl] +#enable = false + +[channel.dl.awgn] +#enable = false +#n0 = -30 + +[channel.dl.fading] +#enable = false +#model = none + +[channel.dl.delay] +#enable = false +#period_s = 3600 +#init_time_s = 0 +#maximum_us = 100 +#minimum_us = 10 + +[channel.dl.rlf] +#enable = false +#t_on_ms = 10000 +#t_off_ms = 2000 + +[channel.dl.hst] +#enable = false +#period_s = 7.2 +#fd_hz = 750.0 +#init_time_s = 0.0 + +[channel.ul] +#enable = false + +[channel.ul.awgn] +#enable = false +#n0 = -30 + +[channel.ul.fading] +#enable = false +#model = none + +[channel.ul.delay] +#enable = false +#period_s = 3600 +#init_time_s = 0 +#maximum_us = 100 +#minimum_us = 10 + +[channel.ul.rlf] +#enable = false +#t_on_ms = 10000 +#t_off_ms = 2000 + +[channel.ul.hst] +#enable = false +#period_s = 7.2 +#fd_hz = -750.0 +#init_time_s = 0.0 + + +##################################################################### +# Expert configuration options +# +# pusch_max_its: Maximum number of turbo decoder iterations (Default 4) +# pusch_8bit_decoder: Use 8-bit for LLR representation and turbo decoder trellis computation (Experimental) +# nof_phy_threads: Selects the number of PHY threads (maximum 4, minimum 1, default 2) +# metrics_period_secs: Sets the period at which metrics are requested from the eNB. +# metrics_csv_enable: Write eNB metrics to CSV file. +# metrics_csv_filename: File path to use for CSV metrics. +# pregenerate_signals: Pregenerate uplink signals after attach. Improves CPU performance. +# tx_amplitude: Transmit amplitude factor (set 0-1 to reduce PAPR) +# link_failure_nof_err: Number of PUSCH failures after which a radio-link failure is triggered. +# a link failure is when SNR<0 and CRC=KO +# max_prach_offset_us: Maximum allowed RACH offset (in us) +# eea_pref_list: Ordered preference list for the selection of encryption algorithm (EEA) (default: EEA0, EEA2, EEA1). +# eia_pref_list: Ordered preference list for the selection of integrity algorithm (EIA) (default: EIA2, EIA1, EIA0). +# +##################################################################### +[expert] +#pusch_max_its = 8 # These are half iterations +#pusch_8bit_decoder = false +#nof_phy_threads = 3 +metrics_period_secs = 0.25 +metrics_csv_enable = true +metrics_csv_filename = /tmp/enb_metrics.csv +#pregenerate_signals = false +#tx_amplitude = 0.6 +#link_failure_nof_err = 50 +#rrc_inactivity_timer = 60000 +#max_prach_offset_us = 30 +#eea_pref_list = EEA0, EEA2, EEA1 +#eia_pref_list = EIA2, EIA1, EIA0 diff --git a/cellular-assignment/example-configurations/epc.conf b/cellular-assignment/example-configurations/epc.conf new file mode 100644 index 0000000..ac551cf --- /dev/null +++ b/cellular-assignment/example-configurations/epc.conf @@ -0,0 +1,106 @@ +##################################################################### +# srsEPC configuration file +##################################################################### + +##################################################################### +# MME configuration +# +# mme_code: 8-bit MME code identifies the MME within a group. +# mme_group: 16-bit MME group identifier. +# tac: 16-bit Tracking Area Code. +# mcc: Mobile Country Code +# mnc: Mobile Network Code +# apn: Set Access Point Name (APN) +# mme_bind_addr: IP bind addr to listen for eNB S1-MME connnections +# dns_addr: DNS server address for the UEs +# encryption_algo: Preferred encryption algorithm for NAS layer +# (default: EEA0, support: EEA1, EEA2) +# integrity_algo: Preferred integrity protection algorithm for NAS +# (default: EIA1, support: EIA1, EIA2 (EIA0 not support) +# paging_timer: Value of paging timer in seconds (T3413) +# +##################################################################### +[mme] +mme_code = 0x1a +mme_group = 0x0001 +tac = 0x0007 +mcc = 001 +mnc = 01 +mme_bind_addr = 127.0.1.100 +apn = colosseum +dns_addr = 8.8.8.8 +encryption_algo = EEA0 +integrity_algo = EIA1 +paging_timer = 2 + +##################################################################### +# HSS configuration +# +# db_file: Location of .csv file that stores UEs information. +# +##################################################################### +[hss] +db_file = user_db.csv + +##################################################################### +# SP-GW configuration +# +# gtpu_bind_addr: GTP-U bind address. +# sgi_if_addr: SGi TUN interface IP address. +# sgi_if_name: SGi TUN interface name. +# max_paging_queue: Maximum packets in paging queue (per UE). +# +##################################################################### + +[spgw] +gtpu_bind_addr = 127.0.1.100 +sgi_if_addr = 172.16.0.1 +sgi_if_name = srs_spgw_sgi +max_paging_queue = 100 + +#################################################################### +# PCAP configuration +# +# Packets are captured to file in the compact format decoded by +# the Wireshark s1ap dissector and with DLT 150. +# To use the dissector, edit the preferences for DLT_USER to +# add an entry with DLT=150, Payload Protocol=s1ap. +# +# enable: Enable or disable the PCAP. +# filename: File name where to save the PCAP. +# +#################################################################### +[pcap] +enable = false +filename = /tmp/epc.pcap + +#################################################################### +# Log configuration +# +# Log levels can be set for individual layers. "all_level" sets log +# level for all layers unless otherwise configured. +# Format: e.g. s1ap_level = info +# +# In the same way, packet hex dumps can be limited for each level. +# "all_hex_limit" sets the hex limit for all layers unless otherwise +# configured. +# Format: e.g. s1ap_hex_limit = 32 +# +# Logging layers: nas, s1ap, mme_gtpc, spgw_gtpc, gtpu, spgw, hss, all +# Logging levels: debug, info, warning, error, none +# +# filename: File path to use for log output. Can be set to stdout +# to print logs to standard output +##################################################################### +[log] +all_level = info +all_hex_limit = 32 +filename = /tmp/epc.log + +#nas_level = debug +#s1ap_level = debug +#mme_gtpc_level = debug +#spgw_gtpc_level = debug +#gtpu_level = debug +#spgw_level = debug +#hss_level = debug diff --git a/cellular-assignment/example-configurations/mbms.conf b/cellular-assignment/example-configurations/mbms.conf new file mode 100644 index 0000000..9c2cca0 --- /dev/null +++ b/cellular-assignment/example-configurations/mbms.conf @@ -0,0 +1,47 @@ +##################################################################### +# srsMBMS configuration file +##################################################################### + +##################################################################### +# MBMS-GW configuration +# +# name: MBMS-GW name +# sgi_mb_if_name: SGi-mb TUN interface name +# sgi_mb_if_addr: SGi-mb interface IP address +# sgi_mb_if_mask: SGi-mb interface IP mask +# m1u_multi_addr: Multicast group for eNBs (TODO this should be setup with M2/M3) +# m1u_multi_if: IP of local interface for multicast traffic +# m1u_multi_ttl: TTL for M1-U multicast traffic +# +##################################################################### +[mbms_gw] +name = srsmbmsgw01 +sgi_mb_if_name = sgi_mb +sgi_mb_if_addr = 172.16.0.254 +sgi_mb_if_mask = 255.255.255.255 +m1u_multi_addr = 239.255.0.1 +m1u_multi_if = 127.0.1.200 +m1u_multi_ttl = 1 + +#################################################################### +# Log configuration +# +# Log levels can be set for individual layers. "all_level" sets log +# level for all layers unless otherwise configured. +# Format: e.g. s1ap_level = info +# +# In the same way, packet hex dumps can be limited for each level. +# "all_hex_limit" sets the hex limit for all layers unless otherwise +# configured. +# Format: e.g. s1ap_hex_limit = 32 +# +# Logging layers: mbms_gw, all +# Logging levels: debug, info, warning, error, none +# +# filename: File path to use for log output. Can be set to stdout +# to print logs to standard output +##################################################################### +[log] +all_level = debug +all_hex_limit = 32 +filename = /tmp/mbms.log diff --git a/cellular-assignment/example-configurations/rr.conf b/cellular-assignment/example-configurations/rr.conf new file mode 100644 index 0000000..1f565d4 --- /dev/null +++ b/cellular-assignment/example-configurations/rr.conf @@ -0,0 +1,90 @@ +mac_cnfg = +{ + phr_cnfg = + { + dl_pathloss_change = "dB3"; // Valid: 1, 3, 6 or INFINITY + periodic_phr_timer = 50; + prohibit_phr_timer = 0; + }; + ulsch_cnfg = + { + max_harq_tx = 4; + periodic_bsr_timer = 20; // in ms + retx_bsr_timer = 320; // in ms + }; + + time_alignment_timer = -1; // -1 is infinity +}; + +phy_cnfg = +{ + phich_cnfg = + { + duration = "Normal"; + resources = "1/6"; + }; + + pusch_cnfg_ded = + { + beta_offset_ack_idx = 6; + beta_offset_ri_idx = 6; + beta_offset_cqi_idx = 6; + }; + + // PUCCH-SR resources are scheduled on time-frequeny domain first, then multiplexed in the same resource. + sched_request_cnfg = + { + dsr_trans_max = 64; + period = 20; // in ms + subframe = [1]; // Optional vector of subframe indices allowed for SR transmissions (default uses all) + nof_prb = 0; // number of PRBs on each extreme used for SR (total prb is twice this number) + }; + cqi_report_cnfg = + { + mode = "periodic"; + simultaneousAckCQI = true; + period = 40; // in ms + //subframe = [0, 10, 20, 30]; // Optional vector of subframe indices every period where CQI resources will be allocated (default uses all) + nof_prb = 0; + m_ri = 8; // RI period in CQI period + }; +}; + +cell_list = +( + { + // rf_port = 0; + cell_id = 0x01; + tac = 0x0007; + pci = 1; + // root_seq_idx = 204; + dl_earfcn = 3400; + //ul_earfcn = 21400; + ho_active = false; + + // CA cells + scell_list = ( + // {cell_id = 0x02; cross_carrier_scheduling = false; scheduling_cell_id = 0x02; ul_allowed = true} + ) + + // Cells available for handover + meas_cell_list = + ( + { + eci = 0x19C02; + dl_earfcn = 2850; + pci = 2; + } + ); + + // ReportCfg (only A3 supported) + meas_report_desc = { + a3_report_type = "RSRP"; + a3_offset = 6; + a3_hysteresis = 0; + a3_time_to_trigger = 480; + rsrq_config = 4; + }; + } + // Add here more cells +); diff --git a/cellular-assignment/example-configurations/sib.conf b/cellular-assignment/example-configurations/sib.conf new file mode 100644 index 0000000..5d7b0a0 --- /dev/null +++ b/cellular-assignment/example-configurations/sib.conf @@ -0,0 +1,156 @@ +sib1 = +{ + intra_freq_reselection = "Allowed"; + q_rx_lev_min = -65; + //p_max = 3; + cell_barred = "NotBarred" + si_window_length = 20; + sched_info = + ( + { + si_periodicity = 16; + + // comma-separated array of SIB-indexes (from 3 to 13), leave empty or commented to just scheduler sib2 + si_mapping_info = [ 3 ]; + } + ); + system_info_value_tag = 0; +}; + +sib2 = +{ + rr_config_common_sib = + { + rach_cnfg = + { + num_ra_preambles = 52; + preamble_init_rx_target_pwr = -104; + pwr_ramping_step = 6; // in dB + preamble_trans_max = 10; + ra_resp_win_size = 10; // in ms + mac_con_res_timer = 64; // in ms + max_harq_msg3_tx = 4; + }; + bcch_cnfg = + { + modification_period_coeff = 16; // in ms + }; + pcch_cnfg = + { + default_paging_cycle = 32; // in rf + nB = "1"; + }; + prach_cnfg = + { + root_sequence_index = 128; + prach_cnfg_info = + { + high_speed_flag = false; + prach_config_index = 3; + prach_freq_offset = 0; + zero_correlation_zone_config = 11; + }; + }; + pdsch_cnfg = + { + /* Warning: Currently disabled and forced to p_b=1 for TM2/3/4 and p_b=0 for TM1 + */ + p_b = 1; + rs_power = 0; + }; + pusch_cnfg = + { + n_sb = 1; + hopping_mode = "inter-subframe"; + pusch_hopping_offset = 2; + enable_64_qam = false; // 64QAM PUSCH is not currently enabled + ul_rs = + { + cyclic_shift = 0; + group_assignment_pusch = 0; + group_hopping_enabled = false; + sequence_hopping_enabled = false; + }; + }; + pucch_cnfg = + { + delta_pucch_shift = 2; + n_rb_cqi = 2; + n_cs_an = 0; + n1_pucch_an = 12; + }; + ul_pwr_ctrl = + { + p0_nominal_pusch = -85; + alpha = 0.7; + p0_nominal_pucch = -107; + delta_flist_pucch = + { + format_1 = 0; + format_1b = 3; + format_2 = 1; + format_2a = 2; + format_2b = 2; + }; + delta_preamble_msg3 = 6; + }; + ul_cp_length = "len1"; + }; + + ue_timers_and_constants = + { + t300 = 2000; // in ms + t301 = 100; // in ms + t310 = 1000; // in ms + n310 = 1; + t311 = 1000; // in ms + n311 = 1; + }; + + freqInfo = + { + ul_carrier_freq_present = true; + ul_bw_present = true; + additional_spectrum_emission = 1; + }; + + time_alignment_timer = "INFINITY"; // use "sf500", "sf750", etc. +}; + +sib3 = +{ + cell_reselection_common = { + q_hyst = 2; // in dB + }, + cell_reselection_serving = { + s_non_intra_search = 3, + thresh_serving_low = 2, + cell_resel_prio = 6 + }, + intra_freq_reselection = { + q_rx_lev_min = -61, + p_max = 23, + s_intra_search = 5, + presence_ant_port_1 = true, + neigh_cell_cnfg = 1, + t_resel_eutra = 1 + } +}; + +sib7 = +{ + t_resel_geran = 1; + carrier_freqs_info_list = + ( + { + cell_resel_prio = 0; + ncc_permitted = 255; + q_rx_lev_min = 0; + thresh_x_high = 2; + thresh_x_low = 2; + + start_arfcn = 871; + band_ind = "dcs1800"; + } + ); +}; diff --git a/cellular-assignment/example-configurations/ue.conf b/cellular-assignment/example-configurations/ue.conf new file mode 100644 index 0000000..cb090ff --- /dev/null +++ b/cellular-assignment/example-configurations/ue.conf @@ -0,0 +1,386 @@ +##################################################################### +# srsUE configuration file +##################################################################### + +##################################################################### +# RF configuration +# +# dl_earfcn: Downlink EARFCN code. +# freq_offset: Uplink and Downlink optional frequency offset (in Hz) +# tx_gain: Transmit gain (dB). +# rx_gain: Optional receive gain (dB). If disabled, AGC if enabled +# +# Optional parameters: +# dl_freq: Override DL frequency corresponding to dl_earfcn +# ul_freq: Override UL frequency corresponding to dl_earfcn +# nof_carriers: Number of carriers +# nof_antennas: Number of antennas per carrier (all carriers have the same number of antennas) +# device_name: Device driver family. Supported options: "auto" (uses first found), "UHD" or "bladeRF" +# device_args: Arguments for the device driver. Options are "auto" or any string. +# Default for UHD: "recv_frame_size=9232,send_frame_size=9232" +# Default for bladeRF: "" +# device_args_2: Arguments for the RF device driver 2. +# device_args_3: Arguments for the RF device driver 3. +# time_adv_nsamples: Transmission time advance (in number of samples) to compensate for RF delay +# from antenna to timestamp insertion. +# Default "auto". B210 USRP: 100 samples, bladeRF: 27. +# continuous_tx: Transmit samples continuously to the radio or on bursts (auto/yes/no). +# Default is auto (yes for UHD, no for rest) +##################################################################### +[rf] +dl_earfcn = 3400 +ul_freq = 1005000000 +dl_freq = 995000000 +freq_offset = 0 +tx_gain = 20 +rx_gain = 20 + +#nof_carriers = 1 +#nof_antennas = 1 +time_adv_nsamples = 100 + +# For best performance in 2x2 MIMO and >= 15 MHz use the following device_args settings: +# USRP B210: num_recv_frames=64,num_send_frames=64 + +# For best performance when BW<5 MHz (25 PRB), use the following device_args settings: +# USRP B210: send_frame_size=512,recv_frame_size=512 + +#device_args = auto +#time_adv_nsamples = auto +#continuous_tx = auto + +# Example for ZMQ-based operation with TCP transport for I/Q samples +#device_name = zmq +#device_args = tx_port=tcp://*:2001,rx_port=tcp://localhost:2000,id=ue,base_srate=23.04e6 + +##################################################################### +# Packet capture configuration +# +# Packet capture is supported at both MAC and NAS layers. +# MAC-layer packets are captured to file in the compact format +# decoded by the Wireshark mac-lte-framed dissector. +# To use this dissector, edit the preferences for DLT_USER to +# add an entry with DLT=147, Payload Protocol=mac-lte-framed. +# For more information see: https://wiki.wireshark.org/MAC-LTE +# NAS-layer packets are dissected with DLT=148, and +# Payload Protocol = nas-eps. +# +# enable: Enable MAC layer packet captures (true/false) +# filename: File path to use for MAC packet captures +# nas_enable: Enable NAS layer packet captures (true/false) +# nas_filename: File path to use for NAS packet captures +##################################################################### +[pcap] +enable = false +filename = /tmp/ue.pcap +nas_enable = false +nas_filename = /tmp/nas.pcap + +##################################################################### +# Log configuration +# +# Log levels can be set for individual layers. "all_level" sets log +# level for all layers unless otherwise configured. +# Format: e.g. phy_level = info +# +# In the same way, packet hex dumps can be limited for each level. +# "all_hex_limit" sets the hex limit for all layers unless otherwise +# configured. +# Format: e.g. phy_hex_limit = 32 +# +# Logging layers: rf, phy, mac, rlc, pdcp, rrc, nas, gw, usim, all +# Logging levels: debug, info, warning, error, none +# +# filename: File path to use for log output. Can be set to stdout +# to print logs to standard output +# file_max_size: Maximum file size (in kilobytes). When passed, multiple files are created. +# If set to negative, a single log file will be created. +##################################################################### +[log] +all_level = warning +phy_lib_level = none +all_hex_limit = 32 +filename = /tmp/ue.log +file_max_size = -1 + +##################################################################### +# USIM configuration +# +# mode: USIM mode (soft/pcsc) +# algo: Authentication algorithm (xor/milenage) +# op/opc: 128-bit Operator Variant Algorithm Configuration Field (hex) +# - Specify either op or opc (only used in milenage) +# k: 128-bit subscriber key (hex) +# imsi: 15 digit International Mobile Subscriber Identity +# imei: 15 digit International Mobile Station Equipment Identity +# pin: PIN in case real SIM card is used +# reader: Specify card reader by it's name as listed by 'pcsc_scan'. If empty, try all available readers. +##################################################################### +[usim] +mode = soft +algo = mil +opc = 63bfa50ee6523365ff14c1f45f88737d +k = 00112233445566778899aabbccddeeff +imsi = 001010123456780 +imei = 353490069873310 +#reader = +#pin = 1234 + +##################################################################### +# RRC configuration +# +# ue_category: Sets UE category (range 1-5). Default: 4 +# release: UE Release (8 to 10) +# feature_group: Hex value of the featureGroupIndicators field in the +# UECapabilityInformation message. Default 0xe6041000 +# mbms_service_id: MBMS service id for autostarting MBMS reception +# (default -1 means disabled) +# mbms_service_port: Port of the MBMS service +##################################################################### +[rrc] +#ue_category = 4 +#release = 8 +#feature_group = 0xe6041000 +#mbms_service_id = -1 +#mbms_service_port = 4321 + +##################################################################### +# NAS configuration +# +# apn: Set Access Point Name (APN) +# apn_protocol: Set APN protocol (IPv4, IPv6 or IPv4v6.) +# user: Username for CHAP authentication +# pass: Password for CHAP authentication +# force_imsi_attach: Whether to always perform an IMSI attach +# eia: List of integrity algorithms included in UE capabilities +# Supported: 1 - Snow3G, 2 - AES +# eea: List of ciphering algorithms included in UE capabilities +# Supported: 0 - NULL, 1 - Snow3G, 2 - AES +##################################################################### +[nas] +apn = colosseum +apn_protocol = ipv4 +#user = srsuser +#pass = srspass +#force_imsi_attach = false +#eia = 1,2 +#eea = 0,1,2 + +##################################################################### +# GW configuration +# +# netns: Network namespace to create TUN device. Default: empty +# ip_devname: Name of the tun_srsue device. Default: tun_srsue +# ip_netmask: Netmask of the tun_srsue device. Default: 255.255.255.0 +##################################################################### +[gw] +#netns = +#ip_devname = tun_srsue +#ip_netmask = 255.255.255.0 + +##################################################################### +# GUI configuration +# +# Simple GUI displaying PDSCH constellation and channel freq response. +# (Requires building with srsGUI) +# enable: Enable the graphical interface (true/false) +##################################################################### +[gui] +enable = false + +##################################################################### +# Channel emulator options: +# enable: Enable/Disable internal Downlink/Uplink channel emulator +# +# -- AWGN Generator +# awgn.enable: Enable/disable AWGN generator +# awgn.n0: Noise power in dBfs +# +# -- Fading emulator +# fading.enable: Enable/disable fading simulator +# fading.model: Fading model + maximum doppler (E.g. none, epa5, eva70, etu300, etc) +# +# -- Delay Emulator delay(t) = delay_min + (delay_max - delay_min) * (1 + sin(2pi*t/period)) / 2 +# Maximum speed [m/s]: (delay_max - delay_min) * pi * 300 / period +# delay.enable: Enable/disable delay simulator +# delay.period_s: Delay period in seconds. +# delay.init_time_s: Delay initial time in seconds. +# delay.maximum_us: Maximum delay in microseconds +# delay.minumum_us: Minimum delay in microseconds +# +# -- Radio-Link Failure (RLF) Emulator +# rlf.enable: Enable/disable RLF simulator +# rlf.t_on_ms: Time for On state of the channel (ms) +# rlf.t_off_ms: Time for Off state of the channel (ms) +# +# -- High Speed Train Doppler model simulator +# hst.enable: Enable/Disable HST simulator +# hst.period_s: HST simulation period in seconds +# hst.fd_hz: Doppler frequency in Hz +# hst.init_time_s: Initial time in seconds +##################################################################### +[channel.dl] +#enable = false + +[channel.dl.awgn] +#enable = false +#n0 = -30 + +[channel.dl.fading] +#enable = false +#model = none + +[channel.dl.delay] +#enable = false +#period_s = 3600 +#init_time_s = 0 +#maximum_us = 100 +#minimum_us = 10 + +[channel.dl.rlf] +#enable = false +#t_on_ms = 10000 +#t_off_ms = 2000 + +[channel.dl.hst] +#enable = false +#period_s = 7.2 +#fd_hz = 750.0 +#init_time_s = 0.0 + +[channel.ul] +#enable = false + +[channel.ul.awgn] +#enable = false +#n0 = -30 + +[channel.ul.fading] +#enable = false +#model = none + +[channel.ul.delay] +#enable = false +#period_s = 3600 +#init_time_s = 0 +#maximum_us = 100 +#minimum_us = 10 + +[channel.ul.rlf] +#enable = false +#t_on_ms = 10000 +#t_off_ms = 2000 + +[channel.ul.hst] +#enable = false +#period_s = 7.2 +#fd_hz = -750.0 +#init_time_s = 0.0 + +##################################################################### +# PHY configuration options +# +# rx_gain_offset: RX Gain offset to add to rx_gain to calibrate RSRP readings +# prach_gain: PRACH gain (dB). If defined, forces a gain for the tranmsission of PRACH only., +# Default is to use tx_gain in [rf] section. +# cqi_max: Upper bound on the maximum CQI to be reported. Default 15. +# cqi_fixed: Fixes the reported CQI to a constant value. Default disabled. +# snr_ema_coeff: Sets the SNR exponential moving average coefficient (Default 0.1) +# snr_estim_alg: Sets the noise estimation algorithm. (Default refs) +# Options: pss: use difference between received and known pss signal, +# refs: use difference between noise references and noiseless (after filtering) +# empty: use empty subcarriers in the boarder of pss/sss signal +# pdsch_max_its: Maximum number of turbo decoder iterations (Default 4) +# pdsch_meas_evm: Measure PDSCH EVM, increases CPU load (default false) +# nof_phy_threads: Selects the number of PHY threads (maximum 4, minimum 1, default 2) +# equalizer_mode: Selects equalizer mode. Valid modes are: "mmse", "zf" or any +# non-negative real number to indicate a regularized zf coefficient. +# Default is MMSE. +# correct_sync_error: Channel estimator measures and pre-compensates time synchronization error. Increases CPU usage, +# improves PDSCH decoding in high SFO and high speed UE scenarios. +# sfo_ema: EMA coefficient to average sample offsets used to compute SFO +# sfo_correct_period: Period in ms to correct sample time to adjust for SFO +# sss_algorithm: Selects the SSS estimation algorithm. Can choose between +# {full, partial, diff}. +# estimator_fil_auto: The channel estimator smooths the channel estimate with an adaptative filter. +# estimator_fil_stddev: Sets the channel estimator smooth gaussian filter standard deviation. +# estimator_fil_order: Sets the channel estimator smooth gaussian filter order (even values perform better). +# The taps are [w, 1-2w, w] +# +# snr_to_cqi_offset: Sets an offset in the SNR to CQI table. This is used to adjust the reported CQI. +# +# interpolate_subframe_enabled: Interpolates in the time domain the channel estimates within 1 subframe. Default is to average. +# +# pdsch_csi_enabled: Stores the Channel State Information and uses it for weightening the softbits. It is only +# used in TM1. It is True by default. +# +# pdsch_8bit_decoder: Use 8-bit for LLR representation and turbo decoder trellis computation (Experimental) +# force_ul_amplitude: Forces the peak amplitude in the PUCCH, PUSCH and SRS (set 0.0 to 1.0, set to 0 or negative for disabling) +# +# in_sync_rsrp_dbm_th: RSRP threshold (in dBm) above which the UE considers to be in-sync +# in_sync_snr_db_th: SNR threshold (in dB) above which the UE considers to be in-sync +# nof_in_sync_events: Number of PHY in-sync events before sending an in-sync event to RRC +# nof_out_of_sync_events: Number of PHY out-sync events before sending an out-sync event to RRC +# +##################################################################### +[phy] +#rx_gain_offset = 62 +#prach_gain = 30 +#cqi_max = 15 +#cqi_fixed = 10 +#snr_ema_coeff = 0.1 +#snr_estim_alg = refs +#pdsch_max_its = 8 # These are half iterations +#pdsch_meas_evm = false +#nof_phy_threads = 3 +#equalizer_mode = mmse +#correct_sync_error = false +#sfo_ema = 0.1 +#sfo_correct_period = 10 +#sss_algorithm = full +#estimator_fil_auto = false +#estimator_fil_stddev = 1.0 +#estimator_fil_order = 4 +#snr_to_cqi_offset = 0.0 +#interpolate_subframe_enabled = false +#pdsch_csi_enabled = true +#pdsch_8bit_decoder = false +#force_ul_amplitude = 0 + +#in_sync_rsrp_dbm_th = -130.0 +#in_sync_snr_db_th = 3.0 +#nof_in_sync_events = 10 +#nof_out_of_sync_events = 20 + +##################################################################### +# Simulation configuration options +# +# The UE simulation supports turning on and off airplane mode in the UE. +# The actions are carried periodically until the UE is stopped. +# +# airplane_t_on_ms: Time to leave airplane mode turned on (in ms) +# +# airplane_t_off_ms: Time to leave airplane mode turned off (in ms) +# +##################################################################### +[sim] +#airplane_t_on_ms = -1 +#airplane_t_off_ms = -1 + +##################################################################### +# General configuration options +# +# metrics_csv_enable: Write UE metrics to CSV file. +# +# metrics_period_secs: Sets the period at which metrics are requested from the UE. +# +# metrics_csv_filename: File path to use for CSV metrics. +# +# have_tti_time_stats: Calculate TTI execution statistics using system clock +# +##################################################################### +[general] +#metrics_csv_enable = false +#metrics_period_secs = 1 +#metrics_csv_filename = /tmp/ue_metrics.csv +#have_tti_time_stats = true diff --git a/cellular-assignment/example-configurations/user_db.csv b/cellular-assignment/example-configurations/user_db.csv new file mode 100644 index 0000000..ed36e5c --- /dev/null +++ b/cellular-assignment/example-configurations/user_db.csv @@ -0,0 +1,21 @@ +# +# .csv to store UE's information in HSS +# Kept in the following format: "Name,Auth,IMSI,Key,OP_Type,OP,AMF,SQN,QCI,IP_alloc" +# +# Name: Human readable name to help distinguish UE's. Ignored by the HSS +# IMSI: UE's IMSI value +# Auth: Authentication algorithm used by the UE. Valid algorithms are XOR +# (xor) and MILENAGE (mil) +# Key: UE's key, where other keys are derived from. Stored in hexadecimal +# OP_Type: Operator's code type, either OP or OPc +# OP/OPc: Operator Code/Cyphered Operator Code, stored in hexadecimal +# AMF: Authentication management field, stored in hexadecimal +# SQN: UE's Sequence number for freshness of the authentication +# QCI: QoS Class Identifier for the UE's default bearer. +# IP_alloc: IP allocation stratagy for the SPGW. +# With 'dynamic' the SPGW will automatically allocate IPs +# With a valid IPv4 (e.g. '172.16.0.2') the UE will have a statically assigned IP. +# +# Note: Lines starting by '#' are ignored and will be overwritten +ue2,mil,001010123456780,00112233445566778899aabbccddeeff,opc,63bfa50ee6523365ff14c1f45f88737d,8000,000000001255,7,dynamic +ue1,xor,001010123456789,00112233445566778899aabbccddeeff,opc,63bfa50ee6523365ff14c1f45f88737d,9001,0000000012b8,7,dynamic diff --git a/custom-container-assignment/custom-container-assignment.md b/custom-container-assignment/custom-container-assignment.md new file mode 100644 index 0000000..6388400 --- /dev/null +++ b/custom-container-assignment/custom-container-assignment.md @@ -0,0 +1,109 @@ +# Custom Container Assignment + +In this assignment, we will first customize a container by adding a GUI for [gnuradio](https://www.gnuradio.org/), then we will use this container to stream samples from a USRP device, acting as a transmitter to another USRP device, acting as a receiver. + + +## Pre-requisites + +- Students have set up their ssh keys ([Upload SSH Public Keys](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253402-upload-ssh-public-keys)) and ssh proxy ([SSH Proxy Setup](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253369-ssh-proxy-setup)). +- Students are able to successfully access to Colosseum resources ([Accessing Colosseum Resources](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253362-accessing-colosseum-resources)), e.g., log in to the SSH gateway and file-proxy servers. +- Students are assigned to the Colosseum team “_gladiators_”. +- A Linux environment (E.g., ubuntu) with LXC installed (it should have been done as a class pre-requisite). + + +## Container Customization + +1. In a Linux environment **open a terminal**, and use the following command to transfer the base image from the File Proxy server to a local folder: `rsync -vP -e ssh file-proxy:/share/nas/gladiators/images/base-2104.tar.gz ./`
This will establish a communication over the network and download a container archived image. + +2. Ensure you have the following lines in the files `/etc/subuid` and `/etc/subgid` + ``` + lxd:100000:65536 + root:100000:65536 + ``` + - By using the following command you can open the files and edit them if they are missing the above lines: `sudo gedit /etc/subuid /etc/subgid` + - This step ensures your user has the required privileges to use lxc. + - Ensure the LXD service is running: `sudo systemctl start lxd` + +3. Import the archived image in lxc: `lxc image import base-2104.tar.gz --alias base`
The archived images cannot be readily used by lxc, and they need to be loaded in the system. You can check the available loaded images typing: `lxc image list` + +4. Initialize and launch the container: + ``` + lxc init local:base my-cont + lxc start my-cont + ``` + Containers are **“running instances of images”**. They share all the contents in terms of files and folders of an image, but they can also be modified and their executables can be run. By starting _my-cont_ from the _base_ image we can prepare our software starting from base-1604-nocuda (avoiding to start from scratch) and later commit it in another image which can be treated as an immutable snapshot of the container. (Hence, granting eventually the repeatability of the Colosseum experiments). + +5. You can now log in in the running container with: `lxc exec my-cont /bin/bash`
The above command launches a process (the bash command shell) inside the container _my-cont_. You could launch any program already present in the container, but to see the command line output you need a shell first. + +6. To customize the container, you can start by choosing a new password typing the following command in the container shell: `passwd`
This will be important later on, when you start your reservation on Colosseum and you are prompted with the password for the container. + +7. The process of installing mainstream software is the same of any Ubuntu machine, using the command `apt`. For this assignment, install the gnuradio-companion package: + ``` + apt update + apt install gnuradio gir1.2-gtk-3.0 + ``` + This will install Gnuradio-companion, which is a Graphical User Interface (GUI) for [gnuradio](https://www.gnuradio.org/) and allows the visual composition of signal processing chains. It can readily be used for experiments on Colosseum. + +8. We are ready to commit our changes and stop the container: + ``` + exit + lxc stop my-cont + lxc publish my-cont --alias my_image + lxc image list + ``` + Stopping the container terminates the processes running from its executables and editing its files; it is an important step for avoiding data inconsistency while publishing (committing) the changes.
The publishing takes a snapshot of the container and saves it in a new image. + +9. Export the updated image in an archive: `lxc image export my_image `
To handle and transfer an image we first need to export it in an archived image. + +10. Upload your newly archived image to Colosseum servers: +`rsync -vP -e ssh .tar.gz file-proxy:/share/nas/gladiators/images/`
Colosseum presents to its users the available containers image present in the related group folder. By transferring the archived image in the folder indicated above you are making it available to all users in your group for starting a Colosseum reservation and experiment. + + +## Experimenting with the new container + +1. Login to [Colosseum website](https://experiments.colosseum.net). + +2. Make a reservation with the **** image for two SRNs (see instructions on [Making a Reservation](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253463-making-a-reservation-interactive-and-batch-mode-)). Call the reservation in a meaningful way (e.g., your name). Two hours should suffice. + +3. In the reservation page, you can find the assigned SRNs/nodes and their hostnames by hovering over nodes. At your scheduled reservation time, **open two terminals** and ssh into the assigned Colosseum SRNs +(see instructions on [Logging into an SRN](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253366-logging-into-an-srn)): `ssh -Y `
+ **Note 1**: You need to setup your ssh config files by following the instructions in SSH Proxy Setup (see the pre-requisites section for more information).
+ **Note 2**: The -Y flag allows the use of GUI applications. + +4. In one of the terminals, run the following command to start a Colosseum Radio-frequency (RF) scenario through the Colosseum CLI API (see instructions [here](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253397-colosseum-cli)): `colosseumcli rf start 1009 -c`. When the scenario starts, an output similar to the following is returned (time is in UTC): + ``` + Scenario Start Time is 22:30:45 + ``` + This will engage the Colosseum RF Channel Emulator and make the necessary connections between the USRPs of the reserved nodes based on the parameters set in the specific RF scenario (see the [Scenario Summary List](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000276224-scenarios-summary-list)). In this assignment we will use the [Test Scenario All Paths 0 dB (1009)](https://colosseumneu.freshdesk.com/support/solutions/articles/61000277641-test-scenario-all-paths-0-db-1009). You can check if the RF scenario is active and running by executing the following command: `colosseumcli rf info` + +5. Update the FPGA firmware `./flash_fpga_x310.sh`
This step ensures the correct firmware is present in the Software Defined Radios by flashing its bitfile. + +6. In both terminals, execute the following command to open the GUI (ignore any warnings that might pop up): `gnuradio-companion`
We will use one node as transmitter and the other one as receiver. + +7. In the transmitter GUI: + 1. Create the following graph with blocks: _Signal Source_, _Throttle_, and _UHD: USRP Sink_ (you can search for a block through the lent icon).

![Transmitter Graph](images/transmitter.png) + 2. Double-click on the _Options_ block to open the block settings and specify the _Id_ to “something”.

![Transmitter Options](images/transmitter_options.png) + 3. Double-click on the _Variable_ block and specify a sampling rate Value of 1 MHz (1000000).

![Transmitter Variable](images/transmitter_variable.png) + 4. Double-click on the _Signal Source_ and specify a Triangle waveform.

![Transmitter Signal Source](images/transmitter_signal_source.png) + 5. Double-click on the _UHD: USRP Sink_ block and in the RF Options tab specify a central frequency of 1 GHz (1000000000) and a Channel Gain Value of 100.

![Transmitter USRP Sink](images/transmitter_usrp_sink.png) + +8. In the receiver GUI: + 1. Create the following graph with blocks: _UHD: USRP Source_ and _QT GUI Time Sink_ (you can search for a block through the lent icon).
![Receiver Graph](images/receiver.png) + 2. Double-click on the _Options_ block to open the block settings and specify the _Id_ to “something”.

![Receiver Options](images/receiver_options.png) + 3. Double-click on the _Variable_ block and specify a sampling rate Value of 1 MHz (1000000).

![Receiver Variable](images/receiver_variable.png) + 4. Double-click on the _USRP Source_ block and in the RF Options tab specify a central frequency of 1 GHz (1000000000) and a Channel Gain Value of 100.

![Receiver USRP Source](images/receiver_usrp_source.png) + +9. To start a system, click on the execute button in the setting bar. You will be prompted to save the sketch somewhere before actually start the processing. Save them and start both the receiver and the transmitter. If everything goes as expected, the output should be similar to this.

![Receiver Options](images/output.gif) + +10. To stop the systems, simply close the windows or click the stop button. + +11. Optional: try to change the signal type and the transmission gain and notice any difference that might occur. + + +## Clean up + +This concludes Colosseum Custom Container assignment. After you are done with your experiments, it is good practice to stop the RF scenario by running the following command from within one of the SRN containers and to terminate your reservation from the Colosseum portal: +- `colosseumcli tg stop` +- `colosseumcli rf stop` +- In all terminals, close your ssh connections by typing: `exit` +- Access the Colosseum portal and delete your reservation. diff --git a/custom-container-assignment/images/output.gif b/custom-container-assignment/images/output.gif new file mode 100644 index 0000000..5b32b29 Binary files /dev/null and b/custom-container-assignment/images/output.gif differ diff --git a/custom-container-assignment/images/receiver.png b/custom-container-assignment/images/receiver.png new file mode 100644 index 0000000..135ca53 Binary files /dev/null and b/custom-container-assignment/images/receiver.png differ diff --git a/custom-container-assignment/images/receiver_options.png b/custom-container-assignment/images/receiver_options.png new file mode 100644 index 0000000..2825cbf Binary files /dev/null and b/custom-container-assignment/images/receiver_options.png differ diff --git a/custom-container-assignment/images/receiver_usrp_source.png b/custom-container-assignment/images/receiver_usrp_source.png new file mode 100644 index 0000000..f63439b Binary files /dev/null and b/custom-container-assignment/images/receiver_usrp_source.png differ diff --git a/custom-container-assignment/images/receiver_variable.png b/custom-container-assignment/images/receiver_variable.png new file mode 100644 index 0000000..41305fd Binary files /dev/null and b/custom-container-assignment/images/receiver_variable.png differ diff --git a/custom-container-assignment/images/transmitter.png b/custom-container-assignment/images/transmitter.png new file mode 100644 index 0000000..83492a5 Binary files /dev/null and b/custom-container-assignment/images/transmitter.png differ diff --git a/custom-container-assignment/images/transmitter_options.png b/custom-container-assignment/images/transmitter_options.png new file mode 100644 index 0000000..0f7acda Binary files /dev/null and b/custom-container-assignment/images/transmitter_options.png differ diff --git a/custom-container-assignment/images/transmitter_signal_source.png b/custom-container-assignment/images/transmitter_signal_source.png new file mode 100644 index 0000000..9702168 Binary files /dev/null and b/custom-container-assignment/images/transmitter_signal_source.png differ diff --git a/custom-container-assignment/images/transmitter_usrp_sink.png b/custom-container-assignment/images/transmitter_usrp_sink.png new file mode 100644 index 0000000..38dbdb5 Binary files /dev/null and b/custom-container-assignment/images/transmitter_usrp_sink.png differ diff --git a/custom-container-assignment/images/transmitter_variable.png b/custom-container-assignment/images/transmitter_variable.png new file mode 100644 index 0000000..5cf6478 Binary files /dev/null and b/custom-container-assignment/images/transmitter_variable.png differ diff --git a/images/colosseum-1.jpg b/images/colosseum-1.jpg new file mode 100644 index 0000000..bbe386a Binary files /dev/null and b/images/colosseum-1.jpg differ diff --git a/images/colosseum-2.jpg b/images/colosseum-2.jpg new file mode 100644 index 0000000..7b7a89a Binary files /dev/null and b/images/colosseum-2.jpg differ diff --git a/wifi-assignment/images/uhd-tone-example.png b/wifi-assignment/images/uhd-tone-example.png new file mode 100644 index 0000000..aec5d5c Binary files /dev/null and b/wifi-assignment/images/uhd-tone-example.png differ diff --git a/wifi-assignment/images/wifi-modem-example.png b/wifi-assignment/images/wifi-modem-example.png new file mode 100644 index 0000000..6339e00 Binary files /dev/null and b/wifi-assignment/images/wifi-modem-example.png differ diff --git a/wifi-assignment/images/wifi-tgen-example.png b/wifi-assignment/images/wifi-tgen-example.png new file mode 100644 index 0000000..de2538f Binary files /dev/null and b/wifi-assignment/images/wifi-tgen-example.png differ diff --git a/wifi-assignment/wifi-assignment.md b/wifi-assignment/wifi-assignment.md new file mode 100644 index 0000000..be3fec6 --- /dev/null +++ b/wifi-assignment/wifi-assignment.md @@ -0,0 +1,75 @@ +# Wi-Fi Assignment + +In this assignment, we will use a GNU Radio [IEEE 802.11 a/g/p transceiver](https://github.com/bastibl/gr-ieee802-11) to instantiate a Wi-Fi-enabled ad hoc network on Colosseum and exchange traffic between the Wi-Fi nodes. + + +## Make a reservation on Colosseum + +1. Connect to Colosseum VPN (instructions [here](https://colosseumneu.freshdesk.com/support/solutions/articles/61000285824-cisco-anyconnect-remote-vpn-access) and login to [Colosseum website](https://experiments.colosseum.net)). +2. Make a reservation with two SRNs with the `webinar-interactive-v1` image (see instructions on [Making a Reservation](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253463-making-a-reservation-interactive-and-batch-mode-)). +Call the reservation in a meaningful way (e.g., your name). Two hours should suffice. +3. In the reservation page, you can find the assigned SRNs/nodes and their hostnames by hovering over nodes. +At your scheduled reservation time, open two terminals and ssh into the assigned Colosseum SRNs[^1],[^2] +(see instructions on [Logging into an SRN](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253366-logging-into-an-srn)): `ssh ` +4. In one of the terminals, run the following command to start a Colosseum Radio-frequency (RF) scenario through the Colosseum CLI API (see instructions [here](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253397-colosseum-cli)): `colosseumcli rf start 1009 -c`. +When the scenario starts, an output similar to the following is returned (time is in UTC): + ``` + Scenario Start Time is 22:30:45 + ``` +5. This will engage the Colosseum RF Channel Emulator and make the necessary connections between the USRPs of the reserved nodes based on the parameters set in the specific RF scenario (see the [Scenario Summary List](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000276224-scenarios-summary-list)). +In this assignment we will use the [Test Scenario All Paths 0 dB (1009)](https://colosseumneu.freshdesk.com/support/solutions/articles/61000277641-test-scenario-all-paths-0-db-1009). +You can check if the RF scenario is active and running by executing the following command: `colosseumcli rf info`. + +[^1]: You need to setup your ssh config files by following the instructions in [SSH Proxy Setup](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253369-ssh-proxy-setup). +[^2]: The password for the `webinar-interactive-v1` container is `sunflower`. + + +## Verifying the RF emulator is setup properly + +In this step, we will verify that Colosseum RF emulator has been setup correctly. + +1. In both terminals, cd to the `/root/utils` directory. +Execute the `uhd_tx_tone.sh` script in the first terminal, and the `uhd_rx_fft.sh` in the second one. +This will send a tone at a set frequency (1.01 GHz in this example) from the first SRN and it will display a spectrum analyzer in the second SRN. +If the RF emulator is set appropriately as explained in the previous section, the signal generated by the first SRN (left terminal in the figure below) will propagate through Colosseum RF emulator and reach the second SRN (right terminal). +The results should look similar to:

![UHD tone example](images/uhd-tone-example.png) + +2. Hit `Ctrl+C` in both terminals to stop the `uhd_tx_tone.sh` and `uhd_rx_fft.sh` example scripts. +3. Optional: edit `uhd_tx_tone.sh` file to change the center frequency to 0.9 GHz. +Repeat Step 1 and compare the results. + + +## Start the Wi-Fi nodes + +1. For each SRN, cd to the `/root/interactive-scripts` directory and execute the `tap_setup.sh` script to setup a tap interface for the SRN (see [Traffic Generation](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253508-traffic-generation) for more information on routing traffic in Colosseum): `/root/interactive_scripts/tap_setup.sh` +2. For each SRN, execute the `route_setup.sh` file (located in the `/root/interactive-scripts` directory) to setup the routing tables: `/root/interactive_scripts/route_setup.sh `. +In each of the SRN, you need to setup the route to the other SRN. The SRN IDs are created by adding 100 to the SRN number assigned to your reservation. As an example, SRN-015 will have ID 115, hence the `tr0` IP address of this node will be 192.168.115.1. In this example, the above command becomes: `/root/interactive_scripts/route_setup.sh 115`. +3. In each SRN, execute the `modem_start.sh` script to start the Wi-Fi modem: `/root/interactive_scripts/modem_start.sh`. +If the interfaces and routes are setup correctly, the results should look similar to:

![Wi-Fi modem example](images/wifi-modem-example.png) + +4. Now, open two new terminals and ssh into the same SRNs as before (this is to keep the other terminals with the modem running). +From each SRN, in the newly opened terminals, ping the `tr0` interface of the other SRN: `ping 192.168..1`. +This transmits ICMP packets over the RF emulator. +If the ping is successful, it means that you have configured your SRNs in the correct way and you have an emulated channel between them. +5. Hit `Ctrl+C` to stop the ping in both SRNs. + + +## Start Colosseum Traffic Generator (TGEN) + +1. In one of the terminals, execute the following command to start a traffic scenario: `colosseumcli tg start 10090` +2. This will engage the Colosseum [Traffic Generator (TGEN)](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000253508-traffic-generation) and start packet flows between Colosseum and the SRNs of your reservation based on the parameters specified in the traffic scenario (see [Scenarios Summary List](https://colosseumneu.freshdesk.com/en/support/solutions/articles/61000276224-scenarios-summary-list)). You can check if the traffic scenario is active (and running) by executing the following command: `colosseumcli tg info` +3. Now you can monitor the packet flow on the `tr0` interface of each SRN by running the following command on each of them: `tcpdump -i tr0`. +Note that it takes a few minutes (~5 mins) for TGEN to initialize the traffic scenario and start transmitting packets to the SRNs. +In the container used in this assignment, a correctly-configured SRN will forward the packets to the other SRN through the RF channel emulator. +A bidirectional transmit/receive flow of packets can be seen in the output of the above tcpdump command:

![Wi-Fi TGEN tcpdump example](images/wifi-tgen-example.png) + +4. Hit `Ctrl+C` in all four terminals to stop the Wi-Fi applications and the tcpdump. + + +## Clean up + +This concludes Colosseum Wi-Fi assignment. After you are done with your experiments, it is good practice to stop the traffic and RF scenarios by running the following command from within one of the SRN containers and to terminate your reservation from the Colosseum portal: +- `colosseumcli tg stop` +- `colosseumcli rf stop` +- In all terminals, close your ssh connections by typing: `exit` +- Access the Colosseum portal and delete your reservation.