Guide - DNP3 connector - Nexalis Docs

1. Introduction

The DNP3 connector extracts values from DNP3 outstations and forwards the data to gRPC_kafka.
Configuration is JSON-based, enabling clear, repeatable deployments for DNP3 environments.

Key Features

DNP3 client (Master) support – communicate with one or more outstations.
Class-based scanning – mirror data by DNP3 class (0–3) instead of single indices.
Flexible configuration – per-class or per-index configuration available.
Human-readable descriptions – optionally attach descriptions to forwarded data points.
Comprehensive logging – log rotation, file templates, and log levels for easy troubleshooting.

2. Configuration

The DNP3 connector is configured through a JSON file composed of:

a logSettings object (optional),
a tagConfiguration array (required),
and an optional tagDescriptions object.

There are two ways to configure tags in the connector:

Class-based configuration
- The simplest approach.
- You configure the connector to poll entire DNP3 classes (0–3).
- All indices belonging to the class are collected automatically and forwarded to the cloud.
- Useful when you want complete mirroring of all data points without manually listing them.
Per-index configuration
- A more granular approach.
- You can specify a list of exact indices (tags) to poll within a class.
- DNP3 class polls still retrieve all values/events in the class, but the connector limits what the connector forwards to the cloud.
- Useful for optimizing bandwidth or focusing on a subset of values.

`logSettings`

Field	Type	Description
`logFilePath`	string	Path template for log files (the `%` is replaced with the device ID)
`logFileMaxMBSize`	number	Maximum size per log file in MB before rotation
`logFileMaxFiles`	number	Number of rotated files to keep
`logLevel`	string	Logging level (`trace`, `debug`, `info`, etc.)

`tagConfiguration` entries

Each entry describes either a DNP3 class or a set of specific indices.

Common fields

Field	Type	Description
`deviceModel`	string	Device model identifier
`classID`	number	DNP3 event class ID (0–3). This is the class priority group, not an address.
`triggerType`	string	Cloud publish policy: `changed` or `cyclic-N` (publish every N seconds).
`metaData`	object	Protocol-specific settings for the DNP3 connector (see below).
`metaData.cyclicPeriod`	number	Scan interval in seconds: how often the connector polls the DNP3 server for this class.

Note (important):

triggerType: “cyclic-N” controls how often values are sent to Nexalis Cloud (publish frequency).
metaData.cyclicPeriod controls how often the connector scans/polls the DNP3 outstation for updates in that class (read/scan frequency).
These two can be different: you may poll frequently (low cyclicPeriod) but publish less frequently (cyclic-N), or publish frequently while polling less often (not recommended if you expect fast-changing signals).

Optional per-index field

Field	Type	Description
`dataPoints`	string[]	List of specific data points to send to Nexalis Cloud (e.g. `"Binary/1"`, `"Analog/3"`)

Important notes about `classID` vs data point address / index

classID is the event class (priority group), not a data point address.
A data point address/index is represented in the data point key (e.g., Binary/2 = Binary type at address 2).
Multiple addresses / indexes can be published in any class (1/2/3).
A single address / index can be published in multiple classes; it is still the same data point / index (same type + address), but appears in different event classes (different priority).

`tagDescriptions`

tagDescriptions is an optional object that lets you configure human-readable descriptions for data points. It also acts as a forwarding allow-list when present:

If tagDescriptions is not provided: the connector forwards data according to tagConfiguration and (optionally) dataPoints. The description field will remain default/empty unless provided elsewhere.
If tagDescriptions is provided: the connector forwards only data points that match an entry in tagDescriptions.

Format

"tagDescriptions": {
  "<key>": "<description string>"
}

Supported keys

You can define descriptions at two different granularities:

Full data point key (type + address)
- Format: "<Type>/<Address>"
- Examples: "Binary/2", "Analog/2", "Binary/4257"
Address-only key
- Format: "<Address>"
- Example: "2"
- Applies to any type at that address (e.g., Binary/2, Analog/2, etc.)

Matching / precedence

When a data point is forwarded, the connector resolves its description as follows:

If an exact match exists for <Type>/<Address> (e.g., Binary/2) → use it.
Else if a match exists for <Address> (e.g., 2) → use it.
Else:
- If tagDescriptions is present → the data point is not forwarded (allow-list behavior).
- If tagDescriptions is absent → the data point may still be forwarded (depending on tagConfiguration), but without a configured description.

Example 1: Class-based configuration

{
    "logSettings": {
        "logFilePath": "./log_files/test_dnp3_log_file.log",
        "logFileMaxMBSize": 1,
        "logFileMaxFiles": 3,
        "logLevel": "debug"
    },
    "tagConfiguration": [
        {
            "deviceModel": "dnp3_model",
            "classID": 0,
            "triggerType": "cyclic-1000",
            "metaData": {
            "cyclicPeriod": 1
            }
        },
        {
            "deviceModel": "dnp3_model",
            "classID": 1,
            "triggerType": "changed",
            "metaData": {
            "cyclicPeriod": 1
            }
        },
        {
            "deviceModel": "dnp3_model",
            "classID": 2,
            "triggerType": "cyclic-5",
            "metaData": {
            "cyclicPeriod": 1
            }
        },
        {
            "deviceModel": "DNP3 device model",
            "classID": 3,
            "triggerType": "cyclic-5",
            "metaData": {
            "cyclicPeriod": 1
            }
        }
    ]
}

Example 2: Per-index configuration (forward only a subset)

{
    "logSettings": {
        "logFilePath": "./log_files/test_dnp3_log_file.log",
        "logFileMaxMBSize": 1,
        "logFileMaxFiles": 3,
        "logLevel": "debug"
    },
    "tagConfiguration": [
        {
            "deviceModel": "dnp3_model",
            "classID": 1,
            "triggerType": "changed",
            "metaData": {
                "cyclicPeriod": 2
            },
            "dataPoints": [
                "Binary/1",
                "Analog/1",
                "DoubleBitBinary/1",
                "Binary/4",
                "Analog/4",
                "DoubleBitBinary/4"
            ]
        },
        {
            "deviceModel": "dnp3_model",
            "classID": 2,
            "triggerType": "changed",
            "metaData": {
                "cyclicPeriod": 4
            },
            "dataPoints": [
                "Binary/2",
                "Analog/2",
                "DoubleBitBinary/2",
                "Binary/5",
                "Analog/5",
                "DoubleBitBinary/5"
            ]
        },
        {
            "deviceModel": "dnp3_model",
            "classID": 3,
            "triggerType": "changed",
            "metaData": {
                "cyclicPeriod": 6
            },
            "dataPoints": [
                "Binary/3",
                "Analog/3",
                "DoubleBitBinary/3",
                "Binary/6",
                "Analog/6",
                "DoubleBitBinary/6"
            ]
        }
    ]
}

Example 3: Configure `tagDescriptions` (descriptions + allow-list)

This example:

defines three class configurations (1/2/3),
and forwards only data points that match tagDescriptions,
with description resolution by datapoint-first, then address-only.

{
  "tagConfiguration": [
    {
      "deviceModel": "DNP3 device model",
      "classID": 1,
      "triggerType": "changed",
      "metaData": { "cyclicPeriod": 1 }
    },
    {
      "deviceModel": "DNP3 device model",
      "classID": 2,
      "triggerType": "changed",
      "metaData": { "cyclicPeriod": 1 }
    },
    {
      "deviceModel": "DNP3 device model",
      "classID": 3,
      "triggerType": "changed",
      "metaData": { "cyclicPeriod": 1 }
    }
  ],
  "tagDescriptions": {
    "Binary/2": "Description of Binary/2, e.g., alarm",
    "2": "Description of index 2, e.g., meter active power",
    "Analog/3": "Description of Analog/3, e.g., meter reactive power"
  }
}

3. Message format sent to Nexalis Cloud

{
    "dataPoint": "Analog/0",
    "description": "DNP3 data point",
    "deviceID": "test device",
    "deviceModel": "DNP3 device model",
    "metaData": {
        "class": 0,
        "nx-agent-id": "fb9cf8e6-xxxx-xxxx-xxxx-be2aea9631d8",
        "registerType": "Analog",
        "type": "double"
    },
    "protocol": "DNP3",
    "qualitySource": "RESTART",
    "siteName": "test site",
    "triggerType": "changed",
    "tsConnector": 1754003248853,
    "tsSource": 0,
    "unit": null,
    "value": 0.0
}

4. Running the Connector

The DNP3 connector is launched automatically by the Nexalis Agent.
For debugging only, it can be started manually:

./dnp3_connector --siteName SITE_1 --deviceID 100 --communicationAddress 127.0.0.1:502 --deviceModel /path/to/device_config/dnp3_model.json

Default gRPC forwarding: localhost:50051
Use --grpcAddress to override.

5. Supported DNP3 Data Types

DataPoint Prefix	Description	Data Type in Cloud
Binary	Binary input (status)	bool
DoubleBitBinary	Double-bit input	uint8_t
Analog	Analog input	double
Counter	Counter input	uint32_t
FrozenCounter	Snapshot counter	uint32_t
BinaryOutputStatus	Status of binary output	bool
AnalogOutputStatus	Status of analog output	double
TimeAndInterval	Timestamped interval values	TimeAndInterval
OctetString	Binary/string data	string
DNPTime	DNP3 time value	DNPTime

6. DNP3 General Information

The DNP3 protocol does not support reading individual object indices for reading specific data points. Instead, it uses polling or scanning methods that discovers and reads multiple object indices grouped by class.

Classes

Class 0 Integrity Poll: Purpose: Retrieves all current values data points at the outstation. Usage: Typically performed at startup or at cyclic periods to get a complete snapshot of the current state of all data points.
Class 1 Poll: Purpose: Retrieves a list of all changes in data from the last poll. Usage: Used to monitor and retrieve updates for high-priority data points.
Class 2 Poll: Purpose: Retrieves a list of all changes in data from the last poll. Usage: Used to monitor and retrieve updates for medium-priority data points.
Class 3 Poll: Purpose: Retrieves a list of all changes in data from the last poll. Usage: Used to monitor and retrieve updates for low-priority data points.

Recommendation: By using a combination of an initial Integrity Poll (i.e., Class 0) and periodic Class 1-3 polls, the Nexalis DNP3 connector ensures comprehensive monitoring and efficient real-time data updating in Nexalis Cloud.

DNP3 Object Variations

In DNP3, each object type (such as Binary, Analog, or Counter) can be represented in different variations.
A variation defines the format and level of detail used when encoding and transmitting data from the outstation (DNP3 server) to the master.

Binary Inputs
- Packed format: multiple inputs encoded in a single byte (bit-packed).
- With flags: includes additional status flags such as online/offline or communication quality.
Analog Inputs
- 16-bit integer values.
- 32-bit integer values.
- 16-bit with status flags.
- 32-bit with status flags.
Counters
- 16-bit counter values.
- 32-bit counter values.
- 16-bit counters with status flags.
- 32-bit counters with status flags.

Important Notes

Variations are configured on the DNP3 outstation (server side), not in the Nexalis DNP3 connector.
The connector does not select or override variations; it polls classes and mirrors the data exactly as provided by the outstation.
This means the same type of data (e.g., an analog input) may arrive with different precision or with/without flags, depending on the device configuration.
The Nexalis connector’s role is to interpret the incoming format correctly and forward it in JSON, preserving the raw information without transformation.

Overview

Nexalis Cloud

Nexalis Agent

​1. Introduction

​Key Features

​2. Configuration

​logSettings

​tagConfiguration entries

​Common fields

​Optional per-index field

​Important notes about classID vs data point address / index

​tagDescriptions

​Format

​Supported keys

​Matching / precedence

​Example 1: Class-based configuration

​Example 2: Per-index configuration (forward only a subset)

​Example 3: Configure tagDescriptions (descriptions + allow-list)

​3. Message format sent to Nexalis Cloud

​4. Running the Connector

​5. Supported DNP3 Data Types

​6. DNP3 General Information

​Classes

​DNP3 Object Variations

​Important Notes