Installation & Configuration

Requirements and Supported Platforms

System Requirements

  • 64-bit Intel/AMD processor (x86_64)

  • Minimum 6 GB disk space to download and install.

  • 64-bit Linux (glibc >= 2.12)

  • BASH or ZSH as your default shell environment (T/CSH is NOT supported)

Software Requirements

Because MCS is written mostly in Python and ANSI C, it can run on any platform that has the required Python modules and GCC compilier. However, it has been developed and deeply tested under CentOS 7.7 and Ubuntu 19.1 x86_64 Linux OS. Python 3.7 or higher and the following packages are required:

The above packages are automatically included in the Anaconda3 package, and then you do not need to install them manually. However, next tools need to be installed by the user following the instructions included in each package:

Additional packages for specific control of the FLI devices are required:

  • fliusb Finger Lakes Linux Kernel module

  • libfli Finger Lakes SDK library

  • python-FLI Python bindings for Finger Lakes Instrumentation (FLI) cameras and peripherals

System Installation

First, you need to prepare your system environment with the software components and its configuration that are required by MCS. It includes:

OS Setup

Concerning the OS, you need to setup next steps on the OS:

  • UTC time: On CentOS, the system’s timezone is set during the install, but it can be easily changed at a later time, running the following command as sudo user:

    $ sudo timedatectl set-timezone UTC

Then, run the timedatectl command to verify the changes:

$ timedatectl

  • NTP config: On CentOS, you should run the following commands as sudo user:

    $ yum install ntp
$ ntpdate -s hora.roa.es  (to force the update **before** ntpd is launched!)
$ timedatectl
$ systemctl enable ntpd
$ systemctl start ntpd
$ ntpstat


-- To force sync no matter the current offset --
$ systemctl stop ntpd
$ ntpd -gq
$ systemctl start ntpd
--

Note

Due to some compatibility problem between our CPU and CentOS kernel (3.10.0-1062), we had to tweak the clock source in the kernel as clocksource=hpet as follow:

Add to /etc/default/grub the next line:

GRUB_CMDLINE_LINUX="crashkernel=auto rd.lvm.lv=centos/root rd.lvm.lv=centos/swap rhgb quiet clocksource=hpet"

And then run:

$ grub2-mkconfig
$ shutdown -r now

However, likely you should not need to modify you clocksource in the the kernel of your OS.

Watchdog

MIMA instrument is an instrument to be run every night when the observing constrains are met. Thus, MCS must be always running properly in the control computer. In order to re-start MCS in case of a crash or failure, a Watchdog monitoring service must be installed in system as follow:

  1. Copy the file MCS/scripts/mcs_watchdog.sh to /usr/local/bin

  2. Edit the crontab file and add next line:

    */5 * * * *   bash -c "export DISPLAY=:1; export PATH=$PATH:/home/mima/anaconda3/bin; /usr/local/bin/mcs_watchdog.sh"

Then, it will monitor MCS for:

  • It is launched

  • It is running properly, detecting a hangup or freeze.

FLI Software

Note

We encourage to update the kernel verion and fliusb kernel module as described below.

  • fliusb Finger Lakes Linux Kernel module (v1.3)

To install the kernel module, follow the next steps:

    First you need to install next modules required for those third party tools::

    $ yum install kernel-headers.x86_64
    (or apt install linux-headers-amd64 linux-headers-4.9.0-3-all)

    $ mkdir ~/Software/MCS/; cd ~/Software/MCS/
    $ wget http://www.flicamera.com/downloads/sdk/fliusb-1.3.2.tgz
    $ tar -xvzf fliusb-1.3.2.tgz
    $ cd fliusb-1.3.2
    $ make
    $ sudo modprobe fliusb (to check the module is loaded without problems)


Then, to install in the system, do the next as root:

    1. Create the file /etc/modules-load.d/fli.conf and add the name of the module `fliusb`(without the .ko extension) on its first line. On boot the kernel will try to load all the modules named in this file.

    2. Copy the module to a suitable folder in /lib/modules/`uname -r`/kernel/drivers.
    In our case this was /lib/modules/`uname -r`/kernel/drivers/fliusb/fliusb.ko. This will place the module in
    modprobe's database. I don't know if this can be a link.

    3. Run depmod. This will find all the dependencies of your module.
    At this point, reboot and then run `lsmod | grep module-name` to confirm that the module was loaded at boot.


Once the module is installed, you need to give access the users to /dev/fliusbX devices. For this,
you have to follow the next steps:

    1. Config the udev-rules file for /dev/fliusbX devices creating the next file content:

    /etc/udev/rules.d/52-fliusb.rules

    # Attempt to have FLI camera and filter_wheel device nodes (/dev/fliusbX) created with global read/write permissions
    KERNEL=="fliusb?" SUBSYSTEM=="usbmisc", ATTRS{idVendor}=="0f18", ATTRS{idProduct}=="0007", MODE="0666", GROUP="plugdev"
    KERNEL=="fliusb?" SUBSYSTEM=="usbmisc", ATTRS{idVendor}=="0f18", ATTRS{idProduct}=="000a", MODE="0666", GROUP="plugdev"

The above KERNEL, SUBSYSTEM and ATTRS attributes are obtained typing:

    > udevadm info -a -n /dev/fliusb1
    > udevadm info -a -n /dev/fliusb2

And, to re-load the rule files:

    > sudo udevadm control --reload-rules && udevadm trigger

Now, you are ready to connect the FLI devices (CCD, Filter Wheel) to the USB ports.

  • fliusb Finger Lakes Linux Kernel module (v1.5)

To install the kernel module, follow the next steps:

On CentOS 7.7 and kernel 3.10.x, we found some problems with the fliusb-1.3 that
provoke a crash of the OS when a FLI USB device (CCD or Filter Wheel) is disconnected.
So encourage to install the lastest version of the fliusb (1.5) with the kernel 5.4.156; however,
it could also work in the kernel 4.x as advised by FLI.

In our case (CentOS 7.7, kernel 5.4.156 + fliusb-1.5), we had to update the GCC version in
order to be able to compile the fliusb kernel module. The steps we followed were:

    > sudo rpm --import https://www.elrepo.org/RPM-GPG-KEY-elrepo.org
    > sudo rpm -Uvh https://www.elrepo.org/elrepo-release-7.0-3.el7.elrepo.noarch.rpm
    > yum list available --disablerepo='*' --enablerepo=elrepo-kernel
    > yum --enablerepo=elrepo-kernel install kernel-lt
    > grub2-set-default 0

Install kernel sources from:
    > rpm -ivh https://elrepo.org/linux/kernel/el7/x86_64/RPMS/kernel-lt-devel-5.4.156-1.el7.elrepo.x86_64.rpm
    > rpm -ivh https://elrepo.org/linux/kernel/el7/x86_64/RPMS/kernel-lt-headers-5.4.156-1.el7.elrepo.x86_64.rpm

Install GCC v9 and enable it:

    > yum --enablerepo=extras install centos-release-scl-rh
    > yum install devtoolset-9-gcc
    > scl enable devtoolset-9 bash

Once you have updated the kernel and installed the GCC v9, you must compile and install the
fliusb kernel module as described above for kernel module v1.3.

  • libfli Finger Lakes SDK library

This SDK library is required in order python-FLI package can provide access to the C library.

The SDK library should be built as a shared object, named ‘libfli.so’, and located in a standard library path, such as /usr/local/lib, or placed in the Python package folder after installation:

    $ mkdir ~/Software/MCS/; cd ~/Software/MCS/
    $ wget http://www.flicamera.com/downloads/sdk/libfli-1.104.zip
    $ tar -xvzf libfli-1.104.zip
    $ cd libfli-1.104
    $ make -f Makefile.so
    $ cp libfli.so /usr/lib

Now depending on the target Linux system /usr/local/lib might not be on the dynamic
libraries path. There are many ways to get this library found, but I have a few
suggestions in order of least hacky first. On Ubuntu and similar, that path could be
added to the end of file /etc/ld.so.conf, which is updated next by running ldconfig.
If that doesn't seem to work, you could create a symbolic link like this:

    sudo ln -s /usr/local/lib/libfli.so /usr/lib

If ctypes is still having trouble finding the library, you could always just
drop it into the python package folder (probably somewhere like:

 /usr/local/lib/python2.7/dist-packages/FLI-dev-py2.7.egg/FLI/

This is the Python bindings for Finger Lakes Instrumentation (FLI) cameras and peripherals. To install:

> git clone https://github.com/SydneyAstrophotonicInstrumentationLab/python-FLI
> cd python-FLI
> python setup.py install

Note

The https://github.com/cversek/python-FLI is not ready for Python3, so you must use the updated version for Python3 https://github.com/SydneyAstrophotonicInstrumentationLab/python-FLI

Python environment (Anaconda)

The MCS package can be installed into a virtualenv or Conda (prefered) environment manager via pip. We recommend a fresh environment with only python installed. Via Conda:

  1. Install Anaconda3 (for Python 3.7), which include Conda manager:

    $ sh Anaconda3-2019.10-Linux-x86_64.sh

  2. Create environment (mcsenv):

    $ conda create -n mcsenv python=3.7

After the installation is complete go ahead and activate the “papienv” environment. This command only needs to be executed one time per terminal session:

$ conda activate  mcsenv

  1. Install main Python staff not included in Anaconda:

    $ conda install -c astropy
$ pip install pyserial
$ pip install sphinx_rtd_theme texlive-formats-extra sphinxcontrib-bibtex
$ pip install pyds9
$ pip install scikit-image
$ pip install qimage2ndarray
$ pip install specutils

Note

These external dependences could also be installed automatically when installing MCS due to the setup.py requirements.

  1. Install Third Party tools:

  • DS9:

    $ wget http://ds9.si.edu/download/centos7/ds9.centos7.8.1.tar.gz
$ tar -xvzf ds9.centos7.8.1.tar.gz
$ cp ds9 /usr/local/bin/

  • XPA:

    $ git clone https://github.com/ericmandel/xpa.git
$ ./configure
$ make install

or

$ yum install xpa.x86_64

Then, set XPA_METHOD=local in your .bashrc profile

MCS Installation

The latest stable version of MCS can be downloaded from GitHub repository .

To install a released (tagged) version, you can install directly from Github. To install tagged release mcs 2.1.0:

$ pip install git+https://github.com/ppmim/MCS.git@2.1.0

The latest development version (from master) can also be installed from Github:

$ pip install git+https://github.com/ppmim/MCS.git

Also, you can install a particular commit hash:

$ pip install git+https://github.com/ppmim/MCS.git@3f03323c

Installing for developers

To obtain the full code, including examples and tests, you can clone the git repository:

$ git clone https://github.com/ppmim/MCS.git
$ cd MCS

Install from your local checked out copy as an “editable” install:

$ pip install -e .

The former command will also install the dependences found in setup.py.

If you want to run the tests and/or build the docs, you can make sure those dependencies are installed too:

$ pip install -e .[test]
$ pip install -e .[docs]
$ pip install -e .[test,docs]

Note: If you wish to install directly from github, but also include the extra dependencies, the syntax is as follows:

$ pip install "papi[test] @ git+https://github.com/ppmim/MCS.git"

Need other useful packages in your development environment:

$ pip install ipython flake8 pytest-xdist

Edit the mcs_setup.sh and set the right values to MCS_CONFIG, and then run the script as an user:

$ ./mcs_setup.sh

Warning

The script mcs_setup.sh is currently implemented only for the Bash shell, and will modify your .bashrc file adding a new line at the end.

Configuring the system

Once MCS is installed, you need to setup the system, that basically consists of:

  1. Edit ~/.mcs/config.ini with your preferences

  2. Create the data directories as especified in the config file

Autostart of MCS GUI after login:

The computer system must to be configured for autologin and autostarup the MCS application after the system boot. For this, next steps need to be followed:

  • Enable user autologin:

    If you’re using GNOME in a single user environment, and you’re confident that nobody else will use your system, you can enable auto-logins without the password questions like this:

    1. Login to GNOME as usual

    2. Find your name at the top right and click on it

    3. Now select Settings

    4. In the new window that opens, find Users

    5. Click on Unlock at the top right

    6. Select your own user and turn on Automatic Logins

    You need supervisor privileges to make this change. Next time you restart your system, you’re logged in automatically.

  • Add MCS to autostartup applications:

    $ gnome-session-properties

This will add a .desktop file in ~/.config/autostart/. You can also alternatively copy the .desktop file yourself.

Building the documentation

The MCS documentation is base on sphinx. With the package installed, the html documentation can be built from the doc directory:

$ cd mcs/doc
$ make html

The documentation will be copied to a directory under build/sphinx.

The documentation can be built in different formats. The complete list will appear if you type make.

Bug reports

Please submit issues with the issue tracker on github.