SLS Detector Package Major Release 10.0.0 released on 10.09.2025
================================================================

This document describes the differences between v10.0.0 and v9.2.0   



    CONTENTS
    --------
    1           Changes
    1.1         Compilation Changes
    1.2         New or Changed Features
        1.2.1   Breaking API
        1.2.2   Resolved or Changed Features
        1.2.3   New Features
    3           On-board Detector Server Compatibility
    4           Firmware Requirements
    5           Kernel Requirements
    6           Download, Documentation & Support




1 Changes
==========



1.1 Compilation Changes
========================


    *   C++ standard
        Bumped up C++ standard from 11 (gcc4.8+) to 17 (gcc8+).


    *   GotthardI
        Dropped support for GotthardI from v10.0.0.


    *   PATCH 
        Find PATCH command required for compilation. Needed for lib zeromq patching.


    *   pmodules support discontinued
    

1.2 New or Changed Features
============================



1.2.1 Breaking API
===================


    Client
    ------


    *   Shared Memory Version
        Version has changed and will throw when using an earlier version of 
        shared memory without freeing it first.


    *   [Mythen3] patternX
        This command has been changed back to 'pattern' as before.


    *   TCP API Incompatibility
        The size of the expected structure has changed when setting rx_hostname compared to previous versions. This change makes it incompatible.


    *   User details
        One can get user or detector details directly from shared memory without
        creating the Detector class. It is now a free function.
        C++ API: getUserDetails
        python/ command line: user
        

    Receiver
    --------

    
    *   Multiple ROIs
        Previously, only one ROI was allowed per detector.
        Now, multiple ROIs are allowed, but restricted to a single ROI per
        UDP port. More details on its help.
        
        As before, this ROI is cut out at the receiver level before 
        writing to file. It does not affect network load, but reduces file size.
        
        Please note that the signature has changed in the Detector API as it now expects a vector. getRxROI returns detector level vector of ROIs for
        the entire detector or port level vector of ROIs for the module index
        provided.
        
        Command line: rx_roi, rx_clearroi
        C++ API: get/setRxROI, clearRxROI 

  
    *   Master File Version
        Binary Master Version: 7.3 => 8.0
        HDF5 Master Version: 6.7 => 7.0


    *   Master File Attributes
        - Fixed master file inconsistencies between binary and hdf5 format.
            So the parameter names might differ in master file.
        - Fixed time inconsistencies due to tolerance for gotthardII.
        - Replaced many of the values that was simply writted usign 'toString'
            with array-based output.
        - JSON additional header always written.
        - HDF5 master file reads 'Version', instead of 'version'.    



1.2.2 Resolved or Changed Features
===================================


    Python
    ------


    *   Shared Memory outliving free
        Depending on a variable’s scope, it was possible to access an invalid
        object and its shared memory even after calling free, since resources
        were not fully released. Shared memory structures now include a flag
        indicating invalidity and will throw an error if accessed after being
        freed.


    Client
    ------


    *   UDP Destination List
        CLI: udp_dstlist
        C++ API: getDestinationUDPList
        Was returning incorrect values. Fixed.
        
    
    Receiver
    --------


    *   [Mythen3] Master File Attributes
        Previously, did not create HDF5 Master file without crashing. Fixed now.


    *   Default File Path
        It used to be '/'. Now, changed to empty and will throw if still 
        unchanged before an acquisition.


    *   Command Line Arguments
        They have been refactored for slsReceiver, slsMultiReceiver and 
        slsFrameSynchronizer. Existing commands remain fully supported for now.

        Usage: slsReceiver Options:
            -v, --version       : Version.
            -p, --port          : TCP port to communicate with client for configuration. Non-zero and 16 bit.
            -u, --uid           : Set effective user id if receiver started with privileges. 

        Usage: slsMultiReceiver Options:
            -v, --version       : Version.
            -n, --num-receivers : Number of receivers.
            -p, --port          : TCP port to communicate with client for configuration. Non-zero and 16 bit.
            -c, --callback      : Enable dummy callbacks for debugging. Disabled by default. 
            -u, --uid           : Set effective user id if receiver started with privileges. 

        Usage: slsFrameSynchronizer Options:
            -v, --version       : Version.
            -n, --num-receivers : Number of receivers.
            -p, --port          : TCP port to communicate with client for configuration. Non-zero and 16 bit.
            -c, --print-headers : Print callback headers for debugging. Disabled by default.
            -u, --uid           : Set effective user id if receiver started with privileges. 


    *   [Moench] No intertpolation
        Fixed no interpolation for Moench03.



1.2.3 New Features
===================


    Compilation
    -----------


    *   Conda and pypi
        Automatic release on both upon release.


    Python
    ------


    *   Exposing Free Shared Memory
        One can do either `slsdet.freeSharedMemory()` or `d.free()`


    Client
    ------


    *   Port size and Port per Module Geometry in Detector class
        C++ API: getPortSize, getPortPerModuleGeometry


    *   ROI structure
        Added 'overlap' function to check if it overlaps with another.


    Receiver
    --------


    *   HDF5 Virtual File with ROI
        Previously, virtual file was not created with ROI. It is now.


    *   Readout speed added to Master File
        

    Documentation
    -------------


    *   Multi Detector and Multi user
        Documentation on multi detector index and multi user considerations for
        using the same client system.
            https://slsdetectorgroup.github.io/devdoc/multidet.html

   
    *   10GbE PC tuning
        Further information for permanent ethtool settings updated.
            https://slsdetectorgroup.github.io/devdoc/troubleshooting.html#receiver-pc-tuning-options


    *   Image Size and Output Characteristics
        Information for different detector types and different parameters that
        affect image size and characteristics have been added.
            https://slsdetectorgroup.github.io/devdoc/dataformat.html


    *   'How To' section added
        Software Architecture
            https://slsdetectorgroup.github.io/devdoc/softwarearchitecture.html

        Set up commands most often used in the config file
            https://slsdetectorgroup.github.io/devdoc/configcommands.html

        Quick start guide has been updated
            https://slsdetectorgroup.github.io/devdoc/quick_start_guide.html



2  On-board Detector Server Compatibility
==========================================


    Eiger       10.0.0
    Jungfrau    10.0.0
    Mythen3     10.0.0
    Gotthard2   10.0.0
    Moench      10.0.0
  

    On-board Detector Server Upgrade
    --------------------------------

    From v6.1.0 (without tftp):
        update only on-board detector server
            Using command 'updatedetectorserver'


        udpate both on-board detector server and firmware simultaneously
            Using command 'update'

    Instructions available at
        https://slsdetectorgroup.github.io/devdoc/serverupgrade.html




3 Firmware Requirements
========================

    Eiger       02.10.2023 (v32)                    (updated in 7.0.3)
    
    Jungfrau    09.02.2025 (v1.6, HW v1.0)          (updated in 9.1.0)
                08.02.2025 (v2.6, HW v2.0)          (updated in 9.1.0)

    Mythen3     13.11.2024 (v2.0)                   (updated in 9.0.0)

    Gotthard2   03.10.2024 (v1.0)                   (updated in 9.0.0)

    Moench      26.10.2023 (v2.0)                   (updated in 8.0.2)


    Detector Upgrade
    ----------------

    The following can be upgraded remotely:

    Eiger      via bit files
    Jungfrau   via command <.pof>
    Mythen3    via command <.rbf>
    Gotthard2  via command <.rbf>
    Moench     via command <.pof>

    Except Eiger, 
        upgrade 
            Using command 'programfpga' or

        udpate both on-board detector server and firmware simultaneously
            Using command 'update'


    Instructions available at
        https://slsdetectorgroup.github.io/devdoc/firmware.html




4 Kernel Requirements
======================


    Blackfin 
    --------
    Latest version: Fri Oct 29 00:00:00 2021
    
    Older ones will work, but might have issues with programming firmware via
    the package.


    Nios
    -----
    Compatible version: Mon May 10 18:00:21 CEST 2021


    Kernel Upgrade
    ---------------
    Eiger   via bit files
    Others  via command

    Commands: udpatekernel, kernelversion
    Instructions available at
        https://slsdetectorgroup.github.io/devdoc/commandline.html
        https://slsdetectorgroup.github.io/devdoc/detector.html
        https://slsdetectorgroup.github.io/devdoc/pydetector.html




5 Download, Documentation & Support
====================================

    Download
    --------
    
    The Source Code:
         https://github.com/slsdetectorgroup/slsDetectorPackage
            
    Documentation
    -------------
    
    Installation:
        https://slsdetectorgroup.github.io/devdoc/installation.html

    Quick Start Guide:
        https://slsdetectorgroup.github.io/devdoc/quick_start_guide.html

    Firmware Upgrade:
        https://slsdetectorgroup.github.io/devdoc/firmware.html

    Detector Server upgrade:
        https://slsdetectorgroup.github.io/devdoc/serverupgrade.html

    Detector Simulators:
        https://slsdetectorgroup.github.io/devdoc/virtualserver.html

    Consuming slsDetectorPackage:
        https://slsdetectorgroup.github.io/devdoc/consuming.html
        
    Software Architecture
        https://slsdetectorgroup.github.io/devdoc/softwarearchitecture.html

    Set up commands in config file
        https://slsdetectorgroup.github.io/devdoc/configcommands.html
        
    Image Size and Output Characteristics
        https://slsdetectorgroup.github.io/devdoc/dataformat.html

    API Examples:
        https://github.com/slsdetectorgroup/api-examples

    Command Line Documentation:
        https://slsdetectorgroup.github.io/devdoc/commandline.html

    C++ API Documentation:
        https://slsdetectorgroup.github.io/devdoc/detector.html
       
    C++ API Example:
        https://slsdetectorgroup.github.io/devdoc/examples.html#
        
    Python API Documentation:
        https://slsdetectorgroup.github.io/devdoc/pygettingstarted.html

    Python API Example:
        https://slsdetectorgroup.github.io/devdoc/pyexamples.html

    Receivers (including custom receiver):
        https://slsdetectorgroup.github.io/devdoc/receivers.html
        https://slsdetectorgroup.github.io/devdoc/slsreceiver.html

    Detector UDP Header:
        https://slsdetectorgroup.github.io/devdoc/udpheader.html
        https://slsdetectorgroup.github.io/devdoc/udpdetspec.html

    Output Data:
        https://slsdetectorgroup.github.io/devdoc/dataformat.html
        https://slsdetectorgroup.github.io/devdoc/fileformat.html
        https://slsdetectorgroup.github.io/devdoc/slsreceiverheaderformat.html
        https://slsdetectorgroup.github.io/devdoc/masterfileattributes.html
        https://slsdetectorgroup.github.io/devdoc/binaryfileformat.html
        https://slsdetectorgroup.github.io/devdoc/hdf5fileformat.html

    slsReceiver Zmq Format:
        https://slsdetectorgroup.github.io/devdoc/slsreceiver.html#zmq-json-header-format

    TroubleShooting:
        https://slsdetectorgroup.github.io/devdoc/troubleshooting.html
        https://slsdetectorgroup.github.io/devdoc/troubleshooting.html#receiver-pc-tuning-options
        
    Further Documentation:
        https://www.psi.ch/en/detectors/documentation
        
    Info on Releases:
        https://www.psi.ch/en/detectors/software


    Support
    -------

        dhanya.thattil@psi.ch
        erik.frojdh@psi.ch
        alice.mazzoleni@psi.ch
