Collector Modbus TCP
  • 11 Aug 2021
  • 8 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Collector Modbus TCP

  • Dark
    Light
  • PDF

Article Summary

The purpose of this article is to be a reference for the Modbus collector part of the full Data Collection Module documentation.

Prerequisite

A Starter package (SiteManager + accounts)
A Modbus slave capable device


Config main

The Config main (array of objects, mandatory) contain the following fields:

FunctionTypeImportanceDescription
ConfigNamestringmandatoryUnique name for this configuration file. Follows the rules for names.
ConfigDescriptionstringoptionaltext describing this configuration.
CheckpointIntervalinteger == 0 or >= 60optionalThe interval with which all data from the internal datasample cache is saved to disk. This more unstable (power) the SiteManager, the more often data should be saved. Saving it often, however will also cost performance and wear on the hard-disk/flash. A value of 0 means, never checkpoint, otherwise it means interval in seconds between saves. If not specified the value 15 * 60 (15 minutes) is used.
AlarmsSavedinteger >= 4optionalThe number of alarms saved in the store-and-forward database. If this values is not specified, it will default to 32.
WaitForNTPbooleanoptionalSynchronize DCM data collection with NTP time. If this parameter is true, all DCM collectors will not begin collecting data until NTP is enabled and configured and NTP has synchronized date/time. If not specified, the value is true.

Since the JSON format itself doesn't define a comment notation, DCM accepts a fieldname comment with any type of value in any section.

Example of comment

"Comment": "Example of a comment for use in any section.": 


Collector main

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

FunctionTypeImportanceDescription
CollectorNamestringmandatoryUnique name (within this configuration file) of a device to collect data from (this is the name used in the agent configuration). Follows the normal rules for names.
CollectorDescriptionstringoptionalDescription of this collector. For your use, no system function.
CollectorIPAddrstringoptionalDefault IP address (or DNS name) for the device to be polled. The agent Target IP address will take precedence over this.
CollectorPortnointeger > 0 and < 65535optionalDefault 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.
AliasstringoptionalThis is the CollectorName of another collector from which all the parameters (expect CollectorName, CollectorDescription, CollectorIPAddr and CollectorPortno) are copied. An alias cannot refer to another alias.
Protocolstring-enummandatoryThe protocol used to collect data. Currently 3 possible values exists: "OPC-UA/TCP", "Modbus/TCP", "Http/GET" and "Simulator".
ConnectRetryMininteger > 0mandatoryThe 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.
ConnectRetryMaxinteger > 0mandatoryMaximum number of seconds before trying to reestablish a connection to the device being sampled.
ModbusAccessobjectoptionalCollection of parameters needed to access a given Modbus server.
SamplePointsarray of objectsmandatoryList 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 contain the following elements:

FunctionTypeImportanceDescription
ModbusFCsarray of objectsmandatoryList of modbus function code (FCs) to be performed during collection of data if the Protocol is "Modbus/TCP".
ModbusTimeoutinteger > 0optionalTimeout (in millisecs) for all modbus FC requests. If not present, the value 500 is used.
ModbusRegswapbooleanoptionalIf true, the 16bit register values retrieved will be byte-swapped before being used. If not specified the value is false.
0x12345678 > 0x34127856



ModbusFCs

The ModbusFCs objects contain the following elements:

FunctionTypeImportanceDescription
ModbusFCIDinteger >= 0mandatoryIs a unique ID (within this Collectors element) for this entry. Used by the SamplePoints entries.
ModbusFCSlaveAddressinteger >= 0 and <= 247 or 255optionalThe 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 is not present, the value 255 is used.
ModbusFCstring-enummandatoryIs the type of Modbus function code used when collecting data. Possible values are:
"coils" (FC 1)
"inputs" (FC 2)
"holding-registers" (FC 3)
"input-registers" (FC 4)
ModbusFCStartinteger >= 0mandatoryStart address on the Modbus for this access.
ModbusFCCountinteger >= 0 and <= 125mandatoryNumber of units (bits or registers) to read in one access.
ModbusFCSampleIntervalinteger >= 0mandatoryNumber of seconds between each collection of data using this FC. If the interval is 0, only event-driven polling is used.
ModbusFCTimeoutinteger > 0optionalTimeout (in milliseconds) for these Modbus FC requests. If not present, the value is that of ModbusTimeout referenced by the ModbusFCID.
ModbusFCRegswapbooleanoptionalIf 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. This function has been deprecated in favor of FCByteMap, but is kept for backwards compatibility reasons.


Samplepoint items

The SamplePoints objects contain the following elements:

FunctionTypeImportanceDescription
SampleNamestringmandatoryName of this sampled value (sometimes called a tagname). Follows the normal rules for names.
SampleDescriptionstringoptionalIs a text description of this sample value.
SampleUnitstringoptionalIs a description of the unit of messurement for this sample.
SampleGroupstringoptionalDesignates (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.
SamplesSavedinteger > 0mandatoryIs 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.
OnlySaveOnChangedbooloptionalControl if new sample values should only be saved to the Store'n'Forward database if the values have changed since last sample. If not set, it is false.
ChangeLimit
integer/double
optional
Only used if OnlySaveOnChanged is true. This describes a limit for what "changed" means. If a new sample value is this amount less or more than the previous sample value, it is considered the "same" value. This is a simple hysteresis to filter out inaccurate (jitter) measurements.
SampleDataTypestring-enummandatoryThe 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)
SampleLowerLimitinteger/doubleoptionalThe lower limit for the collected data. If the collected data value is less than SampleLowerLimit, it is evaluated in accordance with SampleLimitDiscard and SampleLimitAlarm.
SampleUpperLimitinteger/doubleoptionalThe upper limit for the collected data. If the collected data value is more than SampleUpperLimit, it is evaluated in accordance with SampleLimitDiscard and SampleLimitAlarm.
SampleLimitDiscardboolmaybe-optionalControls if a sample limit violation results in the sample value being discarded. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
SampleLimitAlarmboolmaybe-optionalControls if a sample limit violation generates an alarm. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
ModbusValueobjectmaybe-optionalDescription of how to extract a collected datavalue from a FC collected value. Mandatory if the protocol type is "Modbus/TCP".


ModbusValue

The ModbusValue object contains the following elements: 





FCREF integer >= 0mandatoryThis is a reference to the ModbusFCs element with the same value of its field ModbusFCID.
FCOffsetinteger >= 0mandatoryThis is the addressing offset (relative to the referenced __ModbusFCs__s ModbusStart address). It must be lower than ModbusCount field for that same ModbusFCs element. 
FCByteMap
array of integer
optional
This array defines the mapping of incoming data from modbus to outgoing data to the sample value. The incoming data is referencing the index into the array, while the content of the array at that position determines the outgoing byte position. Example: [0,1,2,3,4,5,6,7] is the "identity" map, where no bytes change position. [2,3,0,1] will swap the two 16-bit registers read, but keeing the byteorder. [7,6,5,4,3,2,1,0] will reverse the byteorder of the 64-bit value constructed from 4 16-register read from Modbus. If not specified, the identity map will be used (i.e No swapping will take place). Note that once the bytes have been received and remapped, it is converted into the natural representation of the CPU, so that DCM aggregations can perform calculation on them. This means that the remapping should result in values in "network" order (i.e Big Endian order), which is then converted into Little Endian on SiteManagers with CPUs that use Little Endian. (I.e. ARM, Intel-X86). Also note that FCByteMap is not allowed for samples with SampleDataType of "data", as this data type is used for raw variable length data. NOTE: As of Release 9.5 of the SiteManager DCM code, the float values have changed conversion. All data types are now only using the ModbusRegswap and FCByteMap, so if you wish the float value to result in the same values as in older releases, you must use an FCByteMap [3,2,1,0] (the reverse map).
FCDataMaskinteger >= 0optionalThis 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.
FCDataShiftintegeroptionalThis is the number of bits the collected value is shifted right to get the correct binary weight. 

Together the 4 ModbusValue fields performs the calculation: datavalue = (FCvalue & FCDatamask) >> FCShift. This is traditionally called extracting a bit-field.


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": [
  {
  "comment": "First set of data requested from the Modbus Master, Coils(bit)from coil address 27 to 90 (64 addresses)",
  "comment": "ModbusFCID is a reference number used in samplepoints", 
  "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 in the related articles section below. 


Was this article helpful?