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. Chose 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. Chose 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. Chose 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 <TransportPort 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 <TransportPort COM10 at 38400 baud>.
2026-01-01 01:01:01 INFO     obdii.connection Connection closed.

Auto Connect

auto_connect automatically attempt to connect when the 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 repeated 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 return 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.