barracuda-fsh/pyobd

An OBD-II compliant car diagnostic tool

PYOBD

This is the remake of the program pyobd, a free and open-source program for car diagnostics. The program was originally made by Donour Sizemore a long time ago, but it wasn't operational for the last 15 years, so I upgraded it from Python 2 to Python 3 and all the new libraries to make it work again. After that, I deleted the fixed commands and used the Python-OBD library, which supports a lot more commands and auto-detects what a cars computer supports, so it displays much more data than before. It works on all platforms - Windows, Linux and MacOS.

Presentation on YouTube

Table of Contents

1. PYOBD
   • Overview
   • Prerequisites
   • Installation
     • Windows
     • Linux
     • MacOS
   • Usage
   • Running the Script
     • Windows
     • Linux
     • MacOS
   • Creating the Executable
     • Windows
     • Linux
     • MacOS
   • To-Do List

Prerequisites:

You need an ELM327 adapter, a laptop, and a car that supports OBD2 to use this program. All cars in Europe made since 2001 should support it. And in the USA, all cars made since 1996.

Which ELM327 adapters have been reported to work? Most if not all adapters for $10 or more should work.
This is the list of the ones I tried and worked:

• OBDPro USB Scantool
  
• OBDLink SX USB
  
• Chinese OBD2 1.5 USB
  
• VGate iCar Pro BLE (Bluetooth 4.0).

Please write to me which adapters you have tested working with the app, so I can include it in the list. My e-mail is at the bottom of this readme.

NOTE: Both USB and bluetooth adapters work with this app, but under Linux I had to pair the bluetooth adapter manually via command line and then manually connect to it. It's probably because bluetooth GUI managers under Linux are buggy.

Which adapters are good?

• These may work, but not fully, and the ones that work (at least mostly) properly are $10 or more. There are multiple reasons why a good adapter is not the cheapest. OBDLink makes good adapters, as does VGate; their adapters also receive firmware updates, so while they are already very good, they keep improving. This is what I found out after googling and reading about it for 3 days.
• USB Adapters
  • I recommend USB adapters for a stable and fast connection.
  • USB vLinker FS USB
    • If you want a trusted, good adapter, then I think the current USB vLinker FS USB is the best and has a good price.
• Blutetooth Adapters
  • Bluetooth is slower and less reliable, and wireless has been reported as worse.
  • Vgate iCAR Pro
    • My reccomended choice of bluetooth adapter.
• Chinese clones
  • If you really want to go buy a Chinese clone, I recommend one that has a PIC18F25K80 chip and FTDI chip (for USB), but even then, the firmware is also a factor; 1.5 should be best (for a Chinese clone), but who knows what you will get. I. If you want an affordable Chinese Elm327 that is branded, then go with the Konnwei KW903. It's about $15 with postage included. But iCar Pro is better.
    

Installation

You may need to install libnsl when using linux if it didn't come prepacked with it

Windows-Installation

Download the standalone executable and install the driver for your ELM327 device.

If you have not received a driver with your adapter, then the drivers can be found here

Linux-Installation

Download the standalone executable and add your user account the privileges of accesing USB and serial ports:
Note: After running these commands log out and log back in for it to take effect(or restart)

sudo usermod -a -G dialout $USER
sudo usermod -a -G tty $USER 

For bluetooth adapters, you will probably need to install this:

sudo apt-get install bluetooth bluez-utils blueman

MacOS-Installation

Download the standalone executable and add your user account the privileges of accesing USB and serial ports:
Note: After running these commands log out and log back in for it to take effect(or restart)

sudo usermod -a -G dialout $USER 
sudo usermod -a -G tty $USER 

Usage

For bluetooth adapters, you will need to pair the adapter once and then connect to it(for some reason on Linux I had to connect to it manually via command line).

Run the executable or the script, connect the ELM327 to the computer and the car's OBD port, set the iginition on the car to on(you don't have to start the engine) and click CONNECT in the app. To connect, go to Configure, select the right port and the right baudrate and click connect. You can leave it at AUTO and connect, but it will take longer to connect and in some cases it will not connect. Manual is safest and fastest, but AUTO works in most cases.
UPDATE: automatic port and baud detection should now work every time!

The data will display once you are connected, although most of the sensors display data only when the engine is running. If you connected and then turn the engine on, you have to wait a bit so that the program reconnects.

The program was made with ease of use in mind. With it you can view TESTS data, SENSORS data, FREEZE FRAME data, display and clear the TROUBLE CODES and view live GRAPHS. Currently it only displays live data - no recording and replay is possible.

NOTE: The program only displays the engine data, not airbags, ABS and body control systems. Even if your adapter supports that, you will need a more specialized program for that.

Running the script

Install Python3 if not installed already. You may need to install libsnl when using linux if it didn't come prepacked with it

Windows-Script

pip install -r requirements.txt

The script is executed by running:

python3 pyobd.py

Linux-Script

On Debian 10 and 11 and on Ubuntu, type these commands to install the requirements(on Ubuntu replace libgstreamer-plugins-base1.0 with libgstreamer-plugins-base1.0-0):

sudo apt-get install dpkg-dev build-essential libjpeg-dev libtiff-dev libsdl1.2-dev libgstreamer-plugins-base1.0 libnotify-dev freeglut3 freeglut3-dev libsm-dev libgtk-3-dev libwebkit2gtk-4.0-dev libxtst-dev gettext python3-dev python3-pip
sudo apt-get install python3-pip
pip3 install --upgrade pyinstaller
pip3 install --upgrade pip
sudo apt install libglib2.0-dev libsmbclient-dev libcups2-dev libgirepository1.0-dev libcurl4-openssl-dev libssl-dev libsystemd-dev librsync-dev
pip3 install -r requirements.txt

Note: After running the commands below log out and log back in for it to take effect(or restart)

sudo usermod -a -G dialout $USER
sudo usermod -a -G tty $USER

The script is executed by running:

python3 pyobd.py 

MacOS-Script

run: Note: After running the commands below log out and log back in for it to take effect(or restart)

pip install -r requirements.txt 
sudo usermod -a -G dialout $USER 
sudo usermod -a -G tty $USER

The script is executed by running:

python3 pyobd.py 

Creating the executable

Install Python3 if not installed already. You may need to install libsnl when using linux if it didn't come prepacked with it

Windows-Executable

run:

pip3 install -r requirements.txt 
pip3 install pyinstaller
pip3 install --upgrade pip
pip3 install --upgrade pyinstaller
pyinstaller --onefile -c -i pyobd.ico --add-data "pyobd.ico;." pyobd.py

Linux-Executable

On Debian 10 and 11 and on Ubuntu, type these commands to install the requirements(on Ubuntu replace libgstreamer-plugins-base1.0 with libgstreamer-plugins-base1.0-0):

sudo apt-get install dpkg-dev build-essential libjpeg-dev libtiff-dev libsdl1.2-dev libgstreamer-plugins-base1.0 libnotify-dev freeglut3 freeglut3-dev libsm-dev libgtk-3-dev libwebkit2gtk-4.0-dev libxtst-dev gettext python3-dev python3-pip
sudo apt-get install python3-pip
pip3 install --upgrade pyinstaller
pip3 install --upgrade pip
sudo apt install libglib2.0-dev libsmbclient-dev libcups2-dev libgirepository1.0-dev libcurl4-openssl-dev libssl-dev libsystemd-dev librsync-dev

run:

pip3 install -r requirements.txt
pip3 install pyinstaller
pyinstaller --onefile -w -i pyobd.ico --add-data "pyobd.ico:." pyobd.py

MacOS-Executable

run:

pip3 install -r requirements.txt
pip3 install pyinstaller
python3 -m PyInstaller --onefile -w -i pyobd.ico --add-data "pyobd.ico:." pyobd.py

TO-DO LIST:

Adding sensor data recording and replay feature.

pyobd's Issues

meet requirements on gentoo

hello there, i was trying to find every package required on gentoo, can't really find "pint"
may you provide more details, so i can find the right package?

issues on rasberry pi os

first thanks for rebooting the pyobd project!!

Trying to get it to run on raspberry pi with arm processor so can't use your EXE's.
First had issues with numpy
"ImportError: Unable to import required dependencies: numpy
Original error was: libcblas.so.3: cannot open shared object file: No such file or directory"

Fixed numpy dependancy with "sudo apt-get install libatlas-base-dev" That package seems to include the missing libcblas.so.3

now running script, I get the following output.
user@raspberrypi:~/pyobd $ python3 pyobd.py
Traceback (most recent call last):
File "/home/user/pyobd/pyobd.py", line 53, in
import obd_io # OBD2 funcs
File "/home/user/pyobd/obd_io.py", line 39, in
import obd
File "/home/user/pyobd/obd/init.py", line 41, in
from .obd import OBD
File "/home/user/pyobd/obd/obd.py", line 38, in
from .commands import commands
File "/home/user/pyobd/obd/commands.py", line 36, in
from .decoders import *
File "/home/user/pyobd/obd/decoders.py", line 38, in
from .UnitsAndScaling import Unit, UAS_IDS
File "/home/user/pyobd/obd/UnitsAndScaling.py", line 33, in
import pint
File "/home/user/.local/lib/python3.9/site-packages/pint/init.py", line 28, in
from .formatting import formatter, register_unit_format
File "/home/user/.local/lib/python3.9/site-packages/pint/formatting.py", line 20, in
from .babel_names import _babel_lengths, _babel_units
File "/home/user/.local/lib/python3.9/site-packages/pint/babel_names.py", line 11, in
from .compat import HAS_BABEL
File "/home/user/.local/lib/python3.9/site-packages/pint/compat.py", line 41, in
from typing_extensions import Self # noqa
ImportError: cannot import name 'Self' from 'typing_extensions' (/usr/lib/python3/dist-packages/typing_extensions.py)

I am novice on the raspberry so I am not sure it I am doing something wrong or it just wont run on the rasberry pi OS debian version.
Thanks for your work.

NEED HELP of OBD Bluetooth adapter

In your project, you recommended using Vgate icar pro 4.0, but the device manual we purchased only includes instructions for connecting to a phone. We need to connect to a computer via Bluetooth for development. How did you connect to the computer

FIxes to Readme

This is a very interesting project, I look forward to getting my cable and trying this out on my car. In the mean time I cleaned up my readme so that it would be easier to read. I didn't mess with the text since i'm not sure what your plans for the readme is but any changes you'd like me to make i'd be more than happy to do.

Refactor pyobd.py file is too large

Please consider making pyobd PEP517 compliant by adding pyproject.toml, etc, and placing it on https://pypi.org ?

This should install the executable "pyobd" into bin/.

This would make it easy to create ports/packages for it, and this would make it easier to install for users.

Thanks,
Yuri

Ubuntu Update for Install

There are a few issues for newer Python3 installs...

FreeGLUT3 Lib

For Ubuntu, the freeglut3 library is not found in newer installs (lunar +). However, the older package was just loading the libglut libraries. See Kinetic FreeGLUT files

Also, freeglut3-dev loads the libglut libraries plus the freeglut3 dev files. See Kinetic FreeGLUT Dev files

So, I changed the apt install ... to omit the freeglut3 package and install libglut3.12 instead.

Python and Virtual Environments

The docs don't mention running Python in a venv. New Python3 installs insist on using a venv to run local python apps using pip3. However, system-wide installs augment local venvs.

Since .venv is in the .gitignore file, I assume this is a known issue.

Option 1: Run app in global space

To run the app without a venv, the items in the requirements.txt need to be instead loaded with apt install ...:

sudo apt install python3-wxgtk4.0 python3-serial python3-numpy python3-tornado python3-pint

Then, the app can be run directly:

python3 pyobd.py

Option2: Run app in local venv

In any particular directory (maybe $HOME for a general local user venv):

python -m venv .venv

Then, activate it:

source .venv/bin/activate

Now install all your goodies with pip in the venv. Also, wxpython and tornado use an older style install that will be deprecated. So, until they are fixed, the --use-pep517 option may need to be used. See pypa/pip#8559. On my test install, wxpython version 4.1.1 failed. I changed the requirements.txt to use the latest (removed version control) and added the dependent attrdict3 before it.

requirements.txt

attrdict3
wxpython
pyserial==3.5
numpy==1.23
tornado==3.2.1
pint

pip3 install --use-pep517 -r requirements.txt

Now, run the app, etc.

python3 pyobd.py

When done:

deactivate

To remove a venv, just delete the .venv diretory.

rm -r .venv

ELM OBD Reader stuck at connection

Hello, working on a project, using a new OBD Reader device, first issue is that it is connected to ttyACM0 which is weird (i think), after finding the right device and granting permissions, when i try to establish a connection the whole code gets stuck. I've tried using an older version but to no avail.

It keeps getting stuck on this line

abort, ready, _ = select.select([self.pipe_abort_write_r], [self.fd], [], None)

thanks

Auto diagnostics? You mean car diagnostics?

I had hard time understanding what this package is about. "auto diagnostics" to means something else (automatic diagnostic .. of what). You probably want to say "car diagnostics"?

Add type annotations

[Help needed] I can't connect the OBD-II

Hi,

I'm using a USB OBD-II Connector, Ubuntu 22.04 and I can't get it to work with your software (I'm using the executable in version 1.15 release on GitHub).

I've manage to connect using Putty with these settings :

But when I try with PyOBD using the same settings, it won't connect :

Do you have an idea of what I'm doing wrong ?

Thank you !

A separate branch for development

Where to find the standalone executables ?

Hello,

thanks for that promising project !

The Readme indicates there are standalone executables to download, but I can't find them :/
Could you give more indications on where to find them ?

In the meantime, I'll try running the script

Thank you :)

Could not connect to Citroen Xantia, needed changes to obd/elm327.py

I couldn't connect pyobd to a Citroen Xantia from 2000. I had to modify obd/elm327.py as follows:

--- elm327.py_orig      2024-05-09 09:48:07.604482624 +0200
+++ elm327.py   2024-05-09 10:53:50.468535411 +0200
@@ -294,14 +294,14 @@
         if self.__has_message(r0100, "UNABLE TO CONNECT"):
             logger.error("Failed to query protocol 0100: unable to connect")
             print("Failed to query protocol 0100: unable to connect")
-            return False
+            # return False  -- Try one by one !!

         # ------------------- ATDPN (list protocol number) -------------------
         r = self.__send(b"ATDPN")
         if len(r) != 1:
             logger.error("Failed to retrieve current protocol")
             print("Failed to retrieve current protocol")
-            return False
+            # return False  -- Try one by one !!


         p = r[0]  # grab the first (and only) line returned
         # suppress any "automatic" prefix
@@ -321,7 +321,10 @@
             for p in self._TRY_PROTOCOL_ORDER:
                 r = self.__send(b"ATTP" + p.encode())
                 r0100 = self.__send(b"0100")
-                if not self.__has_message(r0100, "UNABLE TO CONNECT"):
+                if not self.__has_message(r0100, "UNABLE TO CONNECT") and \
+                   not self.__has_message(r0100, "NO DATA") and \
+                   not self.__has_message(r0100, "BUS INIT: ...ERROR") and \
+                   not self.__has_message(r0100, "CAN ERROR"):
                     # success, found the protocol
                     print('success, found the protocol')
                     self.__protocol = self._SUPPORTED_PROTOCOLS[p](r0100)

Please consider supporting OBD2 WIFI

Please consider supporting OBD2 WIFI - like the following adapter:

http://www.mirrors4cars.com.au/index.php/product-detail/jtron-mini-wifi-elm-327-obd2

[ Feature request ]: add nix package.

On nixos running unpackaged applications is annoying and hard, if not impossible. Adding a nix package would be very helpful.

AttributeError: 'MyApp' object has no attribute 'sensor_id'. Code bug?

Hi Guys!

Thank you for this awesome project!
I just thought developers may be interested in the Linux terminal output below that might be a code issue?:

Available ports: ['/dev/ttyUSB0'] Open port event. Traceback (most recent call last): File "DELETED/GIT/pyobd/pyobd.py", line 2160, in OpenPort self.sensor_control_on() File "DELETED/GIT/pyobd/pyobd.py", line 1377, in sensor_control_on self.sensors.Bind(wx.EVT_LIST_ITEM_ACTIVATED, sensor_toggle, id=self.sensor_id) ^^^^^^^^^^^^^^ AttributeError: 'MyApp' object has no attribute 'sensor_id'. Did you mean: 'sensors'?

Please see the last line.
Ran as:
python3 pyobd.py

I did "git clone" on Jul 10, 2024 from the main branch I believe, so it should be relevant.
I followed Linux installation instructions from the main GIT page.
Observed the same output above both when adapter connected to the car and when disconnected from the car.
It still connected to the car well.

Adapter: ELM327.

Ubuntu 24.04 Cinnamon (almost fresh install).
Kernel: 6.8.0-38-generic
Python 3.12.3 (main, Apr 10 2024, 05:33:47) [GCC 13.2.0] on linux

Thank you again for this awesome work!

Detected: Trojan:Win32/Wacatac.B!ml

Error in byte to DTC conversion

There seems to be some logic error in converting byte values to dtc. The logic is present in the 'decoders.py' script under the obd folder. I don't know what is the logic in converting byte values to dtc codes. If anyone has any idea, could you please guide me? It would be a huge favor.
The reason I'm saying this is because when I rise a specific error in OBDSim, a different error is showed on PyOBD. For example, an error of P0103 is shown as P0300 in PyOBD.
It is worth noting that this error is not present on other scanning software though, such as Torque or Car Scanner

Testing of DTC needed

DTC has been showing some errors, which should be hopefully fixed now. But I still need people to test it on their cars and comparing it with other programs, to be sure it works properly now. So I can be sure it is fixed. Please contribute to this if you can. I think under CAN protocol it is fixed, but other protocols need to be tested. Under obdsim app it works good now, but the app only uses CAN protocol.

Please contribute.