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:
| 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. |
LocationMetadata
Contains additional information about the Location.
| Field | Example | Description |
|---|---|---|
| AccuracyRadius (optional) | 10.0 | Accuracy of the location defined as a radius in metres. Corresponds to the Estimated Horizontal Position Error (EHPE) from GPS. |
| HighAccuracy (optional) | true | Whether 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.
| Field | Example | Description |
|---|---|---|
| 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. |
| datetime | 1604042795000 | Unix 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.
| Field | Example | Description |
|---|---|---|
| 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 |
| Success | true | Boolean value for whether the operation was successful. |
| datetime | 1604042795000 | Unix 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:
| Field | Example | Description |
|---|---|---|
| Hour | 42.12 | Decimal amount of hours. |
| datetime | 1604042795000 | Unix 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:
| Field | Example | Description |
|---|---|---|
| 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. |
| datetime | 1604042795000 | Unix 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:
| Field | Example | Description |
|---|---|---|
| datetime | 1604042795000 | Unix timestamp in milliseconds, for when this data point was recorded. |
| UnitOfMeasurement | "%" "rpm" | The unit of measurement, as specified in the CAN profile; not normalized. |
| VariableId | 212 | The internal Trackunit VariableId for this data item. |
| 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 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:
| 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 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).
Updated about 2 months ago