OutstationApplication Interface

The OutstationApplication interface provides callbacks for dynamic events and information that the outstation requires from the user application:

  • Retrieving IIN bits controlled by user code
  • Callback for writing the time
  • Cold and warm restart operations
  • Counter freeze requests

ApplicationIin#

The outstation will call OutstationApplication::getApplicationIin() whenever a solicited or unsolicited response is performed. It will merge private Internal Indication (IIN) bits with the bits returned in the ApplicationIin structure:

The ApplicationIin structure contains 4 internal indication bits that are controllable by application code:

  • needTime - Outstation requires time synchronization
  • localControl - Some output points are in local mode
  • deviceTrouble - Device-specific bit indicating that the device has a problem
  • configCorrupt - Device configuration is corrupt

Time Synchronization#

DNP3 has two different procedures that can be used by a master to synchronize the time on an outstation, LAN and Non-LAN. Outstation implementors needn't worry about which procedure the master uses. Both procedures will result in OutstationApplication::writeAbsoluteTime(..) being called with a timestamp representing the number of milliseconds since January 1st 1970, 00:00:00 UTC.

Outstations that do not support DNP3 time synchronization should return WriteTimeResult::NOT_SUPPORTED. Outstations that receive their time from another source such as NTP or IRIG-B will typically not accept time synchronization requests from DNP3 unless the other time source fails for some reason.

Outstations may notify the master that they require time synchronization by setting the ApplicationIin.needTime bit. Outstations must clear this bit immediately in the writeAbsoluteTime(..) callback or the master may interpret this as a failure. Some DNP3 masters behave very poorly when this bit is not cleared and enter an infinite loop of writing the time.

Typically, outstations are configured to assert this bit periodically depending on how accurate their own internal clock is.

Cold and Warm Restart#

DNP3 requires that compliant outstations be capable of performing a full restart called a "cold restart". Given that this functionality can be easily abused to perform a denial of service, it is recommended that this functionality be disabled in most products. Software gateways and translators that run on a server and are likely sharing this server with other services should never implement this functionality. Return RestartDelay with RestartDelayType::NOT_SUPPORTED to indicate that the operation is not supported. The timestamp will not be used.

If you must implement this functionality due to conformance or customer requirements the callbacks for both cold and warm restart are available. Return RestartDelay with a time estimate of how long the restart will take in seconds or milliseconds. This delay isn't of any practical use to real world masters so don't worry too much about the accuracy of this value.

Freeze Requests#

OutstationApplication contains two methods related to freezing counters:

  • freezeCountersAll - called when a counter freeze operation is received using the All Points (0x06) qualifier
  • freezeCountersRange - called when a counter freeze operation is received using 8-bit (0x00) or 16-bit (0x01) range qualifiers

The FreezeType parameter allows the user to discern between the two types of supported freeze operations:

  • IMMEDIATE_FREEZE - Copy the current value of a counter to the associated frozen counter point
  • FREEZE_AND_CLEAR - Copy the current value of a counter to the associated frozen counter point and clear the current value to 0.

A reference to the Database is provided to allow the user to perform the requested freeze operations.