amici Files

/*
* Copyright 2013 EUROPEAN UNION
*
* Licenced under the EUPL, Version 1.1 only (the "Licence");
* You may not use this work except in compliance with the Licence.
* You may obtain a copy of the Licence at:
*
* http://ec.europa.eu/idabc/eupl.html
*
* Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an "AS IS" basis,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the Licence for the specific language governing permissions and limitations under the Licence.
*/

FDServer solution including SCUnit Version 1.0.0.22 (28/03/2013) and RPLCUnit Version 1.0.0.21 (28/03/2013)

GENERAL USAGE NOTES
-------------------------

The software is meant to aid researchers and engineers to implement cyber-physical security experiments. For this purpose the software package AMICI provides the software units that enable:

- Running physical process models in real-time.

- Interactions with the physical process models in real-time.

- Implementing control code in several ways, e.g. c++ code running near the model and remotely, compiled C# code, run-time compiled C# code, and external scripting.

- Running industrial protocols - currently only Modbus is supported.


SYSTEM PREREQUISITES
-------------------------

The software has been developed in C# (Windows) and has been ported and tested on Unix-based systems with the help of the Mono platform.

The minimum system requirements can vary depending on the complexity of the physical process model. Furthermore, our experience showed that real-time simulation is a processor-consuming task for model execution steps below 10ms.

Consequently, the minimum requirements for running the SCUnit with a 39-bus IEEE model and a 10ms model execution step is the following:

- CPU: At least Dual Core, 2GHz

- RAM: 2GB

- Hard drive: depending on the experiment and the configuration of the software the log file can become quite large. We recommend to run the software on a partition with enough space to store log files, e.g. 20GB.

- Mono platform: the software is currently extensively used and proved to be quite stable with Mono Version 2.6.7. Nevertheless, previous versions might work as well.

- OS: the software is almost exclusively used under FreeBSD 8.2. Nevertheless, it was also tested on Fedora, Ubuntu, and Windows.

The RPLCUnit has the simple task to periodically send queries to the SCUnit and optionally, to run a remote control code. Therefore, it is less processor-consuming. We recommend the following minimum configuration for the RPLCUnit:

- CPU: 2GHz

- RAM: 1GB

- Hard drive: the space to store the software executable.

- Mono platform: Mono Version 2.6.7.

- OS: Preferred FreeBSD 8.2, but it also runs on Fedora, Ubuntu, or Windows.


CONTENTS OF THE AMICI SOFTWARE PACKAGE
-------------------------

The software package is structured in five main folders:

- 'SCUnit': it includes the main code of the simulation unit. The implementation evolved around the PLCCoreTimer.cs file that contains the main structures and real-time simulation algorithm.

- 'RPLCUnit': it includes the code of the remote unit responsible for issuing periodic commands to the SCUnit using .NET's RPC. It can be used as a one-shot get/set software, or it can run more complex control algorithms implemented in c++. The RPLCUnit is also known as a 'proxy' unit since it includes a Modbus implementation as well, which can be used to translate .NET RPC packets to Modbus packets and vice-versa.

- 'lib': it includes several projects that provide the basic building blocks to the SCUnit and RPLCUnit.

- 'ExternalDeps': it includes the additional dependencies ('HiPerfTimer' and 'NativeLibLoader' - see the next section) required to run the software units on Unix-based systems. Additionally, the folder includes:
	- 'Automatise': a Perl script and several template files that are used to automatically generate the SCUnit configuration files and to compile the Matlab Simulink model. It assumes that the model code has already been generated by Simulink Coder.
	- 'SharedMemory': simple application to access the model's inputs/outputs using shared memory mappings.

- 'Test': it contains the components and specific configurations required to run an example cyber-physical experimental scenario.

COMPILATION NOTES
-------------------------

- On Windows AMICI can be compiled by loading the AMICI.sln solution file in Microsoft Visual Studio 2010 and building all projects within the solution. The generated executables and required DLLs are stored in Debug/Release directories.

- On Unix-based systems AMICI can be compiled either by loading the solution in Monodevelop, or from the command-line by running 'xbuild'.

- If the target platform does not have Mono installed you can run 'mkbundle' to incorporate all Mono-related dependencies into a single distribution file.
	- On FreeBSD run the following commands (after ensuring that the 'Requires: glib-2.0 gthread-2.0' line is uncommented in the /usr/local/libdata/pkgconfig/mono.pc file - to avoid errors related to lib and thread):
	
	> mkbundle -c --static --deps -o SC_fbsd SC.exe BasicInterface.dll CommandLineParser.dll PLCCodeRunner.dll PLCDllLoader.dll PLCNetDllLoader.dll PLCNativeLibLoader.dll PLCGeneric.dll
	
	> mkbundle -c --static --deps -o RPLC_fbsd.c RPLC.exe BasicInterface.dll CommandLineParser.dll PLCNativeLibLoader.dll
	
- Additionally, to run the software units within AMICI on Unix-based systems there are two additional dependencies that need to be compiled. These are located in the 'ExternalDeps' folder and the compile instructions are given in 'compile' files in each folder:
	- 'HiPerfTimer' is a Unix-based implementation of the HighPerformanceTimer available on Windows.
	- 'NativeLibLoader' provides a library that dynamically loads other libraries, e.g. control code.
	

KNOWN ISSUES
-------------------------

The software units have been extensively used since the beginning of 2011 and they appear to be stable. Of course, there might be bugs that we are not aware of or insufficient features, which might be addressed in future versions.

A known issue we have encountered involves the execution of the SCUnit and the RPLCUnit on the same machine. In this scenario Mono seems to employ IPC (Inter-Process Communications), which has some severe memory leakages caused by semaphores. Therefore, a subsequent start/stop of AMICI's software units will lead, after a while, to execution errors. Since this is a bug in Mono there is not much we can do about it - it might get fixed in the next versions. However, a preliminary solution we have found is to delete the locked semaphores after processes exit by issuing the following commands:

	> ipcrm -m -1; ipcrm -s -1