/
Modbus Troubleshooting

Modbus Troubleshooting

Modbus Troubleshooting

Below are some common Modbus related issues reported by customers. We recommend reviewing the following items, as they may help identify and resolve existing problems.

Tuning policies

Tuning policies are used to optimize system and network performance by controlling how resources are allocated and utilized. They help ensure efficient CPU and memory usage, reduce latency, and improve overall throughput.

Library-level tuning tags

connTuningRef (ref): Fallback for point tuning.

The connTuningRef tag defines the tuning configuration used for a point when a point-specific tuning policy is not available.

The system searches for this tag in the following order of precedence:

  1. Point record – Check the point itself for a connTuningRef value.

  2. Point's connector record – If not found on the point, check its associated connector.

  3. Connector's extension record – If still not found, check the connector's extension record.

  4. Default connector-type tuning – As a final fallback, use the default tuning policy defined for that connector type.

This hierarchical lookup ensures that the most specific tuning configuration is applied whenever available, while providing reliable fallback behavior when no explicit tuning reference is defined.

maxThreads (number): Defines the maximum size of the shared thread pool used by a connector library. Since connectors run as actors on this thread pool, the setting determines how many connectors of the same type can process work concurrently.

  • Default value: 100

  • Location: Configured on the connector library's extension (ext) record (for example, modbusExt).

  • If the number of connectors exceeds the thread pool size, some connectors may experience delays while waiting for available threads.

  • Increasing maxThreads can improve concurrency in large deployments, but higher values may also increase CPU and memory usage due to thread overhead.

Tune this value to balance connector responsiveness with overall system resource consumption.

Connector-level tuning tags

Connector-level tuning tags are configured on the connTuning record associated with a connector.

actorTimeout (duration): Sets message timeout for synchronous communication.

connLinger (duration): Keeps connections open for a period before closing.

connOpenRetryFreq (duration): Defines retry interval for failed connections.

connPingFreq (duration): Forces periodic pings to maintain connection status.

Point-level tuning

Point-level tuning tags are configured on the connTuning record associated with a point.

pollTime (duration): Defines polling frequency.

staleTime (duration): Marks data as stale if not updated.

writeMinTime & writeMaxTime (duration): Control write frequency and rewrites.

  • writeMinTime (duration): used to throttle writes

  • writeMaxTime (duration): periodically issue rewrites

writeOnOpen & writeOnStart (marker): Configure automatic writes during connector/system startup.

Connector details

Example of connector Debug Info. Useful for capturing connector details and error information to aid in troubleshooting and issue diagnosis.

id: p:test:r:2f3ccdb8-2222f64a
dis: Test
status: ok
pollingMode: buckets (disabled, manual, buckets)
connPollFreq: null
connLinger: 30sec
lingering: null
openPins [,] (usually watch)
actorTimeout: 1min
lastPing: 12min 55sec ago
lastConnOk: 12min 55sec ago
lastConnFail: never
lastPoll: 12min 23sec ago
pollFreq: null
points: 10
pointsInWatch: 0
curErr: null
pollBuckets:

currentMessage: none

Actor
pool: test-Modbus
state: idle
queue: 0 (peak 2)
received: 207631
ticks: 385ms (avg 0.001ms)

ActorPool
name: test-Modbus
maxThreads: 100
maxTime: 1sec
hasPending: false
pending: 0
idle: 17
workers: 17
test-Modbus-Worker-1280: idle
test-Modbus-Worker-1279: idle

Poll buckets for efficient polling

To optimize polling performance, group points into poll buckets and stagger poll intervals across those buckets. This distributes polling activity more evenly over time, rather than having all points poll simultaneously.

By spreading polling requests across multiple intervals, you can:

  • Reduce peak load on devices and networks.

  • Prevent communication bottlenecks.

  • Improve overall system responsiveness.

  • Minimize the risk of missed polls or delayed updates.

  • Achieve more balanced utilization of system resources.

A well-designed polling strategy helps ensure reliable data collection while avoiding unnecessary strain on connected devices and infrastructure.

Example tuning policies:

  • Conn Default Policy - 61 seconds

  • Sensors - 13 seconds

  • Commands - 23 seconds

  • Setpoints - 47 seconds

Best practices & implementation

  • Adjust maxThreads based on system requirements.

  • Fine-tune connLinger to minimize reconnection overhead.

  • Use pollBuckets for structured polling.

  • Modbus specific tuning tags: Modbus Connector

Debugging on site

Consider the following steps when investigating and troubleshooting issues on site. Following a systematic approach can help isolate the root cause, reduce downtime, and resolve issues more efficiently.

You can use both FIN's internal tools and external diagnostic tools to troubleshoot issues, validate system behavior, and identify root causes.

FIN tools

  • Connector details - Share connector details.

  • Tuning policies - Create and assign tuning policies.

  • Logging / Conn Tracing - Logging is available in versions prior to 5.2, while Connection Tracing is available in version 5.2 and later.

    • Set Modbus logging to Debug level and review the logs to gain detailed visibility into connector activity.

      • Run the following query in Folio > Launch to set Modbus logging to “debug”. Replace demo with your project name.
        logList().findAll(x => x->name=="modbus" and x.has("ext") and x->proj=="demo").toRecList().map(x => x->id.logSetLevel("debug"))

      • Run the following query to display Modbus related log entries for troubleshooting and diagnostics.
        logRead(toSpan(today)).findAll(x => x->name=="modbus")

      • Note: When service is restarted, the logging resets back to info.

    • Enable tracing on the modbus connector to provide debug details such as:

      • all dispatch actor messages

      • lifecycle transitions for open, ping, close

      • poll requests

      • connector specific debug for networking messages

  • Console - Run FIN from the command line and review the console output for errors and other diagnostic messages that may assist with troubleshooting. Run FIN through Cmd Prompt

External tools

External diagnostic tools can be used to independently test network connectivity, validate protocol communications, and verify device responsiveness. These tools are valuable for isolating issues and determining whether the root cause lies within the network, field device, or system configuration.