[[Include(WikiToC)]]

== Basic usage ==

=== Description ===
In this tutorial we'll demonstrate how to navigate from the COSMOS sandbox to a single SDR on a node and run an application to read samples from the SDR.

=== Prerequisites ===
In order to access the test bed, create a reservation and have it approved by the reservation service. Access to the resources are granted after the reservation is confirmed. Please follow the process shown on [wiki:CosmosOverview/Workflow the COSMOS work flow page] to get started. 

=== Resources required ===
This tutorial can be run from sb1.cosmos-lab.org using one SDR - either a PCIe-based USRP 2974 or the network based N310.

=== Tutorial Setup ===

Follow the steps below to gain access to this console and set up your node with an appropriate image. 

{{{#!td colspan=2
 1. Sign up for a [https://cosmos-lab.org/portal-2/ COSMOS account].
 2. [GettingStarted#MakeaReservation Create a resource reservation] for sandbox 1.
 3. Once reservation is approved, [wiki:GettingStarted#LogintoyourReservation login into the console].
 4. Use OMF commands to [GettingStarted#ControlResourceswithOMF load baseline-uhd.ndz image] on your resource. Based on the type of SDR used follow the corresponding column. 
}}}
|-
{{{#!td align=left style="background: #abd"
 USRP2974
}}}
{{{#!td align=left style="background: #acd"
 N310
}}}
|-
{{{#!td style="background: #abd"
 {{{#!shell 
 omf load -i baseline-uhd.ndz -t sdr2-s1-lg1
 }}}
}}}
{{{#!td style="background: #acd"
 {{{#!shell
 omf load -i baseline-uhd.ndz -t srv1-lg1
 }}}
}}}
|-
{{{#!td colspan=2
 5. Once the node is successfully imaged, turn it on and check the status.
}}}
|-
{{{#!td align=left style="background: #abd"
 USRP2974
}}}
{{{#!td align=left style="background: #acd"
 N310
}}}
|-
{{{#!td style="background: #abd"
 {{{#!shell 
 omf tell -a on -t sdr2-s1-lg1
 omf stat -t sdr2-s1-lg1
 }}}
}}}
{{{#!td  style="background: #acd"
 {{{#!shell
 omf tell -a on -t srv1-lg1
 omf stat -t srv1-lg1
 }}}
}}}
|-
{{{#!td colspan=2
 6. After giving it some time to power up and boot, ssh to the node
}}}
|-
{{{#!td align=left style="background: #abd"
 USRP2974
}}}
{{{#!td align=left style="background: #acd"
 N310
}}}
|-
{{{#!td style="background: #abd"
 {{{#!shell 
 ssh root@sdr2-s1-lg1
 }}}
 When opening a terminal into console.sb1.cosmos-lab.org [wiki:/UserGuide/RemoteAccess/SshTunnel set up a tunnel] from localhost:5002 to sdr2-s1-lg1.sb1.cosmos-lab.org:9002. This will be used by the web app to connect to a server running on the USRP 2974(Krypton)'s host. 
}}}
{{{#!td style="background: #acd"
 {{{#!shell
 ssh root@srv1-lg1
 }}}
 When opening a terminal into console.sb1.cosmos-lab.org [wiki:/UserGuide/RemoteAccess/SshTunnel set up a tunnel] from localhost:5002 to srv1-lg1.sb1.cosmos-lab.org:9002.
 This will be used by the web app to connect to a server running on the srv1-lg1. 
}}}

=== Experiment Execution ===

==== Configure and detect the radio ====

The USRP 2974 is a PCIe based SDR while the N310 is network based. The instructions are slightly different for setting up communications to each type of SDR. Please follow the appropriate column.

{{{#!td align=left style="background: #abd"
 USRP2974
}}}
{{{#!td align=left style="background: #acd"
 N310
}}}
|-
{{{#!td style="background: #abd"
* The USRP 2974 requires a PCIe driver to control the FPGA with the embedded PC. In the provided images, this will load automatically on boot. If it has issues, you can run it manually via
{{{#!shell
systemctl restart niusrprio.service
}}}

 Detailed steps for driver installation and radio detection are on the [Resources/Notes/KryptonUsage Krypton usage page]. There is also a trouble shooting section at the bottom on that page to update the Krypton's internal firmware if necessary.

* Run ''uhd_find_devices' and check if the X310 is detected
{{{#!shell
uhd_find_devices --args="type=x300"
}}}

* Use the ''uhd_usrp_probe'' command to get more details on the x300. Specifying ''resource=rio0'' ensures only the directly connected radio is probed, instead of the radios on the network.
{{{#!shell
uhd_usrp_probe --args="resource=rio0,type=x300"
}}}

 }}}
{{{#!td  style="background: #acd"
* The N310 requires a network interface for control. Setting up this interface is done with the standard network tools. Detailed instructions are provided on the [wiki:Resources/Notes/N310Usage N310 usage page].

* Display all the network interfaces 
{{{#!shell
ifconfig -a
}}}
* Configure the interface and network buffers
{{{#!shell
ifconfig eno1 10.115.1.1 netmask 255.255.0.0 mtu 8000
sysctl -w net.core.wmem_max=62500000
sysctl -w net.core.rmem_max=62500000
}}}


* Run ''uhd_find_devices' to find all the network based SDRs
{{{#!shell
uhd_find_devices --args="type=n3xx"
}}}

* Use the ''uhd_usrp_probe'' command to get more details.
{{{#!shell
uhd_usrp_probe --args="mgmt_addr=10.113.2.1,addr=10.115.2.1"
}}}


}}}





==== Configure and run the application ====
* Go back to SandBox1 console, download the application source code from the attachment section below and copy it to the SDR.
{{{#!shell-session
username@console:~$ wget https://wiki.cosmos-lab.org/raw-attachment/wiki/Tutorials/Wireless/BasicUsage/spectrum_view.tar.gz
username@console:~$ scp spectrum_view.tar.gz root@sdr2-s1-lg1:~/
}}}

* Untar the source code.
{{{#!shell-session
root@sdr2-s1-lg1:~# tar -zxvf spectrum_view.tar.gz
root@sdr2-s1-lg1:~# cd SPECTRUM_VIEW
}}}

* Please refer to the README file in SPECTRUM_VIEW directory for instructions on compiling and running the application. Before compiling install a few required libraries.
{{{#!shell-session
root@sdr2-s1-lg1:~/SPECTRUM_VIEW# apt update
root@sdr2-s1-lg1:~/SPECTRUM_VIEW# apt-get -y install libboost-program-options-dev libboost-system-dev libboost-thread-dev libboost-filesystem-dev libboost-regex-dev liblog4cxx-dev cmake libfftw3-dev libxml2-dev libpopt-dev libsqlite3-dev pkg-config libxml2-utils gnulib
}}}


* Now compile and make the websocket library.
{{{#!shell-session
root@sdr2-s1-lg1:~/SPECTRUM_VIEW# make websock
}}}

* Lastly compile the application - this will generate the executable ''app_read_sdr_samples'' that reads samples from the SDR.
{{{#!shell-session
root@sdr2-s1-lg1:~/SPECTRUM_VIEW# make
}}}

* Run the application - this will start a server that listens for commands to configure the radio and stream received spectrum samples.
{{{#!shell-session
root@sdr2-s1-lg1:~/SPECTRUM_VIEW# ./app_read_sdr_samples
. INFO  21:17:51.808 (main.cpp:649) - Starting command server at 5180
 INFO  21:17:51.808 (main.cpp:171) - Starting websock server at 9002
.....
}}}


==== Visualize spectrum samples  ====
* Download the spectrum visualizer web client to your desktop. It is all in another zip file - ''spectrum_view.zip''. Unzip this folder and open ''spectrum_view.html'' in a Chrome browser.

 When the viewer is first opened, the page display should be similar to the following
 || [[Image(wiki:Tutorials/Wireless/BasicUsage:basic_usage_spectrum_view_1.png, width=500px)]] ||

{{{#!td align=left style="background: #abd"
 USRP2974
}}}
{{{#!td align=left style="background: #acd"
 N310
}}}
|-
{{{#!td align=left style="background: #abd"
* Set the localhost field to ''localhost:5002''. (Recall from the set up section to create a tunnel from localhost:5002 to sdr2-s1-lg1.sb1.cosmos-lab.org:9002 since the ''app_read_sdr_samples'' application has a websock server listening on that address:port.)

 Set the device type field to ''type=x300''.
}}}
{{{#!td align=left style="background: #acd"
* Set the localhost field to ''localhost:5002''. (Recall from the set up section to create a tunnel from localhost:5002 to srv1-lg1.sb1.cosmos-lab.org:9002 since the ''app_read_sdr_samples'' application has a websock server listening on that address:port.)

 Set the device type field to ''type=n3xx''.
}}}



 Click the ''connect'' button once and a "Websocket Connection" statement should be output by the application.

 Now click on ''make'' to create a device handle.

 The RF radio parameters are already populated with default values for 2.4 GHz WIFI band. To view other active spectrum bands change the RATE, FREQ, GAIN fields.

 || RF Parameter || value || description || 
 || RATE || 25e6 || Sampling rate ||
 || FREQ || 2400e6 || Center frequency ||
 || GAIN || 30 || Receive gain ||
 Then click on ''Submit'' to update the SDR.

 Click on the ''Halted'' button to begin streaming samples from the radio to the browser. The button should change to ''Running'. This should display the spectrum if all went well.
 || [[Image(wiki:Tutorials/Wireless/BasicUsage:basic_usage_spectrum_wifi_sb1.png, width=500px)]] ||


==== Troubleshooting ====
* Check the troubleshooting section in the [https://wiki.cosmos-lab.org/wiki/Resources/Notes/KryptonUsage Krypton usage page] for common errors.