Documentation

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 for the API can be found at API Reference Manual (version 1.0.0).

Server API

LibIEC61850 provides two different APIs to implement MMS server applications. 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 support IEC 61850. If you want to implement IEC 61850 compliant server devices it is not recommended that you use this API because then you are finding yourself implementing a lot of IEC 61850 features.

The other API is a IEC 61850 specific API. It is designed in a way to be independent from the MMS mapping to be able to support other mappings (SCSM) in the future. 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 IEC 61850 data model. Also this 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 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)

IEC 61850 server library (yellow – separately usable MMS server parts)

Client API

There are also two different client APIs.

The first client API is not IEC 61850 specific but is a generic MMS client API. It can be used to implement a generic MMS client or client applications that use other communication specifications like e.g. TASE.2 (ICCP). An introduction by examples can be found in the MMS client tutorial.

The second IEC 61850 specific client API is a higher-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)

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. If you want to port the library to a new platform you need to implement these functions. At the moment implementations for POSIX(Linux, ucLinux …) and Win32 exists. This HAL consists of four files hal/hal.h, hal/socket/socket.h, hal/ethernet/ethernet.h, and hal/thread/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.