This wiki page contains tutorials for open-access remotely-accessible full-duplex (FD) radios integrated in the ORBIT and COSMOS testbeds, a collaboration with the [https://flexicon.ee.columbia.edu Columbia FlexICoN project]. The full-duplex transceivers are currently being integrated into COSMOS. All the source code can be found at [https://github.com/Wimnet/flexicon_orbit this GitHub page]. Authors: * Manav Kohli, Columbia University: mpk2138[at]columbia.edu * Tingjun Chen, Duke University: tingjun.chen[at]duke.edu Last updated: March 22, 2023 == Full-Duplex Wireless in COSMOS == === Description === In this tutorial, we will use the the integrated Columbia [http://flexicon.ee.columbia.edu/ FlexICoN] Gen-2 Wideband FD radios equipped with USRP X310 software defined radios (SDRs) and the Gen-2 frequency-domain equalization (FDE)-based RF canceller box. The testbed may be accessed via {{{ssh}}}, and utilizes the [[Hardware/Compute#Compute|COSMOS servers]]. The PC contains several example experiments, which showcase the capabilities of the integrated FD radios. ||||||Figure 1: Gen-2 FDE Canceller Boxes in COSMOS Sandbox 2 || || [[Image(Gen2Architecture.jpg, 280px)]] || [[Image(Gen2Ceiling.jpg, 375px)]] || || (a) The FlexICoN Gen-2 RF Canceller Box and antenna || (b) Rack-mounted, reorganized Gen-2 RF Canceller Box || ==== Publications ==== For more information about the integration of the FDE-based FD transceivers in COSMOS, please read: 1. ''Manav Kohli, Tingjun Chen, Mahmood Baraani Dastjerdi, Jackson Welles, Ivan Seskar, Harish Krishnaswamy, and Gil Zussman, “Open-access full-duplex wireless in the ORBIT and COSMOS testbeds,” Computer Networks, no. 199, p. 108420, Nov. 2021'' [https://wimnet.ee.columbia.edu/wp-content/uploads/2021/10/orbit_cosmos_comnets_2021.pdf (Download)] 2. ''Tingjun Chen, Mahmood Baraani Dastjerdi, Jin Zhou, Harish Krishnaswamy, and Gil Zussman, “Wideband Full-Duplex Wireless via Frequency-Domain Equalization: Design and Experimentation,” in Proc. ACM !MobiCom'19, Oct. 2019'' [https://wimnet.ee.columbia.edu/wp-content/uploads/2018/12/FDE_MobiCom19.pdf (Download)] Please cite the above papers if you use the hardware. Please email Manav Kohli (mpk2138[at]columbia.edu) or Tingjun Chen (tingjun.chen[at]duke) if you have any questions. ==== Updates ==== * ![03/22/2023] - ''Major update'' - Experimentation has been moved to the COSMOS sandbox servers. Experiments and testbed usage has been updated * ![11/15/2021] - Update PC IP address * ![10/15/2021] - New paper in Computer Networks * ![03/15/2021] - General updates * ![08/28/2020] - Details for each available experiment * ![08/23/2020] - General updates * ![02/03/2020] - Updated UHD and GNU Radio versions * ![11/13/2019] - Updated pictures of Gen2 FDE nodes * ![10/20/2019] - Connection to the FDE PC via COSMOS sb2 * ![10/07/2019] - Baseline overview of initial COSMOS sandbox status and accessibility === Hardware / Software Resources Utilized === 1. 1-4 Columbia FlexICoN Gen-2 RF Canceller Boxes 2. 1-2 USRP X310s (up to 4 transceivers, one for each Canceller Box) 3. The {{{flexicon-cosmos-v1.ndz}}} node image, which contains the experiments, along with [https://github.com/EttusResearch/uhd, UHD] version 4.2.1 and [https://github.com/gnuradio/gnuradio, GNU Radio] 3.8.2. 4. [http://www.xdimax.com/sub20/sub20.html SUB-20] is a multi-interface USB adapter for providing popular interfaces between PC (USB host) and different hardware devices. We use the SUB-20 SPI module to configure the Gen-2 RF canceller (see Fig. 1(a)). The user manual can be found [http://www.xdimax.com/sub20/doc/sub20-man.pdf here]. The SUB-20 devices are through a special GNU radio experiment to configure the RF cancellers. 5. The {{{Eigen C++}}} Library is used for basic algebra used in channel estimation and digital self-interference cancellation. The Eigen releases can be found on the [http://eigen.tuxfamily.org/index.php?title=Main_Page this website]. We use Eigen 3.3.4 in these experiments. 6. The source code for the FD example experiments can be found at [https://github.com/Wimnet/flexicon_orbit this GitHub page]. {{{#!comment For documentation about the available GNU radio OOT modules, please see the README at [https://github.com/Wimnet/flexicon_orbit/blob/master/gr-fullduplex/docs/README.md this page]. }}} ==== The Gen-2 RF Canceller Box ==== The Gen-2 RF canceller box is shown in Figure 1(a). It consists of four components: 1. '''Circulator'''. This provides 15-20dB of isolation between the Tx and Rx. 2. '''Antenna tuner'''. This allows for better matching to the antenna. 3. '''Gen-2 RF canceller PCB'''. This is described in further detail below. 4. '''SUB-20 USB to SPI interface'''. This is used to program the Gen-2 RF canceller PCB over USB. ||Figure 2: Gen-2 RF Canceller PCB || || [[Image(Gen2PCB.png, 450px)]] || The Gen-2 RF canceller PCB has two paths: the Gen-2 FDE wideband path, and the Gen-1 narrowband path. Further details on the circuit design may be found in [ [[wiki:Tutorials/Wireless/FullDuplex#Publications|2]] ], and further details on its use in the Gen-2 RF Canceller box may be found in [ [[wiki:Tutorials/Wireless/FullDuplex#Publications|1]] ]. ==== USRP X310 SDR ==== Each Gen-2 RF canceller box is connected to one transceiver of a [https://www.ettus.com/all-products/x310-kit/ USRP X310 SDR]. There are two USRP X310s in the testbed, each connected to the COSMOS servers over a 10 Gigabit interface. === COSMOS Sandbox 2 === The Gen-2 FDE Canceller Boxes are integrated in COSMOS Sandbox 2 ({{{sb2}}}). The sandbox is located inside a lab at Columbia, allowing for a controlled environment for the testing and evaluation of the Gen-2 Canceller Boxes. The architecture of Sandbox 2, alongside its integration within the larger COSMOS testbed, is shown in Figure 2 below. ||Figure 3: Architecture of COSMOS Sandbox 2 || || [[Image(SandboxArchitecture.png, 450px)]] || === Tutorial === ==== Set Up ==== Before you can access the testbed, you need to [https://www.cosmos-lab.org/schedule make a reservation] and get it approved. After receiving the reservation's confirmation (approval) email: * Login into the reserved domain with the command below. The {{{-X}}} option is for enabling the X11 tunneling. Note: if connecting from macOS, the {{{-Y}}} flag may be needed instead of {{{-X}}}. {{{ ssh -X username@console.sb2.cosmos-lab.org }}} * Once logged in, we can configure the COSMOS server. We will use the Sandbox 2 server {{{srv2-lg1}}}. Run the following command to ensure that the server is switched off: {{{ omf tell -a offh -t srv2-lg1 }}} * You should receive a {{{Reply: OK}}} message. If you do not, please see the troubleshooting section below. After receiving this notice, please run the command below to load the image. Note - this command can take over 5-10 minutes to run, so this is a good time to grab a tea or coffee... {{{ omf load -o 1800 -i flexicon-cosmos-v1.ndz -t srv2-lg1 }}} * '''Let the command run to completion, even if it does not seem to finish.''' Confirm that the command finished and output something along the lines of the text below. If not, please see the troubleshooting section. {{{ INFO exp: ----------------------------- INFO exp: Imaging Process Done INFO exp: 1 node successfully imaged - Topology saved .... INFO exp: ----------------------------- }}} * Switch on the server with the command below, and check for {{{Reply: OK}}}. The server will take a couple of minutes to switch on fully after the command finishes. {{{ omf tell -a on -t srv2-lg1 }}} * Log into the server with SSH {{{ ssh -X root@srv2-lg1 }}} * Run the following command to optimize the server network interfaces for use with UHD and GNU Radio: {{{ ./optimizeInterfaces }}} * At this point, the server is ready to use. Please see the sections below for details on how to use the baseline experiments, the resources that are available on the server, and how to save your work when finished. ==== Running the Baseline Node-level Experiments ==== '''Configuring an FD Radio''' We can open GNU Radio using the following command: {{{ gnuradio-companion & }}} If X-forwarding is setup correctly for your {{{ssh}}} session, the GNU Radio graphical user interface (GUI) program should open. If X-forwarding is not setup correctly, an error will display saying that the GUI window cannot be opened - please ensure you have used the -X flags correctly as described in the setup. Open an example experiment from the {{{~/Experiments/Node}}} directory. The following experiments are available: * {{{wifi_node_level_sic_tune}}} - This is used to configure the Gen-2 FD cancellers. * {{{wifi_node_level_sic_viz}}} - Once the FD canceller is configured, this flowgraph provides a GUI to demonstrate the node-level operation of one FD radio. If we open {{{wifi_node_level_sic_tune.grc}}}, in GNU radio, the following window will show: ||||||Figure 4: The {{{wifi_node_level_sic_tune}}} GNU radio experiment, with different functional parts highlighted. || || [[Image(wifi_node_level_sic_tune_flowgraph.png,640px)]] || This simple flowgraph contains three main components. First, highlighted in green, are the variables used to define important parameters for the experiment. {{{freq}}} is the centre frequency for the RF signal to be transmitted, and {{{samp_rate}}} is the bandwidth of the signal. By default, these values are 920 MHz and 10 MHz respectively. The {{{usrp_source_addr}}} and {{{usrp_sink_addr}}} are IP addresses for the USRP X310 we are using to receive and transmit - in this experiment, they should be identical. {{{subdev_spec}}} is the specific transceiver of the USRP X310, and {{{sub20_sn}}} is the serial number of the SUB-20 device for the combination of {{{usrp_source_addr}}} and {{{subdev_spec}}}. More details on these values is provided later on in the tutorial. Next, highlighted in blue, are the blocks used to define the GUI sliders for adjusting the configuration of the Gen-2 RF canceller. The "FDE Remote Config" block performs the configuration using the SUB-20 device by sending the values of each slider to the SUB-20 device over the network. Lastly, the blocks highlighted in yellow are the data flow for this experiment. The "File Source" block reads a complex-valued baseband signal from a file on the server - this signal represents 802.11a-like data packets with the BPSK 3/4 modulation and coding scheme. This baseband signal is connected to the "USRP Sink", which will transmit the signal from the USRP at the centre frequency specified by {{{freq}}} and the bandwidth specified by {{{samp_rate}}}. The "USRP Source" produces a complex baseband signal received by the radio, and this is fed into a "QT GUI Frequency Sink", which displays the signal on the GUI. To start the experiment, first change {{{samp_rate}}} to 20M, by double-clicking on the variable block and entering {{{20e6}}}. Then, press the play button on the top row of icons. After pressing play, the experiment will start loading, and the GUI in Figure 5 below should display. ||||||Figure 5: The {{{wifi_node_level_sic_tune}}} experiment GUI, showing a power spectrum of the self-interference and sliders for configuring the Gen-2 canceller. || || [[Image(wifi_node_level_sic_tune_gui.png,640px)]] || The power spectrum shown on the left hand side of the GUI is the self-interference (SI) signal, after the RF canceller has performed RF SI cancellation (SIC) on it. The goal of the configuration GUI is to reduce the SI power as much as possible. It is sufficient for the time being to configure the sliders using the values in Figure 5. A table of "starter configurations" is provided later on in the tutorial for each of the four radios. ''Important note: It is not recommended to move the sliders by dragging them. This will cause many configuration requests to be sent to the SUB-20. The GNU Radio GUI elements do not let us specify when to apply the slider value, so it applies it for every value you slide over. It is best to enter values by clicking on the number next to each slider, or clicking along the slider to move it in steps.'' '''Node-Level Performance of the Configured FD Radio''' Now, we can open the {{{wifi_node_level_sic_viz.grc}}} file into GNU Radio. The flowgraph for this is more complex, and utilizes several blocks which have been developed specifically to support the FD experimentation on COSMOS. A description of each block is provided on the [https://github.com/Wimnet/flexicon_orbit/blob/master/gr-fullduplex/docs/README.md GitHub page] for the source code. Change the {{{samp_rate}}} variable to 20M as before, and then press the play button. In this flowgraph, we transmit 802.11a packets with QPSK 3/4 modulation and coding. You should see the GUI in Figure 6. ||||||Figure 6: The {{{wifi_node_level_sic_viz}}} experiment GUI, showing the time-domain received waveform after RF SIC and after digital SIC. Also shown are the corresponding constellation diagrams. || || [[Image(wifi_node_level_sic_viz_gui.png,640px)]] || This GUI shows two important features. First is that, even after RF SIC, the SI can still be fully decoded, shown by the clear QPSK constellation diagram. However, after the second stage of SIC on the digital baseband signal, we can see that the constellation diagram shows only noise, and the time domain signal (the black line) is at the noise floor. '''Configuring the Other Radios''' The procedure for the two flowgraphs can be repeated to configure and benchmark the three other FD radios in the testbed. Please see the tables below, which provides the USRP IP address, the subdevice specifier, the SUB-20 serial number, and a useful initial configuration. Connection details: || Radio # || USRP Address || Subdevice || SUB-20 Serial # || || 1 || 10.116.7.1 || A:0 || 552D || || 2 || 10.116.7.1 || B:0 || 5647 || || 3 || 10.116.7.2 || A:0 || 552C || || 4 || 10.116.7.2 || B:0 || 18A1 || Initial configuration values: || Radio # || {{{cap_0}}} || {{{cap_1}}} || {{{cap_2}}} || {{{qf_0}}} || {{{qf_1}}} || {{{cf_0}}} || {{{cf_1}}} || {{{att_0}}} || {{{att_1}}} || {{{dac_0}}} || {{{dac_1}}} || || 1 || 9 || 10 || 0 || 2 || 2 || 14 || 0 || 60 || 55 || 86 || 107 || || 2 || 4 || 10 || 0 || 0 || 0 || 2 || 7 || 2 || 13 || 201 || 161 || || 3 || 3 || 8 || 0 || 2 || 2 || 0 || 0 || 22 || 91 || 105 || 22 || || 4 || 5 || 3 || 0 || 2 || 2 || 8 || 6 || 11 || 19 || 159 || 155 || Any parameter not in this table should have value 0. For reference, the meaning of each parameter is described below: * {{{cap0, cap1, cap2}}} - these control the antenna tuner. * {{{att0, att1}}} - The attenuator values for FDE tap 0 and tap 1. Higher values lead to greater attenuation. * {{{dac0, dac1}}} - The phase shifter values for FDE tap 0 and tap 1. * {{{cf0, cf1}}} - The center frequency for FDE tap 0 and tap 1. Higher values lead to lower center frequency. * {{{qf0, qf1}}} - The quality factor for FDE tap 0 and tap 1. Higher values lead to lower quality factor. * {{{canc_path}}} - Determines whether the wideband FDE or narrowband Gen-1 canceller path is used. 0 = FDE, 1 = Gen-1. * {{{att2}}} - The attenuator values for the Gen-1 path. Higher values lead to greater attenuation. * {{{dac2}}} - The phase shifter values for the Gen-1 path. Note - the COSMOS FD testbed is contained within a laboratory environment, which is mostly static, but not perfectly so. It is possible that these initial configuration values may not give ideal performance off the bat - if the {{{wifi_node_level_sic_viz}}} flowgraph shows a residual signal in the bottom constellation plot, it is likely that the configuration values need to be adjusted slightly. There is a strategy to do this - first, it is worthwhile to change the {{{dac_0}}} and {{{dac_1}}} values to see if this brings the residual signal power down. If this does not work, then the {{{att_0}}} and {{{att_1}}} values can be changed, followed by again changing {{{dac_0}}} and {{{dac_1}}} until a good configuration is achieved. Generally, the other values are stable. If you would like to configure the Gen-2 RF canceller from scratch, make sure {{{att_0}}} and {{{att_1}}} are set to 127 (effectively turning off the canceller) and then adjust {{{cap_0}}} and {{{cap_1}}} until the SI spectral power density is between -45 to -50 "dB". Then, start reducing the {{{att_0}}} value until you see either a decrease or increase - at this point you can tune {{{dac_0}}} to get the lowest spectral power. Then, repeat this with {{{att_1}}} and {{{dac_1}}}; you may have to go back to {{{att_0}}} and {{{dac_0}}} to get the best configuration. This is a procedure which gets easier with practice - it may be worth sticking with the initial values in the table to begin with. ==== Wrapping Up & Saving Work ==== When you are finished with your experiments, you can save your work to a new node image, that you can then load in next time. Since it can take some time to finish saving your work to a new server image, we recommend saving at least '''30 minutes''' of your reservation time to make sure you have enough time to complete the process. * To ensure a reliable image save, we need to reboot the server first. You will need to return to the Sandbox 2 console, either in a new SSH session, or by typing {{{exit}}} on the server SSH window. * Run the following command from the Sandbox 2 console: {{{ omf tell -a reboot -t srv2-lg1 }}} * Check for {{{Reply: OK}}} and give some minutes to allow the server to come back online. * Log back into the server: {{{ssh -X root@srv2-lg1}}} * Run the following script to prepare the node for imaging. It is ok to ignore warnings and errors from this command. Note the command it provides to you once finishing. {{{ ./prepare.sh }}} * Go back to the Sandbox 2 console by running {{{exit}}}. * Run the command that should have been provided by the {{{prepare.sh}}} script. This command, like the {{{omf load}}} command, can take 5-10 minutes to run. Good time to refill your tea or coffee... {{{ omf save -n srv2-lg1.sb2.cosmos-lab.org }}} * '''Let this command run to completion, even if it does not seem to finish.''' Confirm that the command finished and output something along the lines of the text below. If not, please see the troubleshooting section. {{{ INFO exp: INFO exp: - Saving process started at: 2023-03-21 04:33:09 +0000 INFO exp: (this may take a while depending on the size of your image) INFO exp: - Saving disk image of 'srv2-lg1.sb2.cosmos-lab.org' finished with success. INFO exp: - Saving process completed at: 2023-03-21 04:35:49 +0000 INFO exp: }}} * The filename of your image will be located in the output of the command, specifically in the third line of this part of the output: {{{ INFO srv2-lg1.sb2.cosmos-lab.org: INFO srv2-lg1.sb2.cosmos-lab.org: - Saving image of '/dev/sda' on node 'srv2-lg1.sb2.cosmos-lab.org' INFO srv2-lg1.sb2.cosmos-lab.org: to the file 'mpk2138-node-srv2-lg1.sb2.cosmos-lab.org-2023-03-21-04-32-59.ndz' on host '10.116.0.40' INFO srv2-lg1.sb2.cosmos-lab.org: }}} * Keep a note of this filename. You can use this instead of {{{flexicon-cosmos-v1.ndz}}} the next time you login to use the FD testbed. * If you would like to change the filename, you can run the following command. Note, it is good to keep your COSMOS username on the front of your node image filename. Make sure to use your specific filename that was provided in the output of the {{{omf save}}} command. Spaces cannot be used in the filename. {{{ mv /export/omf-images-5.4/mpk2138-node-srv2-lg1.sb2.cosmos-lab.org-2023-03-21-04-32-59.ndz /export/omf-images-5.4/mpk2138-IMAGE-NAME-HERE.ndz }}} * The node image is now saved, and you will be able to pick up where you left off the next time you login to use the FD radios. === Troubleshooting === There are some errors which may crop up while running this tutorial. This section will help resolve and debug them. If there are any unresolvable issues not covered below, please contact Manav Kohli at mpk2138[at]columbia.edu. '''Received Reply: ERROR (NOT REGISTERED)''' This can occur when using the {{{omf tell -a on}}} or {{{omf tell -an off}}} commands. If it happens, simply run the command again. It should work. '''Imaging the server timed out''' Run the command again, changing {{{-o 1800}}} to {{{-o 3600}}}. It should not time out again. '''Saving the server image failed''' Run the command again, but if it fails more than three times in a row, do not continue, and contact the above email. '''The GNU radio flowgraph did not run, exited with error code -11''' Run the flowgraph again. If the error persists, please attempt the tutorial from the ground-up. If that still fails, contact the above email. '''"Device not found" when running GNU radio flowgraph''' The USRP X310 has become unresponsive or disconnected from the COSMOS network. This is not solvable via the testbed console. Please contact the above email. '''The sliders in {{{wifi_node_level_sic_tune}}} do nothing''' Double check that the combination of IP address, subdevice specifier, and SUB-20 serial number is correct. If you are 100% sure it is correct, please contact the above email. === Acknowledgements === This work was supported in part by NSF grants ECCS- 1547406 and CNS-1827923, NSF-BSF grant CNS-1910757, DARPA RF-FPGA and SPAR programs, and a Facebook Fellowship. We thank Jelena Diakonikolas, Guy Farkash, Jakub Kolodziejski, Prasanthi Maddala, Jonathan Ostrometzky, Michael Sherman, and Jin Zhou for their contributions to various aspects of the project. == Full-Duplex Wireless in ORBIT == === Description === In this tutorial, we'll use node11-10 in the main grid (equipped with a USRP N210) to transmit and receive a single tone over the air to demonstrate full-duplex wireless capability using the Columbia [http://flexicon.ee.columbia.edu/ FlexICoN]'s Gen-1 Narrowband Frequency-Flat Amplitude- and Phase-based RF Canceller. Pictures of the FlexICoN RF canceller and node11-10 in the main grid equipped with full-duplex capability are below: ||||||Figure 1: The ORBIT-FlexICoN Full-Duplex Node|| || [[Image(FlexICoN-gen1-canceller.jpg, 325px)]] [[Image(FlexICoN-gen1-canceller-label.png, 350px)]] || [[Image(FlexICoN-gen1-node11-10.jpg, 400px)]] || || (a) The FlexICoN RF Canceller Box || (b) Full-Duplex SDR at node11-10 in the ORBIT grid || ==== Publications ==== For more information, please read: ''Manav Kohli, Tingjun Chen, Mahmood Baraani Dastjerdi, Jackson Welles, Ivan Seskar, Harish Krishnaswamy, and Gil Zussman, “Open-access full-duplex wireless in the ORBIT and COSMOS testbeds,” in Proc. ACM !MobiCom’20 Workshop on Wireless Network Testbeds, Experimental evaluation & CHaracterization (WiNTECH) (invited), Sept. 2020'' [https://wimnet.ee.columbia.edu/wp-content/uploads/2020/08/wintech2020_orbit_cosmos_fullduplex_integration.pdf (Download)] [https://wimnet.ee.columbia.edu/wp-content/uploads/2020/08/mobicom2020_cosmos_fullduplex_demo.pdf (Demo Abstract)] Please cite the above arXiv report if you use the hardware. Please email Tingjun Chen (tingjun [at] ee.columbia.edu) or Manav Kohli (mpk2138 [at] columbia.edu) if you use (or plan to use) the full-duplex node or if you have any questions. ==== Updates ==== * [09/17/2020]: New full-duplex SDR image {{{flexicon-orbit-v4.ndz}}} released. The real-time OFDM-based full-duplex flowgraph and GNU OOT modules have been updated. Obsolete experiments have been removed. * [04/30/2019]: New full-duplex SDR image {{{flexicon-orbit-v3.ndz}}} released. Main new feature includes the implementation of a real-time OFDM-based full-duplex node. * [01/31/2019]: Developed real-time digital SIC as a GNU Radio OOT module. * [04/05/2018]: New full-duplex SDR image {{{flexicon-orbit-v2.ndz}}} released. New features include (1) GNU Radio OOT module that controls the SUB-20 controller, and (2) integrated full-duplex PSK examples. * [02/28/2018]: PSK examples based on GNU Radio is now available. For more details, please refer to the [http://wimnet.ee.columbia.edu/wp-content/uploads/2018/03/INFOCOM18Demo_FullDuplexORBIT.pdf, INFOCOM'18 Demo Abstract]. * [01/08/2018]: The baseline full-duplex SDR image {{{flexicon-orbit-v1.ndz}}} released. This node image includes an UHD benchmark full-duplex transciever example. For more details, please refer to the [https://arxiv.org/abs/1801.03069, arXiv report]. === Hardware / Software Resources Utilized === 1. The Columbia FlexICoN Gen-1 RF Canceller, which is a frequency-flat ''narrowband'' amplitude- and phase-based RF canceller implemented using discrete components on a PCB. The Gen-1 RF canceller is optimized to have a center operating frequency at 900MHz. 2. The source code for the full-duplex transceiver examples, which can be found at [https://github.com/Wimnet/flexicon_orbit this GitHub page]. We have also built an ORBIT node image {{{flexicon-orbit-v4.ndz}}} with all the required software installed to facilitate the experiments. 3. USRP N210 with {{{node11-10}}} in the ORBIT main grid. 4. [http://www.xdimax.com/sub20/sub20.html SUB-20] is a multi-interface USB adapter for providing popular interfaces between PC (USB host) and different hardware devices. Specifically, we use the SUB-20 SPI module to control and configure the Gen-1 RF canceller (see Fig. 1(a)). The user manual can be found [http://www.xdimax.com/sub20/doc/sub20-man.pdf here]. We also built a GNU Radio Out-Of-Tree (OOT) module to allow controlling the canceller from within the GNU Radio GUI. 5. [https://github.com/EttusResearch/uhd, UHD] and [https://github.com/gnuradio/gnuradio, GNU Radio] are already installed with the imaged SDR node. 6. The {{{Eigen C++}}} Library is used for basic algebra used in channel estimation and digital self-interference cancellation. The Eigen releases can be found on the [http://eigen.tuxfamily.org/index.php?title=Main_Page this website]. We used the latest stable release Eigen 3.3.4 through our testings and experiments. For documentation about the available GNU radio OOT modules, please see the README at [https://github.com/Wimnet/flexicon_orbit/blob/master/gr-fullduplex/docs/README.md this page]. === Tutorial === ==== Set Up ==== Before you can access the testbed, you need to [https://www.orbit-lab.org/schedule make a reservation] and get it approved. After receiving the reservation's confirmation (approval) email: * Login into reserved domain: {{{ssh -X username@conslole.grid.orbit-lab.org}}} (the {{{-X}}} option is for enabling the X11 tunneing) * Make sure that the full-duplex node is powered down for loading the desired image: {{{omf tell -a offh -t node11-10}}} * Load the most updated full-duplex node image (currently {{{flexicon-orbit-v4.ndz}}}) on the node (this process can take about a few minutes so please be patient): {{{omf load -i flexicon-orbit-v4.ndz -t node11-10}}} * Turn on the node: {{{omf tell -a on -t node11-10}}} * Login into the node: {{{ssh -X root@node11-10}}}. After login into the node, a {{{flexicon_orbit}}} folder should exist under the home directory of {{{node11-10:~/}}} which contains the source code of this example. You can also retrieve the most recently updated code from [https://github.com/Wimnet/flexicon_orbit the GitHub repository]. * Configure the USRP Ethernet interface: {{{ifconfig eth2 192.168.10.1 netmask 255.255.255.0 up}}} * Run {{{sudo sysctl -w net.core.rmem_max=50000000}}} and {{{sudo sysctl -w net.core.wmem_max=50000000}}} * Check the conection and serial number of the USRP N210: {{{uhd_find_devices}}}. The serial number should be {{{F331D4}}}. * Set an initial configuration for the Gen-1 canceller PCB: {{{#!shell-session root@node11-10:~ cd flexicon_orbit/fd_transceiver_simple/sub20 root@node11-10:~/flexicon_orbit/fd_transceiver_simple/sub20# ./rf_canc_gen1_config 0 127 16 6 6 Started... Sub20 device found... Serial Number is 48AB Device Opened! ...Finished programming DAC with value 0! ...Finished programming ATT with value 127! ...Finished programming CAP1 with value 16! ...Finished programming CAP2 with value 6! ...Finished programming CAP3 with value 6! }}} ==== Running experiments ==== We provide two sets of experiments. One set is for GNU Radio, which are identical to the experiments described above in COSMOS and located at {{{~/flexicon_orbit/experiments/grc/}}}. To run these experiments, open them from GNU radio after running the {{{gnuradio-companion}}} command. Please note that due to there only being one FD radio present in ORBIT, the two link experiments in GNU Radio are not supported. The flowgraphs are kept present for reference. The other set which are based on UHD, and are legacy experiments - they implement simpler full-duplex transceivers with no available GUI and are also kept for reference. '''Details on configuring the canceller PCB''' Using the experiment {{{node_level_sic_fd_gui}}}, the experimenter can configure the RF canceller PCB using the experiment GUI. There are 2 sliders: * {{{att_0}}} - The attenuator value for the canceller. Higher values lead to greater attenuation. * {{{dac0}}} - The phase shifter values for the canceller. === Available Experiments === ==== node_level_sic_fd_gui (GNU Radio) ==== The primary use of this experiment is to visualize the performance of the FD radio. As the Gen-1 canceller operates in a narrow band, the cancellation bandwidth will be noticeably less than the Gen-2 FD radios available in COSMOS. In this experiment, several performance metrics are visualized: * The received self-interference (SI) after RF SI cancellation (SIC) and after digital SIC. * The received power spectra after RF SIC and after digital SIC. * The complex-valued digital SIC filter taps. * The estimated SI channel. '''Tunable variables''' * {{{freq}}} - the carrier frequency used. The Gen-1 hardware can support roughly 900-1000MHz. * {{{samp_rate}}} - the bandwidth used. As the canceller is narrowband, we recommend using no more than a 5 MHz bandwidth. ==== fd_transciever_simple (Terminal + UHD) ==== This experiment can be used to show the amount of achieved SIC in the RF and digital domains using a command-line interface. It is included here as reference and an example of a full-duplex transceiver implemented in UHD. We recommend using two terminals here, so one terminal can be used to run the experiment in the foreground while the second is used to control the FD radio. '''In Terminal 1''' * Prepare the Eigen library (you can skip this step since the image already contains the Eigen library): {{{#!shell cd ~/flexicon_orbit/fd_transceiver_simple/ sudo cp -r Eigen/ /usr/include/ }}} * Build the example (this is already done in the loaded image): {{{#!shell cd ~/flexicon_orbit/fd_transceiver_simple/uhd/ mkdir build cd build cmake ../ make }}} * Run the example with IQ rate {{{rate}}}, carrier frequency {{{freq}}}, TX gain {{{tx-gain}}}, and RX gain {{{rx-gain}}}: {{{#!shell cd ~/flexicon_orbit/fd_transceiver_simple/uhd/build/ ./fd_transceiver_simple --tx-args="serial=F331D4" --rx-args="serial=F331D4" --rate 1e6 --freq 900e6 --tx-gain 0 --rx-gain 10 }}} The default sine wave has an amplitude {{{ampl=0.3}}} and wave frequency of 100kHz {{{wave-freq=100e3}}}, which corresponds to a 0dBm TX power level. This terminal window will show the power level at RX baseband, after RF cancellation (before digital) and after digital cancellation, respetively. The UHD program is calibrated with {{{--rx-gain=10}}}, other RX gain values may results in inaccurate power level computation. * An example temrinal output is below: {{{#!shell-session root@node11-10:~/flexicon_orbit/fd_transceiver_simple/uhd/build# ./fd_transceiver_simple --tx-args="serial=F331D4" --rx-args="serial=F331D4" --rate 1e6 --freq 900e6 --tx-gain 0 --rx-gain 10 linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.001.001-0-unknown Creating the transmit usrp device with: serial=F331D4... -- Opening a USRP2/N-Series device... -- Current recv frame size: 1472 bytes -- Current send frame size: 1472 bytes . . . Press Ctrl + C to stop streaming... TX Stream time was: 0 full secs, 0.100064 frac secs RX Signal Power: -44.093768 dBm (N_FFt = 2048) RX Res Signal Power: -98.570747 dBm (N_fft = 1024) Amount of Digital SIC: 54.476979 dB RX Signal Power: -44.232740 dBm (N_FFt = 2048) RX Res Signal Power: -98.113147 dBm (N_fft = 1024) Amount of Digital SIC: 53.880407 dB RX Signal Power: -43.959299 dBm (N_FFt = 2048) RX Res Signal Power: -93.406544 dBm (N_fft = 1024) Amount of Digital SIC: 49.447245 dB RX Signal Power: -44.179891 dBm (N_FFt = 2048) RX Res Signal Power: -101.593147 dBm (N_fft = 1024) Amount of Digital SIC: 57.413256 dB }}} In this example, since the TX power level is at 0dBm, a total amount of around 90dB self-interference cancellation is achieved, of which 45dB is obtained by the Gen-1 RF canceller, and 50dB is obtained by the digital cancellation. '''In Terminal 2 (SUB-20)''' * Build the RF canceller configuration code (this is already done in the loaded image): {{{#!shell cd ~/flexicon_orbit/fd_transceiver_simple/sub20/ make }}} * Check the connection to the SUB-20 device using command {{{lbusb}}}. You should see a XDIMAX devices connected to the USB hub. * Program and configure the RF canceller with the desired values: {{{#!shell cd ~/flexicon_orbit/fd_transceiver_simple/sub20/ ./rf_canc_gen1_config PS-CODE ATT-CODE C1-CODE C2-CODE C3-CODE }}} In particular, the {{{PS-CODE=0,1,2,...,255}}} and {{{ATT-CODE=0,1,2,...,127}}} codes are for configuring the 8-bit phase shifter and the 7-bit attenuator of the Gen-1 RF canceller, respectively. It is recommended to use {{{C1-CODE=16, C2-CODE=6, C3-CODE=6}}}, which provides 20dB isolation from the antenna-circulator interface. You can play with the values of {{{ATT}}} and {{{PS}}} until you see good cancellation profile (e.g., low residual self-interference power level) in Terminal 1. * An example terminal output is below: {{{#!shell-session root@node11-10:~/flexicon_orbit/fd_transceiver_simple/sub20# ./rf_canc_gen1_config 110 30 16 6 6 Started... Sub20 device found... Serial Number is 48AB Device Opened! ...Finished programming DAC with value 110! ...Finished programming ATT with value 30! ...Finished programming CAP1 with value 16! ...Finished programming CAP2 with value 6! ...Finished programming CAP3 with value 6! }}} '''A Secondary Transmitter Using Node13-8''' Once the full-duplex node11-10 is up and running, you can turn on another SDR to transmit to the full-duplex node. Below, we use {{{node13-8}}} as an example in the 3rd terminal window (Terminal 3). * Load image, power on, and login into node13-8: {{{#!shell omf tell -a offh -t node13-8 omf load -i baseline-sdr.ndz -t node13-8 omf tell -a on -t node13-8 ssh root@node13-8 }}} * Configure the USRP Ethernet interface: {{{ifconfig eth2 192.168.10.1 netmask 255.255.255.0 up}}} * Set up a secondary transmitter sending a sine wave at a different frequency (e.g., 200 kHz) than that of the full-duplex node: {{{#!shell ./tx_waveforms --args="serial=F331D4" --rate 1e6 --freq 900e6 gain 10 --wave-type SINE --wave-freq 200e3 }}} Now by analyzing the RX baseband data at node11-10, you will observe the received tone at 200kHz while the self-interence tone at 100kHz is cancelled to the USRP noise floor, which is around -90dBm. The secondary transmitter can also be used while running the GNU radio flowgraph {{{node_level_sic_fd_gui}}} which will visualize the received signal from {{{node13-8}}}. === Acknowledgements === This work was supported in part by NSF grant ECCS-1547406, DARPA RF-FPGA program, DARPA SPAR program, a Qualcomm Innovation Fellowship, a National Instruments Academic Research Grant, Texas Instruments, and Intel. We thank Steven Alfano, Jelena Diakonikolas, Aishwarya Rajen, Jinhui Song, Mingyan Yu for their contributions to various aspects of the project. We thank Ivan Seskar, Jakub Kolodziejski, and Prasanthi Maddala from WINLAB, Rutgers University, for their help on the integration with the ORBIT testbed. We also thank Kira Theuer and Kendall Ruiz from NI and the NI technical support team for their help.