diff --git a/docs/src/index.rst b/docs/src/index.rst index af291cd6e..7dfa8b1b6 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -79,8 +79,9 @@ Welcome to slsDetectorPackage's documentation! :caption: Receiver :maxdepth: 2 - receivers slsreceiver + receivers + .. toctree:: :caption: Receiver Files diff --git a/docs/src/receivers.rst b/docs/src/receivers.rst index 29937cf84..31ff8f734 100644 --- a/docs/src/receivers.rst +++ b/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 packets 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` and the :ref:`detector udp format`. -To know more about detector receiver configuration, please check out :ref:`detector udp header and udp commands in the config file ` +| 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 diff --git a/docs/src/serverupgrade.rst b/docs/src/serverupgrade.rst index c6fe1675a..a215da8ae 100644 --- a/docs/src/serverupgrade.rst +++ b/docs/src/serverupgrade.rst @@ -1,4 +1,5 @@ .. _Detector Server Upgrade: + Upgrade ======== diff --git a/docs/src/slsreceiver.rst b/docs/src/slsreceiver.rst index 0413eb10a..932c25a05 100644 --- a/docs/src/slsreceiver.rst +++ b/docs/src/slsreceiver.rst @@ -1,16 +1,55 @@ -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`. + ++----------------------+--------------------+-----------------------------------------+--------------------------------+ +| Receiver Type | slsReceiver | slsMultiReceiver |slsFrameSynchronizer | ++======================+====================+=========================================+================================+ +| Modules Supported | 1 | Multiple | Multiple | ++----------------------+--------------------+-----------------------------------------+--------------------------------+ +| Internal Architecture| Threads per porttt | Multiple child processes of slsReceiver | Multi-threading of slsReceiver | ++----------------------+--------------------+-----------------------------------------+--------------------------------+ +| ZMQ Streaming | Disabled by default| Disabled by default | Enabled, not optional | ++----------------------+--------------------+-----------------------------------------+--------------------------------+ +| ZMQ Synchronization | No | No | Yes, across ports | ++----------------------+--------------------+-----------------------------------------+--------------------------------+ +| Image Reconstruction | No | No | No | ++----------------------+--------------------+-----------------------------------------+--------------------------------+ + + + + +.. _Starting up the Receiver: + +Starting up the Receiver +------------------------- For a Single Module .. code-block:: bash + + slsReceiver # default port 1954 - # default port 1954 - slsReceiver - - # custom port 2012 - slsReceiver -t2012 + slsReceiver -t2012 # custom port 2012 For Multiple Modules @@ -18,57 +57,66 @@ For Multiple Modules # each receiver (for each module) requires a unique tcp port (if all on same machine) - # using slsReceiver in multiple consoles + # option 1 (one for each module) slsReceiver slsReceiver -t1955 - # slsMultiReceiver [starting port] [number of receivers] + # option 2 slsMultiReceiver 2012 2 - # slsMultiReceiver [starting port] [number of receivers] [print each frame header for debugging] - slsMultiReceiver 2012 2 1 + # option 3 + slsFrameSynchronizer 2012 2 + 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 receiver 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`. + + +To know more about detector receiver setup in the config file, please check out :ref:`the detector-receiver UDP configuration in the config file` and the :ref:`detector udp format`. + + +The following are the different ways to establish contact using **rx_hostname** command. .. code-block:: bash - # default receiver tcp port (1954) + # ---single module--- + + # default receiver port at 1954 + rx_hostname xxx + + # custom receiver port + rx_hostname xxx:1957 # option 1 + + rx_tcpport 1957 # option 2 rx_hostname xxx - # custom receiver port - rx_hostname xxx:1957 - # custom receiver port - rx_tcpport 1954 - rx_hostname xxx + # ---multi module--- - # multi modules with custom ports - rx_hostname xxx:1955+xxx:1956+ - - - # multi modules using increasing tcp ports when using multi detector command + # using increasing tcp ports rx_tcpport 1955 rx_hostname xxx - # or specify multi modules with custom ports on same rxr pc - 0:rx_tcpport 1954 + # custom ports + rx_hostname xxx:1955+xxx:1958+ # option 1 + + 0:rx_tcpport 1954 # option 2 1:rx_tcpport 1955 2:rx_tcpport 1956 rx_hostname xxx - # multi modules with custom ports on different rxr pc + # custom ports on different receiver machines 0:rx_tcpport 1954 0:rx_hostname xxx 1:rx_tcpport 1955 - 1:rx_hostname yyy + 1:rx_hostname yyyrxr | Example commands: @@ -91,6 +139,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 diff --git a/docs/src/udpconfig.rst b/docs/src/udpconfig.rst index f3e56d82a..847b11899 100644 --- a/docs/src/udpconfig.rst +++ b/docs/src/udpconfig.rst @@ -1,4 +1,4 @@ -.. _detector udp header: +.. _detector udp header config: Config file diff --git a/docs/src/virtualserver.rst b/docs/src/virtualserver.rst index ae1073d8e..226a94c98 100644 --- a/docs/src/virtualserver.rst +++ b/docs/src/virtualserver.rst @@ -1,4 +1,5 @@ .. _Virtual Detector Servers: + Simulators ===========