Skip to content

Ingestion

This section covers how to ingest messages into Hexastate's system. This could be messages like e.g. sensor measurements or asset health updates.

Pushing messages into Hexastate's app is beneficial in a range of use cases. For example if you already have existing hardware deployed, and you want the measurements recorded pushed into Hexastate's app for analytics reasons, visualizations, or similar. Another case could be that you have your own analytics engine and want to spend your development efforts on that rather than having to build an entire web application. Then you can publish the results from your analytics engine, and utilize Hexastate's web app.

Info

Direct messaging to Hexastate's MQTT server is only available on the Enterprise platform plan.

Messages can be ingested in 2 ways:

  1. Publishing messages to a dedicated topic in our MQTT server (primary).
  2. Hexastate fetches from your API (secondary).

Note

Option 2 of ingestion includes development costs for integration with your API. Also, one of the major advantages of option 1 is that it supports real-time event streaming. Therefore, we recommend option 1.

When you have the necessary platform subscription, you will be able to request connection info to the MQTT server along with your dedicated topic for message publishing. Only publish permissions for the topic will be granted.

Flow

The ingestion layer of Hexastate's app reads the messages instantly when entering the MQTT server. When a measurement is received by the ingestion, it will try to map the sensor_id to an internal ID (UUID) of a sensor in Hexastate's system. If the sensor_id is not matched with any sensor in the system, the measurement will be ignored. Therefore, it is important that any messages being published to the MQTT server already has an associated object created in the app. For example if you publish sensor measurements, you must assert that the sensor is created in the app prior to the publish event.

Note

Messages can be published multiple times. If the same message is received again, an upsert action will be performed against the database. A message is unique based on the ID and its timestamp.

Measurement Types

This chapter describes the various supported message types and shows example messages.

Warning

Published messages must be JSON encoded and the timestamp must be a unix epoch (UTC) integer in second resolution. This also means that the same sensor can't ingest 2 measurements of the same type within the same second.

Temperature

Temperature measurements are currently only accepted in Celsius. It is therefore anticipated that measurements in other units are converted prior to ingestion.

Below is an example of a temperature measurement:

{
  "sensor_id": "device_id_123",
  "gateway_id": "gateway_123",
  "timestamp": 1707118920,
  "measurement_type": "Temperature",
  "value": 23.76
}

RMS (vibration)

RMS vibration measurements are accepted in velocity (mm/s). It is therefore anticipated that measurements in other units are converted prior to ingestion.

Note

Hexastate recommends calculating the RMS of a vibration measurement on frequencies within a 10 - 1000 Hz frequency band.

The "axis" property describes the axis of the measurement.

The value of "axis" can be any of:

  • X
  • Y
  • Z

Below is an example of an RMS measurement:

{
  "sensor_id": "device_id_123",
  "gateway_id": "gateway_123",
  "timestamp": 1707118920,
  "measurement_type": "RMS",
  "axis": "X",
  "value": 2.17
}

Hydrogen Sulphide (H2S)

Hydrogen sulphide measurements are accepted in parts per minute (ppm).

Below is an example of a hydrogen sulphide measurement:

{
  "sensor_id": "device_id_123",
  "gateway_id": "gateway_123",
  "timestamp": 1707118920,
  "measurement_type": "HydrogenSulphide",
  "value": 2.17
}

Power Consumption

Power consumption measurements are accepted in kW.

Below is an example of a power consumption measurement:

{
  "sensor_id": "device_id_123",
  "gateway_id": "gateway_123",
  "timestamp": 1707118920,
  "measurement_type": "PowerConsumption",
  "value": 2.17
}

Output/Count

Output measurements are accepted as a count.

Below is an example of an output measurement:

{
  "sensor_id": "device_id_123",
  "gateway_id": "gateway_123",
  "timestamp": 1707118920,
  "measurement_type": "Output",
  "value": 217
}

The counter can start from any number in the range from -32768 to 32767 (INT16). Internally, the backend will start its own counter based on the first value seen. For example, if the first value from a sensor is 50, and the next value is 67, the internal counter will be 17. This means 17 counts/products were recorded by the sensor in the period between the 2 samples.

Warning

The counter assumes all measurement values are ranging from -32768 to 32767 (INT16). This means the counter will "wrap" around when reaching 32767. For example, if the previous sensor measurement was 32765 and the next value is -32767, it will translate to 4 counts internally.

Simple Health

Simple health is the name of the general asset condition indicator in the system. It is an indicator of the overall condition of an asset. This is currently measured in 4 zones going from best to worst: Good, Satisfactory, Unsatisfactory, and Unacceptable.

The system utilizes sensor measurements to analyze the condition of an asset, and then outputs one of the above values as interpretation of the current health based on the measurements.

If it is not wanted that Hexastate delivers these outputs, the analysis can be disabled on asset level, and updates can be pushed into Hexastate's system from external systems (only available on Enterprise plan).

Below is an example of a simple health update:

{
  "_id": "5946810c-0766-464b-8681-0c0766e64b7c",
  "timestamp": 1707118920,
  "measurement_type": "SimpleHealth",
  "value": 100
}

Here "_id" is the ID of the Asset. Timestamp is a unix epoch (UTC) in second resolution. "measurement_type" is a constant identifying what kind of message it is. "value" is the zone in which the asset is estimated to be in.

For the "value", here is the mapping with the health zones:

Value Status Color Description
100 Good Dark Green The asset is in its best state.
200 Satisfactory Light Green Early signs of degradation or minor increases in vibration energy.
300 Unsatisfactory Orange Clear signs of degradation and excessive vibration energy.
400 Unacceptable Red Excessive vibration energy. Might require immediate action, either as component replacement, maintenance or installation optimizations.

Warning

To avoid redundant analysis outputs on an Asset, each individual asset object that needs externally updated analysis updates must have its "disable_analytics" field set to true. If this field is not set to true, Hexastate's analysis services will still provide updates assuming sensor data is received on the particular asset.