Machine Insights Streaming Dataformat

The Machine Insights based streaming dataformat 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 datalake or in AI-based analytics.

📘

All datafields are optional

For the same machine some 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 datacollection. The interpretation should always be that the individual datapoint was provided at that individual timestamp.

Data is in general in-order, that is most recent datapoint last, but this 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:

Field

Example

Description

UnitInstallDateTime

1604042795000

Unix 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:

Field

Example

Description

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.

UnitId

87654321

The UnitID assigned to the telematics unit within Trackunit's systems.

ExternalReferenceNumber

Customer-assigned

The 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

Field

Example

Description

Latitude

57.048273

Latitude of the location.

Longitude

9.947384

Longitude of the location.

Altitude (optional)

17

Altitude of the location, or null.

Altitudeunits (optional)

"metres"

Units of the altitude (always normalized to "metres"), or null.

datetime

1604042795000

Unix timestamp in milliseconds, for when this location was recorded.

LocationAddress

Contains the approximate street address of the given Location.

Field

Example

Description

Country (optional)

"Denmark"

Country of the location.

Zipcode (optional)

"9000"

Zipcode of the location.

Address (optional)

"Gasværksvej 24"

Street address of the location.

GeoHash (optional)

"u4phd376qbg5"

GeoHash of the location.

datetime

1604042795000

Unix timestamp in milliseconds, for when this location was recorded.

Hours: CumulativeOperatingHours, CumulativeIdleHours, ...

In general, the field CumulativeOperatingHours is the most interesting: this is the total amount of hours for the machine. Other fields might be present as well, if those datapoints are available for this machine, such as CumulativeIdleHours, CumulativeIdleNonOperatingHours, CumulativeProductiveHours, CumulativeMovingHours, etc. The general format of the Hours fields is:

Field

Example

Description

Hour

42.12

Decimal amount of hours.

datetime

1604042795000

Unix timestamp in milliseconds, for when this datapoint was recorded.

Machine Insights

The main fields (around 80 in total) all describe some aspect of semantic data about a machine: FuelRemaining, EngineStatus, Distance travelled, etc. The availability of these datapoints will vary depending on the source of the telematic data (be it GPS, CAN-bus, ISO feed, etc.). The unit of measurement for each datapoint 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:

Field

Example

Description

Field with value (naming varies)

13.8
true

The value of the datapoint itself. Floating point or boolean.

unit (naming sometimes varies)

"km"
"volt"

The unit of measurement for this dataseries. Will always stay the same for the same field.

datetime

1604042795000

Unix timestamp in milliseconds, for when this datapoint was recorded.

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

CANMessages

📘

This is probably not the data you are looking for

In general most of the CAN data has been interpreted to Machine Insights by Trackunit, and it should only be necessary to look at the CANMessages themselves if something particular is needed. CANMessages are not normalized, and not data cleansed to the same degree.
You are probably looking for one of the other fields.

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:

Field

Example

Description

datetime

1604042795000

Unix timestamp in milliseconds, for when this datapoint was recorded.

UnitOfMeasurement

"%"
"rpm"

The unit of measurement, as specified in the CAN profile; not normalized.

VariableId

212

The internal Trackunit VariableId for this dataitem.

VariableName

"Engine Speed"

The name corresponding to the VariableId.

ParsedValue

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

Type

Fields

Description

CanMessageValue

value

A single value was picked up in the capturing interval.

CanMessageMinMax

MinValue
MaxValue

A minimum and maximum value was picked up in the capturing interval.

CanMessageAccumulated

value

The 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:

Field

Example

Description

CanId

217056257

The CAN identifier of the data that was picked up.

SourceAddress

0

The CAN source address of the data that was picked up.

BinaryValue

The bits themselves that was picked up.

Counter

1234

The number of data items that where seen in the capturing period matching this CAN data item.

CapturingPeriod

120

The 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 occured on a machine; typically because it was present on the CAN bus, but could also be imported from an ISO feed, or similar. Each element has the following fields:

Field

Example

Description

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.

datetime

1604042795000

Unix timestamp in milliseconds, for when this fault started appearing.

datetimeCleared

null
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 outher 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).