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).
Updated over 1 year ago