Usage

Using the device

1. Connecting and powering

1. Power the device from a USB-C charger that supports the 12 V PD profile (20 W or more). That same voltage also powers the diagnostic tool, through pin 16 of the J1962 connector, exactly as in a vehicle.
2. Connect the diagnostic tool (an ELM327 adapter, a handheld scanner or another OBD-II tool) to the J1962 connector of the device with a standard OBD-II extension cable. The tool needs no supply of its own, the simulator gives it 12 V, current limited to 500 mA by a resettable fuse.
3. Towards the tool the simulator presents itself as an ECU with identifier 0x7E8 and answers functional (0x7DF) and physical (0x7E0) requests at 500 kbit/s.

2. User interface

The interface is operated by the physical controls along the right edge of the board - a 5-way switch for navigation (Y axis up and down, X axis left and right, and the centre click selects, meaning it opens a submenu or starts editing), an encoder for setting the value of the selected sensor, where each detent step moves the value from whatever the parameter already has and a faster turn gives a larger step, and the buttons CONFIRM (saves the change), CLEAR (cancels the change, and with no entry selected on the fault screen it asks for confirmation to erase the whole DTC memory) and RETURN (gives up and goes back to the previous screen). On the fault screen the click selects a code, and left and right take it from inactive through pending to confirmed and back.

The encoder push button is wired on the board, but the software assigns it no function for now. The OBD-II connector sits along the top edge, above the screen.

The main interface functions:

• Parameter overview - the current values of all 21 simulated PIDs, the same ones the diagnostic tool sees.
• Manual value entry - in the manual profile every parameter (speed, rpm, temperatures and so on) is set directly from the interface.
• Simulation profiles:
  • Manual - values stay put until the user changes them.
  • Idle - the rpm oscillates around 800 rpm, the coolant and the oil warm up exponentially towards operating temperature (time constant 180 s).
  • Driving profile - a driving cycle with accelerations and decelerations in which speed, rpm, load and air flow are physically coupled.
• Fault management (DTC) - activating a fault as pending or confirmed (which turns the MIL on), reviewing the bank and clearing it. The tool sees the number of confirmed faults and the MIL status in PID 0x01.

The values are refreshed every 100 ms (10 Hz), with a small random noise on the "live" sensors for plausibility.

3. Preloaded faults

The bank includes typical codes, for example:

DTC	Description
P0100	MAF sensor circuit malfunction
P0113	Intake air temperature sensor high input
P0128	Coolant temperature below thermostat regulating temperature
P0171	System too lean (bank 1)
P0301	Cylinder 1 misfire detected
P0420	Catalyst efficiency below threshold
P0455	EVAP system large leak detected
P0500	Vehicle speed sensor A malfunction
U0100	Lost communication with the ECM/PCM module

The bank supports up to 20 simultaneously active faults. Once a fault is confirmed, a freeze frame (mode 0x02) is stored as well, holding the values from the moment it appeared.

4. Scenarios and USB transfer

User scenarios are written in JSON format into the /scenarios folder of the internal filesystem (the external S25FL128L flash, 16 MB, FAT). They are exchanged with a computer in two ways:

• USB-C - PC link (MSC): pick PC link (USB-C disk) in the settings, after which the device reboots and appears to the computer as an ordinary USB disk holding the scenarios. After editing, safely eject the disk and press RETURN to return to the simulator.
• USB-A - USB stick: the USB stick: import/export scenarios items in the settings copy all *.json files between the root of the stick and the internal storage.

The ESP32-S3 has a single USB OTG controller, so the PC link and the stick are not used at the same time. The TS3USB221 analogue mux switches the controller between the ports, and the USB stick takes precedence.

A scenario defines the initial parameter values, the operating profile, the VIN and the faults to be activated. The vin field also changes what the device reports in mode 0x09, not only what is shown on the screen. If the field is absent, the factory VIN applies.

{
  "name": "Cold start with misfire",
  "profile": "idle",
  "vin": "WVWZZZ1KZAW000001",
  "sensors": {
    "coolant_temp_c": -10,
    "rpm": 1100,
    "fuel_level_pct": 65
  },
  "dtcs": [
    { "code": "P0301", "state": "confirmed" },
    { "code": "P0171", "state": "pending" }
  ],
  "mil_on": true
}

The keys of the sensors object are the named parameter identifiers (for example coolant_temp_c, rpm, vehicle_speed_kmh, throttle_pct, the full list is in the repository, firmware/include/sensor_meta.h), and the values are physical quantities (°C, rpm, % and so on). The conversion into raw bytes is done by the firmware, clamping to the permitted range of the parameter. The mil_on field is informational: the MIL turns on as soon as the scenario contains at least one fault in the confirmed state. Example scenarios are in the /scenarios folder of the repository.

A factory scenario is built into the firmware (it can be overridden by a factory.json file in the internal storage). Stored scenarios appear in the selection menu, and the last used one is loaded automatically on the next power-up. In the breadboard development build (without the S25FL128L and the USB hardware) persistent storage is not available, so the built-in scenario is used.

5. Supported diagnostic modes

Mode	Function	Status
0x01	Current readings (21 PIDs + support bit masks)	✅
0x02	Freeze frame	✅
0x03	Confirmed faults	✅
0x04	Clear faults + turn the MIL off	✅
0x07	Pending faults	✅
0x09	Vehicle identification (VIN over ISO-TP)	✅
0x05, 0x06, 0x08, 0x0A	-	❌ negative response 0x7F/0x11

6. Limitations

• Only the CAN protocol (ISO 15765-4) is implemented, so older vehicles with a K-line (ISO 9141-2 / ISO 14230) or a J1850 bus are not covered.
• A single ECU (0x7E8) is simulated. Support for multiple ECUs (0x7E8-0x7EF) is on the wish list, see Contributing if you want to help.