1. Installing the SDK#

1.1. Development Platform#

The Observatory Control System (OCS) is designed to be a distributed system with device control components running on real-time computers, connected to common services and user interface components via the control network.

For device control systems, the following operating systems are supported:

The following guide is provided to assist with hardware, operating system and third-party software configuration required for running the OCS SDK.

1.2. Server Configuration#

Servers are used for developing, running and testing device control software and core services. When real-time communication with hardware is required, the real-time kernel should be installed and configured. The following guidelines for creating a server should be tailored according to its intended purpose.

1.2.1. Operating System#

1. Install the Alma Linux Operating System. A minimal server installation is sufficient for the use of the GMT SDK.

  1. Disable firewall

sudo systemctl disable firewalld
sudo systemctl stop firewalld

  1. Disable SELinux

sudo sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config
sudo setenforce 0

Warning

Make sure an external firewall protects your server

  1. Install minimal development tools

sudo dnf install --enablerepo=crb -y git make cmake ninja-build gcc gcc-c++ gdb clang llvm-toolset lldb elfutils autoconf automake libtool

1.2.2. Real-Time Kernel (Optional)#

The real-time kernel is required for real-time tasks, such as EtherCAT communication. The following steps should be taken to install the real-time kernel:

  1. Install the Real-Time Kernel

KERNEL_RT_VERSION="5.14.0-362.13.1.el9_3" && sudo dnf install -y kernel-rt-${KERNEL_RT_VERSION} kernel-rt-devel-${KERNEL_RT_VERSION}

  1. Add users to the realtime group, to allow access to the real-time kernel, for example:

sudo usermod -a -G realtime gmto

  1. Set the real-time kernel as the default kernel

sudo grubby --set-default /boot/vmlinuz-${KERNEL_RT_VERSION}.x86_64+rt

1.2.4. Node Installation#

  1. Install Node version 20:

sudo curl -sL https://rpm.nodesource.com/setup_20.x | sudo bash -

sudo dnf install -y nodejs

  1. Install necessary node packages:

sudo npm install -g coffeescript webpack webpack-cli raw-loader

. note:

If you encounter problems installing nodejs, you probably have an older node version activated.
To change it, run:
`sudo dnf remove -y nodejs && sudo dnf module reset -y nodejs && sudo dnf module enable -y nodejs:20`
 and then install nodejs again.

1.2.5. MongoDB Configuration (for the core services)#

  1. Add the file /etc/yum.repos.d/mongodb-org-6.repo with the following content:

sudo cat << EOF > /etc/yum.repos.d/mongodb-org-7.repo
[mongodb-org-7.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/8/mongodb-org/7.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-7.0.asc
EOF

  1. Install the necessary packages:

sudo dnf -y install mongodb-org

  1. Enable the MongoDB service

sudo systemctl enable mongod
sudo systemctl start mongod

  1. Check that the MongoDB service is up

sudo systemctl status -l mongod

1.2.6. Network Time Protocol Configuration#

For general network timekeeping, NTP client software should be installed and configured to synchronize the system clock with a reliable time source. To check if the system is synchronized with the NTP server, use the chronyc sources command.

sudo chronyc sources

1.3. Software Development Kit (SDK)#

The Software Development Kit is distributed as a TAR file and can be downloaded from the GMTO release server.

The SDK should be installed in a Global GMT Software Location, defined by the GMT_GLOBAL environment variable (default value: /opt/gmt).

A Local Working Directory, defined by the GMT_LOCAL variable, is used as a unique workspace for individual developers. The local working directory typically resides underneath the /home/<username> directory.

  1. Download the latest SDK distribution:

  2. Extract the TAR file in the /opt directory, into a new folder for the latest release (substitute <releasever> with the actual release version):

sudo mkdir /opt/gmt_release_<releasever>
sudo tar -xzvf gmt-sdk.tar.gz -C /opt/gmt_release_<releasever>

where gmt-sdk.tar.gz is the file downloaded in step 1.

  1. Create a symbolic link from the Global GMT Software Location to the latest release:

sudo ln -sfn /opt/gmt_release_<releasever> /opt/gmt

  1. Create a Local Working Directory

mkdir <local_working_dir>

where <local_working_dir> is in the current users’ home directory, for example, ~/work.

The GMT software modules developed by the user are created in this folder.

  1. Add the following lines to your .bash_profile (or .kshrc or .bashrc depending on your preferred shell)

export GMT_GLOBAL=/opt/gmt
export GMT_LOCAL=<local_working_dir>
source $GMT_GLOBAL/bin/gmt_env.sh

This will ensure that the environment variables are correctly configured when opening a new terminal.

Please log out and back in for the changes to take effect. To configure the environment for the current shell, run the commands manually.

  1. Check the values of the environment variables:

gmt_env

  1. Install Node Modules

cd $GMT_GLOBAL
sudo npm install

cd $GMT_LOCAL
cp $GMT_GLOBAL/package.json ./
npm install

  1. Install Python requirements

cd $GMT_GLOBAL
sudo -E $GMT_GLOBAL/ext/bin/pip install -r requirements.txt

  1. Initialize the Development Environment:

cd $GMT_LOCAL
gds init

The correct folders will be created in the $GMT_LOCAL directory for use when compiling and running modules.

  1. Create a modules directory in $GMT_LOCAL

cd $GMT_LOCAL
mkdir modules

  1. Create the bundles.coffee and ocs_local_bundle.coffee files, defining the local modules under development

These files may be copied from $GMT_GLOBAL and then edited to reflect the developer’s configuration.

mkdir $GMT_LOCAL/etc/bundles
cp $GMT_GLOBAL/etc/bundles/bundles.coffee $GMT_LOCAL/etc/bundles/
cp $GMT_GLOBAL/etc/bundles/ocs_local_bundle.coffee $GMT_LOCAL/etc/bundles/

Edit bundles.coffee to point to the ocs_local_bundle.coffee file

module.exports =
    ocs_local_bundle:   {scope: "local",  desc: "GMT iSample and HDK bundle"}

Edit ocs_local_bundle.coffee to include the ISample and HDK modules, or other modules that you are working on, for example:

module.exports =
name:      "local"
desc:      "List of local development modules"
elements:
    isample_dcs: { active: true, test: false, developer: 'gmto', domain: 'idcs' }
    hdk_dcs:     { active: true, test: false, developer: 'gmto', domain: 'idcs' }

  1. Build all model files from modules in your ocs_local_bundles definition. For example:

gds build -t model hdk_dcs
gds build -t model isample_dcs

1.3.1. EtherCAT Configuration (Optional)#

EtherCAT is a high-speed Fieldbus communication system used for real-time control. The following configuration steps should be used as a guide when configuring EtherCAT communications.

A real-time kernel is required for EtherCAT communication. The real-time kernel installation steps are provided above.

For the installation example below, we use the following network interfaces:

  • enp4s0 - EtherCAT Master (Primary)

  • enp5s0 - EtherCAT Master (Backup - Optional, used for redundant topology)

  1. Run the etherlab_install.sh script that comes with the GMT SDK:

cd $GMT_GLOBAL/ext/bin/
sudo -E bash ./etherlab_install.sh enp4s0

  1. Edit /etc/ethercat.conf and set the following configuration options:

MASTER0_DEVICE="enp4s0"
MASTER0_BACKUP="enp5s0"  # optional, for redundant topology

  1. Reboot into the RT Kernel, if you’re not in it already.

  2. Test the EtherCAT configuration (once the EtherCAT slaves are connected):

ethercat master
ethercat slaves

If the ethercat master command does not produce the correct output, ensure that you’re currently running the real-time kernel. If the ethercat slaves command produces no output, check that the ethernet cable is connected to the correct port as configured above.