rearranged receiver topics, differentiated btween receiver variants and added info about slsFrameSynchronizer

docs/src/slsreceiver.rst

@@ -1,8 +1,44 @@
-slsReceiver/ slsMultiReceiver
+In-built Receiver   
 ================================
 
-| One has to start the slsReceiver before loading config file or using any receiver commands (prefix: **rx_** )
 
+
+The receiver essentially listens to UDP data packets sent out by the detector. It's main features are:
+
+- **Listening**: Receives UDP data from the detector.
+- **Writing to File**: Optionally writes received data to disk.
+- **Streaming via ZMQ**: Optionally streams out the data using ZeroMQ.
+
+Each of these operations runs asynchronously and in parallel for each UDP port.
+
+
+.. note ::   
+
+    * Can be run on the same or different machine as the client.
+    * Can be configured by the client. (set file name/ discard policy, get progress etc.)
+    * Has to be started before the client runs any receiver specific command.
+
+
+Receiver Variants
+-----------------
+There are three main receiver types. How to start them is described :ref:`below<Starting up the Receiver>`.
+
+
++----------------------+------------------+-----------------------------------------+--------------------+--------------------+---------------------+
+| Receiver Type        | Modules Supported| Internal Architecture                   | ZMQ Streaming      | ZMQ Synchronization| Image Reconstruction|
++======================+==================+=========================================+====================+====================+=====================+
+| slsReceiver          | 1                | Threads per port                        | Disabled by default| No                 | No                  |
++----------------------+------------------+-----------------------------------------+--------------------+--------------------+---------------------+
+| slsMultiReceiver     | Multiple         | Multiple child processes of slsReceiver | Disabled by default| No                 | No                  |
++----------------------+------------------+-----------------------------------------+--------------------+--------------------+---------------------+
+| slsFrameSynchronizer | Multiple         | Multi-threading of slsReceiver          | Enabled            | Yes, across ports  | No                  |
++----------------------+------------------+-----------------------------------------+--------------------+--------------------+---------------------+
+
+
+.. _Starting up the Receiver:
+
+Starting up the Receiver
+-------------------------
 For a Single Module
     .. code-block:: bash  
 
@@ -18,25 +54,35 @@ For Multiple Modules
 
         # each receiver (for each module) requires a unique tcp port (if all on same machine)
 
-        # using slsReceiver in multiple consoles
+        # using slsReceiver in multiple consoles (one for each module)
         slsReceiver
         slsReceiver -t1955
 
-        # slsMultiReceiver [starting port] [number of receivers]
+        # slsMultiReceiver [starting port] [number of receivers/modules]
         slsMultiReceiver 2012 2
+        slsFrameSynchronizer 2012 2
 
-        # slsMultiReceiver [starting port] [number of receivers] [print each frame header for debugging]
+
+        # slsMultiReceiver [starting port] [number of receivers/modules] [print for debugging]
         slsMultiReceiver 2012 2 1
+        slsFrameSynchronizer 2012 2 1
+
 
 
 Client Commands 
 -----------------
 
-| One can remove **udp_dstmac** from the config file, as the slsReceiver fetches this from the **udp_ip**.
+* Client commands to the receiver begin with **rx_** or **f_** (file commands).
 
-| One can use "auto" for **udp_dstip** if one wants to use default ip of **rx_hostname**.
+* **rx_hostname** has to be the first command to the receiver so the client knows which reciever process to communicate with.
 
-| The first command to the receiver (**rx_** commands) should be **rx_hostname**. The following are the different ways to establish contact.
+* Can use 'auto' for **udp_dstip** if using 1GbE interface or the :ref:`virtual simulators<Virtual Detector Servers>`.
+
+
+To know more about detector receiver setup in the config file, please check out :ref:`the detector-receiver UDP configuration in the config file<detector udp header config>` and the :ref:`detector udp format<detector udp header>`.
+
+
+The following are the different ways to establish contact using **rx_hostname** command.
 
     .. code-block:: bash  
 
@@ -91,6 +137,32 @@ Client Commands
         sls_detector_get -h rx_framescaught
 
 
+Example of a config file using in-built receiver
+
+.. code-block:: bash
+
+    # detector hostname
+    hostname bchip052+bchip053+
+
+    # udp destination port (receiver)
+    # sets increasing destination udp ports starting at 50004
+    udp_dstport 50004
+
+    # udp destination ip (receiver)
+    0:udp_dstip 10.0.1.100
+    1:udp_dstip 10.0.2.100
+
+    # udp source ip (same subnet as udp_dstip)
+    0:udp_srcip 10.0.1.184
+    1:udp_srcip 10.0.2.184
+
+    # udp destination mac - not required (picked up from udp_dstip)
+    #udp_dstmac 22:47:d5:48:ad:ef
+
+    # connects to receivers at increasing tcp port starting at 1954
+    rx_hostname mpc3434
+    # same as rx_hostname mpc3434:1954+mpc3434:1955+
+
 
 
 Performance