Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
371 lines (243 sloc) 11.2 KB
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
For more information about the OpenDNP3 library, visit the project
website at
The OpenDNP3 library and testset is a portable, scalable, and
rigorously tested implementation of the DNP3 ( 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
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.
Building and Installing
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
## GNU rake (ruby make) ##
## Common Dependencies for all platforms ##
Set the TOOLS_HOME environment variable to an appropraite path for
installing tools and libraries. Reasonable choices are C:\Tools or
- 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
## Configuring CYGWIN ##
Get a copy of setup.exe from 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:
The msi installer will put a program called dot onto your path that
doxygen needs to generate images.
## Installing ARM CROSS-COMPILER ##
If you want to build for the Technologic Systems ARM platform, install
the cross-compiler:
cd tools/install_scripts/crosstool
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 Boost ##
Install the boost libraries and headers by running the script:
cd tools/install_scripts/boost/{VERSION}
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
## Install Ruby Gems and Rake ##
RubyGems is a package delivery system for ruby libraries. Follow the
instructions from the RubyGems website to install:
Rake is a ruby gem. To install rake:
gem install rake
## Creating Native -> Java (JNI) Bindings ##
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
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.
## Building the libraries and tests ##
Use rake to build. To see a list of targets and their descriptions,
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
### Examples ###
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
## Generating Code Coverage ##
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
## Generating Documentation ##
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.
### Building the Java bindings ###
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.
### Deploying the jar ###
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
## GNU autotools ##
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.
- 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:
A full list of options can be found using './configure --help'.
You can now build the OpenDNP3 libraries and programs:
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'
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
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 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 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
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
The Python library is called pyopendnp3. The Python class and shared
library are installed to the 'opendnp3' package directory.