CANTrak
Documentation

Setup & Usage Reference

Everything you need to install CANTrak, connect your hardware, and run your first capture session.

Active Development — docs may change
Overview

What CANTrak does

CANTrak is a Python-based CAN bus diagnostic platform that captures live network traffic and analyzes it through pattern recognition and payload transition analysis. It does not require manufacturer-specific databases or proprietary network definitions.

The software is designed to answer three questions for any capture session:

01

Was a command initiated?

02

Which modules participated?

03

Did the network reach the expected final state?

Requirements

Software & hardware requirements

Software

Python3.9+
python-can4.x
Operating SystemWindows / Linux / macOS
Terminal / CLI accessRequired

Hardware

USB CAN adapterSLCAN / SocketCAN compatible
OBD-II breakout or direct harnessVehicle access
Laptop / field computerUSB port required
Proprietary hardwareNot required

Note: CANTrak is hardware agnostic. Any USB CAN adapter supported by python-can will work. Common options include the Canable, PCAN-USB, and Kvaser interfaces.

Installation

Getting CANTrak running

CANTrak is distributed as a Python package. Install it from the repository and configure your CAN interface before running your first session.

1

Clone the repository

Terminal
git clone https://github.com/jeremyrich/cantrak.git
cd cantrak
2

Create a virtual environment

Terminal
python -m venv .venv
source .venv/bin/activate   # Linux / macOS
.venv\Scripts\activate      # Windows
3

Install dependencies

Terminal
pip install -r requirements.txt
4

Configure your interface

Edit config.yaml to match your CAN adapter and bitrate.

config.yaml
interface: socketcan       # or: slcan, pcan, kvaser
channel: can0              # adapter channel (e.g. COM3 on Windows)
bitrate: 500000            # 500 kbps — standard for most vehicles
log_output: true
log_path: ./logs/
Hardware Setup

Connecting to the vehicle

CANTrak accesses the vehicle network through a USB CAN adapter connected to the OBD-II port or directly to the CAN bus harness.

The simplest method. Connect your USB CAN adapter to the OBD-II port under the dash. This provides access to the primary high-speed CAN bus (HS-CAN) on most vehicles. Pin 6 (CAN High) and Pin 14 (CAN Low) carry the main powertrain and body network.

Capture Modes

Running a capture session

Captures payload transitions during a defined event window. Use this mode to verify that a command was transmitted and that the correct modules responded.

Terminal
python cantrak.py --mode verify

# CANTrak will prompt:
# > Press SPACEBAR to begin capture window
# > Perform your switch operation or scanner command
# > Release SPACEBAR to end capture window
# > Delta report will be generated automatically

Output: A delta report listing all arbitration IDs that exhibited payload changes within the capture window, with pre-event and post-event byte values.

Spacebar Clutch

Trigger-based capture

The Spacebar Clutch defines a precise capture window around a physical event. Press and hold the spacebar immediately before the switch operation or scanner command, then release when the event is complete.

How it works

01

Press SPACEBAR — capture window opens, timestamp recorded

02

Perform the switch operation or scanner command

03

Release SPACEBAR — capture window closes, timestamp recorded

04

CANTrak analyzes only the traffic within the window

05

Delta report generated from window-isolated data

Best practices

Keep the capture window as short as possible — 1–3 seconds for most events

Practice the timing before the actual capture to minimize pre/post noise

For scanner commands, trigger immediately before sending the command

For physical switches, trigger before the switch actuation, not after

Run multiple captures and compare results to confirm consistency

Output & Logs

Reading CANTrak output

CANTrak outputs results to the terminal in real time and optionally saves structured logs to CSV or JSON for further analysis.

Example — Command Verification output
CANTrak v0.x — Command Verification
Session: 2026-06-13 14:32:07
Window:  847ms (t=0.000s → t=0.847s)
─────────────────────────────────────────────────────
ARB ID    DLC  PRE-EVENT            POST-EVENT           STATUS
0x07E8    8    FF 00 1A 3C 00 00    00 FF 1A 3C 00 00    VERIFIED
0x0300    8    3C 00 00 1F 00 00    1F 00 00 3C 00 00    VERIFIED
0x04B0    8    A1 00 3F 00 00 00    00 A1 3F 00 00 00    VERIFIED
0x0201    8    00 FF 00 A4 12 00    00 FF 00 A4 12 00    NO CHANGE
0x0400    8    00 00 00 00 00 00    00 00 00 00 00 00    NO CHANGE
─────────────────────────────────────────────────────
Result: 3 IDs verified — command transmitted and acknowledged
Example — Sleep Analysis output
CANTrak v0.x — Sleep & Wake Analysis
Session: 2026-06-13 15:10:22  |  Duration: 120s  |  Threshold: 30s
─────────────────────────────────────────────────────
ARB ID    LAST ACTIVE   MSG/S AT CUTOFF   STATUS
0x07E8    t+2.1s        0                 SLEEP ✓
0x0201    t+1.8s        0                 SLEEP ✓
0x0300    t+3.4s        0                 SLEEP ✓
0x0580    t+119.8s      10                AWAKE ✗
0x06A0    t+118.2s      5                 AWAKE ✗
─────────────────────────────────────────────────────
WARNING: 2 IDs remain active beyond threshold — parasitic drain candidates
Troubleshooting

Common issues