= IBM 28GHz PAAM Basics =

=== Description ===

In this tutorial, we demonstrate the basic use of the IBM 28GHz phased array antenna modules (PAAMs) with USRP N310 software-defined radios (SDRs) in the [https://wiki.cosmos-lab.org/wiki/Architecture/Domains/cosmos_sb2 COSMOS Sandbox2 (sb2)].

Author: Tingjun Chen, Duke University / Columbia University (tingjun.chen [at] duke [dot] edu)

Last updated: Apr. 11, 2021

=== Prerequisites ===

In order to access sb2, create a reservation in sb2 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 getting [https://wiki.cosmos-lab.org/wiki/GettingStarted started page] to get started.

=== Resources Required ===

* 2 USRP N310 SDRs ({{{sdr1-s1-lg1}}} and {{{sdr1-md1}}})
* 2 IBM 28GHz PAAMs ({{{rfdev2-1}}} and {{{rfdev2-2}}})
* 1 Server ({{{srv1-lg1}}})

=== Tutorial Setup ===

Follow the steps below to gain access to the sb2 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 sb2
 1. [Documentation/Short/Login Login] into sb2 console ({{{console.sb2.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-s1-lg1,sdr1-md1,rfdev2-1,rfdev2-2,srv1-lg1
}}}
 1. Use the {{{baseline-28ghz-paam.ndz}}} node image with Ubuntu 18.04, UHD 3.15, gnuradio 3.8, and the IBM 28GHz PAAM API. Load {{{baseline-28ghz-paam.ndz}}} on the server.  
{{{#!shell
omf load -i baseline-28ghz-paam.ndz -t srv1-lg1
}}}
 1. Turn all the required resources on and check the status of all resources
{{{#!shell
omf tell -a on -t sdr1-s1-lg1,sdr1-md1,rfdev2-1,rfdev2-2,srv1-lg1
}}}
{{{#!shell
omf stat -t system:topo:allres
}}}
 1. {{{ssh}}} to the the same server from two terminals. In the first terminal, use option -Y for using GUI with gnuradio. In the second terminal, option -Y is not needed as it will be used to control the two IBM 28GHz PAAMs via command lines.
{{{#!shell
[Terminal 1] ssh -Y root@srv1-lg1,
[Terminal 2] ssh root@srv1-lg1,
}}}

=== Experiment Execution ===
==== Find and prepare USRPs and the IBM 28GHz PAAM API ====

* The IP addresses for Ethernet Port 1 (10G) on {{{sdr1-s1-lg1}}} and {{{sdr1-md1}}} were hard-coded to {{{10.117.2.1}}} and {{{10.117.3.1}}}, respectively. To access them from {{{srv1-lg1}}}, configure the network interface {{{eno1}}} as follows:
{{{#!shell
root@srv1-lg1:~# ifconfig eno1 10.117.1.1 netmask 255.255.0.0 mtu 9000 up
root@srv1-lg1:~# sudo sysctl -w net.core.wmem_max=62500000
net.core.wmem_max = 62500000
root@srv1-lg1:~# sudo sysctl -w net.core.rmem_max=62500000
net.core.rmem_max = 62500000
root@srv1-lg1:~# ifconfig 
eno1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 9000
        inet 10.117.1.1  netmask 255.255.0.0  broadcast 10.117.255.255
        inet6 fe80::1e34:daff:fe42:d4c  prefixlen 64  scopeid 0x20<link>
        ether 1c:34:da:42:0d:4c  txqueuelen 1000  (Ethernet)
        RX packets 15305870  bytes 21326136765 (21.3 GB)
        RX errors 0  dropped 46450  overruns 0  frame 0
        TX packets 16288829  bytes 21257264625 (21.2 GB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

}}}

* Run {{{und_find_devicec}}} to make sure that both USRP N310s can be reached:
{{{#!shell
root@srv1-lg1:~/beta_20200928/examples# uhd_find_devices 
[INFO] [UHD] linux; GNU C++ version 7.5.0; Boost_106501; UHD_3.15.0.HEAD-0-gaea0e2de
--------------------------------------------------
-- UHD Device 0
--------------------------------------------------
Device Address:
    serial: 315A35A
    addr: 10.117.2.1
    claimed: True
    mgmt_addr: 10.116.2.1
    mgmt_addr: 10.117.2.1
    mgmt_addr: 10.118.2.1
    product: n310
    type: n3xx

--------------------------------------------------
-- UHD Device 2
--------------------------------------------------
Device Address:
    serial: 3176DF7
    addr: 10.117.3.1
    claimed: True
    mgmt_addr: 10.116.3.1
    mgmt_addr: 10.117.3.1
    mgmt_addr: 10.118.3.1
    product: n310
    type: n3xx
}}}

* Download and build the RENEW Sounder software **on the {{{develop}}} branch** at [https://github.com/renew-wireless/RENEWLab/ here] and follow the [https://docs.renew-wireless.org/dev-suite/design-flows/cpp/sounder/ instructions] to build it. Note that the {{{master}}} branch does not have UHD support.

* Include in {{{files/usrp-bs-serials.txt}}} the IP address {{{10.118.2.2}}}, i.e., use {{{sdr2-s1-lg1}}} as the base station (BS). In {{{files/usrp-bs-only.json}}}, set {{{"channel" : "AB",}}} to enable dual-channel on {{{sdr2-s1-lg1}}}.

* Similarly, in {{{files/usrp-client-only.json}}}, set {{{"sdr_id" : [ "10.118.3.2" ]}}} (i.e., use {{{sdr2-md1}}} as the user) and {{{"channel" : "AB",}}} to enable dual-channel on {{{sdr2-md1}}}.