Collector SiteManager Internal
  • 09 Dec 2022
  • 6 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Collector SiteManager Internal

  • Dark
    Light
  • PDF

Article summary

The purpose of this article is to serve as a reference for the Internal Collector part of the full Data Collection Module documentation.

Prerequisites

A Starter package (SiteManager + accounts)


Data that you can collect from SiteManager itself includes:

Values from SiteManager-board:
"SystemTemperature" (in centigrade/Celcius)
"CPULoad" (in percent)
"FreeMem" (in kB) 
"UTCRTC" UTC Real Time Clock, broken into 8 separate values
"DigitalInput" (as 0/1)
"IngressRate" (in bytes/s)
"EgressRate" (in bytes/s)
"DBCachesize" (in bytes)
"DBSize" (in bytes)

Values from mobile modem, if connected or SiteManager is XX39 model:
"GSMRssi" (in dBm)
"GSMBer" (in percent)
"GSMOperator" (text string)
"GSMTechnology" (text string: "4G", "3G", "GPRS" etc.).

Values from USB GPS unit if connected :
 "GNSSLatitude" (double in decimal degrees, positive for North, negative for South of Equator).
 "GNSSAltitude" (double in meters MSL).
 "GNSSSatellitesInView" (integer)
 "GNSSSatellitesUsed" (integer)
 "GNSSGeographicDistance" (double in meters).

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.": 


The Collectors (array of objects, mandatory) list of elements contains 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.
CollectorIPAddrstringoptionalProvides a default IP address (or DNS name) for the device to be polled. The agent Target IP address will take precedence over this.
CollectorPortnointeger > 0 and < 65535optionalProvides the 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 to be used will be determined by the Protocol parameter value.
AliasstringoptionalThis is the CollectorName of another collector, from which, all the parameters (except CollectorName, CollectorDescription, CollectorIPAddr and CollectorPortno) are copied from. An alias cannot refer to another alias.
Protocolstring-enummandatoryThe protocol used to collected data. Currently, 7 possible values exists: "OPC-UA/TCP", "Modbus/TCP", "S7/TCP", "Http/GET", "Rockwell", "Simulator" and "Internal".
ConnectRetryMininteger > 0mandatoryMinimum number of seconds before trying to reestablish a connection to the device being sampled. An exponential back-off algorithm is used to retry the establishment of a connection, starting after ConnectRetryMin and increasing to ConnectRetryMax.
ConnectRetryMaxinteger > 0mandatoryMaximum number of seconds before trying to reestablish a connection to the device being sampled.
SamplePointsArray of objectsmandatoryList of samples to be collected, potentially aggregated and stored in the Store'n'Forward database.


Samplepoint items

The SamplePoints objects contains the following elements:

FunctionTypeImportanceDescription
SampleNamestringmandatoryName of this sampled value (sometimes called a tagname). Follows the normal rules for names.
SampleDescriptionstringoptionalA text description of this sample value.
SampleUnitstringoptionalA description of the unit of measurement for this sample.
SampleGroupstringoptionalDesignates (in some datasrvs) that all sample points in the group in question should be handled (displayed) together. The DCM system itself places no significance on this group affiliation.
SamplesSavedinteger > 0optionalThe number of values collected that is saved in the Store'n'Forward database even after the values have been sent to all dataservers. When 0 is specified, the value can be used in aggregators. but nothing is sent via dataservers to cloud system. If left unspecified, values are only saved in the Store'n'Forward database until they have been delivered to all dataservers.
OnlySaveOnChangedbooloptionalChecks whether new sample values should only be saved to the Store'n'Forward database if the values have changed since the last sample. If not set, it is false.
SampleDataTypestring-enummandatoryThe type of data collected. The possible values include: "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 data up to 24575 bytes).
SampleMaxVDataSize
integer > 0 and <= 24575
optional
The max size of variable data enforced for this sample. This is only relevant for SampleDataType "string" or "data". If not specified, the value is 1024.
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-optionalChecks whether a sample limit violation results in the sample value being discarded. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
SampleLimitAlarmboolmaybe-optionalChecks whether a sample limit violation generates an alarm. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
InternalDataObjectmaybe-optionalDescription of the internal behaviour of this sample point. Mandatory if the protocol type is "Internal".


InternalData

The InternalData object contains the following elements:

FunctionTypeImportanceDescription
InternalFunctionstring-enummandatoryThis is the internal function to be performed. The values currently permitted include:
  • "SystemTemperature" (in centigrade Celsius)
  • "CPULoad" (in percent)
  • "FreeMem" (in kB)
  • "UTCRTC" UTC Real TIme Clock broken into 8 separate values. Controlled by InternalIndex.
  • "DigitalInput" (as 0/1). Controlled by InternalIndex.
  • "IngressRate" (in bytes/s). Controlled by InternalFieldname.
  • "EgressRate" (in bytes/s). Controlled by InternalFieldname.
  • "DBCachesize" (in bytes)
  • "DBSize" (in bytes)
  • "GSMRssi" (in dBm)
  • "GSMBer" (in percent)
  • "GSMOperator" (text string)
  • "GSMTechnology" (text string: "4G", "3G", "GPRS" etc.)
  • "GNSSLatitude" (double in decimal degrees, positive for North, negative for South of Equator). Note: The ChangeLimit value for this value is compared to the "GNSSGeographicDistance" value, not the value of the "GNSSLatitude". Also note, that if only OnlySaveOnChanged is set, the ChangeLimit is set to the estimated precision reported by the GNSS chipset.
  • "GNSSLongitude" (double in decimal degrees, positive for East, negative for West of Greenwich). Note: The ChangeLimit value for this value is compared to the "GNSSGeographicDistance" value, not the value of the "GNSSLongitude". Also note, that if only OnlySaveOnChanged is set, the ChangeLimit is set to the estimated precision reported by the GNSS chipset.
  • "GNSSAltitude" (double in meters MSL). Note: If only OnlySaveOnChanged is set, the ChangeLimit is set to the estimated precision reported by the GNSS chipset.
  • "GNSSSatellitesInView" (integer)
  • "GNSSSatellitesUsed" (integer)
  • "GNSSGeographicDistance" (double in meters). The Havesine geographical distance since the last GNSS position was reported.

InternalIndexinteger >= 0maybe-optionalIf InternalFunction is "DigitalInput" this is the mandatory index of the Digital I/O input port from which values are to be collected. If InternalFunction is "UTCRTC" this is the mandatory index of the time:
0 - second (0-59),
1 - minute (0-59),
2 - hour (0-23),
3 - day of the month (1-31),
4 - month (0-11, January = 0),
5 - Year (-1900),
6 - day of the week (0-6, Sunday = 0),
7 - day of the year (0-365, 1. Jan = 0).
InternalFieldnamestringoptionalUsed when the InternalFunction is "IngressRate" as a nameref for the sample for which to show the ingress rate or when the InternalFunction is "EgressRate" as the name of a Dataserver to show the egress rate for. If not specified, the rate is the total ingress or egress rate.
InternalSampleIntervalinteger >= 0mandatoryThe number of seconds between each sample of this Internal object. If the interval is 0, only event-driven polling is used.


Example:

{
  "CollectorDescription": "SDCM Internal Values Server",
  "CollectorName": "demointernal",
  "Protocol": "Internal",
  "SamplePoints": [
    {
      "SampleDataType": "double",
      "SampleDescription": "CPU load",
      "SampleLimitAlarm": false,
      "SampleLimitDiscard": false,
      "SampleLowerLimit": -1000,
      "SampleName": "CPU",
      "SampleUpperLimit": 1000,
      "SamplesSaved": 3000000,
      "InternalData": {
        "InternalFunction": "CPULoad",
        "InternalSampleInterval": 1
      }
    },
    {
      "SampleDataType": "double",
      "SampleDescription": "FreeMem",
      "SampleLimitAlarm": false,
      "SampleLimitDiscard": false,
      "SampleLowerLimit": -1000,
      "SampleName": "FreeMemory",
      "SampleUpperLimit": 1000,
      "SamplesSaved": 3000000,
      "InternalData": {
        "InternalFunction": "FreeMem",
        "InternalSampleInterval": 1
      }
    },
    {
      "SampleDataType": "double",
      "SampleDescription": "SystemTemperature",
      "SampleLimitAlarm": false,
      "SampleLimitDiscard": false,
      "SampleLowerLimit": -1000,
      "SampleName": "SystemTemperature",
      "SampleUpperLimit": 1000,
      "SamplesSaved": 3000000,
      "InternalData": {
        "InternalFunction": "SystemTemperature",
        "InternalSampleInterval": 1
      }
    }
  ]
}

See a complete list of internal collector examples in the "Related articles" section below.


Was this article helpful?