DTC File Structure¶
The DataPump Service exports Diagnostic Trouble Code (DTC) data as .json files.
Depending on the DataPump configuration, files may be delivered uncompressed or compressed with gzip (.json.gz).
Each file contains a set of events about active and completed DTC and lamp states.
Data becomes available once the device is configured for J1939 processing (see J1939 DM1 DM2) and the DataPump service for the DTC and lamp state dataset is enabled on the DataPlatform. Historic DTCs are not available. SPNs, controller names, and FMI descriptions are not included in the file — these must be resolved externally.
Data Model¶
DTCs are treated as events. A DTC can become active and subsequently completed, and lamp states are included in the same file. The file tracks state transitions with start and end times.
Each JSON file contains two top-level objects:
dtcs— contains DTC eventslamps— contains lamp state events
Both objects contain two arrays:
active— events that became active in this transmissioncompleted— events that were completed in this transmission
Note
All dtcs and lamps properties are mandatory. The active and completed arrays can be empty.
DM1/DM2 and DM53 DTCs are both included in the dtcs arrays without distinction. The same (source, SPN, FMI) triple may appear more than once in active[] if it originates from different sources. Consumers must account for this when processing DTC data.
JSON files are named by a randomly generated unique identifier (UUID), for example 3716b7cc-b44a-44c9-a69f-355e2887e865.
The contained object includes a version property identifying the file format version.
DTC Properties¶
Each DTC is represented by an object with the following properties:
| Property | Type | Description |
|---|---|---|
machine |
String | Machine identifier |
source |
Integer | Source address of the controller |
spn |
Integer | Suspect Parameter Number |
fmi |
Integer | Failure Mode Identifier |
start |
Integer | Unix timestamp in milliseconds when the DTC became active |
end |
Integer | Unix timestamp in milliseconds when the DTC was completed (completed DTCs only) |
A DTC event is identified by the combination of source, spn, and fmi. Two DTCs with the same source and spn but different fmi are treated as two independent, simultaneously active entries.
Lamp State Properties¶
Each lamp state is represented by an object with the following properties:
| Property | Type | Description |
|---|---|---|
machine |
String | Machine identifier |
source |
Integer | Source address of the controller |
type |
String | Lamp type: rsl, mil, awl, or protect |
lamp |
Integer | Lamp status: 0, 1, 2, or 3 corresponding to 0b00, 0b01, 0b10, 0b11 |
flash |
Integer | Flash status: 0, 1, 2, or 3 corresponding to 0b00, 0b01, 0b10, 0b11 |
start |
Integer | Unix timestamp in milliseconds when the lamp state became active |
end |
Integer | Unix timestamp in milliseconds when the lamp state was completed (completed states only) |
Lamp types according to the J1939 specification:
| Value | Description |
|---|---|
rsl |
Red stop lamp |
mil |
Malfunction indicator lamp |
awl |
Amber warning lamp |
protect |
Protect lamp |
A lamp state event is identified by the combination of source, type, lamp, and flash. A new event is recorded when this combination appears or disappears from the active set.
Transmission Behavior¶
A DTC or lamp state appears in the active array once — when it is first known to be active.
On subsequent restatements it will not appear again until it is completed.
Once closed, it appears in the completed array with both start and end timestamps.
Scenario 1: DTC Active and Completed in the Same File¶
If a DTC becomes active and completes within the same .clf file, it appears in both the active and completed arrays of the same JSON file.
.clf file
│
├── DTC becomes active
└── DTC completed
│
└──► Single JSON file
├── active: [ DTC ]
└── completed: [ DTC ]
Scenario 2: DTC Active and Completed in Different Files¶
If many .clf files are transmitted between the activation and completion of a DTC, the active and completed events appear in different JSON files.
.clf file 1 .clf files 2…N .clf file N+1
│ │ │
└── DTC active │ └── DTC completed
│ │ │
▼ │ ▼
JSON file 1 │ JSON file N+1
active: [ DTC ] │ completed: [ DTC ]
│
(no DTC events)
Example¶
The following example shows a JSON file containing active and completed DTCs and lamp states:
JSON Example Data (click to view)
{
"version": 3,
"dtcs": {
"active": [
{
"machine": "60334",
"source": 0,
"spn": 151,
"fmi": 981,
"start": 1500016040000
},
{
"machine": "843281",
"source": 12,
"spn": 961,
"fmi": 1423,
"start": 1500016046231
}
],
"completed": [
{
"machine": "60334",
"source": 0,
"spn": 198,
"fmi": 3,
"start": 1500016040000,
"end": 1500016046231
},
{
"machine": "843281",
"source": 12,
"spn": 11,
"fmi": 3,
"start": 1500016046231,
"end": 1500016046231
}
]
},
"lamps": {
"active": [
{
"machine": "60334",
"source": 0,
"type": "mil",
"lamp": 0,
"flash": 1,
"start": 1500016040000
},
{
"machine": "60334",
"source": 0,
"type": "rsl",
"lamp": 1,
"flash": 0,
"start": 1500016040000
},
{
"machine": "60334",
"source": 0,
"type": "awl",
"lamp": 0,
"flash": 0,
"start": 1500016040000
},
{
"machine": "60334",
"source": 0,
"type": "protect",
"lamp": 1,
"flash": 1,
"start": 1500016040000
},
{
"machine": "97976",
"source": 0,
"type": "awl",
"lamp": 1,
"flash": 1,
"start": 1500016050000
}
],
"completed": [
{
"machine": "60334",
"source": 0,
"type": "mil",
"lamp": 1,
"flash": 1,
"start": 1500016040000,
"end": 1500016040000
}
]
}
}