Skip to content
Version 2026.25

Devices and drivers ​

Every device Nexus talks to is one entry under deviceConnections in the configuration file, and one card under Devices in the configuration interface. The entry carries the connection settings and nothing else — which registers it reads comes from the tags bound to it, not from a list on the device.

To have Nexus look for EtherNet/IP, BACnet/IP and Modbus TCP devices on its networks and add the ones you pick, see Finding devices.

What Nexus can talk to ​

driverTalks to
opc-uaAny conformant OPC UA server. The default when driver is absent.
ab-eipAllen-Bradley over EtherNet/IP — ControlLogix, CompactLogix 5370 and later.
siemens-s7Siemens S7 — see plcType below for the family.
modbus-tcpModbus over TCP.
modbus-rtuModbus over a serial line.
clickAutomationDirect CLICK and CLICK PLUS over TCP.
click-rtuThe same, over a serial line.
omron-finsOmron FINS over TCP.
omron-fins-udpOmron FINS over UDP.
dnp3DNP3 outstations.
bacnet-ipBACnet/IP building plant and HVAC.

Nexus is also an OPC UA server, which is a separate thing from the opc-ua driver: the driver connects out to someone else's server, while the server lets another system connect in to Nexus.

Settings every device has ​

json
{
  "deviceConnections": [
    {
      "name": "PLC150",
      "driver": "modbus-tcp",
      "endpoint": "192.168.1.50",
      "port": 502,
      "enabled": true,
      "pollRateMs": 1000,
      "timeoutMs": 2000,
      "reconnectDelayMs": 3000
    }
  ]
}

name is what tags refer to. Changing it after tags are bound to the device breaks those bindings, so rename in the configuration interface rather than by hand in the file.

pollRateMs is the fallback rate. A tag whose tag group sets a rate is scanned at the group's rate instead — see Tag groups below.

There is no address list on a device

Earlier development builds carried addresses[] and subscribeAll on the device. Both are gone. A device polls exactly the tags bound to it, so adding a tag in Studio starts it scanning without editing the device or restarting Nexus.

Allen-Bradley ​

json
{
  "driver": "ab-eip",
  "gateway": "192.168.1.10",
  "path": "1,0",
  "plcType": "ControlLogix"
}

gateway is the controller's address and path is the CIP route to the processor — commonly 1,0 for a slot-0 processor in a single-rack chassis. slot is accepted as the simpler form of the same idea.

Only the Logix family (controllogix, compactlogix) takes a path. A Micro800 (plcType micro800) is addressed directly and takes none: Nexus sends no path for it, even if the device entry still holds an old 1,0, and the form disables the field. MicroLogix, SLC 500 and PLC-5 controllers take a path only when reached through a DH+ bridge; otherwise leave it out.

maxConcurrentReads (1 to 1000, default 200) is the most reads Nexus keeps in flight at once on the connection during a poll. Lower it for a controller that struggles when many reads arrive together. Changing it, or the PLC type or path, applies to the running device without restarting Nexus.

Siemens S7 ​

plcType selects the family: s7-300, s7-400, s7-1200 or s7-1500. rack and slot locate the processor; a 1200 or 1500 is normally rack 0, slot 1, while a 300 or 400 depends on how the chassis is populated. pduSize caps the negotiated PDU if the processor needs it held down.

Modbus, and CLICK ​

Modbus registers are 16 bits, so anything wider — a 32-bit integer, a float — spans two of them, and the two ends have to agree on the order.

SettingMeaning
wordOrderbig or little — which 16-bit word comes first.
byteOrderbig or little — byte order inside each word.
unitIdModbus unit/slave id.

The two are independent, which is what gives the four orderings a Modbus device might use. If a float reads as a wild number but its bytes look familiar, this is the setting to change.

CLICK addressing ​

CLICK is Modbus underneath, so click is the modbus-tcp driver with the CLICK address book on top: tags are addressed in CLICK notation — DS100, DF30, Y002, C15 — and Nexus translates them.

  • The dialect is per device, not per address.
  • wordOrder defaults to little for CLICK, which is what the PLC expects.
  • X, T and CT are read-only. Nexus refuses a write rather than silently dropping it.
  • TXT (the half-register string packing) is refused, not approximated — a partial implementation would corrupt text rather than fail visibly.

DNP3 ​

outstationAddress and masterAddress are the DNP3 link addresses. eventPollEveryNCycles controls how often an event poll is issued relative to ordinary integrity polls, and maxObjectsPerRequest caps request size for outstations that dislike large ones.

DNP3 outstations can supply their own sequence-of-events timestamps. Where one does, Nexus records that timestamp as the source time rather than the moment it received the value.

Omron FINS ​

localNode and remoteNode are the FINS node numbers for Nexus and the PLC. Use omron-fins over TCP where the network is reliable, and omron-fins-udp where the PLC or the intervening network expects UDP.

Tag groups and scan rates ​

A device does not have one rate. Each tag belongs to a tag group, and the group sets how often that tag is scanned:

ModeScanned
directAt a fixed rateMs.
leasedQuickly while something is watching that tag; slowly otherwise.
drivenQuickly while an expression is true.

A fresh gateway ships with default-fast (250 ms), default-slow (5000 ms) and default-historical (10 s). A tag naming no group falls back to a built-in default.

staleMultiplier decides when a tag with no fresh reading is marked Stale: the tag goes stale after rateMs × staleMultiplier without an update, and returns to Good as soon as it is being read again.

Choose a rate the link can actually keep up with

A scan class faster than the device can answer does not make data arrive sooner; it makes the poll fall behind. If tags flicker to Stale under load, the rate is too low for the number of tags on that device, not the other way round.

When a device drops ​

A device that stops answering is marked disconnected, and its tags follow the quality rules above rather than freezing at their last value as though nothing happened. Writes that were forwarded to a device that has since dropped are not silently discarded — see Troubleshooting for reading the device card and the log together.

Comms status as tags ​

Every device connection also publishes its comms state as read-only tags, so a screen can show it and an alarm can fire on it. They sit in the [SYSTEM] provider under Devices/<device name>/ and appear in the tag browser like the other [SYSTEM] tags:

TagTypeMeaning
[SYSTEM]Devices/<name>/ConnectedBooleantrue while the link is up and the last scan returned usable data. A device that accepts the connection but never answers (a dead radio link) reads false.
[SYSTEM]Devices/<name>/LastGoodTimeLongTime of the last good comms, in milliseconds since the Unix epoch (UTC). 0 until the device first connects. It stops moving when comms drop.
[SYSTEM]Devices/<name>/StateStringconnected, disconnected, disabled (configured with enabled: false) or invalid (could not be built, for example an unknown driver).
[SYSTEM]Devices/<name>/LastErrorStringWhy comms are down; empty while connected.

The tags follow the device list live, with no gateway restart. A device you add gets its tags within about a second, a renamed device moves to its new name, and a removed device reads disconnected and its tags are deleted after about three seconds (a short grace so that editing a device, which removes and re-adds it, does not delete and recreate its tags). A disabled or invalid device keeps its tags and reads Connected = false.

How fast a drop shows. For a polled driver (Modbus, CLICK, EtherNet/IP, S7 and the other poll-based drivers) Connected goes false when a scan returns no usable data, so a silent link is caught even while the TCP connection is still open. The worst case at the default settings is about 4 seconds: up to one 1 second poll, the 2 second read timeout, and up to 1 second for the status tags to refresh. Measured on a silent Modbus TCP link: 4.0 seconds.

Things that limit this:

  • A device with no tags bound to it has nothing to read, so a silent link is not noticed; Connected then follows the socket alone.
  • A device whose tags are all in slow tag groups is only checked at that group's rate, so a drop takes that long, plus the timeout, to show.
  • OPC-UA devices are not scanned this way. They report the state of their session only, not whether data is arriving.

LastError repeats the connection error text, so anyone who can read [SYSTEM] tags (including an anonymous kiosk where reads are open) can see it. It carries endpoints and error codes, never credentials.

A device name is used as one tag-path segment, so ., /, [, ] and \ in it become _ (a device named Pump 1.2 publishes under Pump 1_2). Two names that map to the same segment cannot both publish; the second is skipped and the log says so.