Connection

This guide explains how to connect the library to different types of OBDII adapters and start communicating with your vehicle.

Understanding Adapters

An OBDII adapter is a small physical device that acts as a bridge between your vehicle’s diagnostic port and your computer, Raspberry Pi, smartphone, etc..

It plugs into the vehicle’s OBDII diagnostic port (female connector), usually found under the dashboard or near the steering wheel, you can check online for your vehicle’s exact location.

It converts the car’s data signals into a standard format that our library can read.

The image below shows a male OBDII connector, which is the adapter side that plugs into your vehicle’s diagnostic port.

Tip

Don’t have hardware ? Follow the Emulating a Vehicle guide.

Connect your Adapter

1. Plug the OBDII adapter into your vehicle’s diagnostic port.

2. Turn the ignition to the “ON” position (engine does not need to start).

3. Identify your adapter’s connection type.

   Different adapters connect in different ways:

   • Serial: USB and Bluetooth

   • Network: WiFi and Ethernet

Connecting via USB

Use this method if your adapter connects via USB cable.

Linux

1. Identify the USB serial port:

   $ dmesg | grep tty
   

   Note

   You can also list available USB serial devices with:

   $ ls /dev/ttyUSB*
   

2. Choose the correct port from the output (e.g., /dev/ttyUSB0).

3. Use this port for connecting.

   Connection example

   main.py

   from obdii import Connection, at_commands
   
   with Connection("/dev/ttyUSB0") as conn:
       version = conn.query(at_commands.VERSION_ID)
       print(f"Adapter Version: {version.value}")
   

Windows

1. Identify the COM port:

   chgport
   

   Note

   You can also find the COM port in “Device Manager” under “Ports (COM & LPT)”.

2. Choose the corresponding COM port (e.g., COM3).

3. Use this port for connecting.

   Connection example

   main.py

   from obdii import Connection, at_commands
   
   with Connection("COM3") as conn:
       version = conn.query(at_commands.VERSION_ID)
       print(f"Adapter Version: {version.value}")
   

macOS

Untested, help us improve this part of the documentation. Contribute

Connecting via Bluetooth

Use this method if your adapter communicates wirelessly over Bluetooth.

Linux

1. Open the Bluetooth control terminal:

   $ bluetoothctl
   

2. Power on Bluetooth, and pair with the adapter:

   # Power on and scan
   [bluetooth]# power on
   [bluetooth]# agent on
   [bluetooth]# default-agent
   [bluetooth]# scan on
   
   # Note the adapter's MAC address (XX:XX:XX:XX:XX:XX)
   
   # Pair and trust the adapter
   [bluetooth]# pair XX:XX:XX:XX:XX:XX
   [bluetooth]# trust XX:XX:XX:XX:XX:XX
   [bluetooth]# exit
   

3. Bind the adapter to an RFCOMM port:

   $ sudo rfcomm bind /dev/rfcomm0 XX:XX:XX:XX:XX:XX
   

4. Use the /dev/rfcomm0 port for connecting.

   Connection example

   main.py

   from obdii import Connection, at_commands
   
   with Connection("/dev/rfcomm0") as conn:
       version = conn.query(at_commands.VERSION_ID)
       print(f"Adapter Version: {version.value}")
   

Windows

1. Pair the adapter via Bluetooth.

2. Identify the COM port assigned to the adapter:

   chgport
   

   Note

   You can also find the COM port in “Device Manager” under “Ports (COM & LPT)”.

3. Choose the corresponding COM port (e.g., COM7).

4. Use this port for connecting.

   Connection example

   main.py

   from obdii import Connection, at_commands
   
   with Connection("COM7") as conn:
       version = conn.query(at_commands.VERSION_ID)
       print(f"Adapter Version: {version.value}")
   

macOS

Untested, help us improve this part of the documentation. Contribute

Connecting via Network (WiFi/Ethernet)

Use this method if your adapter connects over a network. WiFi and Ethernet adapters use the same network transport.

1. Connect to the adapter’s network (WiFi or Ethernet).

2. Determine its IP address and port.

   Common defaults:

   Address	Port	Device
   192.168.0.10	35000	Generic
   192.168.1.10	35000	Clones

   Note

   These values may vary. Refer to the adapter’s documentation for the correct IP address and port.

3. Use the IP address and port for connecting.

   Connection example

   main.py

   from obdii import Connection, at_commands
   
   with Connection(("192.168.0.10", 35000)) as conn:
       version = conn.query(at_commands.VERSION_ID)
       print(f"Adapter Version: {version.value}")
   

Advanced Connection

When instantiating a obdii.Connection, you can pass optional parameters to control how the connection is established.

Protocol Selection

By default, the library automatically detects supported protocols. When multiple protocols are available, the library selects the preferred one based on performance.

If you specify a protocol, the library will attempt to use it. If the requested protocol is unsupported, it will fall back to the next best available option.

main.py

from obdii import Connection, Protocol

# Create Connection with ISO 15765-4 CAN (29 bit ID, 500 kbaud)

with Connection(
    "COM10",
    protocol=Protocol.ISO_15765_4_CAN_B,
) as conn: ...

Example output showing protocol fallback:

output

2026-01-01 01:01:01 INFO     obdii.connection Attempting to connect to <TransportSerial COM10 at 38400 baud>.
2026-01-01 01:01:01 WARNING  obdii.connection Requested protocol ISO_15765_4_CAN_B cannot be used.
2026-01-01 01:01:01 INFO     obdii.connection Protocol set to ISO_15765_4_CAN.
2026-01-01 01:01:01 INFO     obdii.connection Successfully connected to <TransportSerial COM10 at 38400 baud>.
2026-01-01 01:01:01 INFO     obdii.connection Connection closed.

Auto Connect

auto_connect automatically attempts to connect when the obdii.Connection is instantiated. Set it to False to disable this behavior. You will then need to call obdii.Connection.connect() manually.

Defaults to True.

Smart Query

smart_query is a small optimization that, when set to True, detects identical consecutive commands. Instead of sending the full command again, it sends a shorter special REPEAT command, reducing bus traffic and latency.

Defaults to False. This may not be supported by all adapters or vehicles.

Early Return

early_return is an optimization that, when set to True, makes the ELM327 respond immediately after receiving the expected number of responses, skipping the default timeout.

This reduces latency and increases polling speed for commands with a defined expected_bytes attribute.

Defaults to False. Requires an ELM327 v1.3 or higher.

Logging

This library logs errors and debug information using the standard logging module. When creating a obdii.Connection, a default logging configuration is applied to the obdii logger.

You can override this behavior by providing your own logging handler, formatter and level. By default, logs are configured with the logging.INFO level and written to sys.stderr using a colored formatter.

If you want the logging configuration provided by the library to affect all loggers rather than only obdii, set log_root=True.

main.py

from obdii import Connection

from logging import DEBUG, Formatter
from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
    filename="obdii.log",
    maxBytes=32*1024*1024,
    backupCount=3,
)

formatter = Formatter(
    "[{asctime}] [{levelname:<8}] {name}: {message}",
    "%Y-%m-%d %H:%M:%S",
    style='{',
)

with Connection(
    "COM10",
    log_handler=handler,
    log_formatter=formatter,
    log_level=DEBUG,
    log_root=False,
) as conn: ...

Disabling Default Logging Setup

If you are integrating obdii into a framework that manages its own logging, you may want to disable the library’s default logging setup entirely and let the framework handle it. This can be done by passing None to the log_handler parameter:

main.py

from obdii import Connection

with Connection("COM10", log_handler=None) as conn: ...

Logging will still work as normal through the obdii logger, but the configuration is now your responsibility.

Extra Keyword Arguments

Extra keyword arguments passed to obdii.Connection are forwarded to the transport type used by the connection.

Note

The transport type is automatically determined from the first argument passed to obdii.Connection (e.g., string for serial, tuple for socket).

These arguments are used when obdii.Connection.connect() is called, allowing transport-specific behavior customization, such as timeouts, baud rate, etc.

Currently, the library provides two native transport types, serial.Serial and socket.socket. Refer to their respective documentation for the full list of supported parameters.

A common serial configuration example is shown below:

main.py

from obdii import Connection

with Connection(
    "COM10",
    baudrate=115200,
    timeout=1,
    write_timeout=1,
) as conn: ...