Modbus TCP collector

The purpose of this article is to be a reference for Modbus collector part of the full Data Collection Module documentation
Prerequisite: A Starter package (SiteManager + accounts)  A Modbus slave capable device	Other sections in DCM: Getting started Guides Examples Frequently asked questions Troubleshooting

The Collectors (array of objects, mandatory ) list elements contains the following fields:

Function	Type	Importance	Description
CollectorName	string	mandatory	Unique name (within this confguration file) of a device to collect data from. (This is the name used in the agent configuration). Follows the normal rules for names.
CollectorDesription	string	optional	Description of this collector. For your use, no system function)
CollectorIPAddr	string	optional	Default IP address (or DNS name) for the device to be polled. The agent Target IP address will take precedence over this.
CollectorPortno	integer > 0 and < 65535	optional	Default port number for the device to be polled. The agent Target Port number will take precedence over this. If neither CollectorPortno , nor agent Target Port Number is specified, the appropriate port will be used, depending on the Protocol parameter value.
Alias	string	optional	This is the CollectorName of another collector, from which, all the parameters (expect CollectorName , CollectorDescription , CollectorIPAddr and CollectorPortno ) are copied from. An alias cannot refer to another alias.
Protocol	string-enum	mandatory	The protocol used to collected data. Currently 3 possible values exists: "OPC-UA/TCP", "Modbus/TCP", "Http/GET" and "Simulator".
ConnectRetryMin	integer > 0	mandatory	Minimum number of seconds before trying to reestablish a connection to the device being sampled. An exponential backoff algorithm is used to retry connection establishment, starting after ConnectRetryMin and increasing to ConnectRetryMax.
ConnectRetryMax	integer > 0	mandatory	Maxumin number of seconds before trying to reestablish a connection to the device being sampled.
ModbusAccess	Object	optional	collection of parameters needed to access a given Modbus server.
SamplePoints	Array of objects	mandatory	List of samples to be collected, possibly aggregated and stored in the Store'n'Forward database.

Example of OPCUAaccess object

{
"CollectorName": "ModbusGOT",
"CollectorDescription": "My first modbus",
"Protocol": "ModBus/TCP",
"ConnectRetryMin": 2,
"ConnectRetryMax": 240,
"ModbusAccess": {

ModbusAccess

The ModbusAccess objects contains the following elements:

Function	Type	Importance	Description
ModbusFCs	Array of objects	mandatory	List of modbus functioncode (FCs) to be performed during collection of data if the Protocol is "Modbus/TCP".
ModbusTimeout	integer > 0	optional	Timeout (in millisecs) for all modbus FC requests. If not present, the value 500 is used.
ModbusRegswap	boolean	optional	If true, the 16bit register values retrieved will be byteswapped before being used. If not specified the value is false. 0x12345678 > 0x34127856

ModbusFCs

The ModbusFCs objects contains the following elements:

Function	Type	Importance	Description
ModbusFCID	integer >= 0	mandatory	is a unique ID (within this Collectors element) for this entry. (Used by the SamplePoints entries.
ModbusFCSlaveAddress	(integer >= 0 and <= 247 or 255	optional	The Modbus Slave Address for this access. Note that this is only used in Modbus gateway devices (and should be between 0 and 247), whereas true Modbus endpoint devices should use the value 255. If this not present, the value 255 is used.
ModbusFC	string-enum	mandatory	is the type of Modbus function code used collecting data. Possible values are: "coils" (FC 1) "inputs" (FC 2) "holding-registers" (FC 3) "input-registers" (FC 4)
ModbusFCStart	integer >= 0	mandatory	Start address on the Modbus for this access.
ModbusFCCount	integer >= 0	mandatory	Number of units (bits or registers) to read in one access.
ModbusFCSampleInterval	integer >= 0	mandatory	Number of seconds between each collection of data using this FC. If the interval is 0, only event-driven polling is used.
ModbusFCTimeout	integer > 0	optional	Timeout (in millisecond) for this Modbus FC requests. If not present, the value is that of ModbusTimeout referenced by the ModbusFCID.
ModbusFCRegswap	boolean	optional	If true, the 16bit register values retrieved will be byte-swapped before being used. If not specified the value is that of the ModbusRegswap referenced by the ModbusFCID.

Samplepoint items

The SamplePoints objects contains the following elements:

Function	Type	Importance	Description
SampleName	string	mandatory	Name of this sampled value (sometimes called a tagname). Follows the normal rules for names.
SampleDescription	string	optional	is a text description of this sample value.
SampleUnit	string	optional	is a description of the unit of messurement for this sample.
SampleGroup	string	optional	designates (in some datasrvs) that all samplepoints in that group should be handled (displayed) together. The DCM system itself places no meaning on this group affiliation.
SamplesSaved	integer > 0	mandatory	is the number of values collected that is saved as minimum in the Store'n'Forward database. If set to 0 the Samplepoint isn't stored in the S'n'F database and thus not delivered to cloud, but can be used for aggregations.
OnlySaveOnChanged	bool	optional	control if new sample values should only be saved to the store-and-forward database if the values have changed since last sample. If not set, it is false.
SampleDataType	string-enum	mandatory	The type of data collected. The possible values are: "bool" (1 bit), "sbyte" (8 bit signed), "byte" (8 bit unsigned), "int16" (16 bit signed), "uint16" (16 bit unsigned), "int32" (32 signed), "uint32" (32 bit unsigned), "int64" (64 bit signed), "uint64" (64 bit unsigned), "float" (32 bit), "double" (64 bit), "string" (variable text up to 24575 bytes. Includes terminating NUL), "data" (variable variable data up to 24575 bytes).
SampleLowerLimit	integer/double	optional	The lower limit for the collected data. If the collected data value is less than SampleLowerLimit it is evaluated inaccordance to SampleLimitDiscard and SampleLimitAlarm.
SampleUpperLimit	integer/double	optional	The upper limit for the collected data. If the collected data value is more than SampleUpperLimit it is evaluated inaccordance to SampleLimitDiscard and SampleLimitAlarm.
SampleLimitDiscard	bool	maybe-optional	Controls if a sample limit violation results in the sample value being discarded. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
SampleLimitAlarm	bool	maybe-optional	Controls if a sample limit violation generates an alarm. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
ModbusValue	Object	maybe-optional	Description of how to extract a collected datavalue from a FC collected value. Mandatory of the protocol type is "Modbus/TCP".

ModbusFCs

The ModbusValue object contains the following elements: FCREF (integer >= 0, mandatory) This is a reference to the ModbusFCs element with the same value of it's field ModbusFCID. FCOffset (integer >= 0, mandatory). This is the addressing offset (relative to the referenced __ModbusFCs__s ModbusStart address. It must be lower than ModbusCount field for that same ModbusFCs element. FCDataMask (integer >= 0, optional) This is the value that is bit-wise AND'ed with the collected value. FCDataShift (integer, optional). This is the number of bits the collected value is shifted right.

Function	Type	Importance	Description

Example collecting
64 coils from 27 to 90
53 input registers from 3 to 55
33 holding registers from 100 to 132

{
 "CollectorName": "Test1ModbusDevice",
 "CollectorDescription": "My first modbus",
 "Protocol": "ModBus\/TCP",
 "ConnectRetryMin" : 2,
 "ConnectRetryMax" : 240,
 "ModbusAccess" : {
  "ModbusFCs": [
  {
  "ModbusFCID": 1,
  "ModbusFCSlaveAddress": 1,
  "ModbusFC": "coils",
  "ModbusFCStart": 27,
  "ModbusFCCount": 64,
  "ModbusFCSampleInterval": 5
   },
   {
   "ModbusFCID": 2,
   "ModbusFCSlaveAddress": 1,
   "ModbusFC": "inputs",
   "ModbusFCStart": 3,
   "ModbusFCCount": 53,
   "ModbusFCSampleInterval": 3
   },
   {
   "ModbusFCID": 3,
   "ModbusFCSlaveAddress": 1,
   "ModbusFC": "holding-registers",
   "ModbusFCStart": 100,
   "ModbusFCCount": 33,
   "ModbusFCSampleInterval": 2
   }
  ],
  "ModbusTimeout" : 1000
  },
 "SamplePoints": [
  {
  "SampleName": "test1",
  "SampleDescription": "First coil",
  "SamplesSaved": 10,
  "SampleDataType": "bool",
  "ModbusValue": {
   "FCREF": 1,
   "FCOffset": 0
   },
  "SampleLowerLimit": 0,
  "SampleUpperLimit": 1,
  "SampleLimitDiscard": false,
  "SampleLimitAlarm": false
  },
  {
  "SampleName": "input1",
  "SampleDescription": "first input",
  "SamplesSaved": 10,
  "SampleDataType": "int16",
  "ModbusValue": {
   "FCREF": 2,
   "FCOffset": 0
   },
  "SampleLowerLimit": 0,
  "SampleUpperLimit": 1000,
  "SampleLimitDiscard": false,
  "SampleLimitAlarm": false
  },
  {
  "SampleName": "Holding1",
  "SampleDescription": "first holding register",
  "SamplesSaved": 10,
  "SampleDataType": "int16",
  "ModbusValue": {
   "FCREF": 3,
   "FCOffset": 0
   },
  "SampleLowerLimit": 0,
  "SampleUpperLimit": 1000,
  "SampleLimitDiscard": true,
  "SampleLimitAlarm": true
  }
 ]
}

See complete Modbus examples here: