We've updated our file storage system, so some links may no longer work. If you need a file, just email us at support@secomea.com—we’re happy to help!

Collector SiteManager Internal

  • Published on Dec 17, 2024
  • 7 minute(s) read
  • SE
 Prev Next

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

The Internal SiteManager collector is used to collect samples (data points) from a hardware SiteManager. These samples can be used in the same way as samples collected from external equipment.

Collectable values

These data values from SiteManager itself, can be collected and stored in in the DCM database and forwarded to the data servers.

Values from the SiteManager hardware or firmware.

InternalFunction value Unit Description
SystemTemperature Centigrade/Celsius Temperature measured in the SiteManager.
FreeMem kB Available memory as reported by the kernel.
UTCRTC - UTC Real Time Clock, broken into 8 separate values.
DigitalInput - Reported as zero or one.
IngressRate bytes/s Amount of data collected.
EgressRate bytes/s Amount of data forwarded to data server(s).
DBCachesize bytes Size of the database cache.
DBSize bytes Size of the database.

Values from mobile modem, if SiteManager is XX39 model or external modem is connected.

InternalFunction value Unit Description
GSMRssi dBm Received Signal Strength Indication.
GSMBer percent Bit Error Rate.
GSMOperator string Network operator as reported by the modem.
GSMTechnology string For example "4G", "3G", "GPRS" etc as reported by the modem.

Values from USB GNSS unit (a.k.a GPS), if an unit is connected.

InternalFunction value Unit Description
GNSSLatitude decimal degrees Positive for North, negative for South of Equator.
GNSSLongitude decimal degrees Positive for East, negative for West of Greenwich.
GNSSAltitude meter Height above the meas sea level (MSL).
GNSSSatellitesInView - Number of satellites visible to the GNSS unit.
GNSSSatellitesUsed - Number of satellites used for the position reported.
GNSSGeographicDistance meter The Haversine geographical distance since the last GNSS position was reported.

Configuration

The data collector configuration consist of the fields described below.

Main section

The top level of the data collector contains the following fields:

Function Type Importance Description
CollectorName string mandatory Unique 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.
CollectorDescription 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 (except CollectorName, CollectorDescription, CollectorIPAddr and CollectorPortno) are copied. An alias cannot refer to another alias.
Protocol string-enum mandatory The protocol used to collected data. Currently, 7 possible values exists: OPC-UA/TCP, Modbus/TCP, S7/TCP, Http/GET, Rockwell, Simulator and Internal.
ConnectRetryMin integer > 0 mandatory The minimum number of seconds before trying to re-establish 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 The maximum number of seconds before trying to re-establish a connection to the device being sampled.
SamplePoints Array of objects mandatory List of samples to be collected, possibly aggregated and stored in the Store and Forward database.

SamplePoints object

The SamplePoints objects contains the following fields:

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 A text description of this sample value.
SampleUnit string optional A description of the unit measurement for this sample.
SampleGroup string optional Group affiliation. All sample points in the same group (in some datasrvs) should be handled (displayed) together. The DCM system itself places no meaning on this group affiliation.
SamplesSaved integer > 0 optional Is the number of values collected that is saved in the Store and 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 and Forward database until they have been delivered to all dataservers.
OnlySaveOnChanged boolean optional Specifies if new sample values should be saved to the Store and Forward database only when the value is different from the last sample value. Default: false.
ChangeLimit integer/double optional Used if OnlySaveOnChanged is true. Specifies an amount which a sample must be greater than, to count as a changed value. This is a simple hysteresis to filter out inaccurate (jitter) measurements. Default: 0
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 data up to 24575 bytes).
SampleMaxVDataSize integer > 0 and <= 24575 optional The max size of variable data allowed for this sample. This is only relevant for SampleDataType string or data. If not specified, the value is 1024.
SampleLowerLimit integer/double optional The lower limit for the collected data. If the collected data value is less than SampleLowerLimit it is evaluated in accordance with 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 in accordance with SampleLimitDiscard and SampleLimitAlarm.
SampleLimitDiscard boolean maybe-optional Specifies whether samples that violates the sample limit should be discarded. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
SampleLimitAlarm boolean maybe-optional Specifies whether samples that violates the sample limits should generate an alarm. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
InternalData object mandatory Specification of the internal data collection behaviour of this sample point. Mandatory if Protocol is Internal.

InternalData

The InternalData object contains the following elements:

Function Type Importance Description
InternalFunction string-enum mandatory This is the internal function to be performed. The possible values are described in the InternalFunction configuration section.
InternalIndex integer >= 0 maybe-optional See the InternalFunction configuration section for when to use this field.
InternalFieldname string optional See the InternalFunction configuration section for when to use this field.
InternalSampleInterval integer >= 0 mandatory The number of seconds between each sample of this Internal object. If the interval is 0, only event-driven polling is used.

InternalFunction configuration

The chosen value of the InternalFunction parameter determines if other fields become mandatory. The chosen function also may be impacted by other fields. These dependencies is described below.

Enum value Unit/Type Description
SystemTemperature centigrade/Celsius -
CPULoad percent -
FreeMem kB -
UTCRTC InternalIndex becomes mandatory, and must be one of: 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) or 7 - day of the year (0-365, 1. Jan = 0).
DigitalInput - InternalIndex becomes mandatory, and must specify the index of the Digital I/O input port from which values are to be collected.
IngressRate bytes/s InternalFieldname becomes a nameref for the sample for which to show the ingress rate. If not specified, the rate is the total ingress rate.
EgressRate bytes/s InternalFieldname becomes the name of a data server to show the egress rate for. If not specified, the rate is the total egress rate.
DBCachesize bytes -
DBSize bytes -
GSMRssi dBm -
GSMBer percent -
GSMOperator string -
GSMTechnology string Possible values are: 4G, 3G and GPRS etc.
GNSSLatitude decimal degrees The ChangeLimit value for this value is compared to the GNSSGeographicDistance value, not the value of the GNSSLongitude. If OnlySaveOnChanged is set, then ChangeLimit is set to the estimated precision reported by the GNSS chipset.
GNSSLongitude decimal degrees The ChangeLimit value for this value is compared to the GNSSGeographicDistance value, not the value of the GNSSLongitude. If OnlySaveOnChanged is set, then ChangeLimit is set to the estimated precision reported by the GNSS chipset.
GNSSAltitude meter If OnlySaveOnChanged is set, then ChangeLimit is set to the estimated precision reported by the GNSS chipset.
GNSSSatellitesInView - -
GNSSSatellitesUsed - -
GNSSGeographicDistance meter -

Below is an example of a Internal Collector configuration:

{
  "CollectorDescription": "DCM Internal Values Collector",
  "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
      }
    }
  ]
}