Documentation
Overview of the API
The
API of IEC61850-kit can be divided into a client and a server part. Both APIs
also share common elements. The hopefully complete documentation of the API can
be found in API Reference Manual (version 1.4).
Server API
IEC61850-kit
provides two different server APIs. There is a very generic MMS server API that
has no support for IEC 61850. It can be used to implement generic MMS server
devices that do not want to use IEC 61850. If you want to implement IEC 61850
compliant server devices it is not recommended that you use this API. Also IEC61850-kit
does not provide a full featured MMS stack. The MMS stack was implemented with
IEC 61850 in mind and does only provide MMS features used by IEC 61850.
The
other API is a IEC 61850 specific API. It is highly recommended that you use
this API. Support for IEC 61850 includes the automatic generation of the MMS
device model out of the static IEC 61850 data model. Also this API provides
support for the IEC 61850 control model. The IEC 61850 server stack behind this
API also supports data sets and reporting. This API is intended to have a very
low overhead and to be used to create very small IEC 61850 compliant server
applications.
An
introduction into the usage of the IEC 61850 server API can be found in the Server
tutorial.
Hardware/OS
abstraction layer
IEC61850-kit
provides a hardware/OS abstraction layer (HAL) to hide the dependencies to the
underlying platform. Currently this layer consists of thread, socket and time
abstractions. If you want to port the library to a new platform you need to
implement the functions defined by this API. At the moment implementations for
POSIX(Linux, Mac OS X …) and Win32 exists. This API consists of the three files
hal/hal.h, hal/socket/socket.h and hal/thread/thread.h..
server stack
Client API
The
client API is not yet IEC 61850 specific but is a generic MMS client API that
provides only the features required by the IEC 61850 MMS Mapping.
An
introduction by examples can be found in the MMS client tutoral.
Building the
library and the examples
Building the
library
To
build the library on a Linux platform you can simply execute make in the main folder of the source distribution. It is assumed
that a GCC toolchain and the Make tool is installed. To cross-compile for
another platform you can specify the TARGET variable when executing make. To
cross-compile for Windows you can call make TARGET=WIN32. To cross-compile for ARM Linux you can call make TARGET=LINUX-ARM. It is assumed that a proper GCC
cross-compiler toolchain (like MinGW or arm-linux-gcc) is installed. Probably
you need to adjust the toolchain prefix variables in the file make/target_system.mk. You can also build on a Windows plattform if you have
MinGW installed.
Building the
library with GOOSE support for Windows
To
build the library and run IEC61850-kit applications with GOOSE support on
Windows (7/8) the use of a third-party library (winpcap) is required. This is
necessary because current versions of Windows have no working support for raw
sockets. You can download winpcap here (http://www.winpcap.org).
1. Download and install winpcap. Make sure
that the winpcap driver is loaded at boot time (you can choose this option at
the last screen of the winpcap installer).
2. Reboot the system (you can do this also
later, but you need to reboot or load the winpcap driver before running any IEC61850-kit
applications that use GOOSE).
3. Download the winpcap developers pack from
here (http://www.winpcap.org/install/bin/WpdPack_4_1_2.zip)
4. Unpack the zip file. Copy the folders Lib and Include from the WpdPack directory in the third_party/winpcap directory of IEC61850-kit
5. Build the library with make
Building the
examples
To
build the examples you require a Linux system with gcc and make installed. You
can also build the examples on a Windows system. This requires that you have
installed MinGW. A build with the Visual Studio tools is not supported yet.
On a
linux or windows system with MinGW installed just enter the IEC61850-kit
directory and type
make
This
will build the examples for the host environment (currently Linux or Windows
with MinGW). To test the server examples you can use the client examples. You
can also use third-party tools to test the examples.
You
can cross-compile for Windows on a Ubuntu system by installing the Ubuntu package
mingw32 and starting the build with the TARGET=WIN32 option:
make TARGET=WIN32
The
examples have been tested on the following platforms:
·
Linux/x86
·
Linux/PPC
(iBook with LinuxMintPPC)
·
Linux/MIPS32
(Carambola board)
·
Linux/ARM
(BeagleBone – Cortex-A9, Raspberry Pi – ARM11)
·
ucLinux/ARM7
(Wago Linux Fieldbus coupler)
·
Windows
7/MinGW
Running the
examples
On
Windows you can simply start the .exe files. For the server examples you need
to confirm that the application can accept incoming network connections.
In
Linux the server examples have to be started as root since they require to bind
to the default MMS port 102 and Linux allows this only for programs running
with root permissions. You can start the server examples on a ubuntu system or
similar linux system with:
sudo ./server_example1
You
can also avoid running a server as root by using linux capabilites. Linux
capabilites are file based and allows specific program files to do tasks that
otherwise would require root permissions. You can give the above example the
right to bind to ports below 1024 with the following command:
sudo setcap 'cap_net_bind_service=+ep' server_example1
Afterwards
the server can start without root permissions.
Note:
You need to execute this command each time you rebuild the server application.
Build your own
IEC 61850 server device
Generate model
source from ICD (SCL) file
Note:
You need a Java JRE 6 installed in order to create the model source code!
In the
main directory of the source distribution change to the tools/model_generator
directory. Enter
java -jar genmodel.jar my_model.icd
This
will generate the two files data_model.c and data_model.h. Copy these files to your project directory where the
build system can find them. The file data_model.c contains the
definition of the data structures that build up the IED data model and also
contains pre-configured values provided by the SCL file. The file data_model.h is intended to be included by your code and defines
handles that you can use to efficiently access the data model.
Create a new
project from a template
To get
started you can make a copy of one of the examples projects. Copy the generated
model source code files to your new projects folder. Modify the project
Makefile according to your needs. Important variables are LIBIEC_HOME that is
the path to the source code of IEC61850-kit, PROJECT_BINARY_NAME and
PROJECT_SOURCES.