How a vehicle's computer system actually works

Written for software engineers who know networks and protocols but have never put a scope on a CAN bus. Everything here is grounded in the TARS codebase and in real captures from a 2013 Cadillac SRX — the addresses, the negative responses, and the bugs are the ones we actually hit.

Every layer below adds one specific capability, and every layer has a way to fail that looks exactly like "the car isn't there." Understanding which layer is failing is the entire skill.

The stack, in one view

Click any layer to jump to it. Each row names the closest thing in web engineering — the analogies are imperfect but they get you oriented fast.

What "connecting to the car" actually means

Three very different activities get collapsed into that one phrase. Distinguishing them is the first thing to internalise:

Most consumer scan tools do #1. openpilot-class work lives in #2. TARS does all three, and the third one is where essentially all of the engineering difficulty sits.

Wires and buses — there is more than one network

The single biggest misconception: that "the OBD port" is one network. It is a connector that exposes several physically separate networks on different pins, running at different speeds, carrying different modules.

Why the adapter can only be on one bus at a time

A J2534 pass-thru device opens one protocol channel per physical channel. Reaching the single-wire GMLAN bus means tearing down the 500k HS-CAN channel and reconnecting with SW_CAN_PS at 33.3 kbit/s. That is a real, user-visible mode switch — TARS surfaces it explicitly rather than hiding it:

// One J2534 device serves one channel at a time, so reaching the single-wire
// (LS-GMLAN) modules means moving the RLink off the HS bus — a stop + restart
// with single_wire, reusing the current backend/channel.
await fetch("/api/can/start", { method: "POST", body: JSON.stringify({
  backend,
  channel,
  bitrate: wantSingleWire ? 33300 : 500000,
  listen_only: false,   // active — a scan must transmit
  single_wire: wantSingleWire,
})});

And in the sidecar, the constraint is enforced at the driver level — not every J2534 DLL even declares single-wire capability:

if self._single_wire and not self._dev.protocols.get("SW_CAN_PS"):
    raise J2534Error(
        f'J2534 driver "{self._dev.name}" does not declare SW_CAN_PS, so it '
        "cannot open the single-wire (LS-GMLAN) bus.")

Adapter classes, and what each can actually do

TARS treats these as peers and selects the best transport per task — see the architecture section. An ELM327 in monitor-all mode is silent: it does not transmit, and it does not even ACK frames, which makes it the safest possible thing to hang on a customer's live bus. It also means it can never run a module sweep.

CAN frames — broadcast to everyone, addressed to no one

A CAN frame is astonishingly small and astonishingly dumb. Everything above it is a convention layered on top by people who wanted it to do more.

What is not in a CAN frame

This list is the whole reason vehicle diagnostics is hard:

• No source address. You cannot ask "who sent this."
• No destination address. Everything is a broadcast; addressing is a convention layered on top by assigning IDs.
• No session, no connection, no sequence numbers. Above 8 bytes, ISO-TP invents all of that.
• No type information. Byte 3 of frame 0x3E9 means whatever the OEM's internal spec says. That spec is not public.
• No authentication of any kind. Anything on the bus can claim to be anything.
• No error semantics. A module that ignores you is indistinguishable from a module that isn't installed.

Passive listening — total visibility, zero meaning

Put the adapter in listen-only mode and you receive every frame every module broadcasts. Nothing you do can affect the vehicle. This is where Cardog's openpilot-lineage work lives, and it is a completely different problem from diagnostics.

Decoding: the actual work

Turning a passive capture into signals is a reverse-engineering problem with three standard approaches, all of which TARS implements:

ecus:
  - response_id: 0x7E8
    request_id:  0x7E0
    name: ECM
    kind: physical_11
    services:
      - sid: 0x01
        name: OBD2_ShowCurrentData
        request_count: 560
        response_count: 551
        pids:
          - pid: 0x0C
            name: EngineRPM
            sample_decoded: { value: 871.5, unit: rpm }

OBD-II — the 5% that's guaranteed to work

OBD-II exists because of emissions regulation, not because anyone wanted to give you a diagnostic API. It is narrow, fixed, universally supported, and almost never enough.

The addressing scheme is arithmetic, and that's the whole trick

Requests go to one of nine well-known IDs; responses come back at request + 8. There is no negotiation and no discovery:

The modes, and what each is actually for

Capability discovery: the supported-PID bitmap

OBD-II does have one genuine discovery mechanism. Ask for PID 0x00 and the ECU returns a 4-byte bitmap of which PIDs in 0x01–0x20 it supports; PID 0x20 gets you the next block, and so on. TARS walks all seven blocks per ECU:

ranges = [0x00, 0x20, 0x40, 0x60, 0x80, 0xA0, 0xC0]
for base in ranges:
    send_isotp(0x7DF, bytes([0x01, base]))          # functional broadcast
    # SF: data[1] = 0x41 (mode+0x40), data[2] = base, data[3..6] = bitmap A..D
    for i, b in enumerate(bitmap):
        for bit in range(8):
            if b & (0x80 >> bit):
                supported.add(base + 1 + i*8 + bit)

ISO-TP — the layer that eats engineers

A CAN frame carries 8 bytes. A VIN is 17. A DTC list can be 60. ISO 15765-2 is the segmentation-and-reassembly protocol that bridges the gap — and it is where the most instructive bug in this entire codebase lived.

Four frame types, encoded in one nibble

The first data byte of a diagnostic frame is the PCI (Protocol Control Information). Its high nibble is the frame type:

# A response longer than 7 bytes arrives as First Frame + Consecutive
# Frames, and ISO 15765-2 makes the RECEIVER responsible for releasing the
# CFs: the ECU sends the FF and then waits (N_Bs, typically 1s) for our Flow
# Control before sending anything more. Without this the ECU stays silent,
# the reassembly never completes, and the request times out — which is why
# every short reply (session control, seed request, TesterPresent) worked
# while every real payload (VIN, DTC list, ECU part numbers, memory reads)
# appeared dead.
iso_frame = parse_frame(data)
if iso_frame is not None and iso_frame.kind == FrameType.FF:
    self._send_frame(physical_request_id(request_id, response_id),
                     build_flow_control(), is_extended)

Note physical_request_id(). Flow control is point-to-point, so if the original request went out as a functional broadcast (0x7DF), you cannot send the FC there — every other ECU would see it. You have to invert the responder's ID back to its physical request ID. That's a second, subtler correctness trap sitting right behind the first one.

Block size and STmin — the ECU throttles you

The FC frame carries two parameters the tester must honour when sending a long request:

• BS (block size) — how many consecutive frames you may send before waiting for another FC. BS=0 means "send it all." Blasting past a non-zero BS overruns the ECU's buffer and the transfer is silently dropped.
• STmin — minimum inter-frame gap. Encoded weirdly: 0x00–0x7F is milliseconds, but 0xF1–0xF9 is 100–900 microseconds. Getting that decode wrong makes you 100× too slow or 100× too fast.
• FlowStatus WAIT (PCI byte 0x31 — frame type 3, status 1) restarts the clock: the ECU is asking for more time, not refusing. OVERFLOW (0x32) is fatal. CTS is 0x30.

UDS — sessions, security, and the honest "no"

ISO 14229 is what professional tools actually speak. It is a proper request/response protocol with an error model — and the errors are frequently more informative than the successes.

The response convention

request  22 F1 90
response 62 F1 90 31 47 4B ...
          ↑ 0x22 + 0x40

request  22 F1 90
response 7F 22 31
          ↑    ↑   ↑ NRC: requestOutOfRange
          │    └ the service you asked for
          └ always 0x7F

Services you'll meet

TARS' adaptive retry path treats the dangerous half of that table as off-limits by construction — a policy object, not a code review convention:

safety: {
  // Keep high-risk UDS services out of the adaptive retry path.
  blockedServices: ['10','11','14','27','28','2E','2F','31','34','36','37','85']
}

Negative response codes — searchable

Reading NRCs fluently is most of the job. Filter the table:

OEM dialects — same wire, four different address books

This is the part nobody warns you about. ISO 15765 standardised the powertrain slots and nothing else. Every manufacturer built their body/chassis network on their own addressing scheme, and several predate the standard entirely.

Four arithmetic rules, and none of them is discoverable

Each scheme relates a request ID to a response ID by fixed arithmetic. Knowing the rule is the difference between finding a module and concluding the bus is empty:

These live in one place in the codebase, with the reasoning attached — because six months later nobody remembers why 0x400 and not 0x8:

GMLAN legacy (GM Global A body/chassis modules — the ones ISO 15765 never
reaches, which is why a plain OBD-II scan sees only powertrain):
    Functional (all-node) request: 0x101
    Physical request:              0x241..0x25F   (GM assigns per module)
    Physical response:             request + 0x400 (0x641..0x65F)

The +0x400 relationship is GMLAN's analogue of ISO's +8: it is arithmetic, so
we can invert a response id to its request id without a lookup. Which module
sits at which 0x24x slot is NOT arithmetic — GM assigns it per vehicle — so the
named pairs below are documented Global A defaults, confirmed or corrected by
live discovery.

Different dialects also mean different services

GMLAN-era modules predate UDS and use GM's own service set. Same bus, same ISO-TP, entirely different service IDs for the same conceptual operation:

The identity block is the practical payoff. GM modules publish who built them and what they are via $1A:

(0xB0, "GM module id")            (0x9A, "Hardware version")
(0x90, "VIN (as stored)")         (0x9B, "Software module id")
(0x92, "Supplier + base part")    (0x9C, "Boot software id")
(0x97, "End-model part number")   (0xB4, "ECU serial (traceability)")
(0x98, "Diagnostic address / mfg") (0xC1, "Calibration / build")
(0x99, "Manufacturing date")      (0xCB, "ECU diagnostic spec")

VAG modules publish the same class of information through standard UDS DIDs ($F187 part number, $F189 software version, $F197 system name). TARS tries both conventions on every responder and keeps whichever answers — a module only speaks one of them, so the empty one simply drops out.

Module discovery — nmap, but the network can hurt someone

There is no registry. Nothing on the vehicle will tell you which modules are installed. You find out by asking, one address at a time, and interpreting silence correctly.

Why the obvious approach fails

The textbook method is a functional broadcast: shout 3E 00 at 0x101 and collect whoever answers. On GMLAN this returns nothing, and it took real bench time to understand why:

tester → 0x101 3E 00
(1.5 s of silence)
→ 0 responders

tester → 0x241 3E
0x641  → 7E        (positive)
tester → 0x242 3E
0x642  → 7E
... one unicast per id ...

"""Discover modules by PHYSICALLY addressing each request id in a range.

This is how a scan tool actually finds GM body/chassis modules, and it
is more reliable than a functional broadcast for GMLAN: those modules
commonly suppress the positive response to a functional TesterPresent
(so 0x101 enumeration comes back empty) yet answer a physical request on
their own id immediately.

Read-only: bare TesterPresent actuates nothing."""
for req in range(start_id, end_id + 1):
    resp_id = infer_response_id(req)          # req + 0x400 for GMLAN
    res = self.request(req, b"\x3e", response_id=resp_id, timeout=0.5)
    if res.timed_out: continue
    # a negative response still proves the module is present

The correlation problem — and a bug worth stealing

Here is a failure mode that will bite anyone building this. Response CAN IDs are shared. Every tester on the bus gets its Mode 01 answers from 0x7E8. If your own app is polling live data in another thread — or the shop's other scan tool is plugged in — a frame arriving at the ID you're watching is not necessarily your answer.

The fix is a per-service table of how many bytes a positive response echoes back, and refusing to accept anything that doesn't match:

0x01: 1,  # OBD-II Mode 01 — PID
0x02: 2,  # Mode 02 freeze frame — PID + frame number
0x1A: 1,  # GM legacy ReadDataByIdentifier — identifier
0x22: 2,  # ReadDataByIdentifier — DID
0x31: 3,  # RoutineControl — controlType + routine id
# 0 (or absent) means the service echoes nothing identifying, so
# service-level correlation is all that is available — that is the honest
# default for the transfer services, not an oversight.

There's a further subtlety: the suppressPosRspMsgIndication bit (0x80) lives in the sub-function byte of the request and is not echoed back, so it has to be masked out of the comparison for services like $10, $11, $19, $27, $3E.

From "something answered" to "this is an ABS module"

A responding address is not an identification. TARS separates hints from evidence, and this is the design pattern to carry into any fleet-scale tooling:

Capability probing without touching anything

Once a module is found, TARS classifies which services it answers — using NRCs as a read-only probe. Nothing is actuated; the module's refusal is the measurement:

def _service_state(payload):
    res = self.request(request_id, payload, ...)
    if res.timed_out:   return "no-response"
    if res.is_negative:
        return "absent" if res.nrc == 0x11 else f"present (NRC 0x{res.nrc:02X})"
    return "present"

services = {
  "dtc_read_A9":       _service_state(b"\xA9\x81\x12"),
  "read_data_by_packet_AA": _service_state(b"\xAA"),
  "read_data_by_id_22":  _service_state(b"\x22\xF1\x90"),
}

Only NRC 0x11 means "this module doesn't have that service." Every other NRC means the service exists and the module declined this particular call — which is a completely different fact, and one that a naive implementation throws away.

Walkthrough: sweeping a 2013 Cadillac SRX

Everything above, applied. This is real output from the TARS Module Scan against the LS-GMLAN single-wire bus — the bus a generic scan tool cannot physically reach.

What the tool had to do before a single probe went out

1. Check the capture's current state — which backend, which channel, which bus, listen-only or active.
2. Recognise that the app's own bring-up leaves the capture passive, and a sweep must transmit.
3. Stop the HS-CAN capture, restart on single_wire at 33,300 bit/s with listen_only: false.
4. Verify the J2534 driver declares SW_CAN_PS — not every PassThru DLL does, and the sidecar refuses rather than silently opening the wrong bus.
5. Warn the operator that the HS-CAN view is now dark.
6. Then, and only then, send 31 unicast TesterPresent probes across 0x241–0x25F.

Reading the results

Thirteen modules answered on a bus that OBD-II describes as not existing. Three findings are worth pulling out:

Drilling into one module: the SDM at 0x243

Selecting a module runs the full $1A detail block plus a capability probe. The airbag module (Sensing & Diagnostic Module) returned this:

An engineer new to this reads that right-hand column as three failures. It is the opposite — it's three distinct, actionable facts:

How TARS is put together

Everything above has to be reachable by a voice agent mid-conversation, on a laptop, in a bay, over one of five possible physical transports. The architecture exists to make that tractable.

Why a single tool table matters

The same 25 operations have to be callable from a Claude MCP client, from an OpenAI realtime voice agent, and from React panels. Three copies of those schemas is three chances to drift. The file's own header states the constraint:

// That is why each entry carries a pure `request(args)` builder instead of a
// `call(args)` that performs I/O: the table describes WHAT to ask for
// (backend, method, path, body, timeout) and each consumer owns HOW the
// request travels. Keep this file free of imports and side effects — it must
// load in node and in the browser bundle alike, and a second copy of these
// schemas is exactly the drift this table exists to prevent.

The transport abstraction

A technician says "pull the codes." The agent calls one tool. Underneath, that might be Web Bluetooth in a browser, a serial port in the Electron main process, a TCP socket to a Wi-Fi gateway, or a J2534 DLL — and the answer has to look identical. Two mechanisms make that work:

• Unified service API. A single diagnostic interface presents the same methods regardless of which transport is live; adapters are peers, and the best one for the task is selected rather than hard-coded.
• Single-port handoff. A vLinker/ELM327 speaks over one COM port. TARS releases the OBD-II link before handing that same port to the CAN sidecar for raw monitoring, then takes it back. Two processes, one physical resource, explicit ownership transfer.

Why this is genuinely hard

Not "hard" as in tedious. Hard as in the problem has properties that most software problems don't.

Effort does not track coverage

The legislated 5% of vehicle data is the easy 5%. Everything past it is bespoke per manufacturer, per platform, per model year:

The nine properties that make it hard

What "read-only" has to mean architecturally

Three independent mechanisms, because one is not enough:

1. Probe choice. The sweep uses a bare $3E TesterPresent. It cannot actuate anything, by construction. Not "we're careful" — the payload has no destructive interpretation.
2. Policy blocklist. Twelve high-risk service IDs are excluded from the adaptive retry path in configuration, not in a comment.
3. Honest reporting. DTC reads are attempted and the exact outcome is reported — positive, NRC, or timeout — rather than assumed. From the source: "GMLAN body modules commonly refuse a DTC read with conditionsNotCorrect while the engine runs, and saying so is more useful than pretending it worked."

Glossary

Source map — where each layer lives in the repo

The protocol behaviour, addresses, service tables and code quotations in this document trace to these files in versions/openai-realtime-agents.

Prepared for the Cardog team · August 2026.
The module list, GM module ids, supplier strings and the SDM identity and capability block in the walkthrough are from a live capture on a 2013 Cadillac SRX. The CAN-frame inspector, the OBD-II addressing diagrams, the ISO-TP stepper and the passive-index sample are constructed for teaching: the framing and addressing rules in them are exact, the specific byte values are illustrative.