Outdoor spectrum usage and allocation

Description

Demonstrate outdoor spectrum usage and record measurements to Influx DB.

This example is split into two parts. First part will focus on outdoor spectrum usage and running a simple sdr application for data transfer on shared / non-federal frequency band. Second part will show how to record measured data and visualize statistics using Influx database and Grafana.

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 getting started page to get started.

Resources utilized

• This example will use two x310 SDR on bed.cosmos-lab.org
  • sdr2-s3-lg1.bed.cosmos-lab.org as the transmitting SDR
  • sdr2-s2-lg1.bed.cosmos-lab.org as the receiving SDR
• baseline-uhd.ndz : operating system to load onto above resources.

• [RF control service] to configure the [RF front end's TX chain] on the transmitting SDR.

• ​Influx database - time series database supporting SQL-like queries.
• ​Grafana - a front end visualization and analytic tool for Influx database.

Steps

1. Sign up for a ​COSMOS account
2. Create a resource reservation on bed.cosmos-lab.org
3. Login to your reserved domain.
4. Load baseline-uhd.ndz on your resource. - this is done via OMF

First make sure the resources are turned off

user@console:~$ omf tell -a offh -t sdr2-s2-lg1.bed.cosmos-lab.org,sdr2-s3-lg1.bed.cosmos-lab.org

Load the resources with the image

user@console:~$ omf load -i baseline-uhd.ndz -t sdr2-s2-lg1.bed.cosmos-lab.org,sdr2-s3-lg1.bed.cosmos-lab.org

Turn on the resources

user@console:~$ omf tell -a on -t sdr2-s2-lg1.bed.cosmos-lab.org,sdr2-s3-lg1.bed.cosmos-lab.org

5. Download the application source code from the attachment section below.

   user@console:~$ UPDATE wget https://wiki.cosmos-lab.org/raw-attachment/wiki/tutorials/basic_usage/spectrum_view.tar.gz
   user@console:~$ UPDATE tar -zxvf spectrum_view.tar.gz
   user@console:~$ UPDATE cd SPECTRUM_VIEW
   

Configure transmitter and receive SDRs

Most of this part is scripted via the Makefile. This is to simplify the download and installation of the required libraries onto the resources so we don't have to go back and forth between the console and the resource node.

6. Build the transmit side sdr application.
   Open a terminal and equate the enviroment variable (NODE) to specify the transmitting SDR.

   user@console:~$ export NODE=sdr2-s3-lg1.bed.cosmos-lab.org
   

Next the following make commands are run on the above NODE. This should install all the dependencies to make the sdr application: sdrapp

user@console:~$ make remote-install-deps
user@console:~$ make remote-install-websocket
user@console:~$ make remote-make

Now ssh into the NODE and run sdrapp

user@console:~$ ssh root@$NODE
root@sdr2-s3-lg1:~# cd SDRAPP/build/
root@sdr2-s3-lg1:~/SDRAPP/build# ./sdrapp --cmd "make resource=rio0"

7. Build the receiving side sdr application.
   This is exactly the same as the above step but the environment variable NODE points to a different resource.

Open a terminal again and equate the environment variable (NODE) to specify the receiving SDR.

user@console:~$ export NODE=sdr2-s2-lg1.bed.cosmos-lab.org

Next the following make commands are run on the above NODE. This should install all the dependencies to make the sdr application: sdrapp

user@console:~$ make remote-install-deps
user@console:~$ make remote-install-websocket
user@console:~$ make remote-make

Now ssh into the NODE and run sdrapp

user@console:~$ ssh root@$NODE
root@sdr2-s3-lg1:~# cd SDRAPP/build/
root@sdr2-s3-lg1:~/SDRAPP/build# ./sdrapp --cmd "make resource=rio0"

Keep track of these two terminals. The sdr application will output text as it detected the radios on both transmitter and receiver. When both radios are ready, output similar to the following is shown

:
Number mboards        = 1
Number of rx channels = 2
Number of tx channels = 2
Setting device timestamp to 0...
Device storage: TX
 channels:          2
 buffers  / channel 80
 samples / buffer   256
 bytes / sample     8
 shared memory      0
Device storage: RX
 channels:          2
 buffers  / channel 78125
 samples / buffer   256
 bytes / sample     8
 shared memory      0
[INFO] [main.cpp] Rsp: make resource=rio0

[INFO] [main.cpp] Starting data server at 6180
[INFO] [main.cpp] Starting command server at 5180
[INFO] [main.cpp] Starting websock server at 9002

Turn on the transmitter's power amplifier

8. Configure the transmit antenna using the RF Control service. Please check here for more details on the service.

Open another terminal - this is the 3rd terminal. First we'll configure the TX path, power amplifier and frequency ranges for the transmitting side.

Get current configuration

user@console:~$ curl "am1.cosmos-lab.org:5054/rf_control/get_tx_path?node=sdr2-s3-lg1.bed.cosmos-lab.org"

<response status="OK">
  <nodes>
    <node name="sdr2-s3-lg1.bed.cosmos-lab.org">
      <rf_port number="0" antenna="1" connected="true" power_amp="OFF" f_lower="2350" f_upper="2800"/>
      <rf_port number="1" antenna="3" connected="true" power_amp="OFF" f_lower="2350" f_upper="2800"/>
    </node>
  </nodes>
</response>

Turn on the power amplifier and set frequency appropriately. Check the Outdoor frequency allocation table for acceptable frequency bands. In this example a center frequency of 2600MHz is used.

user@console:~$ curl "am1.cosmos-lab.org:5054/rf_control/set_tx_path?node=sdr2-s3-lg1.bed.cosmos-lab.org&rf_port=0&power_amp=on&f_lower=2500&f_upper=2680"

Transmit and receive over the air

9. Execute the run script to configure and stream both SDRs for receiving and transmitting bursts of packet data. The details in this script are shown below.

   user@console:~$ sh run_data_script.sh
   

The script configures sdr application with radio parameters and begins streaming packets for a few seconds. As long as everything is working fine the script will exit out but the sdr applications will continue to stream packets for a few seconds.

On the transmit side the output should have rows of INFO statements similar to the following.

:
[INFO] [tx_data_link_0]   [sent]   seq_num: 62  pkt_len: 29
[INFO] [tx_data_link_0]   [sent]   seq_num: 63  pkt_len: 8
[INFO] [tx_data_link_0]   [sent]   seq_num: 64  pkt_len: 49
[INFO] [tx_data_link_0]   [sent]   seq_num: 65  pkt_len: 42
[INFO] [tx_data_link_0]   [sent]   seq_num: 66  pkt_len: 63
[INFO] [tx_data_link_0]   [sent]   seq_num: 67  pkt_len: 34
[INFO] [tx_data_link_0]   [sent]   seq_num: 68  pkt_len: 2
:
[INFO] [tx_data_link_0] Transmit complete - summary:
[INFO] [tx_data_link_0] --raw packets:   80 / 21760 bytes
[INFO] [tx_data_link_0] Exitting
:

On the receive side a similar output is expected

:
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 55  pkt_len: 18  corr_strength: 18131.3
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 56  pkt_len: 15  corr_strength: 18124.4
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 57  pkt_len: 3  corr_strength: 18132.9
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 58  pkt_len: 53  corr_strength: 18148.1
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 59  pkt_len: 2  corr_strength: 18128.3
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 60  pkt_len: 34  corr_strength: 18161.1
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 61  pkt_len: 62  corr_strength: 18135.7
[INFO] [rx_data_link_0]   [rcvd]  pkt: OK  seq_num: 62  pkt_len: 29  corr_strength: 18164.7
:
[INFO] [rx_data_link_0] Receive complete - summary:
[INFO] [rx_data_link_0] --raw packets:   79 / 21488 bytes
[INFO] [rx_data_link_0] Avg correlation threshold of successful detections: 18148.4
[INFO] [rx_data_link_0] Exitting
:

10. Lastly turn off the RF front end with the following command.

    user@console:~$ curl "am1.cosmos-lab.org:5054/rf_control/set_tx_path?node=sdr2-s3-lg1.bed.cosmos-lab.org&rf_port=0&power_amp=off"
    

11. Execute the run script again and verify that no packets are received. The transmitters output will show the radio trying to send packets but since the power amplifier is turned on nothing is actually sent over the air. On the receiving end, the radio will still listen for packets however the summary should show 0 packets received.

    :
    [INFO] [rx_data_link_0] Receive complete - summary:
    [INFO] [rx_data_link_0] --raw packets:   0 / 0 bytes
    [INFO] [rx_data_link_0] Avg correlation threshold of successful detections: nan
    [INFO] [rx_data_link_0] Exitting
    :
    

Run script details

View the run_data_script.sh file. A python script is used to remotely configure the sdr application on both the receiving and transmitting side from the console.

user@console:~$ cat run_data_script.sh

The CONFIGURABLES section must have the target node variables pointing at the appropriate devices:

## CONFIGURABLES
export TXNODE=sdr2-s3-lg1.bed.cosmos-lab.org
export RXNODE=sdr2-s2-lg1.bed.cosmos-lab.org

The radio parameters are set up with the following lines.

## SET UP RADIO PORTION HERE
##  Script is set up for x310 which has 2 daughter cards hence 2 channels: {0,1}
##  Both channels must be set to the same sampling rate otherwise HW will barf!


##  Set up transmit / receive chain
##                       txconfig <ch> <freq> <rate> <gain>
##                       rxconfig <ch> <freq> <rate> <gain>

python rc.py $TXNODE 5180 "txconfig 0 2600e6 10e6 25"
python rc.py $TXNODE 5180 "rxconfig 0 2400e6 10e6 5"
python rc.py $TXNODE 5180 "txconfig 1 2000e6 10e6 0"
python rc.py $TXNODE 5180 "rxconfig 1 2050e6 10e6 5"

python rc.py $RXNODE 5180 "rxconfig 0 2600e6 10e6 5"
python rc.py $RXNODE 5180 "txconfig 0 2400e6 10e6 25"
python rc.py $RXNODE 5180 "rxconfig 1 2000e6 10e6 5"
python rc.py $RXNODE 5180 "txconfig 1 2050e6 10e6 0"

After the set up is done, the sdr applications begin streaming data. The receiving end is started first with the specified runtime of 20 seconds. At the same time the transmitting end starts sending packets for 20 seconds at intervals of 250 milliseconds.

## BEGIN data transfer
##  Invoke receive handler
##                       rxsig_data <runtime_in_milliseconds> <correlation threshold>
python rc.py $RXNODE 5180 "rxsig_data 20000 10000"


##  Invoke transmit handler
##                       txsig_data <runtime_in_milliseconds> <delay_between_burst_in_msec>
python rc.py $TXNODE 5180 "txsig_data 20000 250"

In the [next part of this tutorial] we'll add onto the receiving sdr application and recording measured data into Influx Db.