Evidence-backed, AI-assisted CAN/LIN research that becomes more useful every time you use it.
VehicleBusLab is not trying to replace the engineering tools you already use.
Good engineering rarely works that way.
Use SavvyCAN when it is the best viewer. Use OEM software when it solves the problem faster. Keep using your existing DBCs, manuals, Python scripts, CAN tools, oscilloscopes, loggers and development environments.
VehicleBusLab is designed to complement that workflow so well that it becomes the place you start an investigation — and the place the investigation returns to.
I want it to work that way because I built it for the same reason I expect others will use it: I needed a better way to carry my own research forward without losing the evidence, context and decisions between experiments.
VehicleBusLab retains the evidence, references, experiment context and engineering knowledge that would otherwise end up scattered between captures, scripts, chats and notes.
Start in VehicleBusLab
↓
What do we already know?
↓
What do we need to test?
↓
Use the best tool for that step
↓
Bring the evidence back
↓
Compare / hypothesize / confirm
↓
Next experiment starts from everything already learned
For one quick CAN signal, an adapter, a script and an AI assistant may still be faster.
VehicleBusLab starts to make sense when there will be a second experiment.
The first experiment may take more setup.
The second should be easier.
The tenth should begin with everything already learned.
The agent reasons. VehicleBusLab remembers. You decide what is proven.
Current status: Host package 0.2.0 — docs/CURRENT_BASELINE.md · Agent workflows: skills/README.md
| Path | What you need |
|---|---|
| CAN-only research | Extract or clone → setup.cmd → configure <cansub-host>.local if using live CAN → start-vehiclebuslab.cmd → onboarding Skill |
| Optional S32 CAN/LIN | Above + NXP S32DS/RTD (install separately) → firmware/README.md → S32 setup Skill |
Local capture and CLI do not require ChatGPT. AI/MCP is optional. You confirm what is proven; the agent does not.
Public engineering snapshot: docs/PUBLIC_SNAPSHOT.md · Windows release build: docs/RELEASE_PACKAGING.md.
Reverse engineering should not begin by rediscovering information you already possess.
VehicleBusLab can bring existing engineering material into the research environment, including:
- existing DBC files;
- OEM manuals;
- protocol documentation;
- technical notes;
- standards and other reference material available to you.
The supplied Reference Builder workflow turns this material into structured reference knowledge that VehicleBusLab can query during later investigations.
Existing DBCs
OEM documentation
protocol manuals
technical references
↓
Reference Builder
↓
VehicleBusLab reference knowledge
↓
known-first research
That changes the first question from:
“What is this CAN frame?”
to:
“What do we already know about this traffic?”
Reference knowledge remains separate from captured evidence, so VehicleBusLab can still distinguish between:
- what documentation says;
- what the machine actually did;
- what deterministic analysis derived;
- what the current research hypothesis says;
- what the engineer has actually confirmed.
Real machines rarely match one perfect generic DBC.
A working system may contain:
- standard J1939 traffic;
- OEM messages;
- proprietary signals;
- optional equipment;
- implement-specific traffic;
- configuration-dependent behaviour;
- undocumented signals discovered during research.
VehicleBusLab can progressively build knowledge about an individual asset and use both reference information and researched findings to produce a more useful DBC.
Existing DBCs
+
OEM documentation
+
captured traffic
+
researched behaviour
+
human-confirmed findings
↓
asset-specific VehicleBusLab knowledge
↓
custom DBC
Those DBCs are intended to continue into your normal engineering workflow.
Use them with:
- SavvyCAN;
- CANsub/web-based tools;
- Python CAN tooling;
- other DBC-aware software.
VehicleBusLab does not need to become the best graphing or visualization tool.
It can help create a better description of the actual machine, then let specialist tools do what they are already good at.
A DBC is therefore treated as an engineering output, not as the complete research record.
One of the hardest parts of vehicle-network research is correlating bus traffic with a physical action.
A CAN trace does not necessarily tell you exactly when the operator:
- moved a hydraulic lever;
- pressed a switch;
- enabled a section;
- opened a valve;
- changed a setpoint;
- triggered a machine state.
VehicleBusLab includes a local companion marker workflow for this problem.
During a guided experiment, the agent can tell the operator what action to perform.
The operator performs the action and presses MARK.
baseline traffic
↓
agent instruction
↓
operator action
↓
MARK
↓
response traffic
↓
recovery
↓
before / after comparison
The marker is intentionally honest.
It means:
“The operator marked the event here.”
It does not claim that the physical action occurred with bus-level timing precision.
What it gives the investigation is a useful timing anchor around which captured traffic can be compared.
For timing domains, synchronization and the limits of marker correlation, see docs/architecture/TIMING_MODEL.md.
The current Skills are packaged for ChatGPT because that is the first acceptance-proven agent workflow.
The engineering knowledge inside them is not intended to be locked to ChatGPT.
Each Skill also contains portability guidance describing the workflow contract another capable agent needs to preserve when rebuilding it in its own native structure.
That includes things such as:
- workflow purpose;
- required inputs and outputs;
- execution order;
- decision points;
- safety and authority boundaries;
- provenance rules;
- acceptance checks;
- information that must not be silently inferred or discarded.
The intended model is:
VehicleBusLab workflow knowledge
↓
ChatGPT Skill today
↓
another capable agent
↓
rebuild equivalent workflow
↓
same engineering intent and trust boundaries
The Skill format can change. The engineering workflow should survive.
ChatGPT is currently acceptance-proven on the testing bench. Other agent and connector combinations should be locally proven rather than assumed.
The same principle applies to the wider project:
The AI can change. The investigation should not disappear with it.
AI has made analysing CAN and LIN traffic much easier.
A capable model can already work with:
- CAN captures;
- individual frames;
- DBC files;
- Python scripts;
- protocol manuals;
- technical documentation.
For a small problem, that can work remarkably well.
The difficulty appears when the investigation continues.
You capture another operating condition.
Then another machine.
Then another configuration.
You test the same signal at several setpoints.
Another model looks at the evidence.
An OEM manual disagrees with what the bus appears to be doing.
You return two weeks later.
Soon the engineering record is scattered across:
captures
scripts
chat histories
screenshots
notes
DBCs
spreadsheets
memory
The problem is no longer:
“Can AI help decode this?”
It becomes:
“Can we preserve this investigation well enough that we still know what has actually been demonstrated?”
That is the problem VehicleBusLab is trying to solve.
VehicleBusLab keeps research state outside the AI conversation.
Close the chat.
Switch models.
Restart the PC.
Come back next week.
A fresh agent or another engineer should still be able to inspect:
- what was captured;
- which asset it came from;
- which experiment was being performed;
- which references were available;
- what the operator was instructed to do;
- where events were marked;
- what deterministic analysis found;
- what hypotheses were proposed;
- which evidence supports or contradicts them;
- what the engineer eventually confirmed.
VehicleBusLab does not merely remember conclusions.
It preserves the engineering trail behind them.
The AI conversation is useful.
It should not be the engineering record.
VehicleBusLab deliberately keeps different kinds of knowledge separate.
OBSERVED
↓
REFERENCE
↓
DERIVED
↓
HYPOTHESIS
↓
CONFIRMED
What was actually captured.
CAN frames, LIN-derived evidence, timestamps, operator markers and session metadata.
What an external source says.
DBCs, OEM manuals, standards and other supplied engineering material.
What deterministic analysis calculated.
Decoding, coverage, statistics, timing relationships, comparisons and other repeatable results.
What may explain the observed behaviour.
Hypotheses can retain supporting, contradicting and neutral evidence from multiple experiments.
What the engineer has explicitly accepted as proven.
The AI does not silently promote its own interpretation into confirmed engineering knowledge.
Human confirmation remains a deliberate authority boundary.
Deeper model: docs/architecture/KNOWLEDGE_AND_PROVENANCE_MODEL.md.
Traditional CAN tools naturally work around:
- frames;
- traces;
- messages;
- plots;
- DBCs;
- individual captures.
VehicleBusLab uses all of those where useful.
But its larger unit of work is the investigation.
A real research problem may look more like:
reference documentation
+
capture A
baseline condition
+
capture B
operator action
+
capture C
different setpoint
+
comparison
+
hypothesis
+
controlled experiment
+
response evidence
↓
confirmed behaviour
A single log can contain useful evidence.
It is rarely the complete engineering story.
Suppose you want to determine which CAN signal changes when a hydraulic lever is moved.
A quick capture may reveal several candidate bytes.
That is useful.
But the engineering question is:
Which candidate consistently represents the behaviour we care about?
VehicleBusLab can help structure the investigation:
- inspect existing asset knowledge;
- check imported references first;
- start a retained session;
- record a baseline;
- guide the operator through a controlled action;
- record a companion marker;
- capture response and recovery;
- compare before and after traffic;
- create or update a hypothesis;
- link evidence to that hypothesis;
- design another test;
- repeat under a different condition;
- leave final confirmation to the engineer.
The passive research loop becomes:
observe
→ hypothesize
→ plan
→ test
→ capture
→ compare
→ refine
→ repeat
Where controlled transmission is appropriate and explicitly enabled, the research loop can extend to:
observe
→ hypothesize
→ plan
→ preview
→ approve
→ execute
→ capture
→ compare
→ refine
VehicleBusLab is being built for running an investigation, not merely examining a trace.
No engineering product solves every problem.
VehicleBusLab does not try to.
A normal investigation may move between several tools:
VehicleBusLab
↓
inspect existing research
SavvyCAN
↓
quick visual exploration
VehicleBusLab
↓
record hypothesis
OEM diagnostic software
↓
change machine state
VehicleBusLab companion
↓
MARK the action
CANsub / capture
↓
collect evidence
VehicleBusLab
↓
compare and retain result
S32DS
↓
develop embedded implementation
VehicleBusLab
↓
retain research handover
That is intentional.
VehicleBusLab is designed to complement an engineering workflow so well that it becomes the first place you start — not the only place you work.
VehicleBusLab currently uses CANsub.2 as its primary proven CAN acquisition hardware.
That relationship is intentionally complementary.
CANsub.2 provides the physical connection to the CAN network.
VehicleBusLab adds the retained investigation around it.
vehicle CAN
↓
CANsub.2
↓
timestamped evidence
↓
VehicleBusLab
↓
retained investigation
VehicleBusLab gives CANsub hardware another way to be useful.
It does not attempt to make the hardware unnecessary.
The accessible CANsub API is one of the reasons this architecture works well.
CANsub.2 is physically proven on the testing bench. Other adapter and topology combinations may be supported in software but are not all acceptance-proven.
See docs/CURRENT_BASELINE.md for the current qualification boundary.
The optional S32 hardware is not required for CAN research.
For a CAN-only investigation:
machine CAN
↓
CANsub.2
↓
VehicleBusLab
↓
AI-assisted research
The CAN-only workflow supports areas including:
- retained multi-session capture;
- imported references;
- asset history;
- J1939 research;
- unknown traffic analysis;
- guided experiments;
- companion markers;
- comparisons;
- hypotheses;
- evidence relationships;
- confirmed findings;
- DBC planning and generation.
If the job only involves CAN, stop there.
Adding LIN to a research setup can become expensive if dedicated multi-bus logging hardware is required.
VehicleBusLab supports an optional NXP FRDM-A-S32K312 development board as a LIN research extension.
The board provides:
- two LIN interfaces;
- CAN;
- an automotive MCU;
- programmable acquisition and research behaviour.
The S32 does not replace CANsub.2.
It complements it.
machine CAN ───────→ CANsub.2 ────────┐
│
LIN ───────────────→ S32K312 ├──→ VehicleBusLab
│ │
└ research CAN┘
The result is a comparatively inexpensive path to investigating behaviour that crosses CAN and LIN.
CANsub remains the CAN observation interface.
The S32 adds LIN-derived evidence when required.
This allows investigations such as:
operator input
↓
LIN switch module
↓
controller
↓
CAN
↓
another ECU
↓
actuator response
without making embedded hardware a requirement for every CAN-only user.
Timing and correlation details: docs/architecture/TIMING_MODEL.md.
VehicleBusLab tries not to reverse-engineer something that is already documented.
Imported references are checked before traffic is treated as unknown.
captured traffic
+
reference knowledge
↓
known traffic
+
unknown remainder
↓
research effort
This concentrates engineering effort on the part of the network that actually requires investigation.
The source of that knowledge remains visible.
An OEM manual describing a signal is still REFERENCE.
A captured frame is still OBSERVED.
A researched interpretation remains a HYPOTHESIS until the engineer decides that the evidence is sufficient to confirm it.
VehicleBusLab can associate research with real equipment.
An asset may represent:
- a tractor;
- an implement;
- an ECU;
- a controller;
- another machine or network configuration.
Over time an asset can accumulate:
sessions
references
observed nodes
known signals
unknown traffic
research notes
hypotheses
comparison evidence
confirmed findings
custom DBC knowledge
That allows the project to progressively develop a better model of the actual machine being investigated.
Not simply an idealized generic protocol.
A DBC is excellent for representing CAN messages and signals.
It is not designed to preserve:
- why a signal interpretation exists;
- which experiment discovered it;
- contradictory evidence;
- uncertainty;
- operator events;
- research history;
- provenance.
VehicleBusLab retains that information separately.
Suitable reference and confirmed knowledge can then be projected into a DBC for use by conventional CAN tools.
That allows the DBC to do what it does well without asking it to become the entire research database.
VehicleBusLab exposes deterministic research operations to capable AI agents.
An agent can help:
- inspect existing knowledge;
- query reference coverage;
- plan captures;
- start and stop sessions;
- guide experiments;
- query markers and timelines;
- compare evidence;
- maintain research queues;
- create hypotheses;
- link evidence;
- plan controlled experiments.
But the agent is not:
- the raw evidence store;
- the source of truth;
- the owner of confirmed engineering knowledge.
The retained project remains useful if you:
- change AI model;
- change agent platform;
- rebuild a Skill for another agent;
- use the CLI directly;
- hand the investigation to another engineer.
The intelligence can change.
The engineering record remains.
VehicleBusLab currently ships ChatGPT-oriented Skills for workflows that would otherwise require remembering setup details, commands and ordering.
| Skill | Purpose |
|---|---|
| VehicleBusLab onboarding | Install, configure, connect and prove the first CAN capture |
| S32K312 setup | Optional CAN/LIN hardware and toolchain setup |
| Reference builder | Convert DBCs, manuals and documentation into reusable reference knowledge |
| Research orchestrator | Run known-first, evidence-backed research investigations |
Each Skill also contains the portable workflow knowledge needed for another capable agent to reconstruct an equivalent workflow in its own preferred format.
The goal is not to make VehicleBusLab dependent on one AI product.
The goal is to make the research method reusable.
Human-facing guide: skills/README.md.
VehicleBusLab takes more setup than dropping a CSV into a Python notebook.
That is a deliberate trade.
A working installation can retain:
- hardware configuration;
- acquisition setup;
- references;
- asset history;
- confirmed findings;
- research state;
- agent integration.
install
→ configure hardware
→ connect agent
→ import references
→ first retained capture
→ first investigation
start-vehiclebuslab.cmd
→ status.cmd
→ existing hardware
→ existing references
→ existing research
→ continue investigation
The setup only makes sense if its value compounds.
That is the design target.
Connector setup: docs/MCP_CONNECTOR_SETUP.md
Restart and recovery: docs/CONNECTOR_RESTART_RECOVERY.md
VehicleBusLab is passive-first.
Listening and understanding remain the normal starting point.
For controlled research environments, policy-gated CAN transmission is also available.
Current scoped bench-proven primitives include:
can_tx_once
can_tx_periodic
can_tx_sequence
Control passes through the same pipeline:
request
→ validate
→ policy
→ prepare
→ execute
→ audit
Transmission remains default OFF.
Its purpose is experimental validation.
For example:
“If this candidate byte is changed within these approved limits, does the expected response occur?”
That is different from unrestricted CAN injection or production machine control.
VehicleBusLab is a research environment.
Bench evidence:
- CAN TX acceptance
- CAN TX sequence qualification
- Closed-loop experiment acceptance (single iteration)
- Phase 6 structured multi-iteration acceptance
VehicleBusLab includes foundations for structured CAN experiments.
An experiment can describe:
- the hypothesis;
- target bus and channel;
- baseline observation;
- proposed stimulus;
- permitted CAN IDs;
- permitted byte ranges;
- rate and duration limits;
- maximum frame count;
- abort conditions;
- iteration limits.
The workflow becomes:
hypothesis
↓
experiment plan
↓
guardrails
↓
preview
↓
human approval
↓
controlled execution
↓
captured response
↓
comparison
↓
evidence
↓
(optional) prepare → apply → approve next iteration → run again
Multi-iteration research is human-gated at each physical step: child iterations are persisted separately, approved separately, and executed via run_can_experiment_sequence with an explicit channel/events envelope that must exactly match the approved persisted plan (MCP CONTROL — not opaque IDs alone).
An important distinction remains:
Approving an experiment is not the same as confirming a finding.
The experiment may support or contradict a hypothesis.
The engineer decides when the evidence is sufficient to call the behaviour confirmed.
The canonical source for what is proven, shipped, planned or not yet enabled is:
Broadly, VehicleBusLab currently includes:
- retained multi-stream CAN sessions;
- session manifests and catalog;
- recorder daemon;
- start/stop orchestration;
- markers;
- stream-aware analysis;
- CANsub acquisition.
- explicit clock domains;
- timestamp mapping;
- normalized timelines;
- materialized timelines;
- marker-window analysis;
- cross-stream correlation;
- before/after comparisons.
- assets;
- reference sources;
- reference bundle import;
- known-first J1939 decoding;
- unknown traffic research;
- research queues;
- hypotheses;
- evidence links;
- comparison evidence;
- human-confirmed findings;
- DBC generation.
- guided runs;
- retained experiment context;
- local companion markers;
- agent-orchestrated research workflows.
Scoped bench proof exists for:
- one-shot CAN TX;
- periodic CAN TX;
- timed CAN sequences;
- same-channel duplex capture and TX;
- human-approved experiment creation, preview, approval, execution and comparison;
- structured
byte_valuesmulti-iteration orchestration on Office CANsub.2 (Phase 6 CLOSED / PASS) — deterministic compile, persisted child iterations, explicit execution envelope, CL1000 bus confirmation;byte_range/bit_togglecompiler-proven in tests (not separately live-signed).
- passive LIN receive;
- timestamps;
- LIN-derived evidence;
- CAN/LIN research correlation.
VehicleBusLab does not currently claim:
- production machine control;
- unrestricted autonomous CAN experimentation;
- LIN TX execution;
- replay execution;
- complete support for every CAN adapter;
- complete J1939 or ISOBUS knowledge;
- CANsub.4 hardware qualification;
- perfect physical-event timing from human markers;
- automatic proof that an AI hypothesis is correct.
Research remains evidence-driven.
A tool returning an answer is not the same thing as the machine proving it.
The useful endpoint is not simply:
“We decoded this frame.”
It is:
“We understand enough of this undocumented system to hand the behaviour to somebody else to implement.”
A mature research handover may contain:
- system and hardware topology;
- reference inventory;
- experiment matrix;
- confirmed messages and signals;
- addressing;
- timing;
- state behaviour;
- command/response relationships;
- counters and checksums;
- example traces;
- unresolved questions;
- safety assumptions;
- validation procedures;
- provenance back to the source evidence.
unknown system
↓
VehicleBusLab investigation
↓
evidence
↓
repeated experiments
↓
confirmed behaviour
↓
implementation specification
↓
embedded engineer / agent / other toolchain
VehicleBusLab should discover and document behaviour.
Another engineer or toolchain can implement it.
VehicleBusLab is aimed at technically capable people investigating real equipment where the work is likely to continue beyond one capture.
That may include:
- vehicle and machinery integrators;
- controls technicians;
- auto electricians;
- embedded engineers;
- independent researchers;
- small engineering businesses;
- advanced hobbyists;
- anyone reverse-engineering poorly documented CAN or LIN systems.
You should not need to abandon the tools you already know.
VehicleBusLab should make those tools more useful by giving the investigation somewhere to live.
The recommended route is agent-guided onboarding.
Tell your agent:
“Use the VehicleBusLab onboarding Skill and get me to a first successful CAN capture.”
Windows entry points:
| Command | Purpose |
|---|---|
setup.cmd |
First-time setup |
start-vehiclebuslab.cmd |
Start local services |
status.cmd |
Check core, recorder, MCP, CAN and configured AI connection |
Useful documentation:
- Installation
- Agent workflows
- Connector setup
- Restart and recovery
- Commands cheatsheet
- Current proven baseline
- Documentation index
VehicleBusLab grew from the ideas proven in CAN Research.
CAN Research established several useful principles:
- known-first analysis;
- raw evidence as authority;
- retained research knowledge;
- deterministic tools for AI agents;
- explicit hypothesis and confirmation boundaries;
- reusable Skills for repeatable workflows.
VehicleBusLab generalizes those ideas into a persistent multi-session research environment.
CAN Research
↓
repeatable evidence-backed workflow
↓
VehicleBusLab
VehicleBusLab does not require CAN Research at runtime.
VehicleBusLab is currently Windows-first and uses Python 3.11+.
For setup, commands and internal documentation, see:
- docs/INSTALLATION.md
- docs/COMMANDS_CHEATSHEET.md
- docs/README.md
- tools/firmware/README.md for optional firmware tooling
The architecture overview is in docs/architecture/PRODUCT_ARCHITECTURE.md and docs/architecture/HOST_ARCHITECTURE.md.
VehicleBusLab is passive-first.
Listening, recording, decoding and comparison are the normal starting point.
Active transmission is default-disabled and intended for controlled research under explicit policy and operator authority.
Production machine control, unrestricted machine-bus actuation and LIN master transmission are not normal enabled operating modes.
See docs/architecture/CONTROL_AND_TX_MODEL.md.
Third-party and reference information:
VehicleBusLab is designed to complement your existing engineering tools so well that it becomes the place you start an investigation, retain what you learn, and decide what to test next.
If all you need is one quick answer, use the simplest tool that gives it to you.
If the work will continue tomorrow:
keep the investigation.