Changes between Version 9 and Version 10 of Tutorials/k0SDR/Tutorial20

Timestamp:

Feb 16, 2017, 6:19:07 PM (7 years ago)

Author:

nilanjan

Comment:

—

Tutorials/k0SDR/Tutorial20

@@ -7 +7 @@
 2) controller node (ie. node21-1) imaged with ''ubuntu-14-04-64bit-uhd-003.010.001-gnu-3.7.10.ndz'' \\
 3) OML - Orbit Measurement Library to record measurements into database \\
-4) rf_hw_intf - application to configure a set of USRPs for receiving samples at a specified frequency, samples rate, gain, etc... \\
+4) rf_hw_intf - this a multi-channel uhd streaming application to configure a set of USRPs for receiving samples at a specified frequency, samples rate, gain, etc... \\
 5) sigproc_avg_bw_pwr - application for processing received samples and writing in OML database \\
 
-Details on the applications can be found on this page.
+Details on the streaming applications can be found on this page.
 
 === Receive multi channel signal for processing and plotting ===
@@ -94 +94 @@
 
  || [[Image(mimo_rx.png, width=600px)]] ||
+
+
+
+
+
+
+== Multi-channel Uhd STreamer ==
+
+=== Description ===
+A high-level application to stream real-time samples from multiple IP addressable USRP devices. 
+
+=== How it works (without going into the source-code :-D ===
+Application is split into two run-time objects:
+ 1) hardware interface application - talks to radio and manages sample streaming\\
+ 2) signal handler application - a customized application to process streams samples.
+
+The hardware interface application controls and initializes the USRP devices with configuration parameters, enables a remote-commander for run-time query and limited parameter updates and configures a circular queue of shared memory buffers (similar to IPC) for continuous real-time sample streaming to/from the device. At the moment this can run in one mode: receive OR transmit streaming. This object uses an XML file containing a list of devices with configuration parameters to set up all the devices. Once all the devices are configured, this starts a continuous receive / transmit streaming thread for the signal handler application. 
+
+The second object attaches to the already created shared memory buffer and allows customized processing of the streaming samples in the receive direction or construction of samples in the transmit direction.
+
+=== Source code & compilation ===
+Download the source code from here.
+
+Install the required libraries using the package manager and then use ''make'' to generate the executable.
+{{{
+> apt-get update
+> apt-get install libboost-all-dev libpugixml-dev libpugixml1 liblog4cxx10 liblog4cxx10-dev
+
+> make
+}}}
+
+Upon successful compilation the following apps will be generated:
+ 1) ''rf_hw_intf''          - the hardware interface application \\
+ 2) ''sigproc_avg_bw_pwr''  - example signal handler application for processing received samples \\
+ 3) ''sigtran''             - example transmit side signal handler application for transmitting 
+\\ 
+
+
+== Hardware interface application ==
+
+The ''rf_hw_intf'' must be specified with an an xml file for device configuration and direction for sample processing.
+For a list of arguments use ''--help'':
+{{{
+linux; GNU C++ version 4.8.4; Boost_105400; UHD_003.010.001.000-0-unknown
+
+Multi-channel Uhd STreamer v000.001.000
+ Allowed options:
+  --help                 help message
+  --conf arg             specify xml device configuration file and path
+                         "devices.xml,/devices/active"
+  --print-conf           print device conf
+  --rx-only              enable receive direction only
+  --tx-only              enable transmit direction only
+  --cmd-port arg (=5180) command server port
+}}}
+
+
+
+=== XML file ===
+The XML file template is described below. A description of the xml nodes and attributes are in the table.
+{{{
+ <devices>
+  <_grp_rx_ sync="now" rx_freq="1900e6" rx_rate="5e6" rx_gain="10">
+    <device type="n210" ip="192.168.101.102">
+      <ch rx_bw="25e6" rx_ant="RX2"
+          tx_gain="20" tx_bw="25e6" tx_ant="TX/RX" />
+    </device>
+
+    <device type="x310" ip="10.10.23.2">
+      <ch rx_bw="25e6" rx_ant="RX2"
+          tx_gain="20" tx_bw="25e6" tx_ant="TX/RX" />
+    </device>
+  </_grp_rx_>
+ <devices>
+
+}}}
+
+
+ ||'''Group (parent) nodes / attributes'''  || Description ||
+ || _grp_rx || specify a group name for a cluster of devices  ||
+ || sync || clock/time source options \\ now - use internal clock,\\  pps - use external clock and external time source  ||
+
+ ||'''Device (child) nodes / attributes'''  || Description ||
+ || device || specifies a unique radio  ||
+ || type || device category \\ b200 - this USB based devices. ie. no IP address \\ n210 - IP addressable, must specify sttribute: ip \\ x310 - IP addressable, must specify sttribute: ip  ||
+ || ip || address of device  ||
+
+ ||'''Group / channel attributes, \\ channel attribute takes precedence '''  || Description ||
+ || ch || specifies a unique radio within device  ||
+ || rx_freq || receiver carrier frequency  ||
+ || rx_gain || receiver gain  ||
+ || rx_rate || receiver rate  ||
+ || rx_bw   || receiver bandwidth  ||
+ || rx_ant  || receiver antenna options: \\ TX/RX \\ RX2 ||
+ || tx_freq || transmit carrier frequency  ||
+ || tx_gain || transmit gain  ||
+ || tx_rate || transmit rate  ||
+ || tx_bw   || transmit bandwidth  ||
+ || tx_ant  || transmit antenna options: \\ TX/RX ||
+
+
+=== Command server ===
+The command server can be used to communicate with the application and issue a limited set of control and query commands. This a way to remotely control the device settings during runtime.
+ ||''' RC commands '''  || Description ||
+ || rxfreq all || get rx carrier frequency for all channels ||
+ || rxgain all || get rx gain for all channels ||
+ || rxrate all || get rx rate for all channels ||
+ || rxfreq all <freq> || set rx carrier frequency for all channels ||
+ || rxgain all <gain> || set rx gain for all channels ||
+ || ---- || set rx rate is not supported during runtime ||
+
+ || txfreq all || get tx carrier frequency for all channels ||
+ || txgain all || get tx gain for all channels ||
+ || txrate all || get tx rate for all channels ||
+ || txfreq all <freq> || set tx carrier frequency for all channels ||
+ || txgain all <gain> || set tx gain for all channels ||
+ || ---- || set tx rate is not supported during runtime ||
+
+
+=== Usage Example=== 
+To stream samples in the receive direction from the device group in /devices/mimo_rx with a command server listening on port 5111.
+{{{
+node21-1> ./rf_hw_intf --conf "mimo1.xml,/devices/mimo_rx" --rx-only --cmd-port 5111
+}}}
+
+Stream samples in the transmit direction:
+{{{
+node1-1> ./rf_hw_intf --conf "devices.xml,/devices/grid_tx" --tx-only --cmd-port 5112
+}}}
+
+Use the python script to run commands via the hardware interface's command port:
+{{{
+console> python rc.py node21-1 5111 "rxfreq all"
+console> python rc.py node21-1 5111 "rxfreq all 2800e6"
+}}}
+
+== Signal handler applications ==
+The signal handler application attaches the shared memory buffer allocated by the hardware interface app.
+Both receive and transmit direction have separate shared memory buffers. The signal handler applications are meant to be run for several iterations without stopping the hardware interface.
+
+An example of a receive direction signal handler is provided. Running is app will attach to the receive side shared memory buffer and perform some processing on the received samples. This app (or some variation of it with a different signal handler) can be run for several iterations without stopping the hardware interface application.
+{{{
+node21-1> ./sigproc_avg_bw_pwr --time 15
+}}}
+
+
+Likewise a signal handler for the transmit direction is provided as an example. This attaches to the transmit direction shared memory buffer and populates with predefined samples passed in as an argument.
+{{{
+node1-1> samps="octave -qf awgn256.m"
+node1-1> ./sigtran --sig "`$samps`" --intv 500
+}}}
+
+== Tutorials ==
+* Multi Channel Sample Processing & Visualization