After installing the library, simply
import obd, and create a new OBD connection object. By default, python-OBD will scan for Bluetooth and USB serial ports (in that order), and will pick the first connection it finds. The port can also be specified manually by passing a connection string to the OBD constructor. You can also use the
scan_serial helper retrieve a list of connected ports.
import obd connection = obd.OBD() # auto connect # OR connection = obd.OBD("/dev/ttyUSB0") # create connection with USB 0 # OR ports = obd.scan_serial() # return list of valid USB or RF ports print ports # ['/dev/ttyUSB0', '/dev/ttyUSB1'] connection = obd.OBD(ports) # connect to the first port in the list
OBD(portstr=None, baudrate=None, protocol=None, fast=True, timeout=0.1, check_voltage=True):
portstr: The UNIX device file or Windows COM Port for your adapter. The default value (
None) will auto select a port.
baudrate: The baudrate at which to set the serial connection. This can vary from adapter to adapter. Typical values are: 9600, 38400, 19200, 57600, 115200. The default value (
None) will auto select a baudrate.
protocol: Forces python-OBD to use the given protocol when communicating with the adapter. See protocol_id() for possible values. The default value (
None) will auto select a protocol.
fast: Allows commands to be optimized before being sent to the car. Python-OBD currently makes two such optimizations:
- Sends carriage returns to repeat the previous command.
- Appends a response limit to the end of the command, telling the adapter to return after it receives N responses (rather than waiting and eventually timing out). This feature can be enabled and disabled for individual commands.
Disabling fast mode will guarantee that python-OBD outputs the unaltered command for every request.
timeout: Specifies the connection timeout in seconds.
check_voltage: Optional argument that is
True by default and when set to
False disables the detection of the car supply voltage on OBDII port (which should be about 12V). This control assumes that, if the voltage is lower than 6V, the OBDII port is disconnected from the car. If the option is enabled, it adds the
OBDStatus.OBD_CONNECTED status, which is set when enough voltage is returned (socket connected to the car) but the ignition is off (no communication with the vehicle). Setting the option to
False should be needed when the adapter does not support the voltage pin or more generally when the hardware provides unreliable results, or if the pin reads the switched ignition voltage rather than the battery positive (this depends on the car).
OBDCommand to the car, and returns an
OBDResponse object. This function will block until a response is received from the car. This function will also check whether the given command is supported by your car. If a command is not marked as supported, it will not be sent, and an empty
OBDResponse will be returned. To force an unsupported command to be sent, there is an optional
force parameter for your convenience.
For non-blocking querying, see Async Querying
import obd connection = obd.OBD() r = connection.query(obd.commands.RPM) # returns the response from the car
Returns a string value reflecting the status of the connection after OBD() or Async() methods are executed. These values should be compared against the
OBDStatus class. The fact that they are strings is for human readability only. There are currently 4 possible states:
from obd import OBDStatus # no connection is made OBDStatus.NOT_CONNECTED # "Not Connected" # successful communication with the ELM327 adapter OBDStatus.ELM_CONNECTED # "ELM Connected" # successful communication with the ELM327 adapter, # OBD port connected to the car, ignition off # (not available with argument "check_voltage=False") OBDStatus.OBD_CONNECTED # "OBD Connected" # successful communication with the ELM327 and the # vehicle; ignition on OBDStatus.CAR_CONNECTED # "Car Connected"
The status is set by
Async() methods and remains unmodified during the connection.
status() shall not be checked after the queries to verify that the connection is kept active.
OBD_CONNECTED are mostly for diagnosing errors. When a proper connection is established with the vehicle, you will never encounter these values.
The ELM327 controller allows OBD Commands and AT Commands. In general, OBD Commands (which interact with the car) can be succesfully performed when the ignition is on, while AT Commands (which generally interact with the ELM327 controller) are always accepted. As the connection phase (for both
Async objects) also performs OBD protocol commands (after the initial set of AT Commands) and returns the “Car Connected” status (“CAR_CONNECTED”) if the overall connection phase is successful, this status means that the serial communication is valid, that the ELM327 adapter is appropriately responding, that the OBDII socket is connected to the car and also that the ignition is on. “OBD Connected” status (“OBD_CONNECTED”) is returned when the OBDII socket is connected and the ignition is off, while the "ELM Connected" status (“ELM_CONNECTED”) means that the ELM327 processor is reached but the OBDII socket is not connected to the car. “OBD Connected” is controlled by the
check_voltage option that by default is set to
True and gets the ignition status when the socket is connected. If the OBDII socket does not support the unswitched battery positive supply, or the OBDII adapter cannot detect it, then the
check_voltage option should be set to
False; in such case, the "ELM Connected" status is returned when the socket is not connected or when the ignition is off, with no differentiation.
Returns a boolean for whether a connection was established with the vehicle. It is identical to writing:
connection.status() == OBDStatus.CAR_CONNECTED
Returns the string name for the currently connected port (
"/dev/ttyUSB0"). If no connection was made, this function returns an empty string.
Returns a boolean for whether a command is supported by both the car and python-OBD
Both functions return string names for the protocol currently being used by the adapter. Protocol ID's are the short values used by your adapter, whereas protocol names are the human-readable versions. The
protocol_id() function is a good way to lookup which value to pass in the
protocol field of the OBD constructor (though, this is mainly for advanced usage). These functions do not make any serial requests. When no connection has been made, these functions will return empty strings. The possible values are:
|1||SAE J1850 PWM|
|2||SAE J1850 VPW|
|3||AUTO, ISO 9141-2|
|4||ISO 14230-4 (KWP 5BAUD)|
|5||ISO 14230-4 (KWP FAST)|
|6||ISO 15765-4 (CAN 11/500)|
|7||ISO 15765-4 (CAN 29/500)|
|8||ISO 15765-4 (CAN 11/250)|
|9||ISO 15765-4 (CAN 29/250)|
|A||SAE J1939 (CAN 29/250)|
Closes the connection.
Property containing a
set of commands that are supported by the car.
If you wish to manually mark a command as supported (prevents having to use
query(force=True)), add the command to this set. This is not necessary when using python-OBD's builtin commands, but is useful if you create custom commands.
import obd connection = obd.OBD() # manually mark the given command as supported connection.supported_commands.add(<OBDCommand>)