dnp3 / opendnp3

DNP3 (IEEE-1815) protocol stack. Modern C++ with bindings for .NET and Java.

End-of-Life

This project will reach end-of-life on September 1st, 2022. On this date:

1. This repository will be archived, making it read-only.
2. The Google Group will be locked, but will remain publicly searchable.
3. The project homepage, this README, and group will be updated to indicate that the project is end-of-life.

We will consider bug fixes from the community or support requests from existing customers up until this date.

Please make appropriate plans if you are using this library in production, e.g.:

• Dedicate personnel to maintaining your own internal copy of the library.
• Consider a commercial library such as the one offered by Step Function I/O.

You can read about this decision in these blog posts:

• OpenDNP3 Retrospective
• DNP3 1.0.0 (Rust)

Overview

Opendnp3 is a portable, scalable, and rigorously tested implementation of the DNP3 protocol stack written in C++11. The library is designed for high-performance applications like many concurrent TCP sessions or huge device simulations. It also embeds with a small footprint on Linux.

Build status

Branch	Build	Code coverage	Quality
release-2.x			-
develop

Documentation

The documentation can be found on the project homepage.

If you want to help contribute to the official guide its in this repo.

License

Licensed under the terms of the Apache 2.0 License.

Copyright (c) 2010, 2011 Green Energy Corp

Copyright (c) 2013 - 2020 Step Function I/O LLC

Copyright (c) 2020 - 2022 Step Function I/O LLC

Copyright (c) 2010 - 2022 various contributors

opendnp3's Issues

Add controllable support for TCP keepalives

TCP sockets sometimes need keepalives enabled. There doesn't appear to be a way of setting the socket options from the application code to enable such features.

Remove all mutex/conditions from opendnp3 & openpal

Move further towards an MCU portable library

User callback to allow for pseudo-randomization of TCP retry attempts

The TCP retry mechanism is currently set to a static period. I'm encountering a problem right now where this causes a persistent deadlock due to a race condition in networking equipment. What would fix it is if I had the ability to pseudo-randomize (like via a back-off timer) connection attempts.

Ideally, this mechanism should be exposed to the user application as a callback hook "tcpRetryWaitBeforeReconnecting()" or something.

Empty DataObserver transactions being reported to the application

The DataObserver start() / end() methods are being called without any calls to update() in between. This "null" behavior isn't bad, just annoying and not useful.

Add link-layer keep alive using REQUEST_LINK_STATES as per specificaiton

DNP Master doesn't seem to recover from TCP errors

Issue is described here with log file from Verges

https://groups.google.com/forum/#!topic/automatak-dnp3/25j_dbERmqM

Send APDU as a single TCP fragment when possible

Currently, APDU's are chunked into TPDUs, which are then transmitted individually. Due to Nagle's algorithm, the first TPDU is transmitted in one fragment and the rest are transmitted in a second fragment. If all TPDU's were written to the TCP socket at the same time, they could be grouped into one fragment, thus reducing the overall number of packets required by 50%.

2.0.x make install does not install headers

In the 2.0.x branch, doing a make install does not install the headers anymore. The headers are installed in the 1.1.x branch. Looks like commit 6335e66 removed them from Makefile.am.

Auto-detect Boost version during configure and set CXXFLAGS+=-DOPENDNP3_BOOST_TIMER_PATCH if needed

Add support for Assign Class command (function code 22)

We're looking to implement (at least in the Masterstation) assign class - function code 22.
Happy to take ownership of this feature

java.lang.NoClassDefFoundError thrown when starting the Java examples

Read requests are ignored while waiting for an unsolicited confirmation

Our customer is finding that on start-up, the DNP stack does not respond to any read request until a confirmation is first sent. I dug into it and the stack appears to be expecting a confirmation on start-up because of the start-up unsolicited message requirement. While the start-up unsolicited message is appropriate, I believe that according to the standard, if a read request comes in while the outstation is waiting for unsolicited response confirmation that it should at some point times out, abort the unsolicited series and respond to the read request instead. Per rule 16 Section 4.6.6 of the standard:

If the outstation receives a read request of any kind while waiting for a confirmation to an unsolicited response, it shall defer building a response until either
1) The unsolicited response confirmation is received. The outstation shall then
i) Immediately clear the confirmed event data from its event buffer(s) according to Rule 11.
ii) Respond to the deferred read request as though it had just been received.
2) Timeout occurs waiting for the unsolicited confirmation. At this time, the outstation shall not send a retry unsolicited response; instead it
i) Shall terminate the current unsolicited response series17, assume the confirmation is not forthcoming, and make the events available to be reported in a subsequent solicited response or a subsequent original unsolicited response.
ii) Respond to the deferred read request as though it had just been received and wait for confirmation to that read response if confirmation is required.
iii) Thereafter, may formulate a new original unsolicited response for any remaining events that are permitted18 to be transmitted in an unsolicited response.

Factor out Hardware Abstraction Layer (HAL)

Remove thread pool, timers, time source, physical layers, and all other ASIO related components into a separate project library. The objective is two-fold:

1. Make this common infrastructure reusable for other protocols like 60870 and Modbus. Sharing a thread pool, etc will make gateways and RTUs VERY efficient.

2. Factoring out the HAL will allow it to be implemented for platforms aren't supported by ASIO.

Build executable JAR for each Java demo

Build one executable JAR for the MasterDemo and another for the OutstationDemo.

Add support for on-demand polling by a Master

Certain kinds of physical layers (such as cellular) incur cost per byte transferred. For these units, we want the integrity polling interval to be very large by default. Exception scans are used to fill in the gaps.

However, when we issue a output write (such as an analog output or binary output), we want to temporarily increase our polling frequency so that we can positively detect the "set" operation via a change in the corresponding output status points. As the output status points are not sent during a standard exception scan, what is needed is a way to either adjust the integrity poll period on the fly or enable an external agent to instruct the Master to perform an integrity poll on-demand. (The scheduling can be then handled by the external agent.)

Quality of boolean values does not look compatible with some outstations

Hi, I have been implementing a dnp3 master using opendnp3.
For tests I use the slave simulator provided in https://github.com/gec/dnp3slavesim
The thing is, for binary points, the slave provides the quality value 0 for 'ONLINE', and opendnp3 cannot map that to the enumeration of binary quality when I read it from the Binary object. Is that correct?
Moreover, the quality retrieved from the same objects seems to be varying whenever I change the boolean value of the point. I believe this is not correct.

Kind regards, Felipe.

./configure --with-java=<javac-path> not working

Complaining about not being able to find javac and the associated jni.h even though javac and jni.h exist where specified. May be an issue with AC_PATH_PROG usage in ax_jni_include_dirs.m4.

Add ability to perform basic READ commands

Some basic outstations only support reading objects using read all/range commands.
Suggested enhancement is to implement a demand and period read function (eg AddReadScan).

MasterAdapter.cpp - should be TotalMiliseconds

Should be TotalMilliseconds instead of Milliseconds

IMasterScan^ MasterAdapter::AddClassScan(int aClassMask, System::TimeSpan period, System::TimeSpan taskRetryPeriod)
{
auto scan = mpMaster->AddClassScan(aClassMask, openpal::TimeDuration::Milliseconds(period.Milliseconds), openpal::TimeDuration::Milliseconds(taskRetryPeriod.Milliseconds));
return gcnew MasterScanAdapter(scan);
}

transport layer conformance issue

Transport function should allow multi-APDU TPDU's size to vary. Issue was noted on the other branch.

Ensure tests for time sync timer are functional

https://groups.google.com/forum/#!topic/automatak-dnp3/JXWhS8XlRwk

Java API - race condition with state listeners

The process to define a stack is:

Channel channel = new DNP3Manager().addTCPClient(...);
channel.addStateListener(listener);

Master master = channel.addMaster(...);
master.addStateListener(listener);

Since execution starts immediately after creation, there is an uncontrollable time delay between creating the object and registering the state listeners at both the Channel and Master level.

Java Logging: "bad sequence number" shows character glyph

"Address incompatible with the requested protocol" error when creating a new boost socket

Hello,
I am try in to add another socket to my program that is already running openDNP3. however when I create another boost connection acceptor, the openDNP3 errors saying "An address incompatible with the requested protocol was used" is it possible to create another acceptor while running the openDNP3? if so how can it be done?
Thanks
DW

Java API - ListenableFuture with get(timeout) mechanism

Pull Java JNI LogEntry changes from 1.1.x to 2.0.x branch

Implement async DNS host name resolution on tcp client.

Use async:

http://stackoverflow.com/questions/4678903/async-resolve-with-boost-asio

1. Perform resolution on every connect call, don't cache results.

2. What do we do with the list of multiple IP addresses? What's our strategy? Round robin them?

Add support for reading & responding to device attributes (Group 0)

2.0.x - CommandResponse.Result always NO_COMMS in 2.0.x branch

CommandResponse.Result appears to be always NO_COMMS in the 2.0.x branch

Looks like its because the Ctor initialiser uses a fixed value instead of a parameter and the CommandResponse::OK method is never called by CommandTask

CommandResponse::CommandResponse(CommandResult aResult, CommandStatus aStatus) :
mResult(CommandResult::NO_COMMS),
mStatus(aStatus)
{}

Should this just be:

mResult(aResult), 
mStatus(aStatus) 

?

Not sure if this issue persists in the 'parser' branch or not

Using --enable-opendnp3nomaster causes error

When I configure using the --enable-opendnp3nomaster switch, then make, I get the following error:

In file included from cpp/src/opendnp3/DNP3Channel.cpp:23:0:
cpp/src/opendnp3/DNP3Channel.h:60:118: error: 'IMonotonicTimeSource' has not been declared

This is in 1.1 branch of things.

Not sure what is going on.

Add callback and/or poll support for network traffic usage

For certain network types which charge per byte, it would be useful to have the dnp stack report its traffic usage as a function of async_read/write() calls. Some mechanism to allow for real-time callback and scheduled polling of these values would be good.

Java API - MasterConfig.java maxRequestFragmentSize visibility

Is maxRequestFragmentSize missing "public"?

Migrate to header-only ASIO

Drop BOOST entirely except for the unit test framework. It will no longer be required to build/run the core library. The usage of C++11 has already weened the library off of all the other components like thread, date_time, etc.

getValue() doesn't place nicely with Java generics

When using the AnalogInput, BinaryInput, Counter, AnalogOutputStatus, and BinaryOutputStatus classes with Java generics, the Java compiler complains about their respective getValue() methods being "not found". I think that the Measurement or BaseMeasurement classes need to take some generic specifier, such as:

public abstract class Measurement<T> {
    protected T value;
    public T getValue() { return this.value; }
}

Make Integrity poll conformat

Class 0 -> Class 1/2/3/0

Time sync not writing expected time

When connecting an Automatak DNP3 master to a GEC DNP3 outstation, the following is seen during the time sync 'write' packet:

Note that the master's system clock is currently set to Mon Nov 4 09:28:26 PST 2013 of that screenshot.

Make CommandResult differentiate between local failrues (timeouts/not connected) & remote failures

You can't tell at the moment. Bad API.

Add support for building DEBs

Plan is to create the following packages:

• libopendnp3
  • contains the core C++ library
• libopendnp3-java
  • contains the Java JNI library and "api" and JARs for the "api" and "bindings" Java packages
• libopendnp3-dev
  • contains the C++ API headers and JARs for javadocs/source for the "api" and "bindings" Java packages
• libopendnp3-cpp-demos
  • contains the source code and binary executables for the C++ demos
• libopendnp3-java-demos
  • contains the source code and binary executables for the Java demos (exectuable, javadocs, and source)

Java: Assertion leClz != __null failure in LogSubscriberAdapter::Log(const LogEntry&)

java: java/cpp/LogSubscriberAdapter.cpp:40: virtual void LogSubscriberAdapter::Log(const opendnp3::LogEntry&): Assertion `leClz != __null' failed.

License discrepancy

With the 1.1 branch I notice a lot of the source files use the agpl license in addition to the original apache license.

In the 2.0 branch, I don't see the same licensing terms.

Your web site states that the license is Apache.

What is the license of the 1.1 branch?

Remote endpoint address should be re-resolved before each async_connect() attempt

Currently, in both the 1.1.x and 2.0.x branches, the mRemoteEndpoint.address is resolved once, in the constructor:

https://github.com/automatak/dnp3/blob/2.0.x/cpp/asiopal/src/PhysicalLayerAsyncTCPClient.cpp#L53

The problem is that if a DNS label is provided instead of a static IP address, the DNS label can resolve to different things over time. To accommodate for this, it would be preferable to re-resolve the address before each mSocket.async_connect() attempt:

https://github.com/automatak/dnp3/blob/2.0.x/cpp/asiopal/src/PhysicalLayerAsyncTCPClient.cpp#L59

A similar thing should be done for the corresponding TCP Server sockets. (While unusual to use a DNS name for a server socket, it is not impossible.)

Add support for DNP over UDP

Remove exceptions from state-machine base classes

Mainly an internal design issue. This makes it impossible for unexpected exceptions to be thrown at run-time that could put the stack into a bad state.

Measurement timestamps should have a way to indicate they are not present in the actual DNP update

Scenario:

• Outstation has a Class 1 Analog or Binary Input point with a timestamp (not 1970-01-01 00:00:00.000) associated
• Application registers a master stack to some outstation
• Stack starts to come up, issuing "Read Class 0" (integrity scan) then "Read Class 1,2,3" (exception scan)
• Stack passes the results of the integrity scan to the application
• Application parses the results, but sees the timestamp set as "1970-01-01 00:00:00.000" as a result of no timestamp being provided in the static object type
• Stack passes the results of the exception scan to the application
• Application sees the timestamp set properly now

There is no way for the application to distinguish between a false timestamp (1970-01-01 00:00:00.000) that was injected as a result of the integrity poll and a real timestamp (which could, though unlikely, be set to the same) as a result of an exception scan.

Application control of NEED_TIME IIN bit

For some systems, allowing the DNP stack to control the IIN NEED_TIME bit is sufficient. For others with dedicated time-keeping devices (such as GPS time sync or cellular radios), a more precise time can be determined from these external sources. It would be beneficial if the application layer could control the stack's automatic use of the IIN NEED_TIME bit in such circumstances. (Like a "disable / enable" flag that operates at runtime.)

merge timesync fix into 1.2.x

Merge was pretty disastrous in terms of conflicts. Probably easier to manually fix.

Java API - Counter and CounterInputQuality don't share a common base name

AnalogInput -> AnalogInputQuality
BinaryInput -> BinaryInputQuality
Counter -> CounterInputQuality

Some parallelism in structure here!

Strangely truncated log message: 'Unexpected response with sequence:'

21:53:48.698 [Thread-6] {} WARN  (MasterStackManagerImpl.java:225) - DNP Log Message: (channel-tcp-client-endpoint-11.stack-master-endpoint-11.app.sol:-1) Unexpected response with sequence: 
21:53:48.699 [Thread-6] {} WARN  (MasterStackManagerImpl.java:225) - DNP Log Message: (channel-tcp-client-endpoint-11.stack-master-endpoint-11.app.sol:-1) Unexpected response with sequence: 
21:53:48.699 [Thread-6] {} WARN  (MasterStackManagerImpl.java:225) - DNP Log Message: (channel-tcp-client-endpoint-11.stack-master-endpoint-11.app.sol:-1) Unexpected response with sequence: 

The log message appears to be truncated prematurely. There is no additional context before/after this to help with analysis.

IIN Event bits not behaving to conformance.

Occasional "no such method" error when running Java tests

Exception in thread "Thread-34" java.lang.NoSuchMethodError: onStateChange

Happens in both maven and IntelliJ