1 Prerequisites ================= MRCI can be installed in one of two ways. A set of binary packages are available for installation on systems running Debian or Mandrake Linux. These packages can be found in the subsection of the download page entitled _Linux and RTAI packages_. After downloading and installing the packages for the distribution being used, proceed with the installation instructions in the next section. The binary installation only provides a default configuration that uses the COMEDI data acquisition drivers and RTAI (Real-Time Application Interface) Linux. If the user desires to use a different driver, or RT-Linux, then MRCI has to be built from source code. In order to build MRCI, one needs a working installation of Real-Time Linux, also known as RT-Linux, or RTAI, which is an alternative to RT-Linux. RT-Linux ver. 3.2 can be found at `http://www2.fsmlabs.com/3.2-free.html'. RTAI can be downloaded from `http://www.rtai.org/'. Detailed installation instructions about both RT-Linux and RTAI can be found inside their respective distribution packages. Once RTAI or RT-Linux are installed, proceed with the instructions in section 3. 2 Binary Installation ======================= Under Debian Linux: Add the following to /etc/apt/sources.list: deb http://www.neuro.gatech.edu/mrci/debian testing main Then install MRCI as follows: apt-get update apt-get install mrci-modules-2.4.27-adeos-3-arch where arch is one of the following architectures: 586mmx Pentium-compatible with MMX support p3 Pentium III p3-smp Pentium III with SMP support p4 Pentium 4 p4-smp Pentium 4 with SMP and hyperthreading support k8 AMD K8 k8-smp AMD K8 with SMP support After installing the kernel image, reboot the system and boot the `-adeos' kernel. Run MRCI as described in section 5. 3 Unpacking ============= Decompress and extract the files from the MRCI distribution archive: tar zxf mrci-1.9.6.tar.gz This will extract the `mrci' directory with the following subdirectories: `app/' MRCI application `common/' A library of commonly used C++ classes `debian/' Support files for the Debian package build system `doc/' Documentation `elisp/' Emacs mode for editing MRCI files `examples/' Example system description files `math/' Real-time Linux math library `module/' MRCI kernel module `nical/' NI calibration module `nidaq/' NI driver module `remote/' Support scripts for MRCI remote mode; source code for the MRCI remote client `scripts/' MRCI scripts used to start and stop the system `translator/' MRCI translator 4 Building and Installation ============================= First, the configure script must be launched from within the location where the distribution archive was uncompressed: ./configure Running `configure' takes awhile. While running, it prints some messages telling which features it is checking for. When `configure' is done, MRCI can be compiled by issuing the following command: make After the build process has completed successfully, MRCI can be installed with the following command, which requires root privileges: su - make install By default, the MRCI program and accompanying scripts are installed in directory `/usr/local/bin', the example and data files in `/usr/local/share/mrci', and the kernel module is installed in `/lib/modules/osrelease/misc' where OSRELEASE is the version of the currently running kernel (as reported by `uname -r'). 4.1 Configuring MRCI for use with RTAI ---------------------------------------- Options `--with-rtai', `--with-rtai-scripts', `--with-rtai-headers' specify the directory or directories where the RTAI headers and scripts are located. The installer can work under one of two assumptions: a) RTAI 3.x is being used and the header files and scripts for RTAI reside in a single directory (`/usr/lib/realtime' by default)--in that case the argument to the `--with-rtai' option points to the top-level RTAI directory; or b) RTAI 2.x is being used and the headers and scripts have been installed in a custom directory or directories; in this case, the argument to option `--with-rtai-scripts' points to the directory that contains the RTAI scripts, and the argument to option `--with-rtai-headers' points to the directory that contains the RTAI header files. For example, if the RTAI scripts have been installed in directory `/usr/local/bin' and the RTAI header files in directory `/usr/local/include', the MRCI configuration script needs to be invoked with the following options in order for it to be able to use RTAI: ./configure --with-rtai-scripts=/usr/local/bin --with-rtai-headers=/usr/local/include When using RTAI 3.x, the following will be sufficient for successful MRCI installation: ./configure --with-rtai=/usr/lib/realtime or ./configure --with-rtai which causes the installer script to search for RTAI in the default locations, `/usr/lib/realtime', `/usr/local/lib/realtime', `/usr/realtime'. 4.2 Configuring MRCI for use with RT-Linux and RT-Linux Pro ------------------------------------------------------------- Option `--with-rtlinux' specifies the directory where the RT-Linux installation script has placed the RT-Linux header files, libraries, and executables (`/usr/rtlinux' by default). Option `--with-rtlpro-shm' directs the build process to compile MRCI with support for the shared memory interface used with RT-Linux Pro. This option is required when configuring MRCI for use with RT-Linux Pro. This code is still experimental and is not considered stable. 4.3 Configuring MRCI for use with COMEDI ------------------------------------------ Option `--with-comedi' specifies that MRCI should be compiled with Comedi support. This is the recommended driver for use with MRCI, and configuration default as of version 1.9.0. If the option is given a value (e.g. `--with-comedi=dir'), this value is used as the directory where COMEDI is installed. 4.4 Configuring MRCI for use with the bundled NI driver --------------------------------------------------------- Option `--with-nidaq' specifies that MRCI should be compiled with the NI driver that is bundled with the MRCI distribution. This driver will eventually be phased out; Comedi is the recommended driver for use with MRCI. If MRCI is to be used with National Instruments ISA data acquisition boards, the following options need to be used in conjunction with `--with-nidaq': ./configure --with-nidaq --with-type0=NI_AT_MIO_16E_1 --with-base0=0x100 \ --with-irq0=5 where `--with-base' and `--with-irq' specify a hexadecimal base address and interrupt request line, respectively. The integer in each option keyword specifies the board index (0--3). The `--typeN' option indicates the model of the board. A list of all supported models can be found in the file `NI_BOARD_LIST', which is located in the MRCI distribution package, and is placed by the installation script in directory `/usr/local/share/mrci' (provided the default installation directory hasn't been changed). MRCI supports several different gain ranges for data acquisition. By default, the acquisition range used is +/- 0.1V. To specify a different gain range, the option `--with-gainN' can be used, where N is the board index (0--3) and the value of the argument is an integer between 0 and 2, where: `0' +/- 0.1 V `1' +/- 1V `2' +/- 10V For example, if we want to specify a gain range of +/- 10V for board 0: ./configure ... --with-gain0=2 4.5 Other configuration options --------------------------------- Option `--with-waveform-buffers=N' can be used to change the default number of waveform buffers supported by MRCI (four, if this option is not specified). For detailed explanation on waveform buffers, see the MRCI manual. For further help on the parameters of the configure script, use the `--help' option: ./configure --help 5 Running =========== MRCI is started by invoking the `run_mrci' script. Among other things, the script loads the kernel modules of RT-Linux and MRCI, so it needs to be run with root privileges: su - run_mrci system.mrci When the MRCI application starts, it attempts to locate a file called `.mrcirc' in the home directory of the user running MRCI (usually root). If this file is found, all MRCI commands in it are executed prior to presenting the user with the MRCI command prompt. The location of this file can be specified with the `-i' option, thusly: run_mrci -i /some/location/init-mrci system.mrci The `-w' argument specifies the number of waveform buffers to be created by MRCI. For detailed explanation on waveform buffers, see the MRCI manual. While running, the MRCI application maintains a history of all commands entered by the user. This list is by default saved at program exit and loaded at program startup. The file used for saving the command history is named `.mrci_history' and is located in the user's home directory. Only the last 4096 commands are saved in this file. The above behavior can be changed with the following command-line options: `--history-file', which specifies the location of a file to be used for saving and loading the command history, and `--history-limit' which can be used to alter the command history limit. For example: run_mrci --command-history my-history --command-limit 100 system.mrci This will make MRCI save the last 100 commands entered by the user in a file named `my-history'. 6 Uninstalling ================ Issuing the command make uninstall from the MRCI source directory will remove the MRCI executables, scripts and kernel modules from their respective installation locations. Root privileges are required in order to execute this command. 7 Running in Remote Mode ========================== Beginning with version 1.7.0, MRCI supports the so-called "remote mode", where the MRCI application is controlled by a remote computer over a network connection. A remote MRCI client is available, and its source code can be found in subdirectory `remote' in the MRCI distribution archive. The client is also available as a binary distribution for MS Windows, which can be downloaded from the MRCI web site. MRCI's remote mode relies on the internet services daemon, inetd/xinetd, so either one must be installed if remote operation of MRCI is desired. It is presumed that the inetd configuration file is located in `/etc/inetd.conf', and the xinetd service configuration files are placed in directory `/etc/xinetd.d'. Because MRCI runs with root user privileges, it is necessary to secure the remote connection; Stunnel (`http://www.stunnel.org') and OpenSSL (`http://www.openssl.org') are used to encrypt the connection, and so they are required to be installed on the machine running MRCI. MRCI can be set up to run in remote mode by using the `--with-remote' command-line option when invoking the `configure' script: ./configure --with-remote ... The installation script will setup inetd/xinetd to listen on port 7091 (which is defined as the port for MRCI service) and upon a connection initiated by a client, to launch MRCI via the Stunnel wrapper. Also note that the xinetd MRCI service is set up to listen on the localhost interface; you will need to go into the directory where the xinetd service configuration files are stored (usually `/etc/xinetd.d', open the file called `mrcis', and change _localhost_ in the following line to the name of the network interface where you want the MRCI service to listen: bind = localhost # change to desired interface Because the connection between the machine running MRCI and the client controlling it is encrypted, "encryption certificates" need to be generated. When a MRCI client connects to a MRCI server, the server presents a certificate, essentially an electronic piece of proof that machine is who it claims to be. This certificate is signed by a "certificate authority" (or CA for short). A client will accept this certificate only if the certificate presented matches the private key being used by the remote end. During installation, a certificate authority and a server-side certificate will be generated. The installation program will ask you the following questions. While it is not strictly necessary to provide correct and complete answers, it is good practice to do so. The most important question is the password one: remember the password that you use when creating the certificate authority, because you will need it afterwards: when you are creating a server-side certificate, when Stunnel is being set up, and when you are creating a client certificate (discussed below). _Question_ Example Answers _PEM pass phrase_ ****** _Country name_ PL, UK, US, CA _State or Province name_ Illinois, Ontario _Locality_ Chicago, Toronto _Organization Name_ Wossamotta U, Acme Anvils _Organizational Unit Name_ Dept. of Math _Common Name_ MRCI certificate authority, MRCI server certificate The installation script of MRCI generates a certificate authority, a server-side certificate, and places them in the right directories, so that MRCI is automatically set up on the server side. In order to connect to the MRCI machine with the MRCI client one needs to generate a "client certificate", and copy that certificate to the client machine. The script `mrci_mkcert' can be used for the purposes of generating a client certificate, as seen in the following example. Please note that the first password question pertains to the password to be used with the client certificate, i.e. this is the password you will be using when connecting with the MRCI remote client; the second password question is asking about the password of the certificate authority, i.e. this is the password you entered when the installation script prompted you to create one. $ mrci_mkcert Using configuration from /usr/local/share/mrci/remote/openssl.cnf Generating a 1024 bit RSA private key .......++++++ .........................................++++++ writing new private key to '/usr/local/share/mrci/remote/MrciCA/clients/newreq.pem' Enter PEM pass phrase: ***** Verifying password - Enter PEM pass phrase: ***** ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [US]: State or Province Name (full name) [Georgia]: Locality Name (eg, city) [Atlanta]: Organization Name (eg, company): Georgia Institute of Technology Organizational Unit Name (eg, section): Laboratory for Neuroengineering Common Name (eg, YOUR name): MRCI client certificate Email Address []: Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: (can be left blank) Using configuration from /usr/local/share/mrci/remote/openssl.cnf Enter PEM pass phrase: ****** Check that the request matches the signature Signature ok The Subjects Distinguished Name is as follows countryName :PRINTABLE:'US' stateOrProvinceName :PRINTABLE:'Georgia' localityName :PRINTABLE:'Atlanta' organizationName :PRINTABLE:'Georgia Institute of Technology' organizationalUnitName:PRINTABLE:'Laboratory for Neuroengineering' commonName :PRINTABLE:'MRCI client certificate' Certificate is to be certified until Nov 28 16:19:27 2004 GMT (365 days) Sign the certificate? [y/n]:y 1 out of 1 certificate requests certified, commit? [y/n]y Write out database with 1 new entries Data Base Updated The newly generated client certificate and key files are located at: /usr/local/share/mrci/remote/MrciCA/clients/03.cert /usr/local/share/mrci/remote/MrciCA/clients/03.key Please transfer these files to the computer where the MRCI remote client will be running.