Skip to main content

OutstationApplication Interface

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

  • Internal Indication (IIN) bits
  • Callback for writing the time
  • Cold and warm restart operations
  • Counter freeze requests

ApplicationIin​

The outstation will call OutstationApplication::getApplicationIin() whenever the system performs a solicited or unsolicited response. It will merge private IIN bits with the bits returned by the ApplicationIin structure, which contains four internal indication bits that you can control:

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

Time Synchronization​

DNP3 has two different procedures for synchronizing the outstation's time: LAN and Non-LAN. You don't need to worry about which procedure the master uses; both procedures will call OutstationApplication::writeAbsoluteTime(..), 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, won't typically accept time synchronization requests from DNP3 unless the other time source is unavailable.

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. Otherwise, the master may interpret this as a failure, causing some DNP3 masters to enter an infinite loop of writing the time.

Typically, an outstation will assert this bit periodically, depending on its internal clock accuracy.

Cold and Warm Restart​

DNP3 requires that compliant outstations be capable of performing a full restart, also known as a "cold restart". Because an attacker could abuse this functionality to perform a denial of service, we recommend that you disable this functionality in most products. Software gateways and translators that run on a server shared with other services should never implement this functionality. Return RestartDelay with RestartDelayType::NOT_SUPPORTED to indicate that the operation is not supported so that the timestamp isn't used.

If you must implement this functionality to pass conformance tests or due to customer requirements, 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 has no practical use for 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: This is called when a counter freeze operation is received using the All Points (0x06) qualifier.
  • freezeCountersRange: This is called when a counter freeze operation is received using 8-bit (0x00) or 16-bit (0x01) range qualifiers.

A provided reference to a DatabaseHandle may be used to copy counters to frozen counters. The FreezeType parameter lets you choose between 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.