The DNP3 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 library has been verified under linux, cygwin, and windows. Two build systems are included:
- GNU g++ and the rake (ruby make) build system provided. This build system is verified under ubuntu and cygwin.
- Visual Studio SLN and PROJ files
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.
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:
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:
Rake is a ruby gem. To install rake:
gem install rake
We have created native bindings for java using SWIG. The native libraries are embedded into the jar file and extracted before use on the target, this allow us to keep the versions perfectly in-sync and keep installation time and complexity to a minimum. We make use of the "buildr" tool to automate uploading the jar to the repository.
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 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)