██╗██████╗ ███████╗██████╗ ██╗ ██╗ █████╗ ██████╗ ██╗
██║╚════██╗██╔════╝╚════██╗██║ ██║ ██╔══██╗██╔══██╗██║
██║ █████╔╝███████╗ █████╔╝███████║█████╗███████║██████╔╝██║
██ ██║██╔═══╝ ╚════██║ ╚═══██╗╚════██║╚════╝██╔══██║██╔═══╝ ██║
╚█████╔╝███████╗███████║██████╔╝ ██║ ██║ ██║██║ ██║
╚════╝ ╚══════╝╚══════╝╚═════╝ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝
A Comprehensive Python Library for SAE J2534 PassThru Vehicle Diagnostics
Developed by ECUUNLOCK - Vehicle ECU Programming & Security Research
📋 Table of Contents
- ⚡ Complete SAE J2534-1 Implementation - Full support for PassThru API v04.04
- 🎯 High-Level Interface - Simple, Pythonic API for vehicle diagnostics
- 🔍 Auto-Discovery - Automatically find and connect to J2534 devices
- 📡 Multi-Protocol Support - CAN, ISO15765, J1850 VPW/PWM, ISO9141, ISO14230, SCI
- 🐛 Debug Modes - Built-in debug logging with hex dump utilities
⚠️ Exception Handling - Optional exception mode for detailed error info- 🎨 GUI Examples - 4 complete GUI frameworks demonstrated
- 📝 Type Hints - Full type annotations for IDE support
- 📦 pip Installable - Easy installation with optional dependencies
# Basic installation
pip install j2534-api
# With GUI support (choose your framework)
pip install j2534-api[gui-pyqt5]
pip install j2534-api[gui-customtkinter]
pip install j2534-api[gui-all] # All GUI frameworksgit clone https://github.com/keenanlaws/j2534-api.git
cd j2534-api
pip install -e .| Requirement | Details |
|---|---|
| Python | 3.10 or higher (32-bit recommended for J2534 DLL compatibility) |
| OS | Windows only (uses Windows Registry and DLLs) |
| Hardware | Any SAE J2534-1 compliant PassThru device |
Note
32-bit Python is recommended because most J2534 device DLLs are 32-bit. Using 64-bit Python may cause DLL loading failures.
| Manufacturer | Devices |
|---|---|
| Drew Technologies | Mongoose Pro, CarDAQ-Plus 3 |
| Ford | VCM II |
| General Motors | MDI, MDI 2 |
| Honda | HDS |
| Toyota | Techstream |
| Bosch | KTS Series |
| And more... | Any J2534-1 compliant device |
fromJ2534_REGISTRYimportget_all_j2534_devicesdevices=get_all_j2534_devices()
fordeviceindevices:
print(f"{device.name} - {device.vendor}")
print(f" DLL: {device.function_library_path}")
print(f" Protocols: {', '.join(device.supported_protocols)}")fromAutoJ2534importj2534_communication# Automatically find device and connect to vehicleresult=j2534_communication.auto_connect()
ifresult:
tool_index, connection_key, key_name, device_name, firmware_version, dll_version=resultprint(f"Connected to {device_name}")
print(f"Firmware: {firmware_version}")
print(f"DLL: {dll_version}")
# Send a diagnostic message (TesterPresent)response=j2534_communication.transmit_and_receive_message([0x3E, 0x00])
print(f"ECU Response: {response}")
# Clean upj2534_communication.disconnect()
j2534_communication.close()📖 More Examples
fromAutoJ2534importj2534_communication, Connections# List available devicesj2534_communication.numbered_tool_list()
# Connect to device 0 with Chrysler PCM configurationifj2534_communication.open_communication(device_index=0, connection_name="chrys1"):
# Get device infoinfo=j2534_communication.tool_info()
print(f"Device: {info[0]}, FW: {info[1]}, DLL: {info[2]}")
# Check battery voltagevoltage=j2534_communication.check_volts()
print(f"Battery: {voltage:.2f}V")
# Send diagnostic requestresponse=j2534_communication.transmit_and_receive_message([0x10, 0x01])
print(f"Response: {response}")
# Disconnectj2534_communication.disconnect()
j2534_communication.close()fromJ2534import (
pt_open, pt_close, pt_connect, pt_disconnect,
pt_read_message, pt_write_message, pt_start_ecu_filter,
set_j2534_device_to_connect, get_list_j2534_devices,
ProtocolId, BaudRate, TxFlags, PassThruMsgBuilder,
j2534_config
)
# Enable debug loggingj2534_config.enable_debug()
# Enable exception mode (raises exceptions on errors)j2534_config.enable_exceptions()
# List and select devicedevices=get_list_j2534_devices()
print(f"Found {len(devices)} devices")
set_j2534_device_to_connect(0)
# Open devicedevice_id=pt_open()
# Connect with ISO15765 protocolchannel_id=pt_connect(
device_id=device_id,
protocol_id=ProtocolId.ISO15765,
flags=0,
baud_rate=BaudRate.CAN_500K
)
# Set up flow control filter (required for ISO15765)filter_id=pt_start_ecu_filter(
channel_id=channel_id,
protocol_id=ProtocolId.ISO15765,
mask_identifier=0xFFFFFFFF,
pattern_identifier=0x7E8, # ECU response IDflow_control_identifier=0x7E0# Tester request ID
)
# Create and send a messagetx_msg=PassThruMsgBuilder(ProtocolId.ISO15765, TxFlags.ISO15765_FRAME_PAD)
tx_msg.set_identifier_and_data(0x7E0, [0x3E, 0x00]) # TesterPresentpt_write_message(channel_id, tx_msg, 1, 1000)
# Read responserx_msg=PassThruMsgBuilder(ProtocolId.ISO15765, 0)
ifpt_read_message(channel_id, rx_msg, 1, 2000) ==0:
print(f"Response: {rx_msg.dump_output()}")
# Clean uppt_disconnect(channel_id)
pt_close(device_id)| Protocol | ID | Baud Rate | Use Case |
|---|---|---|---|
| ISO 15765 | 6 | 500K | Modern CAN diagnostics (OBD-II 2008+) |
| CAN | 5 | 125K-500K | Raw CAN bus access, J1939 |
| J1850 VPW | 1 | 10.4K | GM vehicles (pre-2008) |
| J1850 PWM | 2 | 41.6K | Ford vehicles (pre-2008) |
| ISO 9141 | 3 | 10.4K | K-Line (older European/Asian) |
| ISO 14230 | 4 | 10.4K | KWP2000 (European vehicles) |
| SCI | 7-10 | 7.8K-62.5K | Chrysler/Stellantis proprietary |
Tip
For ISO15765 (CAN diagnostics), a flow control filter is required. Use pt_start_ecu_filter() to set it up.
graph TD
A[Your Python App] --> B[AutoJ2534<br/>High-Level API]
A --> C[J2534<br/>Low-Level API]
B --> C
C --> D[DLL Interface<br/>ctypes bindings]
D --> E[J2534 PassThru Device<br/>Mongoose, VCM II, etc.]
E --> F[Vehicle ECU<br/>via OBD-II/CAN]
G[J2534_REGISTRY] --> C
G -.-> |Device Discovery| D
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#fff3e0
style D fill:#f3e5f5
style E fill:#e8f5e9
style F fill:#ffebee
style G fill:#fce4ec
j2534-api/
├── J2534/ # Low-level PassThru API
│ ├── api.py # High-level API functions
│ ├── config.py # Debug/exception configuration
│ ├── constants.py # Protocol constants (IntEnum)
│ ├── dll_interface.py # DLL bindings
│ ├── exceptions.py # Exception hierarchy
│ ├── logging_utils.py # Debug utilities
│ └── structures.py # ctypes structures
│
├── AutoJ2534/ # High-level vehicle interface
│ ├── interface.py # J2534Communications class
│ ├── ecu_parameters.py # Connection configurations
│ └── negative_response_codes.py # UDS error codes
│
├── J2534_REGISTRY/ # Windows registry scanner
│ ├── registry_scanner.py # Device enumeration
│ └── device_info.py # Device dataclass
│
└── examples/ # GUI examples (4 frameworks)
The library includes complete GUI examples using 4 different frameworks:
| Framework | Description | Installation |
|---|---|---|
| Tkinter | Built-in Python GUI | No installation needed |
| PyQt5 | Professional cross-platform | pip install j2534-api[gui-pyqt5] |
| CustomTkinter | Modern themed Tkinter | pip install j2534-api[gui-customtkinter] |
| FreeSimpleGUI | Rapid prototyping | pip install j2534-api[gui-pysimplegui] |
# Run an examplecd examples/tkinter_example
python main.py🐛 Debug Mode
fromJ2534importj2534_config# Enable verbose debug outputj2534_config.enable_debug()
# Disable debug outputj2534_config.disable_debug()
# Check current stateifj2534_config.is_debug_enabled:
print("Debug mode is ON")⚠️ Exception Mode
fromJ2534importj2534_config# Enable exception mode (raises J2534Error on failures)j2534_config.enable_exceptions()
# Disable exception mode (returns False/None on failures)j2534_config.disable_exceptions()🚗 Pre-Defined Connections
The library includes pre-configured connection settings for common vehicles:
fromAutoJ2534importConnections# Available Chrysler/FCA configurationsprint(Connections.CHRYSLER_ECU.keys())
# ['chrys1', 'chrys2', 'chrys3', 'chrys4', 'chrys5', 'chrys6', 'chrys7', 'chrys8']# SCI protocol configurationsprint(Connections.SCI.keys())
# ['SCI_A_ENGINE', 'SCI_A_TRANS', 'SCI_B_ENGINE', 'SCI_B_TRANS']✅ With Exceptions (Recommended)
fromJ2534importj2534_config, pt_openfromJ2534.exceptionsimportJ2534OpenErrorj2534_config.enable_exceptions()
try:
device_id=pt_open()
exceptJ2534OpenErroraserror:
print(f"Failed to open device: {error}")
print(f"Error code: {error.error_code}")❌ Without Exceptions
fromJ2534importpt_opendevice_id=pt_open()
ifdevice_idisFalse:
print("Failed to open device")| Module | Description | Link |
|---|---|---|
| J2534 | Low-level PassThru API | 📖 Documentation |
| AutoJ2534 | High-level interface | 📖 Documentation |
| J2534_REGISTRY | Device discovery | 📖 Documentation |
| SAE J2534-1 | Official standard | 🔗 SAE Website |
❌ No Devices Found
- Verify J2534 device drivers are installed
- Check USB connection to device
- Run as Administrator (registry access may require elevation)
- Confirm device appears in Windows Device Manager
[!TIP] Use
get_all_j2534_devices()to see what devices are detected in the registry.
⏱️ Connection Timeouts
- Ensure vehicle ignition is ON
- Verify correct protocol and baud rate for your vehicle
- Increase timeout values in
pt_read_message() - Check OBD-II cable connection
📡 Message Filter Errors
- For ISO15765, flow control filter is REQUIRED
- Verify CAN IDs match your vehicle's ECU addresses
- Check filter mask is correctly configured
[!IMPORTANT] Standard OBD-II uses 0x7E0 (request) and 0x7E8 (response). Your vehicle may use different IDs.
💻 DLL Load Failures
- Ensure you're using 32-bit Python (most J2534 DLLs are 32-bit)
- Check the DLL path in the registry is correct
- Verify all DLL dependencies are present
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- SAE International for the J2534 PassThru standard
- The Python community for excellent tooling
- Claude AI for generating this README
Warning
Disclaimer: This software is provided for educational and research purposes. Always ensure you have proper authorization before performing vehicle diagnostics. The authors are not responsible for any damage or issues caused by the use of this software.