DNP3 Guide

Overview

DNP3 (Distributed Network Protocol) is a SCADA protocol widely used to link control centers with RTUs and IEDs across electric, water, and oil & gas utilities. ControlBird provides DNP3 as a dedicated service with two operational roles. The Master role acts as a client: it polls outstations, receives unsolicited events, and issues commands. The Outstation role acts as a server: it listens for master connections, exposes ControlBird entity data as DNP3 points, and emits unsolicited responses.

Each role connects over one of three transports (TCP, serial RS-232/RS-485, or TLS) and binds DNP3 points to ControlBird entity fields through a mapper architecture. You configure everything through the Device Manager application; no service-level configuration files are required.

Transports

Serial endpoints support baud rates from 1200 to 115200 (default 9600), data bits 5–8, stop bits One or Two, and parity None, Odd, or Even. All transports share a common set of link-layer and polling parameters.

Entity Model

A DNP3 integration is built from a controller, one endpoint, and one or more mappers. The controller references its endpoints, and mappers bind individual points to ControlBird entity fields.

Link-layer addressing

DNP3 uses 16-bit link-layer addresses to distinguish the master from the outstation on a shared link. The master address defaults to 1 and the outstation address defaults to 1024. Both addresses must match on the two ends of a connection.

Object Groups

DNP3 organizes data into object groups. ControlBird maps each group to an appropriate ControlBird value type. Writable groups can be targeted by master commands; all groups can be read.

Double-bit binary values map to a choice field with four states: 0 = Intermediate, 1 = DeterminedOff, 2 = DeterminedOn, and 3 = Indeterminate.

Quality flags

Every DNP3 point carries quality flags. ControlBird monitors ONLINE, RESTART, COMM_LOST, REMOTE_FORCED, LOCAL_FORCED, OVER_RANGE, and REFERENCE_ERR. A point is treated as good when ONLINE is set and COMM_LOST is clear.

Mappers and Source Paths

A mapper binds one DNP3 point to one ControlBird entity field. The point is identified by its object group and point index. The SourcePath field uses the notation ObjectGroup:Index: for example, AnalogInput:5 selects analog input point 5.

Polling and Events

A DNP3 master combines periodic integrity polls (which request all data) with more frequent event polls (which request only changed data), plus optional unsolicited responses pushed by the outstation. The relevant timing fields on the endpoint are:

Unsolicited response classes

Outstations can push events without being polled. Each event is tagged with the class assigned by its mapper's EventClass field: Class 1 (urgent), Class 2 (normal), and Class 3 (background). Enable reporting per class on the endpoint via EnableUnsolicited and the UnsolicitedClass1/2/3 flags, and size the outstation's event queue with EventBufferSize.

Configuration Workflow

All DNP3 entities are created in the Device Manager app. The typical flow is:

1. Open Device Manager in the ControlBird UI.
2. Create a Dnp3MasterController or Dnp3OutstationController to pick the role.
3. Add an endpoint for your transport (TCP, serial, or TLS) using the matching endpoint entity.
4. For TLS, link CertificateEntity (this endpoint's own certificate) and TrustedCertificateEntity (the peer's trusted certificate). See Certificates.
5. Set the protocol parameters: master/outstation addresses, polling intervals, and response timeout.
6. For outstations, enable unsolicited responses per class and set EventBufferSize.
7. Create mappers: Dnp3Mapper for a master, Dnp3ServerMapper for an outstation.
8. In each mapper, set ObjectGroup, PointIndex, and SourcePath, then bind TargetEntity and TargetField.
9. For master output mappers, choose a CommandMode. For outstation mappers, assign an EventClass.
10. Enable the mappers and endpoint; the service auto-connects based on endpoint type.

For a hands-on introduction to binding a device to Store entities, see walkthrough step 7: Connect a Device.

Examples

Master over TCP

Dnp3MasterEndpoint
  Host:              192.168.1.100
  Port:              20000
  MasterAddress:     1
  OutstationAddress: 1024
  IntegrityPollIntervalMs: 60000
  EventPollIntervalMs:      5000

Outstation over serial

Dnp3OutstationSerialEndpoint
  SerialPort:    /dev/ttyUSB0
  BaudRate:      9600
  ListenAddress: 0.0.0.0
  Port:          20000
  EventBufferSize: 100

Master mapper: poll an analog input

Dnp3Mapper
  ObjectGroup: AnalogInput
  PointIndex:  5
  SourcePath:  AnalogInput:5
  TargetEntity: <device entity>
  TargetField:  <temperature field>

Master mapper: command a binary output

Dnp3Mapper
  ObjectGroup: BinaryOutput
  PointIndex:  0
  CommandMode: SelectBeforeOperate
  TargetEntity: <relay entity>
  TargetField:  <state field>

Outstation mapper: unsolicited event

Dnp3ServerMapper
  ObjectGroup: AnalogInput
  PointIndex:  10
  EventClass:  Class1
  TargetEntity: <sensor entity>
  TargetField:  <value field>

Notes

• Logging is configurable per endpoint, with adjustable maximum log file count and size per file.
• The TLS endpoints expose a SkipCertVerification flag that bypasses peer certificate validation. Leave it disabled in production, since it removes authentication guarantees.

Limitations

• The master role does not currently provide end-to-end TLS confidentiality; use a network-layer tunnel or VPN when securing master connections over untrusted networks.
• Common mapper fields such as Direction and ReadMode are managed automatically and are not set as part of DNP3-specific configuration.