- renamed README to README.md and now using markdown syntax

- added pyiec61850 tutorial and example thanks to Cédric Boudinet

README.md

@@ -1,93 +1,98 @@
-README:
--------
+# README libIEC61850
 
-This file is part of the documentation of libiec61850. More documentation can be found online at http://libiec61850.com or in the provided doxygen documentation.
+This file is part of the documentation of **libIEC61850**. More documentation can be found online at http://libiec61850.com or in the provided doxygen documentation. Also consider to review the examples to understand how to use the library
 
 Content:
-- Overview
-- Building and running the examples
-- Installing the library and the API headers
-- Building on Windows with GOOSE support
-- Building with the cmake build script
-- C# client API
-- Licensing
-- Third-party contributions
 
+* Overview
+* Building and running the examples
+* Installing the library and the API headers
+* Building on Windows with GOOSE support
+* Building with the cmake build script
+* Using the log service with sqlite
+* C# API
+* Licensing
+* Contributing
+* Third-party contributions
 
-Overview
----------
 
-libiec61850 is an open-source (GPLv3) implementation of an IEC 61850 client and server library. It is implemented in C (according to the C99 standard) to provide maximum portability. It can be used to implement IEC 61850 compliant client and server applications on embedded systems and PCs running Linux and Windows. Included is a set of simple example applications that can be used as a starting point to implement own IEC 61850 compliant devices or to communicate with IEC 61850 devices.
+## Overview
+
+
+libiec61850 is an open-source (GPLv3) implementation of an IEC 61850 client and server library implementing the protocols MMS, GOOSE and SV. It is implemented in C (according to the C99 standard) to provide maximum portability. It can be used to implement IEC 61850 compliant client and server applications on embedded systems and PCs running Linux, Windows, and MacOS. Included is a set of simple example applications that can be used as a starting point to implement own IEC 61850 compliant devices or to communicate with IEC 61850 devices. The library has been successfully used in many commercial software products and devices.
 
 For commercial projects licenses and support is provided by MZ Automation GmbH. Please contact info@mz-automation.de for more details on licensing options.
 
-Building and running the examples
-----------------------------------------
+## Building and running the examples with the provided makefiles
 
 In the project root directoy type
 
-> make examples
+```
+make examples
+```
 
 If the build succeeds you can find a few binary files in the projects root directory. You can also find a binary version of the library ("libiec61850.a") in the "build" directory.
 
 Run the sample applications in the example folders. E.g.:
 
-> cd examples/server_example1
-> sudo ./server_example1
+```
+cd examples/server_example1
+sudo ./server_example1
+```
 
 on the Linux command line.
 
 You can test the server examples by using a generic client or the provided client example applications.
 
 
-Installing the library and the API headers
---------------------------------------------
+## Installing the library and the API headers
 
 The make and cmake build scripts provide an install target. This target copies the API header files and the static library to a single directory for the headers (INSTALL_PREFIX/include) and the static library (INSTALL_PREFIX/lib). With this feature it is more easy to integrate libiec61850 in an external application since you only have to add a simple include directory to the build tool of your choice.
 
 This can be invoked with
 
-make install
+`make install`
 
 The default install directory for the make build script is ".install".
 
 You can modify this by setting the INSTALL_PREFIX environment variable (e.g.):
 
-make INSTALL_PREFIX=/usr/local install
+`make INSTALL_PREFIX=/usr/local install`
 
 For the cmake build script you have to provide the CMAKE_INSTALL_PREFIX variable
 
 
-Building on windows with GOOSE support
----------------------------------------
+## Building on windows with GOOSE support
 
-To build the library and run libiec61850 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).
+To build the library and run libiec61850 applications with GOOSE support on Windows (7/8/10) 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 llibiec61850 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 libiec61850
 
-Building with the cmake build script
--------------------------------------
+## Building with the cmake build script
 
 With the help of the cmake build script it is possible to create platform independet project descriptions and let cmake create specific project or build files for other tools like Make or Visual Studio.
 
-If you have cmake installed fire up a command line (cmd.exe) and create a new subdirectory in the libiec61850-0.x folder. Change to this subdirectory. Then you can invoke cmake. As an command line argument you have to supply a "generator" that is used by cmake to create the project file for the actual build tool (in our case Visual Studio).
+If you have cmake installed fire up a command line (cmd.exe) and create a new subdirectory in the libiec61850 folder. Change to this subdirectory. Then you can invoke cmake. As an command line argument you have to supply a "generator" that is used by cmake to create the project file for the actual build tool (in our case Visual Studio).
 
-cmake -G "Visual Studio 11" ..
+`cmake -G "Visual Studio 11" ..`
 
 will instruct cmake to create a "solution" for Visual Studio 2012. To do the same thing for Visual Studio 2010 type
 
-cmake -G "Visual Studio 10" ..
+`cmake -G "Visual Studio 10" ..` 
 
-Note: The ".." at the end of the command line tells cmake where to find the main build script file (called CMakeLists.txt). This should point to the folder libiec61850-0.x which is in our case the parent directory (..).
+Note: The ".." at the end of the command line tells cmake where to find the main build script file (called CMakeLists.txt). This should point to the folder libiec61850 which is in our case the parent directory (..).
+
+Depending on the system you don't have to provide a generator to the cmake command.
 
 To select some configuration options you can use ccmake or cmake-gui.
 
 
-Building the sqlite logging driver
------------------------------------
+## Using the log service with sqlite
+
+The library provides support for the IEC 61850 log service. It provides an abstract interface for a logging database. Included is a driver for using sqlite for logging. This driver can be seen as an example on how to use the abstract logging interface.
 
 You can use the driver by including the src/logging/drivers/sqlite/log_storage_sqlite.c file into your application build. 
 
@@ -96,25 +101,27 @@ On Ubuntu Linux (and simpilar Linux distributions) it is enough to install the s
 On windows the cmake skript will detect the sqlite source code and also creates the example project for logging.
 
 
-C# client API
---------------
+## C# API
 
 A C#/.NET wrapper and examples and Visual Studio/MonoDevelop project files can be found in the dotnet folder. The examples and the C# wrapper API can be build and run on .NET or Mono.
 
-Experimental Python bindings
-----------------------------
+## Experimental Python bindings
 
 The experimental Python binding can be created using SWIG with cmake.
 
 To enable the bindings you have to select the phyton configuration option with ccmake of cmake-gui.
 
-Commercial licenses
--------------------
-Commercial licensing and support options are provided by MZ Automation GmbH. Please contact info@mz-automation.de for more details.
+## Commercial licenses and support
+
+Support and commercial license options are provided by MZ Automation GmbH. Please contact info@mz-automation.de for more details.
+
+## Contributing
+
+If you want to contribute to the improvement and development of the library please send me comments, feature requests, bug reports, or patches. For more than trivial contributions I require you to sign a Contributor License Agreement. Please contact info@libiec61850.com.
+
 
+## Third-party contributions
 
-Third-party contributions:
---------------------------
 - The Mac OS X socket and ethernet layer has been kindly contributed by Michael Clausen, HES-SO Valais-Wallis, http://www.hevs.ch 
 
 

pyiec61850/CMakeLists.txt

@@ -20,4 +20,4 @@ EXECUTE_PROCESS ( #Finding python modules install path
 INSTALL ( FILES ${CMAKE_CURRENT_BINARY_DIR}/iec61850.py DESTINATION ${PYTHON_SITE_DIR})
 INSTALL ( TARGETS _iec61850   LIBRARY DESTINATION ${PYTHON_SITE_DIR})
 
-add_test(test_pyiec61850 ${PYTHON_EXECUTABLE} test_pyiec61850.py)
+add_test(test_pyiec61850 ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_LIST_DIR}/test_pyiec61850.py)

pyiec61850/examples/dispServerStruct.py

@@ -0,0 +1,37 @@
+#!/usr/bin/python
+import os,sys
+import iec61850
+if __name__=="__main__":
+	hostname = "localhost";
+	tcpPort = 102
+	if len(sys.argv)>1:
+		hostname = sys.argv[1]
+	if len(sys.argv)>2:
+		port = sys.argv[2]
+	con = iec61850.IedConnection_create()
+	error = iec61850.IedConnection_connect(con, hostname, tcpPort)
+	if (error == iec61850.IED_ERROR_OK):
+		[deviceList, error] = iec61850.IedConnection_getLogicalDeviceList(con)
+		device = iec61850.LinkedList_getNext(deviceList)
+		while device:
+			LD_name=iec61850.toCharP(device.data)
+			print("LD: %s" % LD_name)
+			[logicalNodes, error] = iec61850.IedConnection_getLogicalDeviceDirectory(con, LD_name)
+			logicalNode = iec61850.LinkedList_getNext(logicalNodes)
+			while logicalNode:
+				LN_name=iec61850.toCharP(logicalNode.data)
+				print(" LN: %s" % LN_name)
+				[LNobjects, error] = iec61850.IedConnection_getLogicalNodeVariables(con, LD_name+"/"+LN_name)
+				LNobject = iec61850.LinkedList_getNext(LNobjects)
+				while LNobject:
+					print("  DO: %s" % iec61850.toCharP(LNobject.data))
+					LNobject = iec61850.LinkedList_getNext(LNobject)
+				iec61850.LinkedList_destroy(LNobjects)
+				logicalNode = iec61850.LinkedList_getNext(logicalNode)
+			iec61850.LinkedList_destroy(logicalNodes)
+			device = iec61850.LinkedList_getNext(device)
+		iec61850.LinkedList_destroy(deviceList)
+		iec61850.IedConnection_close(con)
+	else:
+		print("Failed to connect to %s:%i\n"%(hostname, tcpPort))
+	iec61850.IedConnection_destroy(con)

pyiec61850/iec61850.i

@@ -18,6 +18,10 @@ ModelNode* toModelNode(DataObject * DO)
 {
     return (ModelNode*) DO;
 }
+char* toCharP(void * v)
+{
+    return (char *) v;
+}
 DataAttribute* toDataAttribute(DataObject * DO)
 { return (DataAttribute*)DO;}
 DataAttribute* toDataAttribute(ModelNode * MN)
@@ -40,3 +44,4 @@ ModelNode* toModelNode(LogicalNode *);
 ModelNode* toModelNode(DataObject *);
 DataAttribute* toDataAttribute(DataObject *);
 DataAttribute* toDataAttribute(ModelNode *);
+char* toCharP(void *);

pyiec61850/test_pyiec61850.py

@@ -1,11 +1,12 @@
 #!/usr/bin/python
 import sys
 import time
-import iec61850
 import threading
 import traceback
 import signal
 import sys
+sys.path.append('.')
+import iec61850
 def signal_handler(signal, frame):
 	global running
 	running =0

pyiec61850/tutorial.md

@@ -0,0 +1,50 @@
+# Building
+Before building you should install swig and python.
+To build python bindings you have to turn on the BUILD\_PYTHON\_BINDINGS flag in CMake from cmake-gui or in command line:
+```sh
+$ cmake -DBUILD_PYTHON_BINDINGS=ON .
+```
+Then compile the library and install it. CMake and swig will automatically detect your python version and install the python library in python library directories.
+
+pyiec61850 library is to be imported calling 
+```python
+import iec61850
+```
+# Client tutorial
+
+The python bindings works similarly to the basic C library. However there are some differences:
+
+* a specific function is to be called to cast variables from one type to another
+* arguments passed by pointer are to be removed from arguments and append to the return list
+
+
+For example to create a connection, call:
+```python
+	con = iec61850.IedConnection_create()
+	error = iec61850.IedConnection_connect(con, "localhost", 102)
+	if (error == iec61850.IED_ERROR_OK):
+		# Do some work
+		iec61850.IedConnection_close(con)
+	iec61850.IedConnection_destroy(con)
+```
+
+To iterate over a list of logical devices, the code becomes:
+```python
+[deviceList, error] = iec61850.IedConnection_getLogicalDeviceList(con)
+device = iec61850.LinkedList_getNext(deviceList)
+ 
+while device:
+	print("LD: %s" % iec61850.toCharP(device.data))
+	[logicalNodes, error] = iec61850.IedConnection_getLogicalDeviceDirectory(
+				con, iec61850.toCharP(device.data))
+	device = iec61850.LinkedList_getNext(device)
+iec61850.LinkedList_destroy(deviceList)
+```
+
+Reading and writing operations can be performed using this syntax:
+```python
+[floatValue, error] = iec61850.IedConnection_readFloatValue(con,
+	"simpleIOGenericIO/GGIO1.AnIn1.mag.f", iec61850.IEC61850_FC_MX)
+err = iec61850.IedConnection_writeFloatValue(con, 
+	"simpleIOGenericIO/GGIO1.AnIn1.mag.f", iec61850.IEC61850_FC_MX, 10.0)
+```