open-dnp3 Copyright (c) 2010, 2011 Green Energy Corp.

This project is licensed under the terms of the Apache Public License v2.0. For additional details on licensing terms and conditions, see COPYING.

For more information about the OpenDNP3 library, visit the project website at http://code.google.com/p/dnp3.

The OpenDNP3 library and testset is a portable, scalable, and rigorously tested implementation of the DNP3 (www.dnp.org) protocol stack written in C++ and provided by Green Energy Corp to the community under the Apache 2.0 license. The library is optimized for massively parallel front end processor implementations and slave device simulations, although it has been verified to perform very well on embedded linux ARM architectures. It includes a command line master/slave test set.

The repository is organized as a set of projects of libraries and executables.

The main libraries are:

APL Portable functionality for things like parsing, physical layers, logging

APLTestTools Library of tools/mocks uses for testing

DNP3 Protocol library for dnp3

Terminal Extensible library for creating command line driven UI

DNP3Java Library generated by swig that wraps the stack with JNI

The main executable targets are:

TestAPL A test suite for the PSI library

DNP3Test A test suite for the DNP3 library

TerminalTest A test suite for the Terminal library

TestSet A dnp3 command line master/slave test set.

The OpenDNP3 library has been verified under linux, cygwin, and windows. Three build systems are included:

1. GNU g++ and the rake (ruby make) build system provided
2. GNU autotools (experimental)
3. Visual Studio SLN and PROJ files

Set the TOOLS_HOME environment variable to an appropraite path for installing tools and libraries. Reasonable choices are C:\Tools or ~/tools.

• On cygwin/windows this variable is set via: Start Menu > ControlPanel > System > Advanced > EnvironmentVariables

• On Linux systems its common to add the following line to /.bashrc export TOOLS_HOME=/tools

Get a copy of setup.exe from www.cygwin.com. Hold onto setup.exe as you may need it to install additional packages.

You will need the following additional packages to build the C++ libraries and tests. Please be careful to get the correct version if noted below:

• Web -> wget // used in install scripts to retrieve packages
• Devel -> gcc-g++ // C++ compiler (version 3.4.4, not tested on gcc4x)
• Devel -> cache // C compiler cache for improving recompilation
• Devel -> make // GNU version of make utility
• Devel -> ruby // Scripting language we use it for build scripts
• Devel -> libtool // Shared library generation tool

Optional packages:

• Devel -> swig // C/C++ wrapper generator used for Java bindings
• Devel -> doxygen // documentation system for C++

Doxygen needs GraphViz. Download and install GraphViz: http://www.graphviz.org/Download_windows.php

The msi installer will put a program called dot onto your path that doxygen needs to generate images.

If you want to build for the Technologic Systems ARM platform, install the cross-compiler:

cd tools/install_scripts/crosstool ./install-crosstool.sh

It is important that this step be completely successfully prior to the boost installation, as the Boost libraries will be built for ARM as well as your platform.

Install the boost libraries and headers by running the script:

cd tools/install_scripts/boost/{VERSION} ./install-boost.sh

This step will take some time as it retrieves the boost package and builds from source for both your platform and for ARM.

When the boost version we are using is updated we will update the references in rakefile.rb and config/boost_*.vsprops to use the new version name and include updated installers to compile the new version, if after and update the build suddenly fails with missing boost include errors errors check that the boost version hasn't been upgraded recently.

RubyGems is a package delivery system for ruby libraries. Follow the instructions from the RubyGems website to install:

http://rubygems.org/

Rake is a ruby gem. To install rake:

gem install rake

We have created native bindings for java using SWIG. Prior to version 0.9.3, the native libraries where embedded into the jar file and extracted before use on the target. This caused us problems with OSGi and made integrating the jar difficult with some build tools.

The shared library must now be installed in a directory found on the java.library.path. Typical locations are /usr/lib or C:<windir>\System32.

We keep some precompiled versions of the library on the project site for various platforms.

1. Use rake to generate the bindings and build the shared library. This step also outputs the java code.
2. cd to the DNP3Java dir and use Maven to build/deploy the jar.

Use rake to build. To see a list of targets and their descriptions, type:

rake -T

rake understands dependencies similarly to the GNU make utility. To build and run the dnp3test executable, type:

rake dnp3test:run

Flags not documented by Rake -T:

• debug=true // debug mode, compiler generate debug information to // use with gdb, etc

• arm=true // crosscompile for arm, requires the arm cross //compiler to be installed w/ arm Boost libs

• coverage=true // compile with coverage information

• SH_VERBOSE=true // print every command that rake issues to the shell

rake // build everything

rake arm=true // build everything in // release mode for arm

rake dnp3test:run debug=true // build and run the // dnp3test w/ debug info

rake dnp3test:run["--show_progress=true"] // run the test in release // mode, w/ arg for // Boost.Test

To generate documentation for the code coverage of the unit tests relative to the rest of the stack, you will need to have lcov installed before invoking:

rake dnp3test:run coverage=true

Be patient, this generates several megabytes of data.

The HTML output will be generated in at ./coverage-DNP3Test/html/index.html.

To generate documentation for the stack you need to have doxygen and graphviz (dot) installed before invoking:

rake document

Be patient, this generates hundreds of megs worth of images.

The HTML output will be generated in ./docs.

The Java Developers Kit (JDK) and Swig are required to build Java bindings. Install Open JDK 1.6 or greater.

Set the JAVA_HOME directory to the install path of your JDK version.

The deployment tasks require Apache Buildr to be installed:

gem install buildr

There are 2 tasks for deploying the jar:

• dnp3java:install : copies the file to your local maven repository (doesn't overwrite an existing build so delete that library first)

• dnp3java:upload : uploads the file to the remote maven repository (this should generally only be done by the build server)

The GNU autotools are comprised of two packages, GNU autoconf and GNU automake. Libtool support is required. Lcov and swig support may be required if you choose to build those options.

Requirements:

• astyle v2.01 or later (required if 'make astyle')
• boost v1.42 or later (required)
  • boost::date_time (required)
  • boost::program_options (required)
  • boost::system (required)
  • boost::thread (required)
  • Boost Unit Test Framework (required)
• docbook v0.6.14 or later (required if 'make docs')
• lcov (required if 'make lcov')
• libtool (required)
• swig v1.3.17 or later (required if 'configure --with-java')
• Java JDK with JNI support (required if 'configure --with-java')
• Python 2.6 or later (required if 'configure --with-python')

To start, first reinitialize autotools to be compatible with the version running on your system:

autoreconf -f -i

Next, run the 'configure' script:

./configure

A full list of options can be found using './configure --help'.

You can now build the OpenDNP3 libraries and programs:

make

When ready, you can install the libraries, headers, and programs onto your system:

make install

If you want to generate the book "OpenDNP3 Library: The Definitive Guide," use one or more of the following make target after configuring the system:

make docs make docs-html make docs-pdf

The resulting book will be placed in a subfolder inside of the 'docs' folder.

If you want to build the doxygen code documentation, use the following make target after configuring the system:

make doxygen-doc

The resulting HTML documentation will be placed in a folder named 'doxygen-doc'.

If you want to build the libraries with lcov support (analysis tool for code coverage of the unit/integration test infrastructure), the process changes slightly:

autoreconf -f -i ./configure --enable-lcov make ./dnp3test make lcov

The lcov HTML report is written to './lcov/html/index.html' and can be opened with any standard web browser.

If you will be making changes to the unit/integration test infrastructure while analyzing the lcov results, use an alternate sequence to reduce the amount of rebuilding required:

autoreconf -f -i ./configure --enable-lcov make ./dnp3test make lcov

Iterate on the following sequence after changing the tests:

 make lcov-reset        ; # Reset lcov data between each run
 make                   ; # Rebuild with the new changes
 ./dnp3test             ; # Profile the new changes
 make lcov-report       ; # Regenerate the lcov report

If you are a developer and are making changes to the OpenDNP3 library code, you can run the 'astyle' utility to ensure that your code conforms to the style guidelines used for the project:

make astyle

Please run this utility before submitting any patches to the project.

If you want to build the Java bindings for the OpenDNP3 library, make sure that your system has both swig and a valid JDK installed. Enable the build tree to create the Java library:

autoreconf -f -i ./configure --with-java=/path/to/jdk/include make

The Java source files are created in the 'src' directory structure.

If you want to build the Python bindings for the OpenDNP3 library, make sure that your system has both swig and a valid Python interpreter installed. Enable the build tree to create the Python library:

autoreconf -f -i ./configure --with-python make

The Python library is called pyopendnp3. The Python class and shared library are installed to the 'opendnp3' package directory.