From 603ddb0d754e5fc8db11441b41c01aa0a182a269 Mon Sep 17 00:00:00 2001 From: Dhanya Thattil Date: Fri, 25 Sep 2020 19:24:26 +0200 Subject: [PATCH] updated docs, execcommand multiple words --- RELEASE.txt | 116 ++++++++- docs/CMakeLists.txt | 2 + docs/src/commandline.rst | 18 +- docs/src/firmware.rst | 357 +++++++++++++++++++++++++++ docs/src/index.rst | 6 + docs/src/installation.rst | 20 ++ docs/src/serverupgrade.rst | 88 +++++++ slsDetectorSoftware/src/CmdProxy.cpp | 7 +- 8 files changed, 608 insertions(+), 6 deletions(-) create mode 100644 docs/src/firmware.rst create mode 100644 docs/src/serverupgrade.rst diff --git a/RELEASE.txt b/RELEASE.txt index 492ba483b..ac6469594 100755 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -1,2 +1,114 @@ -Draft -- dr 4, 8, 16 in eiger -> speed 0, 32 stays same (speed 1) +SLS Detector Package 5.0.0-rc1 released on 25.09.2020 (Release Candidate 1) +=========================================================================== + + CONTENTS + -------- + 1. Firmware Requirements + 2. Download, Documentation & Support + + +1. Firmware Requirements +======================== + + Eiger + ===== + Minimum compatible version : 27 + Latest compatible version : 27 + + Jungfrau + ======== + Minimum compatible version (PCB v1.0) : 24.07.2020 (v0.8) + Latest compatible version (PCB v1.0) : 24.07.2020 (v0.8) + Minimum compatible version (PCB v2.0) : 21.07.2020 (v2.1) + Latest compatible version (PCB v2.0) : 21.07.2020 (v2.1) + + Gotthard + ======== + Minimum compatible version : 11.01.2013 + Latest compatible version : 08.02.2018 (50um and 25um Master) + 09.02.2018 (25 um Slave) + + Mythen3 + ======= + Minimum compatible version : 25.09.2020 + Latest compatible version : 25.09.2020 + + Gotthard2 + ========= + Minimum compatible version : 25.09.2020 + Latest compatible version : 25.09.2020 + + Moench + ====== + Minimum compatible version : 02.03.2020 + Latest compatible version : 02.03.2020 + + Ctb + === + Minimum compatible version : 27.11.2019 + Latest compatible version : 27.11.2019 + + + Detector Upgrade + ================ + Eiger Remotely via bit files + Jungfrau Remotely using sls_detector_put programfpga + Gotthard Cannot be upgraded remotely. Requires programming via USB blaster + Mythen3 Remotely using sls_detector_put programfpga + Gotthard2 Remotely using sls_detector_put programfpga + Moench Remotely using sls_detector_put programfpga + Ctb Remotely using sls_detector_put programfpga + + Instructions available at + https://slsdetectorgroup.github.io/devdoc/firmware.html + + Please refer to the link below for more details on the firmware versions. + https://www.psi.ch/en/detectors/firmware + + +2. Download, Documentation & Support +==================================== + + Download + -------- + + The Source Code (Default C++ API): + https://github.com/slsdetectorgroup/slsDetectorPackage + + Documentation + ------------- + + Installation: + https://slsdetectorgroup.github.io/devdoc/installation.html# + + Consuming slsDetectorPackage: + https://slsdetectorgroup.github.io/devdoc/consuming.html + + 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 + + TroubleShooting: + https://www.psi.ch/en/detectors/troubleshooting + + Further Documentation: + https://www.psi.ch/en/detectors/users-support + + + Support + ------- + + dhanya.thattil@psi.ch + erik.frojdh@psi.ch + anna.bergamaschi@psi.ch diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index b39097084..da5807142 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -45,6 +45,8 @@ set(SPHINX_SOURCE_FILES src/ToString.rst src/examples.rst src/pygettingstarted.rst + src/firmware.rst + src/serverupgrade.rst ) diff --git a/docs/src/commandline.rst b/docs/src/commandline.rst index 1a7380745..11cb67ed8 100644 --- a/docs/src/commandline.rst +++ b/docs/src/commandline.rst @@ -4,12 +4,28 @@ Command line interface Usage ------------- -Commands can be uses either with sls_detector_get or sls_detector_put +Commands can be used either with sls_detector_get or sls_detector_put .. code-block:: sls_detector_get vrf +Help +-------- + +.. code-block:: + + # get list of commands + sls_detector_get list + + # search for a particular command using a word + sls_detector_get list | grep adc + + # get help for a particular command + sls_detector_get -h fpath + sls_detector_help fpath + + Commands ----------- diff --git a/docs/src/firmware.rst b/docs/src/firmware.rst new file mode 100644 index 000000000..ab5f31d30 --- /dev/null +++ b/docs/src/firmware.rst @@ -0,0 +1,357 @@ +Firmware Upgrade +================= + + + +Eiger +------------- +.. note :: + | Eiger firmware can be upgraded remotely. + | The programming executable (bcp) and corresponding bit files are provided by the SLS Detector group. + + +Compatibility +^^^^^^^^^^^^^ + +**Release candidate 5.0.0-rc1** + .. code-block:: bash + + Minimum compatible version : 27 + Latest compatible version : 27 + +`Older versions `_ + + +Upgrade +^^^^^^^^ +#. Tftp must be already installed on your pc to use the bcp executable. + +#. Kill the on-board servers and copy new servers to the board. + + .. code-block:: bash + + # Option 1: from detector console + # kill old server + ssh root@bebxxx + killall eigerDetectorServer + + # copy new server + cd executables + scp user@pc:/path/eigerDetectorServerxxx . + chmod 777 eigerDetectorServerxxx + ln -sf eigerDetectorServerxxx eigerDetectorServer + sync + + # Options 2: from client console for multiple modules + for i in bebxxx bebyyy; + do ssh root@$i killall eigerDetectorServer; + scp eigerDetectorServerxxx root@$i:~/executables/eigerDetectorServer; + ssh root@$i sync; done + + + * This is crucial when registers between firmwares change. Failure to do so will result in linux on boards to crash and boards can't be pinged anymore. + +#. Bring the board into programmable mode using either of the 2 ways. Both methods result in only the central LED blinking. + + * **Manual:** + + Do a hard reset for each half module on back panel boards, between the LEDs, closer to each of the 1G ethernet connectors. Push until all LEDs start to blink. + + * Software: + .. code-block:: bash + + ssh root@bebxxx + cd executables + ./boot_recovery + +#. Start a terminal for each half module and run the following to see progress. + + .. code-block:: bash + + nc -p 3000 -u bebxxx 3000 + # Press enter twice to see prompt with board name. + > bebxxx + # After each bcp command, wait for this terminal to print "Success". + + +#. In another terminal, run the following to update firmware. Please update bit files with great caution as it could make your board inaccessible, if done incorrectly. + + .. code-block:: bash + + #update back end fpga + bcp download.bit bebxxx:/fw0 + + #update front left fpga + bcp download.bit bebxxx:/febl + + #update front right fpga + bcp download.bit bebxxx:/febr + + #update kernel (only if required by the SLS Detector Group) + bcp download.bit bebxxx:/kernel + +#. Reboot the detector. + +Jungfrau +------------- +.. note :: + | Jungfrau firmware can be upgraded remotely. + | The corresponding programming file (pof) is provided by the SLS Detector group. + + +Compatibility +^^^^^^^^^^^^^ + +**Release candidate 5.0.0-rc1** + + .. code-block:: bash + + # PCB v1.0 + Minimum compatible version : 24.07.2020 (v0.8) + Latest compatible version : 24.07.2020 (v0.8) + # PCB v2.0 + Minimum compatible version : 21.07.2020 (v2.1) + Latest compatible version : 21.07.2020 (v2.1) + +`Older versions `_ + + +Upgrade (from v4.x.x) +^^^^^^^^^^^^^^^^^^^^ +#. Tftp must be installed on pc. + +#. Update client package to the latest (5.0.0-rc1). + +#. Disable server respawning or kill old server + .. code-block:: bash + + # Option 1: if respawning enabled + telnet bchipxxx + # edit /etc/inittab + # comment out line #ttyS0::respawn:/jungfrauDetectorServervxxx + reboot + # ensure servers did not start up after reboot + telnet bchipxxx + ps + + # Option 2: if respawning already disabled + telnet bchipxxx + killall jungfrauDetectorServerv* + +#. Copy new server and start in update mode + .. code-block:: bash + + tftp pcxxx -r jungfrauDetectorServervxxx -g + chmod 777 jungfrauDetectorServervxxx + ./jungfrauDetectorServervxxx -u + +#. Program fpga from the client console + .. code-block:: bash + + sls_detector_get free + # Crucial that the next command executes without any errors + sls_detector_put hostname bchipxxx + sls_detector_put programfpga xxx.pof + +#. After programming, kill update server using Ctrl + C. + +#. Enable server respawning if needed + .. code-block:: bash + + telnet bchipxxx + # edit /etc/inittab + # uncomment out line #ttyS0::respawn:/jungfrauDetectorServervxxx + # ensure the line has the new server name + reboot + # ensure both servers are running using ps + jungfrauDetectorServervxxx + jungfrauDetectorServervxxx --stop-server 1953 + + +Upgrade (from v5.0.0-rc1) +^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Program from console + .. code-block:: bash + + # copies server from tftp folder of pc, programs fpga, + # removes old server from respawn, sets up new server to respawn + # and reboots + sls_detector_put update jungfrauDetectorServervxxx pcxxx xx.pof + + # Or only program firmware + sls_detector_put programfpga xxx.pof + + +Gotthard +--------- + +.. warning :: + | Gotthard firmware cannot be upgraded remotely and requires the use of USB-Blaster. + | It is generally updated by the SLS Detector group. + + +Compatibility +^^^^^^^^^^^^^ + +**Release candidate 5.0.0-rc1** + + .. code-block:: bash + + Minimum compatible version : 11.01.2013 + Latest compatible version : 08.02.2018 (50um and 25um Master) + 09.02.2018 (25 um Slave) + +`Older versions `_ + + +Upgrade +^^^^^^^^ + +#. Download `Altera Quartus software or Quartus programmer `_. + + +#. Start Quartus programmer, click on Hardware Setup. In the "Currently selected hardware" window, select USB-Blaster. + +#. In the Mode combo box, select "Active Serial Programming". + +#. Plug the end of your USB-Blaster with the adaptor provided to the connector 'AS config' on the Gotthard board. + +#. Click on 'Add file'. Select programming (pof) file provided by the SLS Detector group. + +#. Check "Program/Configure" and "Verify". Push the start button. Wait until the programming process is finished. + +#. In case of error messages, check the polarity of cable (that pin1 corresponds) and that the correct programming connector is selected. + +#. Reboot the detector. + + +Mythen3 +------- +.. note :: + | Mythen3 firmware can be upgraded remotely. + | The corresponding programming file (rbf) is provided by the SLS Detector group. + + +Compatibility +^^^^^^^^^^^^^ + +**Release candidate 5.0.0-rc1** + + .. code-block:: bash + + Minimum compatible version : 25.09.2020 + Latest compatible version : 25.09.2020 + + +Upgrade (from v5.0.0-rc1) +^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Program from console + .. code-block:: bash + + # copies server from tftp folder of pc, programs fpga, + # and reboots (new server not respawned currently) + sls_detector_put update mythen3DetectorServervxxx pcxxx xxx.rbf + + # Or only program firmware + sls_detector_put programfpga xxx.rbf + + + +Gotthard2 +---------- +.. note :: + | Gotthard2 firmware can be upgraded remotely. + | The corresponding programming file (rbf) is provided by the SLS Detector group. + + +Compatibility +^^^^^^^^^^^^^ + +**Release candidate 5.0.0-rc1** + + .. code-block:: bash + + Minimum compatible version : 25.09.2020 + Latest compatible version : 25.09.2020 + + +Upgrade (from v5.0.0-rc1) +^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Program from console + .. code-block:: bash + + # copies server from tftp folder of pc, programs fpga, + # and reboots (new server not respawned currently) + sls_detector_put update gotthard2DetectorServervxxx pcxxx xxx.rbf + + # Or only program firmware + sls_detector_put programfpga xxx.rbf + + + +Moench +------ +.. note :: + | Moench firmware can be upgraded remotely. + | The corresponding programming file (pof) is provided by the SLS Detector group. + + +Compatibility +^^^^^^^^^^^^^ + +**Release candidate 5.0.0-rc1** + + .. code-block:: bash + + Minimum compatible version : 02.03.2020 + Latest compatible version : 02.03.2020 + + +Upgrade (from v5.0.0-rc1) +^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Program from console + .. code-block:: bash + + # copies server from tftp folder of pc, programs fpga, + # removes old server from respawn, sets up new server to respawn + # and reboots + sls_detector_put update moenchDetectorServervxxx pcxxx xx.pof + + # Or only program firmware + sls_detector_put programfpga xxx.pof + +Ctb +--- +.. note :: + | Ctb firmware can be upgraded remotely. + | The corresponding programming file (pof) is provided by the SLS Detector group. + + +Compatibility +^^^^^^^^^^^^^ + +**Release candidate 5.0.0-rc1** + + .. code-block:: bash + + Minimum compatible version : 27.11.2019 + Latest compatible version : 27.11.2019 + + +Upgrade (from v5.0.0-rc1) +^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Program from console + .. code-block:: bash + + # copies server from tftp folder of pc, programs fpga, + # removes old server from respawn, sets up new server to respawn + # and reboots + sls_detector_put update ctbDetectorServervxxx pcxxx xx.pof + + # Or only program firmware + sls_detector_put programfpga xxx.pof \ No newline at end of file diff --git a/docs/src/index.rst b/docs/src/index.rst index 5ece80817..8643f477f 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -54,6 +54,12 @@ Welcome to slsDetectorPackage's documentation! :caption: Servers servers + serverupgrade + +.. toctree:: + :caption: Firmware + + firmware .. Indices and tables .. ================== diff --git a/docs/src/installation.rst b/docs/src/installation.rst index eb5822f5f..1bb451c04 100644 --- a/docs/src/installation.rst +++ b/docs/src/installation.rst @@ -44,6 +44,26 @@ The easiest way to configure options is to use the ccmake utility. ccmake . +Build using cmk.sh script +------------------------- +.. code-block:: bash + + # new build and make with 9 parallel threads + ./cmk.sh -cbj9 + + # build with python + ./cmk.sh -bpj9 + + # build with GUI + ./cmk.sh -bgj9 + + # build with hdf5 + ./cmk.sh -hj9 -d [path of hdf5 dir] + + # get all options + ./cmk.sh -? + + Install binaries using conda -------------------------------- diff --git a/docs/src/serverupgrade.rst b/docs/src/serverupgrade.rst new file mode 100644 index 000000000..592a06dca --- /dev/null +++ b/docs/src/serverupgrade.rst @@ -0,0 +1,88 @@ +Server Upgrade +================= + + + +Eiger +------------- + +#. Kill old server and copy new server + .. code-block:: bash + + # Option 1: from detector console + # kill old server + ssh root@bebxxx + killall eigerDetectorServer + + # copy new server + cd executables + scp user@pc:/path/eigerDetectorServerxxx . + chmod 777 eigerDetectorServerxxx + ln -sf eigerDetectorServerxxx eigerDetectorServer + sync + + # Options 2: from client console for multiple modules + for i in bebxxx bebyyy; + do ssh root@$i killall eigerDetectorServer; + scp eigerDetectorServerxxx root@$i:~/executables/eigerDetectorServer; + ssh root@$i sync; done + + +#. Reboot the detector. + + +Jungfrau +------------- + +#. Program from console (only from 5.0.0-rc1) + .. code-block:: bash + + # copies new server from pc tftp folder, respawns and reboots + sls_detector_put copydetectorserver jungfrauDetectorServerxxx pcxxx + + +Gotthard +--------- +#. Program from console (only from 5.0.0-rc1) + .. code-block:: bash + + # copies new server from pc tftp folder, respawns and reboots + sls_detector_put copydetectorserver gotthardDetectorServerxxx pcxxx + + + +Mythen3 +------- + +#. Program from console (only from 5.0.0-rc1) + .. code-block:: bash + + # copies new server from pc tftp folder and reboots (does not respawn) + sls_detector_put copydetectorserver mythen3DetectorServerxxx pcxxx + + +Gotthard2 +---------- +#. Program from console (only from 5.0.0-rc1) + .. code-block:: bash + + # copies new server from pc tftp folder and reboots (does not respawn) + sls_detector_put copydetectorserver gotthard2DetectorServerxxx pcxxx + + +Moench +------ +#. Program from console (only from 5.0.0-rc1) + .. code-block:: bash + + # copies new server from pc tftp folder, respawns and reboots + sls_detector_put copydetectorserver moenchDetectorServerxxx pcxxx + + +Ctb +--- +#. Program from console (only from 5.0.0-rc1) + .. code-block:: bash + + # copies new server from pc tftp folder, respawns and reboots + sls_detector_put copydetectorserver ctbDetectorServerxxx pcxxx diff --git a/slsDetectorSoftware/src/CmdProxy.cpp b/slsDetectorSoftware/src/CmdProxy.cpp index 7b05a8e2b..d4fce7586 100644 --- a/slsDetectorSoftware/src/CmdProxy.cpp +++ b/slsDetectorSoftware/src/CmdProxy.cpp @@ -2680,10 +2680,11 @@ std::string CmdProxy::ExecuteCommand(int action) { } else if (action == defs::GET_ACTION) { throw sls::RuntimeError("Cannot get."); } else if (action == defs::PUT_ACTION) { - if (args.size() != 1) { - WrongNumberOfParameters(1); + std::string command; + for (auto &i: args) { + command += (i + ' '); } - auto t = det->executeCommand(args[0], std::vector{det_id}); + auto t = det->executeCommand(command, std::vector{det_id}); os << OutString(t) << '\n'; } else { throw sls::RuntimeError("Unknown action");