Stomp protocol description

To send data to Scout, it is recommended to use Stomp with our custom headers and payload definitions.

Stomp protocol

Stomp protocol is very simple, it's a text based protocol with a few commands and headers. The semantics is implemented via the destination header.

Connection

To connect to Scout you must use the following parameters:

Parameter	Value
URL	wss://scout.circutor.com/ws/stomp
Host	pro
Username	<claimID>
Password	<Token>

• <claimID> are unique identifiers (8 charts, A-Za-z0-9) that are used to identify the gateway that is sending the data.
• <Token> is the token that is used to authenticate the gateway.

Both values are provided by the platform upon gateway creation. They can be created from the factory and configured into the hardware.

Headers

Those are the headers that are required to send data to Scout:

Header	Descripton	Example
myc-version	Protocol version	1.0
myc-message-type	Message type	EVENT,METRIC,WAVEFORM,ATTRIBUTE
myc-fw-version	Firmware (communication) version	X.Y.Z
myc-hw-version	Hardware version	X.Y.Z
myc-gw-type	Gateway Type	gatewayType
myc-fw-measure	Measure firmware version(optional)	X.Y.Z
myc-serial-number	Gateway Serial Number	2145588744588

Data format

To send data (events, metrics, waveforms or attributes) to Scout, you must use the

Metrics

Metrics are the most common data type sent to Scout. They are used to represent a value at a given time.

destination: /exchange/metrics/gateways.<claimID>

{
    "gateway_device_id": "MAIN",
    "metrics": [
        {
            "ts": "2024-09-30T09:00:00.000Z",
            "data": {
                "P_CON_TOT_ENERGY": 756387.9,
                "P_GEN_TOT_ENERGY": 6.7711396,
                "Q_Q1_TOT_ENERGY": 120348.6,
                "Q_Q2_TOT_ENERGY": 1.2876,
                "Q_Q3_TOT_ENERGY": 0.0013434684,
                "Q_Q4_TOT_ENERGY": 0.16768773,
                "S_TOT_ENERGY": 770940.9
            }
        }
    ]
}

Take into account that the ts field must be in ISO 8601 format and that gateway_device_id is a unique identifier for the device in the gateway scope.

For devices that include both gateway and device (such as ComputerC6, or QNA600), the gateway_device_id is always MAIN.

For other gateways that have more slaves (such as Line EDS Cloud), the gateway_device_id is the slave identifier (for example modbus address or device name).

Attributes

Attributes are used to send configuration data to Scout. They are used to communicate the configuration of the gateway or device to the platform.

destination: /exchange/attributes/gateways.<claimID>

{
  "gateway_attributes": { 
    "SERIAL_NUMBER": "82621240052", 
    "FW_VERSION": "2.03.01",
    "FW_MEASURE": "2.6.0",
    "HW_MODEL": "EDSCLOUD",
    "HW_VERSION": "1"
  },
  "device_attributes": { 
    "<slave_1>": {
      "SERIAL_NUMBER": "12300012345678",
      "FW_VERSION": "1.1.0",
      "FW_MEASURE": "2.6.0",
      "HW_MODEL": "CVM-D50-ITF",
      "HW_VERSION": "1",
      "CONNECTION_TYPE": "3PH4W"

    },
    "<slave_2>": {
      "SERIAL_NUMBER": "12300012345679",
      "FW_VERSION": "1.1.1",
      "FW_MEASURE": "2.6.2",
      "HW_MODEL": "CVM-D50-ITF",
      "HW_VERSION": "1",
      "CONNECTION_TYPE": "3PH4W"

    }
  }
}

Both gateway_attributes and device_attributes are optional. If device_attributes is present, it must contain a map of identifier -> device information. This gateway identifiers are shown in the payload as<slave_1> and <slave_2>. As value it can be used a modbus address or the device name, as long as the value is unique.

There are some specific attribute keys that have speciall effect on the platform. All fields are optinal

Attribute	Description	Behaviour
SERIAL_NUMBER	Serial Number	Updates serial number (gateway or device)
FW_VERSION	Firmware Version	None, just updates info
FW_MEASURE	Measure Firmware version	None, just updates info
HW_VERSION	Hardware Version	None, just updates info
HW_MODEL	Hardware Variant (itf, flex, ...)	None, just updates info

Events

destination: /exchange/events/gateways.<claimID>

{
    "gateway_device_id": "MAIN",
    "events": [
        {
            "id": "e9adb178-3a7c-4e90-9ea8-d0a3fc5ddc34",
            "type": "EXPORT_CONNECTED",
            "ts": "2024-09-30T12:13:54.094+02:00",
            "status": "INFO",
            "index": "NONE",
            "info": {}
        }
    ]
}

Some description on the fields: - id: Unique identifier for the event (optional) - type: Event type (required), recommended to follow the event type list - ts: Event timestamp (required), must be in ISO 8601 format - status: Event status (required), can be INFO, ON, OFF - index: It is intented to use to represent phases, attribute names, etc. (default should be NONE) - info: Additional information that might be interesting (optional)

Waveforms

Waveforms are used to send high frequency data to the platform. They are used to represent the waveform of a signal.

destination: /exchange/waveforms/gateways.<claimID>

{
  "id": "2ec67a5a-7310-42ae-95ec-1203d8fc634b",
  "gateway_device_id": "QNA600",
  "start_at": "2024-05-16T09:26:27.976Z",
  "first_event_ts": "2024-05-16T09:26:28.040Z",
  "sample_rate": 12797.278,
  "channels_analog": [
    {
      "name": "V_AN",
      "sample_factor": 0.02519966,
      "samples": [
        [
          0,
          12436
        ],
        [
          78,
          12313
        ]
      ]
    },
    {
      "name": "V_BN",
      "sample_factor": 0.02519966,
      "samples": [
        [
          0,
          12475
        ],
        [
          78,
          12352
        ]
      ]
    },
    {
      "name": "V_CN",
      "sample_factor": 0.02519966,
      "samples": [
        [
          0,
          12456
        ],
        [
          78,
          12345
        ]
      ]
    },
    {
      "name": "I_AN",
      "sample_factor": 0.00066365,
      "samples": [
        [
          0,
          12
        ],
        [
          78,
          11
        ]
      ]
    },
    {
      "name": "I_BN",
      "sample_factor": 0.00066365,
      "samples": [
        [
          0,
          4
        ],
        [
          78,
          13
        ]
      ]
    },
    {
      "name": "I_CN",
      "sample_factor": 0.00066365,
      "samples": [
        [
          0,
          17
        ],
        [
          78,
          27
        ]
      ]
    }
  ]
}