First Time Users: Running a Basic Interactive Job
=================================================

This page provides a hands-on practice for first time Colosseum users to gain experience with Colosseum Interactive Mode of operation. By following the steps below, users will be able to experiment with a wifi transceiver that send/receives packet through a fixed-gain RF scenario emulated by Colosseum RF channel emulator.

Prerequisites
~~~~~~~~~~~~~

- Setup the :doc:`Colosseum VPN </getting_started/cisco_anyconnect_remote_vpn_access>` on your local machine
- Users have setup their ssh keys (:doc:`Upload SSH Public Keys </getting_started/upload_ssh_keys>`) and ssh proxy (:doc:`SSH Proxy Setup </getting_started/ssh_proxy_setup>`)
- Users are able to successfully access to Colosseum resources (:doc:`Accessing Colosseum Resources </getting_started/accessing_colosseum_resources>`), e.g., log in to the SSH gateway and file-proxy servers.

Interactive Mode Experiment Practice
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Follow these steps to practice the interactive jobs.

1. Login to user website at https://experiments.colosseum.net
2. Make a reservation with the ``webinar-interactive-v1`` image for two SRNs. (see instructions on :doc:`Making a Reservation </reservations/making_a_reservation_interactive_and_batch_mode>`)

.. figure:: /_static/resources/tutorial/interactive/new_reservation.png
   :width: 600px
   :alt: Colosseum Reservation
   :align: center

3. In the reservation page, you can find the assigned SRNs/nodes and their hostnames by hovering over nodes (in this example SRN-13 with hostname wineslab-013 and SRN-15 with hostname wineslab-015).

.. figure:: /_static/resources/tutorial/interactive/reservation_overview.png
   :width: 600px
   :alt: Colosseum Reservation
   :align: center

At your scheduled reservation time, open two terminals and ssh into the assigned SRNs. (see instructions on :doc:`Logging into an SRN </getting_started/logging_into_an_srn>`)

.. code-block:: bash

   ssh wineslab-013

and ssh into SRN-15 in another terminal by running:

.. code-block:: bash

   ssh wineslab-015

.. note::
   It is assumed that users have setup their ssh config files by following the instructions in :doc:`SSH Proxy Setup </getting_started/ssh_proxy_setup>` (see the pre-requisites section for more information).

.. note::
   The password for the ``webinar-interactive-v1`` container is ``sunflower``

.. figure:: /_static/resources/tutorial/interactive/login.png
   :width: 600px
   :alt: SRN Login
   :align: center

4. From inside one of the containers, run the following command to start a RF scenario (:doc:`Colosseum CLI </radio_api_traffic/colosseum_cli>`).

.. code-block:: bash

   colosseumcli rf start 1009 -c

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 (:doc:`Scenarios Page </scenarios/index>`). In this practice we use the Test Scenario All Paths 0 db (1009). Users can check if the RF scenario is active and running by executing the following command:

.. code-block:: bash

   colosseumcli rf info

.. figure:: /_static/resources/tutorial/interactive/rf_info.png
   :width: 600px
   :alt: RF Info
   :align: center

5. In both terminals, cd to ``~/utils`` and run the ``uhd_tx_tone.sh`` in one container and ``uhd_rx_fft.sh`` in the other one:

This will send a tone at a defined frequency (1.01 GHz in this example) from one SRN and will display a spectrum analyzer in the other SRN.

In our example, from within SRN-13 we execute:

.. code-block:: bash

   ~/utils/uhd_tx_tone.sh

and from within SRN-15 we execute:

.. code-block:: bash

   ~/utils/uhd_rx_fft.sh

.. figure:: /_static/resources/tutorial/interactive/fft.png
   :width: 600px
   :alt: UHD FFT
   :align: center

If the USRPs function properly and the RF emulator is set appropriately as explained in Step 4, the signal generated by the SRN on the left side will propagate through the RF emulator system and reach the SRN on the right side.

.. figure:: /_static/resources/tutorial/interactive/tone.png
   :width: 600px
   :alt: UHD Tone
   :align: center

Hit ``Ctrl+c`` in both terminals to stop the ``uhd_tx_tone.sh`` and ``uhd_rx_fft.sh`` example scripts.

**Optional:** Users can edit the ``uhd_tx_tone.sh`` file to change the center frequency, repeat **Step 5** and see the results.

6. In both terminals, cd to ``~/interactive-scripts`` and execute the ``tap_setup.sh`` file to setup a tap interface for each of the SRNs (see :doc:`Traffic Generation </radio_api_traffic/traffic_generation>` for more information on routing traffic in Colosseum):

.. code-block:: bash

   ~/interactive_scripts/tap_setup.sh

.. figure:: /_static/resources/tutorial/interactive/tap_setup.png
   :width: 600px
   :alt: Tap Setup
   :align: center

7. In both terminals, execute the following ``route_setup.sh`` file (located in the ``~/interactive-scripts`` directory) to setup the route tables for each of the SRNs:

.. code-block:: bash

   ~/interactive_scripts/route_setup.sh 

.. note::
   In each of the SRNs you need to setup the route to the other SRNs. In our example we set the route to SRN-15 from inside container of SRN-13, and vice versa. Note that the SRN IDs are created by adding 100 to the SRN number assigned to your reservation, e.g., SRN-15 will have SRN ID of 115, and hence the tr0 IP address of this node will be 192.168.115.1.

.. figure:: /_static/resources/tutorial/interactive/route_setup.png
   :width: 600px
   :alt: Route Setup
   :align: center

8. Execute the ``modem_start.sh`` to start a WiFi modem in both of the SRNs.

.. code-block:: bash

   ~/interactive_scripts/modem_start.sh

.. figure:: /_static/resources/tutorial/interactive/modem_start.png
   :width: 600px
   :alt: Modem Start
   :align: center

If the USRPs work properly and the interfaces and routes are established appropriately, the results should look like:

.. figure:: /_static/resources/tutorial/interactive/wifi_modem.png
   :width: 600px
   :alt: WiFi Modem
   :align: center

9. Now, open two new terminals and ssh into the same SRNs (this is to keep the other terminals with the modem running). From inside both containers and in the newly opened terminals, ping the tr0 interface of the other node. This essentially send ping traffic over the RF emulator, and if the ping is successful it means that you have set up everything correctly in your SRNs and have a RF emulated channel between the nodes with the specific channel characteristics as defined in your chosen RF scenario (in this case Test Scenario All Paths 0 db (1009)).

From SRN-13:

.. code-block:: bash

   webinar-interactive-v1-srn13:~# ping 192.168.115.1

From SRN-15:

.. code-block:: bash

   webinar-interactive-v1-srn15:~# ping 192.168.113.1

.. figure:: /_static/resources/tutorial/interactive/wifi_modem_2.png
   :width: 600px
   :alt: WiFi Modem 2
   :align: center

Hit ``Ctrl+c`` to stop the ping in both SRNs.

10. From one of the terminals start a traffic scenario with the following command:

.. code-block:: bash

   colosseumcli tg start 10090

This will engage the Colosseum Traffic Generator TGEN (:doc:`Traffic Generation </radio_api_traffic/traffic_generation>`) and make the necessary connections between the TGEN and the reserved nodes based on the parameters set in the specific Traffic scenario (:doc:`Scenarios Summary Page </scenarios/index>`). In this practice we use the Test Scenario All Paths 0 db (1009). Users can check if the Traffic scenario is active and running by executing the following command:

.. code-block:: bash

   colosseumcli tg info

.. figure:: /_static/resources/tutorial/interactive/tg_info.png
   :width: 600px
   :alt: TG Info
   :align: center

Now you can monitor the traffic flow on the tr0 interface of both SRNs by running the following command:

.. code-block:: bash

   tcpdump -i tr0

.. figure:: /_static/resources/tutorial/interactive/tcpdump.png
   :width: 600px
   :alt: TCP Dump
   :align: center

.. note::
   It takes a few minutes (~5 mins) for the TGEN to start sending packets to each SRN, and if the SRN is set up appropriately, it will forward the packets to the other SRN through the RF channel emulator. A bidirectional send/receive flow of packets can be seen in the output of tcpdump command.

.. figure:: /_static/resources/tutorial/interactive/tcpdump_2.png
   :width: 600px
   :alt: TCP Dump 2
   :align: center

Hit ``Ctrl+c`` in all four terminals to stop the modem and the tcpdump.

This concludes the Colosseum interactive job practice. After you are done with you experiment, it is good practice to stop the Traffic and RF scenarios by running the following command from within one of the SRN containers:

.. code-block:: bash

   colosseumcli tg stop
   colosseumcli rf stop

Now you can safely exit your ssh connection from all terminals by executing and exit command:

.. code-block:: bash

   exit