[[Include(WikiToC)]]

== GNURadio CFO Estimation tutorial ==

=== Description ===

This tutorial illustrates the use of GNURadio flowgraphs to estimate the Carrier Frequency offset between a pair of USRPs in COSMOS, ORBIT testbeds. 


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

=== Resources required ===
2 USRPs in COSMOS or ORBIT testbed, 2 host nodes, and 2 mmWave devices(if using mmWave) are required.  
This page uses the 28GHz IBM mmWave devices in [https://wiki.cosmos-lab.org/wiki/Architecture/Domains/cosmos_sb1 sb1.cosmos-lab.org]. As shown in the [https://wiki.cosmos-lab.org/wiki/Tutorials/Wireless/mmwavePaamBasics basic tutorial for IBM 28GHz devices], the current connections in SB1 are as shown in this [https://wiki.cosmos-lab.org/wiki/Architecture/Domains/cosmos_sb1#RFPathConfigurationsformmWaveDevelopmentPlatforms diagram]
* {{{sdr1-in1}}} RF2 TX/RX -- {{{rfdev4-in1}}} all ICs/TX/H, {{{sdr1-in1}}} RF2 RX2 -- {{{rfdev4-in1}}} all ICs/RX/H
* {{{sdr1-in1}}} RF3 TX/RX -- {{{rfdev4-in1}}} all ICs/TX/V, {{{sdr1-in1}}} RF3 RX2 -- {{{rfdev4-in1}}} all ICs/RX/V
* {{{sdr1-in2}}} RF2 TX/RX -- {{{rfdev4-in2}}} all ICs/TX/H, {{{sdr1-in2}}} RF2 RX2 -- {{{rfdev4-in2}}} all ICs/RX/H
* {{{sdr1-in2}}} RF3 TX/RX -- {{{rfdev4-in2}}} all ICs/TX/V, {{{sdr1-in2}}} RF2 RX2 -- {{{rfdev4-in2}}} all ICs/RX/V

Hence, the resources required to execute this tutorial are rfdev4-in1, rfdev4-in2 (IBM PAAMs), sdr1-in1, sdr1-in2 (USRP N310s), srv1-lg1, srv2-lg1 in sb1.cosmos-lab.org.

=== Tutorial Setup ===

Follow the steps below to gain access to the sandbox console and set up nodes with appropriate images.
 1. If you don't have one already, sign up for a [https://www.cosmos-lab.org/portal-2/ COSMOS account]
 1. [wiki:/GettingStarted#MakeaReservation Create a resource reservation] on COSMOS SB1
 1. [Documentation/Short/Login Login] into sandbox console ({{{console.sb1.cosmos-lab.org}}} with two SSH sessions. 
 1. Make sure all the nodes and devices used in the experiment are turned off. 
    {{{#!shell
    omf tell -a offh -t sdr1-in1,sdr1-in2,rfdev4-in1,rfdev4-in2,srv1-lg1,srv2-lg1
    }}}
 1. Use the {{{gnuradio_ofdm.ndz}}} node image with Ubuntu 20.04, UHD 4.4, gnuradio 3.9, and a grc example used in this tutorial. Load {{{gnuradio_ofdm.ndz}}} on the servers.  
    {{{#!shell
    omf load -i gnuradio_ofdm.ndz -t srv1-lg1,srv2-lg1
    }}}
 1. Turn all the required resources on and check the status of all the resources. Use the following commands .
    {{{#!shell
    omf tell -a on -t sdr1-in1,sdr1-in2,rfdev4-in1,rfdev4-in2,srv1-lg1,srv2-lg1
    }}}    
    {{{#!shell
    omf stat -t all
    }}}
 1. {{{ssh}}} to the server with option -Y for using GUI with gnuradio. 
    {{{#!shell
    ssh -Y root@srv1-lg1
    }}}
=== Experiment Execution ===
==== Find and prepare USRPs  ====
* Upon logging into the server, run eth_config.sh script. This sets up the 10G data interfaces eno1, eno2. After running the script, you should see that the data interfaces have the appropriate IP addresses assigned, as per the tables for [https://wiki.cosmos-lab.org/wiki/Architecture/Domains/cosmos_sb1#IPAddressAssignment SB1] and [https://wiki.cosmos-lab.org/wiki/Architecture/Domains/cosmos_sb2#IPAddressAssignment SB2]. 
{{{#!td
   SB1
   {{{#!shell
root@srv1-lg1:~# ./eth_config.sh
root@srv1-lg1:~# ifconfig eno1
eno1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 9000
        inet 10.38.1.1  netmask 255.255.0.0  broadcast 10.38.255.255
        inet6 fe80::1e34:daff:fe42:c3c  prefixlen 64  scopeid 0x20<link>
        ether 1c:34:da:42:0c:3c  txqueuelen 1000  (Ethernet)
        RX packets 712  bytes 74814 (74.8 KB)
        RX errors 0  dropped 595  overruns 0  frame 0
        TX packets 42  bytes 9132 (9.1 KB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
root@srv1-lg1:~# ifconfig eno2
eno2: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 9000
        inet 10.39.1.1  netmask 255.255.0.0  broadcast 10.39.255.255
        inet6 fe80::1e34:daff:fe42:c3d  prefixlen 64  scopeid 0x20<link>
        ether 1c:34:da:42:0c:3d  txqueuelen 1000  (Ethernet)
        RX packets 643  bytes 51548 (51.5 KB)
        RX errors 0  dropped 599  overruns 0  frame 0
        TX packets 42  bytes 9132 (9.1 KB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
   }}}
}}}
* Run {{{und_find_devices}}} to make sure that both USRP N310s can be reached:
{{{#!td 
   SB1
   {{{#!shell
root@srv1-lg1:~# uhd_find_devices
[INFO] [UHD] linux; GNU C++ version 7.5.0; Boost_106501; UHD_3.15.0.0-release
--------------------------------------------------
-- UHD Device 0
--------------------------------------------------
Device Address:
    serial: 3176DF5
    addr: 10.38.2.1
    claimed: False
    mgmt_addr: 10.37.2.1
    mgmt_addr: 10.38.2.1
    mgmt_addr: 10.39.2.1
    product: n310
    type: n3xx
--------------------------------------------------
-- UHD Device 1
--------------------------------------------------
Device Address:
    serial: 3196937
    addr: 10.38.3.1
    claimed: False
    mgmt_addr: 10.37.3.1
    mgmt_addr: 10.38.3.1
    mgmt_addr: 10.39.3.1
    product: n310
    type: n3xx
   }}}
}}}

==== Configure IBM 28GHz PAAM ====
COSMOS uses a RESTful [https://wiki.cosmos-lab.org/wiki/Resources/Services/ArrayMgmt service for IBM PAAM management]
The service can be used for
* Dynamic array management - where the user connects to the antenna using {{{connect}}} command, dynamically steers the antenna during the experiment using {{{steer}}} command, and disconnects once the experiment is done.
* Static array management - where the user can connect, steer and disconnect using a single command, {{{configure}}}

Details and examples for the above are provided at the [https://wiki.cosmos-lab.org/wiki/Resources/Services/ArrayMgmt array management page].
For this experiment, we use static array management commands as shown below. 
First, start PAAM #1 (rfdev4-in1) in RX mode with V-polarization using 16 antenna elements on all the ICs, and configure the RX beamforming direction to be in the broadside (0,0). Check the current consumption on 2v7_0,1,2,3 to make sure all the ICs have been successfully initialized. 
{{{#!shell
root@console:~# curl "http://am1.orbit-lab.org:5054/array_mgmt/configure?dev_name=rfdev4-in1.sb1.cosmos-lab.org&ics=all&num_elements=16&txrx=rx&pol=v&theta=0&phi=0"
}}}
{{{#!shell
<?xml version="1.0" encoding="UTF-8"?>
<response status="OK">
  <action service="array_mgmt" name="configure" ipaddr="10.37.7.1">
    <step name="open" duration="3.599997"/>
    <step name="initializaition" duration="0.071123"/>
    <step name="enabling" duration="0.016817"/>
    <step name="steering" duration="0.007705"/>
    <state PAAM_ID="0x36" LO_switch="PLL" if_sw1="0x0" if_sw2="0x0" if_sw3="0x0" if_sw4="0x0"/>
    <adc>
      <conv index="0" name="1v2" tADC="120" tVolt="0.293" tCurr="0.147"/>
      <conv index="1" name="1v5" tADC="334" tVolt="0.816" tCurr="1.632"/>
      <conv index="2" name="1v8" tADC="24" tVolt="0.059" tCurr="0.029"/>
      <conv index="3" name="2v7_0" tADC="163" tVolt="0.398" tCurr="0.797"/>
      <conv index="4" name="2v7_1" tADC="206" tVolt="0.503" tCurr="1.007"/>
      <conv index="5" name="2v7_2" tADC="220" tVolt="0.538" tCurr="1.075"/>
      <conv index="6" name="2v7_3" tADC="180" tVolt="0.440" tCurr="0.880"/>
      <conv index="7" name="3v3_pll" tADC="408" tVolt="0.997" tCurr="0.499"/>
      <conv index="8" name="5v_uzed" tADC="206" tVolt="0.503" tCurr="0.503"/>
      <conv index="9" name="12v" tADC="244" tVolt="0.596" tCurr="1.988"/>
      <conv index="10" name="0V" tADC="0" tVolt="0.000"/>
      <conv index="11" name="1V8" tADC="737" tVolt="1.801"/>
    </adc>
    <step name="status" duration="0.020882"/>
    <step name="close" duration="0.100221"/>
  </action>
</response>
}}}

Similarly, start PAAM #2 (rfdev4-in2) in TX mode with V-polarization using 16 antenna elements on all the ICs, and configure the TX beamforming direction to be in the broadside (0,0). Check the current consumption to make sure the ICs have been successfully initialized.
{{{#!shell
root@console:~# curl "http://am1.orbit-lab.org:5054/array_mgmt/configure?dev_name=rfdev4-in2.sb1.cosmos-lab.org&ics=all&num_elements=16&txrx=tx&pol=v&theta=0&phi=0"
}}}
{{{#!shell
<?xml version="1.0" encoding="UTF-8"?>
<response status="OK">
  <action service="array_mgmt" name="configure" ipaddr="10.37.7.2">
    <step name="open" duration="3.558891"/>
    <step name="initializaition" duration="0.072244"/>
    <step name="enabling" duration="0.018709"/>
    <step name="steering" duration="0.008254"/>
    <state PAAM_ID="0x30" LO_switch="PLL" if_sw1="0x0" if_sw2="0x0" if_sw3="0x0" if_sw4="0x0"/>
    <adc>
      <conv index="0" name="1v2" tADC="125" tVolt="0.305" tCurr="0.153"/>
      <conv index="1" name="1v5" tADC="331" tVolt="0.809" tCurr="1.618"/>
      <conv index="2" name="1v8" tADC="22" tVolt="0.054" tCurr="0.027"/>
      <conv index="3" name="2v7_0" tADC="255" tVolt="0.623" tCurr="1.246"/>
      <conv index="4" name="2v7_1" tADC="250" tVolt="0.611" tCurr="1.222"/>
      <conv index="5" name="2v7_2" tADC="266" tVolt="0.650" tCurr="1.300"/>
      <conv index="6" name="2v7_3" tADC="264" tVolt="0.645" tCurr="1.290"/>
      <conv index="7" name="3v3_pll" tADC="410" tVolt="1.002" tCurr="0.501"/>
      <conv index="8" name="5v_uzed" tADC="215" tVolt="0.525" tCurr="0.525"/>
      <conv index="9" name="12v" tADC="300" tVolt="0.733" tCurr="2.444"/>
      <conv index="10" name="0V" tADC="0" tVolt="0.000"/>
      <conv index="11" name="1V8" tADC="734" tVolt="1.794"/>
    </adc>
    <step name="status" duration="0.021005"/>
    <step name="close" duration="0.100240"/>
  </action>
</response>
}}}

==== Run the experiment ====
* On srv1-lg1, start gnuradio companion and open the example experiment that establishes a single tone transmission. Use the file that is appropriate for the domain (SB1 or SB2).
{{{#!shell
root@srv1-lg1:~# gnuradio-companion example_paam_tone_sb1.grc 
}}}

* For running the experiment on SB1, configure the USRP sink (TX) with sdr1-in2 ("mgmt_addr=10.37.6.2,addr=10.39.6.2") and the USRP source (RX) with sdr1-in1("mgmt_addr=10.37.6.1,addr=10.39.6.1"). For SB2, configure the USRP sink (TX) with sdr1-s1-lg1 ("mgmt_addr=10.116.2.1,addr=10.117.2.1") and the USRP source (RX) with sdr1-md1 ("mgmt_addr=10.116.3.1,addr=10.117.3.1"). Set the carrier frequency to 3GHz (3e9) and the subdev to be "B:1" (RF3) (For SB2, use "B:0", RF2) on both TX and RX. In this example flowgraph, the sampling rate and the tone frequency are set to be 2.5MHz (2.5e6) and 1MHz (1e6), respectively.
|| [[Image(mmwavePaamBasicsFlowgraph.png, 600px)]] ||