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

docs/src/index.rst

@@ -79,8 +79,9 @@ Welcome to slsDetectorPackage's documentation!
     :caption: Receiver
     :maxdepth: 2
 
-    receivers
     slsreceiver
+    receivers
+    
 
 .. toctree::
     :caption: Receiver Files

docs/src/receivers.rst

@@ -1,25 +1,25 @@
-Receivers
+Custom Receiver
 =================
 
-Receiver processes can be run on same or different machines as the client, receives the data from the detector (via UDP packets).
-When using the slsReceiver/ slsMultiReceiver, they can be further configured by the client control software (via TCP/IP) to set file name, file path, progress of acquisition etc.
+The receiver essentially listens to UDP data packats sent out by the detector.
+
+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>`.
 
 
-To know more about detector receiver configuration, please check out :ref:`detector udp header and udp commands in the config file <detector udp header>`
+| Please note the following when using a custom receiver:
 
-Custom Receiver
-----------------
+* **udp_dstmac** must be configured in the config file. This parameter is not required when using an in-built receiver.
 
-| When using  custom receiver with our package, ensure that **udp_dstmac** is also configured in the config file. This parameter is not required when using slsReceiver.
+* Cannot use "auto" for **udp_dstip**.
 
-| Cannot use "auto" for **udp_dstip**.
+* No **rx_** commands in the config file. These commands are for configuring the slsReceiver.
 
-| Also ensure that there are no **rx_** commands in the config file. These commands are for configuring the slsReceiver.
+
+
+The main difference is the lack of **rx_** commands or file commands (eg. **f**write, **f**path) and the **udp_dstmac** is required in config file.
 
 Example of a custom receiver config file
 
-* The main difference is the lack of **rx_** commands or file commands (eg. fwrite, fpath) and the udp_dstmac is required in config file.
-
 .. code-block:: bash
 
     # detector hostname

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 

docs/src/udpconfig.rst

@@ -1,4 +1,4 @@
-.. _detector udp header:
+.. _detector udp header config:
 
 
 Config file