When You Need a Custom Niagara Driver (and When You Do Not)

How a Niagara Driver Is Actually Structured

A driver appears in the station as four nested things. A network component sits under the station's Drivers container and owns the transport: the connection itself, the poll scheduler, and the tuning policies. Under it sit device components, one per physical unit, each holding its own address, status and health record. Each device carries a Points extension, and under that sit the proxy points. Every proxy point has a proxy extension, and that extension is the only part that knows the device's address space: it holds the address, the read and write mode, and the fault cause when a read fails.

The split matters as soon as something breaks. Status propagates down the chain, so a network that cannot open its connection marks every device under it down, and each of those marks its own points down; the flag showing on the point looks the same whichever level caused it. Tuning policies are also defined once on the network and referenced by name from each proxy point, which means poll rate and stale time are properties of the policy a point points at rather than of the point.

• Network component: the connection, the poll scheduler with its fast, normal and slow rate buckets, the tuning policy map, and the monitor that decides a device has stopped answering.
• Device component: the address, whether that is an IP address and port or a MAC and unit ID; the status; and a health record carrying last success and last failure times plus the alarm raised when the device goes offline.
• A Points extension under each device, which is both the container for proxy points and the entry point for discovery. Other device extensions, such as alarm source configuration or schedule export, sit beside it rather than inside it.
• Proxy extension on each point: the address inside the device, the read and write mode, the conversion between the raw value and the Niagara value, and the fault cause string that a commissioning engineer will read first.
• Facets on the point: units, precision, enum range, and true and false text. Everything downstream reads facets, so a wrong enum range surfaces in every Px view, every alarm message and every report built later.
• Alarm and history extensions, added per point and independent of the proxy extension. A point can be reading correctly and logging nothing, because those are separate objects with separate configuration.

The Middle Tier Between a Shipped Driver and a New Module

There is a tier of work between a driver that ships with Niagara and a module written from scratch. Everything in it uses drivers and components already installed on the host, and the effort goes into configuration, addressing and naming rather than into Java.

The options below differ mainly in how much a person has to type, and in how many times that typing has to be repeated at the next site.

• Once you have addresses, data types, scaling and word order, proxy points cover a Modbus device with no code at all. Two things bite: register documentation is frequently 1-based while the wire is 0-based, and a 32-bit value spans two registers in a word order vendors do not agree on.
• A BACnet device that answers Who-Is on UDP 47808 can be discovered and learned in with the stock driver. The obstacles that remain are not protocol work: MS/TP MAC and network numbering, duplicate device instance numbers, and a device on another subnet that cannot hear the broadcast without BBMD or foreign device registration.
• A generic driver that matches the transport rather than the manufacturer: SNMP for anything that publishes MIB objects, oBIX or OPC UA where the device already exposes one, or a database driver where the data lands in a table the device writes to. The vendor name does not have to appear anywhere for the integration to work.
• One-off arithmetic or scheduling that will only ever run in this one station can be assembled on a wiresheet from stock control and schedule components. It becomes module work when the same behavior has to ship as a reusable, brandable, signed component across stations.
• A program object for a simple text protocol over TCP or serial, where the source lives with the component in the station rather than in a jar to version and install. The cost is that it is invisible to the Point Manager: points are created and named by hand, and there is no learn pane waiting at the next site.
• The dividing line is repetition rather than difficulty. A map configured once for one building usually stays in this tier, while the same map re-entered at every site is where a module that discovers its own points frequently earns the work.

What the Work Needs From the Device Before Code Starts

Protocol work is bounded by what the device will tell you about itself, and that is a documentation problem before it is a coding one. A specification detailed enough to implement against gives frame layout, function or command codes, byte order, timing constraints and error responses. A datasheet listing supported protocols is not that document, and asking for the revision date of the document is a fast way to learn whether it describes what the firmware in the field actually does.

Firmware is the part that surprises people later. Vendors change register maps, add points and adjust scaling between minor revisions, and a site rarely runs one revision across its whole population. The unit on the bench is one data point; the set of models and revisions actually installed is the requirement.

• Link parameters: baud rate, parity, stop bits and unit ID for serial; IP address, port and any authentication for TCP.
• Session limits. Many serial devices and some TCP devices accept exactly one master or client at a time, so a vendor tool or an existing panel already on that link is a design constraint rather than a detail to sort out during commissioning.
• Write rules: which addresses accept writes, whether a write survives a power cycle, whether writing requires a mode change or handshake first, and what a partially applied write leaves behind.
• Timing: the minimum gap between frames, the poll rate at which the device begins dropping responses, the response timeout, and how long the device stays unresponsive after a write or a reboot.
• Failure behavior. When the device loses its own upstream link or a sensor, does it return the last value, a zero, or an error? Those are three different things to model, and only one of them is safe to show as live data.

Failure Modes That Appear After the Bench Test Passes

A device on a bench meets none of the conditions that break drivers in a building: forty devices sharing one segment, a network that drops packets rather than refusing them, controllers that reboot on a schedule nobody wrote down, and a station that is also running histories, alarms and several other networks on the same processor.

What makes these hard is that they look alike in the point list. Almost everything presents as points that are stale, in fault, or quietly wrong, so the useful knowledge is the diagnostic that separates one cause from another. Most of those diagnostics are comparisons rather than measurements: this device against its neighbors, the network's status against the point's status, the value against the same value read by the vendor's own tool.

• Points stale with no errors: the poll cycle is longer than the tuning policy tolerates. Compare the poll scheduler's measured cycle time against the stale time in the policy. The usual causes are too many points sitting in the fast rate bucket and a link that cannot carry them, which arrives early on RS-485 at 9600 baud.
• One device down while its neighbors are fine: addressing or the device, not the driver. Read its health record for the last successful response, then check whether another master or a laptop running the vendor tool is holding the only session the device allows.
• A whole network down after months of working: something shared changed. The network component's fault cause describes the transport, while a device's fault cause describes the conversation, so read the network first and only then the device.
• Values consistently wrong by a factor or byte-swapped: scaling or word order, not protocol. A 32-bit float reading as an absurd magnitude is word order; a value off by exactly ten or a hundred is a scale factor in the register map.
• Writes accepted and then reverting: either the register is volatile, or something else is writing the same value back. Re-read after the device's own update cycle rather than immediately, and check whether a local panel or HMI owns that point.
• Slow growth in memory or thread count over days: reconnection logic that opens a new socket per retry, or a queue that grows while a device is unreachable. It only appears if a device is left offline for hours, which is exactly what a bench test does not do.

Signing, Licensing and Version Targets Are Operational Facts

Three separate mechanisms decide whether a module that compiled cleanly will run on a customer's host, and they fail in different places with different symptoms. Signing is checked when the module loads: the jar's signature has to chain to a certificate the host trusts, and code-signing certificates expire, so who holds the signing key and what happens at renewal are questions worth settling at the start rather than at the next release. Licensing is checked separately. A licensed module needs a feature entry in the license file on that host, keyed to the host ID, and a module that runs on a developer's bench and refuses on a controller is often a missing license line rather than a code fault.

Installation is the third. Modules are pushed to a host over a platform connection using the Software Manager, not by copying a file into a station folder, and the station has to be restarted before a new or changed module is loaded. Module dependencies are declared with vendor versions and checked at load time, so a driver can fail to start because something it depends on is a version behind. An upgrade is therefore a defined piece of work with named steps.

• Rebuild against the target version and confirm every declared dependency resolves at the vendor version actually present on the host.
• Confirm the signing chain is still trusted by the target platform and that the certificate has not expired since the last release went out.
• Confirm the license on that specific host carries the feature entry. Licenses are tied to a host ID, so a replaced controller is a new license question even though nothing about the module changed.
• Install through the Software Manager and restart the station. A module sitting in the modules directory that never loaded leaves its evidence in the platform log, not in the station log where engineers usually look first.
• Treat a learn table captured under the previous version as documentation, not as evidence for the new one.
• Check the Supervisor and its subordinate controllers separately. A mixed system can be running more than one Niagara version at a time, and each host needs the build that matches it.