Machine Insights Streaming Dataformat

The Machine Insights based streaming data format provides high-level semantic information about machines. This means that e.g. information about "Operating Hours", "Fuel Remaining in Tank", "DEF Level" and "Battery Voltage" are immediately present in a normalized format - no matter the input source. This is perfectly tailored towards usage in a data lake or in AI-based analytics.

📘

All data fields are optional

For the same machine, some fields might be filled out in one message while others are filled out in the next message; which fields are filled out depends on the technical details of the data collection. The interpretation should always be that the individual data point was provided at its respective timestamp.

The data is generally ordered in sequence, with the most recent data point appearing last, although this order is not guaranteed. If the most recent data is needed the timestamps should be compared. Any processing of historic data should be prepared to receive and handle data out of order.

Header and Metadata information

Metadata about the machine itself is contained in the field EquipmentHeader, with the following fields:

FieldExampleDescription
UnitInstallDateTime1604042795000Unix timestamp in milliseconds at which point the telematics unit was installed on the machine.
OEMName"Red Tractors"The brand name of the machine.
Model"F6000"The model name of the machine.
EquipmentID"My Red F6000"The name given to the machine by the customer account.
SerialNumber"1GCHC33N7RJ376544"The serial number given to the machine - currently the same as the PIN.
PIN"1GCHC33N7RJ376544"The PIN given to the machine.

Metadata about the telematics device, and further links into the Trackunit APIs is given in the field Metadata:

FieldExampleDescription
TelematicSerialNumber"1234568"The serial number of the telematics device.
MachineId"60b1b9ab-1902-4e43-adfd-fc8f29acd838"The UUID assigned to the machine within Trackunit's systems.
UnitId87654321The UnitID assigned to the telematics unit within Trackunit's systems.
ExternalReferenceNumberCustomer-assignedThe external reference number assigned to this machine by the customer account.

In general the MachineId is used to navigate to the various Iris APIs, while the UnitId can be used to access the Classic APIs.

Location and LocationAddress

The fields Location and LocationAddress contain the position, and the approximate street address of the machine at the given time.

Location

FieldExampleDescription
Latitude57.048273Latitude of the location.
Longitude9.947384Longitude of the location.
Altitude (optional)17Altitude of the location, or null.
AltitudeUnits (optional)"metres"Units of the altitude (always normalized to "metres"), or null.
datetime1604042795000Unix timestamp in milliseconds, for when this location was recorded.

LocationMetadata

Contains additional information about the Location.

FieldExampleDescription
AccuracyRadius (optional)10.0Accuracy of the location defined as a radius in metres. Corresponds to the Estimated Horizontal Position Error (EHPE) from GPS.
HighAccuracy (optional)trueWhether the location in com.aemp20.Location is accurate enough to be used for business purposes.

LocationAddress

Contains the approximate street address of the given Location.

FieldExampleDescription
Country (optional)"Denmark"Country of the location.
Zipcode (optional)"9000"Zipcode of the location.
City (optional)"Aalborg"City of the location.
Address (optional)"Gasværksvej 24"Street address of the location.
GeoHash (optional)"u4phd376qbg5"GeoHash of the location.
datetime1604042795000Unix timestamp in milliseconds, for when this location was recorded.

AccessControlKeyUsage

The field AccessControlKeyUsage contains information about an access operation for a machine. Relaying information about who initiated the operation, which key was used and if the operation was successful.

FieldExampleDescription
OperatorId (optional)"60b1b9ab-1902-4e43-adfd-fc8f29acd838"ID of the operator performing the operation, if identifiable.
KeyId (optional)"84c63030-00a2-4b90-81bd-e63ee18751e8"ID of the key used in the operation, if identifiable.
Operation"LOCK"
"UNLOCK
The type of operation performed.
AccessType"DIGITAL_KEY"
"ROLLING_PIN
The type of access used for the operation. This can be on of DIGITAL_KEY, ROLLING_PIN, STATIC_PIN, KEY_CARD, KEYPAD_USE
SuccesstrueBoolean value for whether the operation was successful.
datetime1604042795000Unix timestamp in milliseconds, for when this operation was recorded.

Hours: CumulativeOperatingHours, CumulativeIdleHours, ...

The Cumulative Operating Hours field is a crucial parameter that represents the total number of hours the machine has been in operation. Depending on the machine type, the following fields may also be present:

  • CumulativeIdleHours
  • CumulativeIdleNonOperatingHours
  • CumulativeProductiveHours
  • CumulativeMovingHours
  • etc.

The general format of the Hours fields is:

FieldExampleDescription
Hour42.12Decimal amount of hours.
datetime1604042795000Unix timestamp in milliseconds, for when this data point was recorded.

Machine Insights

The main fields (around 130 in total) all describe some aspect of semantic data about a machine: FuelRemaining, EngineStatus, Distance travelled, etc. The availability of these data points will vary depending on the source of the telematic data (be it GPS, CAN-bus, ISO feed, etc.). The unit of measurement for each data point will always be the same, i.e., the unit for Distance will always be "km" for kilometres. The general format of the machine insights is, with varying field names:

FieldExampleDescription
Field with value (naming varies)13.8
true
The value of the data point itself. Floating point or boolean.
unit (naming sometimes varies)"km"
"volt"
The unit of measurement for this data series. Will always stay the same for the same field.
datetime1604042795000Unix timestamp in milliseconds, for when this data point was recorded.

For the exact semantics and availability of these data points, please see the data model description.

CANMessages

📘

This is low-level data

Most of the CAN data has been interpreted to Machine Insights by Trackunit. CANMessages are not normalized, and not data cleansed to the same degree. CANMessages should only be necessary if something particular is needed.
We recommend looking at the other fields first.

CAN messages is data directly from the CAN bus of the machine. In general a working knowledge of the CAN bus, and sometimes the specific CAN bus of a machine, is needed to interpret this data. The CANMessages field is an array, where each element has the following format:

FieldExampleDescription
datetime1604042795000Unix timestamp in milliseconds, for when this data point was recorded.
UnitOfMeasurement"%"
"rpm"
The unit of measurement, as specified in the CAN profile; not normalized.
VariableId212The internal Trackunit VariableId for this data item.
VariableName"Engine Speed"The name corresponding to the VariableId.
ParsedValue1234.5678
"the value"
The parsed value; either a double or a string.

More detail about the value collected is available in the "CanMessageValues" field which can be one of these types:

TypeFieldsDescription
CanMessageValuevalueA single value was picked up in the capturing interval.
CanMessageMinMaxMinValue
MaxValue
A minimum and maximum value was picked up in the capturing interval.
CanMessageAccumulatedvalueThe sum of all observed values in the capturing interval was picked up.

More details about how the data was picked is available in the "CanMessageData" field, which has the following subfields:

FieldExampleDescription
CanId217056257The CAN identifier of the data that was picked up.
SourceAddress0The CAN source address of the data that was picked up.
BinaryValue-The bits themselves that was picked up.
Counter1234The number of data items that where seen in the capturing period matching this CAN data item.
CapturingPeriod120The number of seconds the capturing period lasted.
CanType"Can A"
"Can B"
The type of CAN bus.

FaultCodes

FaultCodes contain an array of faults that occurred on a machine, typically because they were present on the CAN bus, but they could also be imported from an ISO feed or similar sources. Each element in the array has the following fields:

FieldExampleDescription
CodeIdentifier"1234-56"
"Free text"
The identifier for the fault; for CAN errors this will normally be "SPN-FMI", but for other sources this is entirely free text.
CodeDescription"Engine Fuel Delivery Pressure too low"The interpretation of the fault that Trackunit knows and shows in Manager.
CodeSeverity"67"
"Low", "High", "Free text"
The severity of the fault; if originating from a Trackunit device it will be between 0 and 100; from other sources this can be free text.
CodeSource"0"
"Engine"
The source where the fault originates from; for CAN errors this will normally be the CAN source address; from other sources this can be free text.
datetime1604042795000Unix timestamp in milliseconds, for when this fault started appearing.
datetimeClearednull
1604046795000
Unix timestamp in milliseconds, for when this fault stopped appearing, or null if still present or unknown.
For CAN errors there will normally be one message with datetimeCleared = null, followed at a later time by a message with datetimeCleared != null. From other sources, this behaviour is not guaranteed.

Trackunit Kin

For messages related to Trackunit Kin tags, EquipmentHeader contains asset data on which the Kin tag is onboarded. Metadata consists of Kin serial number and asset ID (as MachineId field).