documentation and examples

slsdetectorgroup · Nov 12, 2023 · 0aef811 · 0aef811
1 parent 9785a41
commit 0aef811
Show file tree

Hide file tree

Showing 17 changed files with 110 additions and 80 deletions.
diff --git a/docs/src/consuming.rst b/docs/src/consuming.rst
@@ -19,7 +19,7 @@ A minimal CMakeLists.txt could look like this:
 .. code-block:: cmake
 
     project(myDetectorIntegration)
-    cmake_minimum_required(VERSION 3.12)
+    cmake_minimum_required(VERSION 3.14)
     add_subdirectory(slsDetectorPackage)
 
     #Add your executable
@@ -43,7 +43,7 @@ should be needed, otherwise specify cmake prefix path.
 
 .. code-block:: cmake 
 
-    cmake_minimum_required(VERSION 3.12)
+    cmake_minimum_required(VERSION 3.14)
     project(myintegration)
 
     find_package(slsDetectorPackage 5.0 REQUIRED)

diff --git a/docs/src/dependencies.rst b/docs/src/dependencies.rst
@@ -13,7 +13,7 @@ To use the basic building blocks, meaning sls_detector_get/put and
 the shared libraries these are needed: 
 
  * Linux, preferably recent kernel (currently no cross platform support)
- * CMake > 3.14 
+ * CMake >= 3.14 
  * C++11 compatible compiler. (We test with gcc and clang)
 
 -----------------------

diff --git a/docs/src/detector.rst b/docs/src/detector.rst
@@ -1,16 +1,19 @@
 Detector
 ==============================================
 
-The sls::Detector is the new public API to control 
+The sls::Detector is the public API to control 
 detectors from C++. This API is also used internally
 for the Python bindings and the command line interface. 
-If a receiver has been configured this is also controlled
+If a receiver has been configured, this is also controlled
 through this class.
 
 Most, if not all, functions are called in parallel
 and the return value is a thin std::vector wrapper 
-containing results from all modules. (Result<T>)
+containing results from all modules. (:ref:`Result class<Result Class>`)
 
+Here are some :ref:`examples <Cplusplus Api Examples>` on how to use the API.
+
+.. _Cplusplus Api Examples:
 .. doxygenclass:: sls::Detector
    :members:
    :undoc-members:
diff --git a/docs/src/examples.rst b/docs/src/examples.rst
@@ -1,3 +1,4 @@
+.. _Cplusplus Api Examples:
 
 
 
@@ -53,8 +54,8 @@ then set up the detector.
 
     jungfrauDetectorServer_virtual
 
-This launches a virtual Jungfrau detector server. As default is uses port 1952 and 1953
-for communication over TCP. Most commands go on 1952 and only stop and status on 1953. 
+This launches a virtual Jungfrau detector server. As default it uses port 1952 and 1953
+for communication over TCP. Most commands go on 1952 and only a few such as stop and status on 1953. 
 
 **Run example to configure**
 
@@ -90,7 +91,10 @@ std::vector.
     sls::Result<int> res1{1, 1, 1};
     std::cout << "res1: " << res1 << '\n';
     res1.squash();
+    # return -1 if different
     res1.squash(-1);
+    # throw exception with custom message if different
+    res1.tsquash("Values are different);
 
 
 

diff --git a/docs/src/firmware.rst b/docs/src/firmware.rst
@@ -120,7 +120,7 @@ Program from console
         # removes old server from respawn, sets up new lnked server to respawn
         # programs fpga, reboots
 
-        # v5.0.0 - 6.0.0 (copies server from tftp folder of the pc)
+        #  older versions: v5.0.0 - 6.0.0 using tftp from tftp folder of pc
         sls_detector_put update jungfrauDetectorServervxxx pcxxx xx.pof
 
         # v6.1.1 - present (copies server from the full path provided)
@@ -190,7 +190,7 @@ Program from console
         # removes old server from respawn, sets up new lnked server to respawn
         # programs fpga, reboots
 
-        # v5.0.0 - 6.0.0 (copies server from tftp folder of the pc)
+        #  older versions: v5.0.0 - 6.0.0 using tftp from tftp folder of pc
         sls_detector_put update mythen3DetectorServervxxx pcxxx xxx.rbf
 
         # v6.1.1 - present (copies server from the full path provided)
@@ -224,7 +224,7 @@ Program from console
         # removes old server from respawn, sets up new lnked server to respawn
         # programs fpga, reboots
 
-        # v5.0.0 - 6.0.0 (copies server from tftp folder of the pc)
+        #  older versions: v5.0.0 - 6.0.0 using tftp from tftp folder of pc
         sls_detector_put update gotthard2DetectorServervxxx pcxxx xxx.rbf
 
         # v6.1.1 - present (copies server from the full path provided)
@@ -275,7 +275,7 @@ Program from console
         # removes old server from respawn, sets up new lnked server to respawn
         # programs fpga, reboots
 
-        # v5.0.0 - 6.0.0 (copies server from tftp folder of the pc)
+        #  older versions: v5.0.0 - 6.0.0 using tftp from tftp folder of pc
         sls_detector_put update moenchDetectorServervxxx pcxxx xx.pof
 
         # v6.1.1 - present (copies server from the full path provided)
@@ -310,7 +310,7 @@ Program from console
         # removes old server from respawn, sets up new lnked server to respawn
         # programs fpga, reboots
 
-        # v5.0.0 - 6.0.0 (copies server from tftp folder of the pc)
+        #  older versions: v5.0.0 - 6.0.0 using tftp from tftp folder of pc
         sls_detector_put update ctbDetectorServervxxx pcxxx xx.pof
 
         # v6.1.1 - present (copies server from the full path provided)

diff --git a/docs/src/index.rst b/docs/src/index.rst
@@ -8,8 +8,8 @@ Welcome to slsDetectorPackage's documentation!
 
 .. note :: 
 
-    This is the documentation for the latest development version of slsDetectorPackage
-    For documentation on current and previous releases visit the official page: https://www.psi.ch/en/detectors/documentation
+    This is the documentation for the latest development version of slsDetectorPackage.
+    For further documentation, visit the official page: https://www.psi.ch/en/detectors/documentation
 
 .. toctree::
     :maxdepth: 1

diff --git a/docs/src/installation.rst b/docs/src/installation.rst
@@ -113,6 +113,8 @@ Example cmake options               Comment
 -DSLS_USE_PYTHON=ON                 Python
 -DPython_FIND_VIRTUALENV=ONLY       Python from the conda env 
 -DSLS_USE_GUI=ON                    GUI
+-DSLS_USE_HDF5=ON                   HDF5
+-DSLS_USE_SIMULATOR=ON              Simulator
 ===============================     ===============================
 
 .. note ::   
@@ -255,7 +257,7 @@ is to use conda
 
 .. code-block:: bash
 
-    conda create -n myenv python sphinx_rtd_theme breathe
+    conda create -n myenv python=3.12 sphinx sphinx_rtd_theme breathe doxygen numpy
 
 
 .. code-block:: bash
@@ -279,7 +281,7 @@ Pybind and Zeromq
 | v8.0.0+:
 |   pybind11 (v2.11.0) is built 
 |   * by default from tar file in repo (libs/pybind/v2.11.0.tar.gz) 
-|   * or use option SLS_FETCH_PYBIND11_FROM_GITHUB `[link] <https://github.com/pybind/pybind11>`__.
+|   * or use advanced option SLS_FETCH_PYBIND11_FROM_GITHUB [`link <https://github.com/pybind/pybind11>`__].
 |
 | v7.x.x:
 |   pybind11 packaged into 'libs/pybind'. No longer a submodule. No need for "recursive" or "submodule update".
@@ -307,11 +309,11 @@ Pybind and Zeromq
 | v8.0.0+:
 |   zeromq (v4.3.4) is built 
 |   * by default from tar file in repo (libs/libzmq/libzmq-4.3.4.tar.gz) 
-|   * or use option SLS_FETCH_ZMQ_FROM_GITHUB `[link] <https://github.com/zeromq/libzmq.git>`__.
+|   * or use advanced option SLS_FETCH_ZMQ_FROM_GITHUB [`link <https://github.com/zeromq/libzmq.git>`__].
 |
 | v7.x.x and older:
 |   zeromq must be installed and one can hint its location using
 |   * cmake option:'-DZeroMQ_HINT=/usr/lib64' or 
 |   * option '-q' in cmk.sh script: : ./cmk.sh -cbj5 -q /usr/lib64
-|   * 'zeromq' dependencies when installing using conda
+|   * 'zeromq' dependency added when installing using conda
 
diff --git a/docs/src/quick_start_guide.rst b/docs/src/quick_start_guide.rst
@@ -109,12 +109,14 @@ For Multiple Modules
         # connects to mulitple modules
         hostname bchipxxx+bchipyyy+
 
+        # tcp port increases for each module (multi detector command)
+        rx_tcpport 2012
+
         # connects to receivers at ports 2012 and 2014
-        rx_hostname mpc1922:2012+mpc1922:2013+
+        rx_hostname mpc1922
 
-        # sets differernt destination udp ports
-        0:udp_dstport 50012
-        1:udp_dstport 50014
+        # increasing udp ports (multi detector command)
+        udp_dstport 50012
 
         # source udp ips must be same subnet at destintaion udp ips
         0:udp_srcip 192.168.1.112

diff --git a/docs/src/result.rst b/docs/src/result.rst
@@ -1,3 +1,5 @@
+.. _Result Class:
+
 Result
 ==============================================
 

diff --git a/docs/src/slsreceiver.rst b/docs/src/slsreceiver.rst
@@ -52,8 +52,13 @@ Client Commands
 
         # multi modules with custom ports
         rx_hostname xxx:1955+xxx:1956+
+        
+        
+        # multi modules using increasing tcp ports when using multi detector command
+        rx_tcpport 1955
+        rx_hostname xxx
 
-        # multi modules with custom ports on same rxr pc
+        # or specify multi modules with custom ports on same rxr pc
         0:rx_tcpport 1954
         1:rx_tcpport 1955
         2:rx_tcpport 1956

diff --git a/docs/src/virtualserver.rst b/docs/src/virtualserver.rst
@@ -86,7 +86,8 @@ For a Single Module (With Options)
         udp_dstport 50012
 
         # source udp ips must be same subnet at destintaion udp ips
-        udp_srcip 192.168.1.112
+        # takes the same ip as hostname
+        udp_srcip auto
 
         # destination udp ip picked up from rx_hostname (if auto)
         udp_dstip auto
@@ -101,12 +102,14 @@ For Multiple Modules
         virtual 2 1912
         # or hostname localhost:1912+localhost:1914+
 
-        # connects to receivers at ports 2012 and 2014
-        rx_hostname mpc1922:2012+mpc1922:2013+
+        # increasing receiver tcp ports (multi detector command)
+        rx_tcpport 2012
 
-        # sets differernt destination udp ports
-        0:udp_dstport 50012
-        1:udp_dstport 50014
+        # connects to reciever at port 2012 and 2013
+        rx_hostname mpc1922
+
+        # sets increasing destination udp ports
+        udp_dstport 50012
 
         # source udp ips must be same subnet at destintaion udp ips
         0:udp_srcip 192.168.1.112

diff --git a/examples/eiger_10Gb.config b/examples/eiger_10Gb.config
@@ -4,27 +4,33 @@ detsize 1024 512
 # detector hostname for controls
 hostname beb059+beb058+ 
 
-# 1Gb receiver pc hostname with tcp port to configure receiver
-rx_hostname x12sa-vcons:1991+x12sa-vcons:1992
+# increasing receiver tcp port (multi detector command)
+rx_tcpport 1991
 
-# udp port first quadrant, first halfmodule         
-0:udp_dstport 50011 
+# 1Gb receiver pc hostname to configure receiver
+rx_hostname x12sa-vcons
 
-# udp port second quadrant, first halfmodule       
-0:udp_dstport2 50012 
+# or 1Gb receiver pc hostname with tcp port to configure receiver
+#rx_hostname x12sa-vcons:1991+x12sa-vcons:1992
+
+# increasing udp destination ports for all half modules
+udp_dstport 50011
 
+# udp port first quadrant, first halfmodule         
+#0:udp_dstport 50011 
+# udp port second quadrant, first halfmodule       
+#0:udp_dstport2 50012 
+# udp port first quadrant, second halfmodule       
+#1:udp_dstport 50013 
+# udp port second quadrant, second halfmodule  
+#1:udp_dstport2 50014 
+
 # udp IP of the receiver over 10Gb              
 0:udp_dstip 10.0.30.210 
 
 # first half module 10 Gb IP (same subnet as 0:udp_dstip)
 0:udp_srcip 10.0.30.100 
 
-# udp port first quadrant, second halfmodule       
-1:udp_dstport 50013 
-
-# udp port second quadrant, second halfmodule  
-1:udp_dstport2 50014 
-
 # udp IP of the receiver over 10Gb, 
 1:udp_dstip 10.0.40.210  
 

diff --git a/examples/eiger_1Gb.config b/examples/eiger_1Gb.config
@@ -4,18 +4,23 @@ detsize 1024 512
 # detector hostname for controls
 hostname beb059+beb058+ 
 
-# 1Gb receiver pc hostname with tcp port to configure receiver
-rx_hostname x12sa-vcons:1991+x12sa-vcons:1992
+# increasing receiver tcp port (multi detector command)
+rx_tcpport 1991
+
+# 1Gb receiver pc hostname to configure receiver
+rx_hostname x12sa-vcons
+
+# increasing udp destination ports for all half modules
+udp_dstport 50011
 
 # udp port first quadrant, first halfmodule         
-0:udp_dstport 50011 
+#0:udp_dstport 50011 
 #udp port second quadrant, first halfmodule       
-0:udp_dstport2 50012 
-
+#0:udp_dstport2 50012 
 # udp port first quadrant, second halfmodule       
-1:udp_dstport 50013 
+#1:udp_dstport 50013 
 # udp port second quadrant, second halfmodule  
-1:udp_dstport2 50014 
+#1:udp_dstport2 50014 
 
 # output directory
 fpath /sls/X12SA/data/x12saop/Data10/Eiger0.5M
diff --git a/examples/jungfrau_two.config b/examples/jungfrau_two.config
@@ -4,32 +4,30 @@ detsize 1024 1024
 # detector hostname
 hostname bchip048+bchip052+
 
-# 1Gb receiver pc hostname  (default tcpport: 1954)
-rx_hostname pcmoench01:1954+pcmoench01:1955+
+# increasing receiver ports 1954 and 1955 (multi detector command)
+rx_tcpport 1954
 
+# 1Gb receiver pc hostname
+rx_hostname pcmoench01
 
 
-# udp configurations for 1st module
-# udp destination port (receiver)
-0:udp_dstport 50004
+# increasing udp ports 50004 and 50005 (multi detector command)
+udp_dstport 50004
+# or custom udp destination port (receiver) for 1st module
+#0:udp_dstport 50014
+
 
 # udp destination ip (receiver)
 0:udp_dstip 10.1.1.100
 
 # udp source ip (same subnet as 0:udp_dstip)
 0:udp_srcip 10.1.1.10
 
-
-
-# udp configurations for 2nd module
-# udp destination port (receiver)
-1:udp_dstport 50005
-
 # udp destination ip (receiver)
-1:udp_dstip 10.1.1.100
+1:udp_dstip 10.1.2.100
 
 # udp source ip (same subnet as 1:udp_dstip)
-1:udp_srcip 10.1.1.11
+1:udp_srcip 10.1.2.11
 
 
 
@@ -45,5 +43,5 @@ timing trigger
 # output file directory
 fpath /external_pool/jungfrau_data/softwaretest
 
-# disable file writing
+# disable file writing (default)
 fwrite 0
diff --git a/examples/virtual_eiger_2_half_modules.config b/examples/virtual_eiger_2_half_modules.config
@@ -2,10 +2,8 @@
 hostname localhost:1900+localhost:1902+
 
 # udp destination ports
-0:udp_dstport 50000
-0:udp_dstport2 50001
-1:udp_dstport 50002
-1:udp_dstport2 50003
+udp_dstport 50000
+udp_dstport2 50001
 
 # receiver hostname
 rx_hostname mpc1922:2000+mpc1922:2001+