API overview
The API (Application Programming Interface) of libIEC61850 consists of a client and a server part for MMS and publisher/subscriber parts for GOOSE and SV (Sampled values). All API parts also share common elements. The reference documentation of the API can be found here.
Server API
The library provides an IEC 61850 specific high-level API. It is designed to be independent from the MMS mapping to be able to support other mappings (SCSM) in the future. Support for IEC 61850 includes the automatic generation of the MMS device model out of the IEC 61850 data model. Also the API provides support for the IEC 61850 control model, log services, setting group model, etc. The IEC 61850 server stack behind this API also supports data sets, logging, 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 to the usage of the IEC 61850 server API can be found in the Server tutorial. The Control tutorial explains how to handle control objects within the server.
IEC 61850 server library (yellow – separately usable MMS server parts)
Client API
The IEC 61850 client API is a high-level API. It is the first choice if you want to implement IEC 61850 compliant clients. It supports model discovery, variable read and write, reporting, and control services. A detailed tutorial is missing yet but you can have a look at the examples provided with the source distribution as well as the documentation available in the API reference manual. The Control tutorial explains how the different control models of IEC 61850 can be used with the client API.
Figure 2: IEC 61850 client architecure (separately usable MMS client parts are in yellow)
Hardware/OS abstraction layer
libIEC61850 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. For GOOSE support also an abstraction for direct Ethernet access is provided. For file service support also an abstraction layer exists. If you want to port the library to a new platform you need to implement these functions. Depending on the services you need not all of the functions are required. At the moment ready to use implementations for POSIX(Linux, ucLinux …) and Win32 exists. This HAL consists of five files hal_time.h, hal_socket.h, hal_ethernet.h, hal_filesystem.h, and hal_thread.h.
C#/.NET API
The native API of libIEC61850 is the C API. However since many people are using C# and .NET today for client/server applications the latest version also contain a C# API (see Using the C# API). At the moment this API does not provide access to all features of the library.
Building the library and the examples
For an introduction on how to build the library and the examples see Building the library
Create your own IEC 61850 server device
The server API provides support for three different ways to set up a data model for the server. The first one is to create a complete static model that cannot be changed at runtime of the application. In this case the data model provided as SCL(ICD) file is converted to C source code and statically compiled into the application. This results in a very low footprint since there is no configuration file parser required. It could even be used on systems where no file system is available or desirable. The second way is a pure programmatic model generation approach where the data model is generated at runtime by API calls. This approach can be used for very dynamic devices like gateways, protocol converters, simulation tools etc. The third approach uses a simple configuration file format to feed the application with the IEC 61850 device model.
Generate the static model source code 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 static_model.c and static_model.h. Copy these files to your project directory where the build system can find them. The file static_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 static_model.h is intended to be included by your code and defines handles that you can use to efficiently access the data model.
Generate a server configuration file from ICD(SCL) file
This also requires a Java runtime environment on the development system to generate the configuration file. The usage of the provided tool does not differ much from the tool for static model generation.
In the main directory of the source distribution change to the tools/model_generator directory. Enter
java -jar genconfig.jar my_model.icd my_model.cfg
This will generate the file my_model.cfg. The file is a simple text file format containing the complete data model description including preset values and optional short addresses. The access to the data attributes also happens by handles at runtime. The difference is that these handles are not known at compile time by the application. Instead the handles have to be requested by API calls either using the object reference or short address of the data attribute.
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 libiec61850, PROJECT_BINARY_NAME and PROJECT_SOURCES.