== Multi channel sample collection with x310 ==

=== Description ===
We'll demonstrate using multiple USRPs to collect samples.

=== Set up ===
 1. [https://www.orbit-lab.org/schedule Make a reservation] of the grid console.
 2. Verify availability of x310s of the grid, then power cycle the x310s with omf commands.
 {{{
   grid> omf stat -t [23,1..8]
   grid> omf tell -a offh -t [23,1..8]
   grid> omf tell -a on   -t [23,1..8]
 }}}

 3. In this example we'll use node21-1 to run the application to collect samples. This node will have access to all usrps on the grid's RF device column ie. ''-t [23,1..8]''

 Load ''baseline-sdr.ndz'' image and then ssh into node21-1
 {{{
   grid> omf load -i baseline-sdr.ndz -t node21-1
   grid> omf tell -a on -t node21-1
   grid> ssh root@node21-1
 }}}

 4. [Optional] Test the PPS input to x310s
 {{{
   root@node21-1:~/uhd/host/build/examples# ./test_pps_input --args="addr=10.10.23.1" --source external
 }}}
 Output text should indicate "Success!"

=== Collect samples ===
 1. The application to collect samples is ''rx_multi_receive''. Run this with --help to get a list of options. 
 {{{
root@node21-1:~/RX_MULTI_RECEIVE# ./rx_multi_receive --help
linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.009.003-0-unknown

UHD RX Multi Samples Allowed options:
  --help                  help message
  --args arg              single uhd device address args
  --secs arg (=1.5)       number of seconds in the future to receive
  --nsamps arg (=10000)   total number of samples to receive
  --freq arg (=900000000) RF center frequency in Hz for all channels
  --rate arg (=6250000)   rate of incoming samples for all channels
  --gain arg (=0)         gain for the RF chain for all channels
  --prefix arg            enables file output with filename prefix
  --addr arg              udp address: 10.10.0.10
  --port arg (=1337)      udp port: 1337
  --sync arg (=now)       synchronization method: now, pps, mimo
  --subdev arg            subdev spec (homogeneous across motherboards)
  --dilv                  specify to disable inner-loop verbose
  --int-n                 tune USRP with integer-N tuning
  --channels arg (=0)     which channel(s) to use (specify "0", "1", "0,1",
                          etc)

 }}}

 This app is very similar to ''rx_multi_sample'' provided in the UHD examples directory but with a few additional arguments.
  * The values given with options --freq and --gain are specified across all channels.
  * Use the option --prefix to collect samples from all channels to a file name tagged with the prefix and channel number.
  * Use the --sync option with PPS option synchronize sampling across all devices. This option selects the time source to the external 10Mhz refernce clock.
  * The samples can also be sent out via UDP by providing --addr and --port.

 2. To collect samples with 3 x310s with both daughter boards (for a total of 6 channels)
 {{{
root@node21-1:~/RX_MULTI_RECEIVE# now="date +%Y%m%d"T"%H%M%S"Z" "
root@node21-1:~/RX_MULTI_RECEIVE# ./rx_multi_receive --nsamps 1024 --rate 5e6 --args="addr0=10.10.23.1,addr1=10.10.23.3,addr2=10.10.23.4" --subdev "A:0 B:0" --channels "0,1,2,3,4,5" --prefix "x310_`$now`_"  --sync "pps" --secs 5
 }}}

 Each channel data is collected into an ascii file with meta information and a binary file with only sample data:
 {{{
-rw-r--r-- 1 root root   27262 May  6 14:28 x310_20160506T142807Z_ch_0_meta
-rw-r--r-- 1 root root    8192 May  6 14:28 x310_20160506T142807Z_ch_0_binary
-rw-r--r-- 1 root root   27643 May  6 14:28 x310_20160506T142807Z_ch_2_meta
-rw-r--r-- 1 root root    8192 May  6 14:28 x310_20160506T142807Z_ch_2_binary
-rw-r--r-- 1 root root   27735 May  6 14:28 x310_20160506T142807Z_ch_1_meta
-rw-r--r-- 1 root root    8192 May  6 14:28 x310_20160506T142807Z_ch_1_binary
-rw-r--r-- 1 root root   27360 May  6 14:28 x310_20160506T142807Z_ch_4_meta
-rw-r--r-- 1 root root    8192 May  6 14:28 x310_20160506T142807Z_ch_4_binary
-rw-r--r-- 1 root root   27678 May  6 14:28 x310_20160506T142807Z_ch_3_meta
-rw-r--r-- 1 root root    8192 May  6 14:28 x310_20160506T142807Z_ch_3_binary
-rw-r--r-- 1 root root   26868 May  6 14:28 x310_20160506T142807Z_ch_5_meta
-rw-r--r-- 1 root root    8192 May  6 14:28 x310_20160506T142807Z_ch_5_binary
 }}}

 3. Details of each channel in the meta file. The channel sample data is also appended in ascii text if the samples collected is less than ~16000.
 {{{
root@node21-1:~/RX_MULTI_RECEIVE# more x310_20160506T142807Z_ch_0_meta
channel              : 0
mboard id            : X310
mboard_serial        : 30A3570
mboard_name          : Mercury
rx_id                : UBX-160 v1 (0x007a)
rx_subdev_name       : UBX RX
rx_subdev_spec       : A:0 B:0
total samples        : 1024
sample size          : 8
RX frequency (MHz)   : 900
RX sample rate (MHz) : 5
RX gain (dB)         : 0
 }}}

 4. The channel's complete sample data is located in the files labeled binary. To quickly view contents of the binary file:
 {{{
root@node21-1:~/RX_MULTI_RECEIVE# hexdump -v -e '"%010_ad [" 2/4 "%f " "]\n"' x310_20160506T142807Z_ch_0_binary
0000000000 [0.000000 0.000031]
0000000008 [-0.000244 -0.000092]
0000000016 [-0.000153 0.000061]
0000000024 [-0.000214 0.000061]
0000000032 [-0.000122 0.000061]
0000000040 [0.000031 0.000153]
0000000048 [-0.000122 -0.000061]
0000000056 [-0.000183 -0.000061]
0000000064 [-0.000092 0.000153]
0000000072 [-0.000031 0.000031]
0000000080 [-0.000153 0.000000]
0000000088 [0.000031 0.000061]
:
:
:
 }}}

 5. As an example here is a plot of the all channels receiving a test signal around 900MHz. Although the signal was captured with the --sync PPS option, the start phase of each signal receive is different from channel to channel.