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
#
ApplicationIinThe 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 synchronizationlocalControl
- Some output points are in local modedeviceTrouble
- Device-specific bit indicating that the device has a problemconfigCorrupt
- Device configuration is corrupt
#
Time SynchronizationDNP3 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 RestartDNP3 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 RequestsOutstationApplication
contains two methods related to freezing counters:
freezeCountersAll
- called when a counter freeze operation is received using the All Points (0x06) qualifierfreezeCountersRange
- 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 pointFREEZE_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.