These notes detail the steps necessary to build and install the Segment Control System (SCS). This system comprises a number of parts and several build steps. The build process has been tested with RHEL 6 and RHEL 7 as of this writing, though some steps vary between these targets. Overall, this document will cover the installation of the software located in the SCS repository. This repository is currently located at: svn+ssh://ute2/repos/scs Specific stable releases of the SCS software will be located in the /tags subdirectory of the repository. Additionally, some components will be required that are part of a separate collection called ScsTools. The installation of these components will be summarized in its own section of this document. Finally, SCS has certain hardware configuration requirements that will be summarized below. ################################################## SCS Hardware Install: SCS 2 supports the RS232 serial communication method of SCS 1.x, plus the new ethernet-connected "SMOCO" actuator control system. ----------------------------------------------- RS232 communication support, using StarTech PEX16S550LP PCI-Express low-profile 16-port serial card: No special details for the hardware installation. The card has jumper settings to support power supplied to devices; leave these in their default positions (this feature is not needed). The card uses a serial chipset produced by Systembase; the kernel modules for it must be compiled and installed for the target platform. Make sure OS is up-to-date (sudo yum update) and install drivers using script from StarTech. Download the driver file from the Startech site, find the PDF and an archive containing a script -- sysbas_mpdrv.v21.0.sh as of this writing. This script file contains an embedded compressed archive with the driver source, which the script extracts and attempts to build. Failure in the driver script may be caused by a failure in the build; run the make file (in the directory the script creates) manually to see the error. Kernel source directory mismatch may be fixed by updating OS and ensuring kernel-headers and kernel-devel packages are installed. Once the script successfully runs, the configuration will NOT survive a reboot. Systembase attempts to add the modprobe call to their driver ("golden_tulip") in /etc/rc.d/rc.local. This file must be set to executable in order for this to work: $ sudo chmod +x /etc/rc.d/rc.local ----------------------------------------------- SMOCO communication support: SMOCO motor controllers receive commands and send responses via CAN bus, and an ethernet gateway is provided to make this communication bus accessible to PC software. The gateway product supported by SCS is the "IXXAT CAN@Net NT 200", which supports two physical CAN ports. The two ports must be wired in parallel to each other and to the SMOCO CAN bus, as the second CAN port listens to traffic on the bus and acts as a flow control mechanism. It is highly recommended to place this component on a private network connection and subnet on the server computer, routing communication to it though a physical network interface separate from the server's primary network connection (performance differences have been noted in testing). ################################################## SCS Software Install: Overview The software in this repository is split into two separate builds: libraries (scs_libs) and executable applications and daemon processes. The Libraries must be built and installed before the other software will build successfully. These builds are based on the CMake build system, which must be installed at a minimum version of 3.0. This may be provided by the OS in a package called "cmake" or "cmake3". For ease of use, the GUI tool is recommended; for example in the latter case this package would be called "cmake3-gui". The install instructions below will assume the use of the CMake GUI. Standard CMake usage involves what are called "out-of-source builds", for which CMake creates a build directory separate from the source. Expect to create these directories (likely using the CMake tool) and then discard them along with the source directory tree once the installation is complete. ################################################## Software Prerequisites, basic library components and build tools: The following will assume the use of the 'yum' package manager utility on a RHEL 6 or RHEL 7 system. The build process has been tested on Fedora as well, in which case 'dnf' can be used interchangeably. It is expected as of this writing that RHEL 8 (currently in beta) will have migrated to DNF as well. Basic prerequisites, command line: sudo yum install epel-release make gcc cmake3-gui doxygen libmodbus-devel libconfuse-devel libconfig-devel tk (Substitute "cmake-gui" for "cmake3-gui" if needed). The above is the minimal install list; each of the listed packages may result in the inclusion of multiple additional dependencies, or may be skipped if they're already present in the target system. ~~~~~~~~~~~~~~~~~~~~~~~~~ ZeroMQ Prerequisites: Several processes and libraries in SCS 2 make use of the ZeroMQ message queueing system, and its C API, CZMQ. This dependency is installed differently depending on whether the target is RHEL 6 or RHEL 7+. The release page for ZeroMQ is located here: ZeroMQ: http://zeromq.org/area:download CZMQ: http://czmq.zeromq.org/page:get-the-software According to the above, the official distribution of ZeroMQ software is maintained by OpenSUSE at this link, from which the target OS can be selected: https://build.opensuse.org/repositories/network:messaging:zeromq:release-stable A summary of the installation steps for ZeroMQ follows. ~~~~~~~~~~~~~~~~~~~~~~~~~ Installing on RHEL 7: The versions of ZeroMQ and CZMQ as provided with RHEL 7 are not sufficiently recent to work properly with smocod. These libraries should be at least 4.x versions. The current ZeroMQ libraries should be obtained from the official binary distribution site. Download the following repo file and copy to /etc/yum.repos.d, observing correct ownership and permissions: https://download.opensuse.org/repositories/network:/messaging:/zeromq:/release-stable/RHEL_7/network:messaging:zeromq:release-stable.repo After this Yum repository is installed, the ZeroMQ components are installed with the following command line: sudo yum install zeromq-devel czmq-devel A large number of dependencies may be installed as well. ~~~~~~~~~~~~~~~~~~~~~~~~~ Installing on RHEL 6: A repository is not available for RHEL 6 (and the CentOS 6 repository has been found to have inconsistent dependency problems when used on RHEL 6) so it is recommended to build from source. The source tarballs are distributed from github: ZeroMQ: https://github.com/zeromq/libzmq/releases CZMQ: https://github.com/zeromq/czmq/releases For example, the installation was tested with the following specific releases: https://github.com/zeromq/libzmq/releases/download/v4.3.1/zeromq-4.3.1.tar.gz https://github.com/zeromq/czmq/releases/download/v4.2.0/czmq-4.2.0.tar.gz Extract from these files and from within each resulting directory, build with the standard autotools method: ./configure && make && sudo make install ~~~~~~~~~~~~~~~~~~~~~~~~~ Other prerequisites The actuator position update script (update_positions.py) needed during BCD->smocod migration requires a python module called 'pexpect': sudo yum install pexpect ################################################## Installing SCS Libraries First, launch the CMake GUI (eg. 'cmake3-gui') to configure the out-of-source build for the SCS libraries. For source location field, select 'scs-libs' from inside the source directory containing this file. For the build location field, select a convenient directory separate from the source. For example, the directories might be like the following: Source: /home/username/development_files/src/scs2/scs_libs Build: /home/username/development_files/build/scs_libraries Click Configure, and CMake will make a first attempt to configure the source. Select standard Unix Makefiles as the "generator" when prompted, and if the Build directory you chose doesn't exist, confirm that CMake should create it. Type in "Debug" or "Release" for the CMAKE_BUILD_TYPE. CMAKE_INSTALL_PREFIX should be set to /usr/local for a production install (it can be set to a personal directory for development work). (If Eclipse was selected rather than Unix makefiles, additional fields pertinent to Eclipse projects will be presented; those will not be covered here.) Click Configure again after entering or changing any of these values. Click Generate to create the build directory and set up the build environment. Close the CMake GUI. From within the build directory, execute the command line: make clean && make all && sudo make install This will install the libraries and headers into /usr/local. ################################################## Installing SCS Software The build environment generation will be similar to the above process for the libraries. Launch the GUI, select 'scs' from inside the source directory containing this file. Continuing the above example: Source: /home/username/development_files/src/scs2/scs Build: /home/username/development_files/build/scs_software After clicking Configure and specifying "Debug"/"Release" for CMAKE_BUILD_TYPE, the following entries will also be needed: SCSLibs_DIR: /usr/local/lib/cmake (assuming CMAKE_INSTALL_PREFIX was set to /usr/local for the library install above) MODBUS_INCLUDE_DIR: /usr/include/modbus (correct location will probably be set by default) Click Configure again once these values have been specified, and then click Generate. Exit the GUI. From within the build directory, execute: make clean && make all && sudo make install Executable files should be found in /usr/local/bin. ################################################## SCSTools Install The SCSTools software is needed for communication between SCS and other systems, eg. MARS and SAMS. It is installed in two parts, both of which use an Autotools-based build system. Get the software from the repository: svn+ssh://ute2/repos/scstools For example: svn co svn+ssh://ute2/repos/scstools/UtilLib/trunk UtilLib svn co svn+ssh://ute2/repos/scstools/ScsTools/tags/1.1.1 ScsTools ~~~~~~~~~~~~~~~~~~~~~~~~~ UtilLib must be installed first. Inside the UtilLib/trunk directory from the above repository location, execute the following sequence: autoconf ./configure sudo make sudo make install NOTE that the "make" step also requires superuser priveleges (in addition to the "make install" step where this is normally expected), as it attempts to install header files to /usr/local. After install, /usr/local/lib should contain libcomms.a and liberror.a. ~~~~~~~~~~~~~~~~~~~~~~~~~ The installation of the SCSTools utilities is a little more elaborate. From the ScsTools/tags/1.1.1 directory: libtoolize autoreconf ./configure make sudo make install /usr/local/bin should contain samsclient, marsclient, samsserver, and tiptilt. ################################################## Platform Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~ File Descriptors for smocod The smocod process utilizes a large number of concurrent internal socket connections to coordinate threads. The default of 1024 is insufficient and if smocod is launched in this condition it will report an error and terminate. Add these lines to /etc/security/limits.conf: * soft core unlimited * soft nofile 8192 * hard nofile 65535 Check /etc/pam.d/system-auth for the following line, which it must contain: session required pam_limits.so Reboot after making the necessary changes. Running 'ulimit -n' should return 8192.