ESP32 OBD-II Diagnostic Dongle Firmware

Production-ready firmware for an OBD-II diagnostic dongle based on ESP32, enabling CAN bus communication with vehicles and supporting USB, WiFi, and Bluetooth connectivity.

Features

• CAN Bus Communication: Full CAN 2.0A/2.0B support with configurable bit rates (125K, 250K, 500K, 1M bps)
• Multi-Transport Support:
  • USB Serial (921600 baud)
  • WiFi AP/Station mode
  • Bluetooth Classic (SPP)
• High Performance: Handles 10,000+ CAN frames/second
• Reliable Operation: Watchdog protection, automatic recovery, overflow detection
• Persistent Configuration: NVS storage for settings
• OTA Updates: Over-the-air firmware updates via WiFi
• LED Indicators: Visual feedback for power, CAN activity, and connection status

Hardware Requirements

Target Hardware

• Microcontroller: ESP32 or ESP32-S3
• CAN Transceiver: MCP2562, TJA1050 (5V) or TCAN332 (3.3V)
• Power: 12V from OBD-II → Buck converter → 5V → 3.3V LDO
• Connectivity: USB Type-C, WiFi 802.11n, Bluetooth Classic/BLE

Pin Connections

CAN Interface:
  - TX: GPIO 4
  - RX: GPIO 5

Status LEDs (optional):
  - Power:     GPIO 2
  - CAN RX:    GPIO 15
  - CAN TX:    GPIO 16
  - Status:    GPIO 17

OBD-II Connections:
  - Pin 6:  CAN-H
  - Pin 14: CAN-L
  - Pin 16: +12V
  - Pin 4/5: Ground

Getting Started

Prerequisites

1. ESP-IDF (v5.0 or later)

   git clone --recursive https://github.com/espressif/esp-idf.git
   cd esp-idf
   ./install.sh esp32,esp32s3
   source export.sh

2. PlatformIO (optional but recommended)

   pip install platformio
   pio platform install espressif32

Building the Firmware

Using PlatformIO:

# Build for ESP32
pio run -e esp32

# Build for ESP32-S3
pio run -e esp32s3

# Build and upload
pio run -e esp32 -t upload

# Monitor serial output
pio device monitor

Using ESP-IDF:

# Configure
idf.py set-target esp32

# Build
idf.py build

# Flash
idf.py flash

# Monitor
idf.py monitor

Flashing the Firmware

1. Connect the ESP32 via USB
2. Put into download mode (if needed - hold BOOT button while pressing RESET)
3. Flash the firmware:

   pio run -e esp32 -t upload

   or

   idf.py flash

Usage

Initial Setup

On first boot, the dongle will:

• Initialize with default settings (500 kbps CAN, WiFi AP mode)
• Create WiFi Access Point: OBD-Dongle-XXXX (password: 12345678)
• Start USB serial on UART0 at 921600 baud
• Enable Bluetooth with name OBD-Dongle

Connecting to the Dongle

Via USB:

• Connect to the serial port at 921600 baud, 8N1
• Use any serial terminal (PuTTY, screen, minicom)

Via WiFi:

1. Connect to WiFi AP OBD-Dongle-XXXX
2. Connect to IP 192.168.4.1:8080 via TCP
3. Multiple clients supported (up to 4)

Via Bluetooth:

1. Pair with OBD-Dongle
2. Connect to SPP serial profile
3. Send/receive data like serial

Communication Protocol

The dongle uses a binary protocol for frame exchange:

CAN Frame Format (Dongle → Host):

Standard Frame (11-bit ID):
[0xAA][ID_H][ID_L][DLC][FLAGS][DATA0-7][CHECKSUM]
Total: 15 bytes

Extended Frame (29-bit ID):
[0xAA][ID_3][ID_2][ID_1][ID_0][DLC][FLAGS][DATA0-7][CHECKSUM]
Total: 17 bytes

Command Format (Host → Dongle):

[0x55][CMD][LENGTH][PAYLOAD...]

Supported Commands:

Command	Code	Description
Set CAN Bitrate	0x01	Change CAN bus speed
Get Status	0x02	Retrieve statistics
Reset Buffers	0x03	Clear RX/TX buffers
Set WiFi	0x04	Configure WiFi credentials
Factory Reset	0x05	Restore defaults
CAN Frame	0x10	Send CAN frame
Ping	0xFE	Connection test
Pong	0xFF	Ping response

Example: Set CAN Bitrate to 500 kbps

Send: [0x55][0x01][0x04][0x00][0x07][0xA1][0x20]
      (start)(cmd)(len)(---500000 in Hz---)

Receive: [0x55][0x01][0x01][0x00]
         (start)(cmd)(len)(success)

Configuration

Runtime configuration via commands. Configuration is automatically saved to NVS and persists across reboots.

Architecture

System Architecture

┌─────────────────────────────────────────┐
│           ESP32 Firmware                │
├─────────────────────────────────────────┤
│  CAN Driver ◄──► Frame Buffer          │
│       │              │                   │
│       └──────┬───────┘                   │
│              │                           │
│     Transport Manager                    │
│       ├─────┼─────┐                     │
│       │     │     │                      │
│      USB  WiFi  Bluetooth                │
│                                          │
│   Config · Logging · Watchdog · LEDs    │
└─────────────────────────────────────────┘

FreeRTOS Task Structure

Priority 10: CAN_RX_Task      (Core 0)
Priority 8:  CAN_TX_Task      (Core 0)
Priority 5:  Transport_TX     (Core 1)
Priority 5:  Transport_RX     (Core 1)
Priority 3:  Watchdog         (Any core)
Priority 2:  Diagnostics      (Any core)
Priority 2:  LEDs             (Any core)

Development

Project Structure

firmware/
├── platformio.ini           # Build configuration
├── partitions.csv           # Flash partitions (OTA support)
├── README.md                # This file
├── include/
│   ├── pins.h               # GPIO definitions
│   └── version.h            # Firmware version
├── src/
│   ├── main.cpp             # Application entry point
│   ├── config.h             # Configuration interface
│   ├── can/
│   │   ├── can_driver.*     # CAN peripheral driver
│   │   └── can_buffer.*     # Frame buffering
│   ├── protocol/
│   │   ├── frame_handler.*  # Protocol serialization
│   │   └── command_handler.* # Command processing
│   ├── transport/
│   │   ├── transport_manager.* # Transport coordination
│   │   ├── usb_transport.*    # USB serial
│   │   ├── wifi_transport.*   # WiFi TCP/UDP
│   │   └── bluetooth_transport.* # BT SPP
│   └── utils/
│       ├── config.*         # NVS storage
│       ├── logging.*        # Log configuration
│       ├── watchdog.*       # Watchdog timer
│       └── leds.*           # LED indicators
└── test/
    ├── test_main.cpp        # Test runner
    ├── test_frame_handler.cpp
    ├── test_can_buffer.cpp
    └── test_config.cpp

Running Tests

# Build tests
pio run -e esp32 -t buildfs

# Upload and run tests
pio test -e esp32

# Monitor test output
pio device monitor

Performance

• CAN Frame Rate: 10,000+ frames/second
• Latency: <5ms from CAN RX to transport TX
• CPU Utilization: <50% under normal load
• Memory: <60% RAM utilization
• Power: <150mA @ 5V (active mode)

Troubleshooting

Dongle Not Responding

1. Check power LED (GPIO 2 should be on)
2. Verify OBD-II connection (pins 4,5,6,14,16)
3. Check serial output for errors
4. Try factory reset

CAN Frames Not Received

1. Verify CAN bitrate matches vehicle (usually 500 kbps)
2. Check CAN-H and CAN-L connections
3. Ensure vehicle is powered on
4. Check for bus-off errors in status command

WiFi Connection Issues

1. Verify SSID and password
2. Check WiFi mode (AP vs STA)
3. Ensure not too far from dongle (AP mode)
4. Check firewall settings (STA mode)

High Error Rate

1. Check CAN bus termination (120Ω)
2. Verify transceiver power supply (5V or 3.3V)
3. Check for loose connections
4. Monitor overflow statistics

Safety & Compliance

• Always disconnect from OBD-II when vehicle is off
• Do not operate while driving
• Ensure proper CAN bus termination
• Use only in authorized diagnostic scenarios
• Complies with ISO 11898-1:2015 (CAN 2.0)

Changelog

Version 1.0.0 (Initial Release)

• Complete CAN 2.0A/2.0B implementation
• USB, WiFi, and Bluetooth transports
• Binary protocol with checksum
• NVS configuration storage
• Watchdog protection
• LED status indicators
• OTA update support
• Comprehensive unit tests

Credits

Built with ESP-IDF framework by Espressif Systems.