CMMS Protocol Adapters

CMMS protocol adapters connect field systems and equipment signals to FactVerse maintenance workflows. Use this page when a CMMS or facility operations deployment needs to read mapped points from BACnet, Modbus, or SNMP devices and use those values in asset context, work-order triage, predictive maintenance, or evidence review.

Protocol adapters should be planned with the site controls owner. A point mapping needs a stable point ID, address, data type, unit, read-only setting, and owner-approved write policy before it is used in operations.

Prerequisites

• Equipment and location records are available in CMMS Operations or Facility Operations.
• The site controls owner has approved the protocol, device address range, network path, and read frequency.
• Each mapped point has a stable point ID, data type, unit, and business meaning.
• Writable points are reviewed separately and remain disabled unless the customer operating policy approves them.
• DFS or AI Agent consumers know whether they need current values, historical time series, or both.

Adapter workflow

Supported protocol families

Protocol	Typical use	Read behavior	Write behavior
BACnet/IP	Building automation systems, AHU, chiller, fan, pump, and controller points.	Reads configured BACnet object present-value values and can discover devices when configured points are absent.	Writes present-value only for mapped points marked writable.
Modbus TCP	PLCs, meters, chillers, panels, and industrial controllers.	Reads configured coils, discrete inputs, input registers, and holding registers.	Writes writable coils and holding registers through the configured function code path.
RTU-over-TCP	Sites that tunnel Modbus RTU frames over TCP.	Uses the configured unit ID and point mapping.	Uses RTU framing with CRC over the TCP connection.
SNMP	UPS, networked power devices, environmental monitors, and managed infrastructure.	Uses GET for mapped OIDs and discovery walk when a root OID is configured.	Uses SET only for writable mapped OIDs with an approved syntax.

BACnet mapping

BACnet connections use BACnet/IP. A connection can set timeout, local UDP port, and optional BBMD foreign-device registration. When the mapping includes points, discovery returns those configured points. When points are not configured, discovery can send Who-Is and return discovered device entries.

Map each point with one of these object families:

Object family	Examples
Analog	analog-input, analog-output, analog-value
Binary	binary-input, binary-output, binary-value
Multi-state	multi-state-input, multi-state-output, multi-state-value
Device	Device records used for discovery metadata

Example mapping:

{
  "timeoutMs": 5000,
  "localPort": 0,
  "bbmdHost": "10.10.0.20",
  "bbmdPort": 47808,
  "foreignDeviceTtlSeconds": 300,
  "points": [
    {
      "pointId": "ahu-supply-temp",
      "address": "analog-input,0",
      "dataType": "FLOAT",
      "readOnly": true,
      "unit": "C"
    },
    {
      "pointId": "fan-enable",
      "objectType": "binary-value",
      "instance": 1,
      "dataType": "BOOLEAN",
      "readOnly": false
    }
  ]
}

Modbus mapping

Modbus connections use explicit point mappings. The adapter reads configured points and avoids scanning arbitrary device ranges. Use this path when register addresses, unit IDs, scaling, and units are agreed with the site controls owner.

Point type	Read support	Write support
Coil	Function code 01	Function code 05
Discrete input	Function code 02	Read only
Holding register	Function code 03	Function code 06 or 16
Input register	Function code 04	Read only

Example mapping:

{
  "transport": "tcp",
  "unitId": 1,
  "timeoutMs": 3000,
  "poolSize": 2,
  "points": [
    {
      "pointId": "chiller-discharge-pressure",
      "type": "holding-register",
      "register": 40001,
      "dataType": "INT",
      "scale": 0.1,
      "offset": 0,
      "readOnly": false,
      "unit": "bar"
    },
    {
      "pointId": "compressor-run",
      "address": "coil,5",
      "dataType": "BOOLEAN",
      "readOnly": false
    }
  ]
}

For 32-bit floating point registers, set dataType to FLOAT, set quantity to 2, and record wordOrder or byteOrder when the device uses a specific endian format.

SNMP mapping

SNMP connections support v1, v2c, and v3 targets. Use v3 where the customer security standard requires authenticated and encrypted access. A trap listen port can be configured when the deployment needs to receive trap messages.

Example mapping:

{
  "version": "v3",
  "securityName": "operator",
  "authProtocol": "SHA",
  "authPassphrase": "auth-secret",
  "privacyProtocol": "AES128",
  "privacyPassphrase": "priv-secret",
  "timeoutMs": 3000,
  "retries": 1,
  "discoveryRootOid": "1.3.6.1.2.1.33",
  "trapListenPort": 0,
  "points": [
    {
      "pointId": "ups-battery-charge",
      "oid": "1.3.6.1.2.1.33.1.2.4.0",
      "dataType": "INT",
      "unit": "%",
      "readOnly": true,
      "syntax": "integer"
    }
  ]
}

Supported SET syntax values include integer, gauge, counter, oid, ipAddress, and octetString.

Write governance

Writable protocol points need an explicit operating decision. Before enabling writes, confirm:

• the mapped point is safe to change through a CMMS or operations workflow;
• the point owner has approved the write boundary;
• the role or service account has the required write scope;
• the workflow records requestor, target point, value, reason, time, and result;
• rollback or manual correction is understood by the site owner;
• field teams know which system is authoritative for the point.

Read-only deployments can still use protocol values for dashboards, work-order triage, evidence review, and predictive maintenance inputs.

Validation checklist

• Each point has a stable pointId, source address, data type, unit, and read-only flag.
• Sample reads return expected values with correct units and scaling.
• Discovery output matches the approved device or point scope.
• Writable points have owner approval and a review workflow.
• Failed reads, timeouts, and rejected writes are visible to operators.
• Protocol credentials and community strings follow the customer's secret-management policy.
• CMMS work orders and asset context reference the same equipment identity used by DFS and MDM.

Troubleshooting

Symptom	Check
Connection times out	Host route, firewall, port, local BACnet port, SNMP target, Modbus unit ID, and timeout settings.
Point cannot be read	Address format, object type, register type, OID, data type, and device permissions.
Value has wrong scale	Modbus scale or offset, register quantity, word order, byte order, and unit mapping.
Discovery returns too much data	Add an explicit point list or narrow the SNMP discovery root.
Write is rejected	readOnly flag, writable object type, permission scope, review policy, and device-side access control.
SNMP v3 fails	Security name, auth protocol, auth passphrase, privacy protocol, privacy passphrase, and engine compatibility.

Related docs

• CMMS Operations
• Connect CMMS and EAM Data to FactVerse
• CMMS Permissions and Service Accounts
• Facility Operations Operational Data Readiness
• DFS Lite Connector Configuration