Linux OS‎ > ‎


Linux ELM327 OBDII Interfacing

Last Update 12/24/17


Terminal Interface
Python ELM source code
Wills Console OBD Interface
Wills Linux Serial IO Primer


I recently had a couple of my old clunky vehicles show their age by having the check engine light come on. Although I know some friendly garage mechanics I wondered what was involved in checking and clearing these codes myself. I was pleased and surprised to find that there were interface devices that would connect a computer to the car's OBDII interface jack and allow me to interact with the car's diagnostic chip available for under $20. I used Amazon for the two I purchased, but a google search turns up lots of hits as does searching or Apparently many of the less expensive ones are prirate clones of the ELM327 chip created in China, but they seem to work. However if you care about this stuff the chip designer isn't getting any revenue from these sales.

The standard seems to be to supply the device with Microsoft Windows software drivers and some form of GUI program for the user to interact with the ELM327 device. Often this program is scantool_net113win.exe although there are others. I personally do not like using the evil empire's operating system so I looked for free Linux solutions to this interface issue. I outline four methods I've found online, and one I developed from scratch (although its not very elegant it taught me a lot about the ELM327).

ELM Electronics manufactures the ELM327 and a couple related chips. All of them convert an rs232 signal to one or more of the OBDII protocols as described here. The vendors package this up with a plug that fits into the OBDII connector on your car on one end and some form of rs232 compatible interface on the other. Traditionally the connection was made with a standard rs232 cable, but more recently devices are available with usb or bluetooth connections. In the usb case there is a built in usb to serial converter in the device and it plugs into your usb port. In the bluetooth case there is no visible connector, the device attaches in Linux via the bluetooth rfcomm protocol and you must have a suitable transceiver installed on your computer. Suitable USB rfcomm dongles are available for under $5 but you will need one of these in addition to establish communication unless bluetooth is already built into your computer.

Terminal Interface

On investigation I decided the ELM327 chip was very nicely designed for the amature home user. Since the marketed devices all come with a GUI interface I originally assued one was dealing with complicated encoded signal here, but that is not the case. The ELM327 accepts commands and responds in ASCII. If you are old enough to remember the days of dial up modems you probably remember the Hayes AT command set that became the standard for configuring and controlling your modem. The ELM327 is very similar to this, except that its output is always in ASCII (it does not switch to a binary mode once a connection is made). I recommend looking at the following references started, but there are many others out there:
On-board_diagnostics summary from wikipedia
Full AT command set
AT command summary for USB interface

Kris Occhipinti has released a nice video clip of using the Linux 'screen' terminal program to interact directly with an ELM327. I think there are actually three videos in the series, this is the 2nd which I found the most informative, but you might want to watch all three if you find it interesting. I was fascinated to learn how easy it was to talk to these devices the first time I saw this video. Kris might have been better served if he had issued an 'ATL1' command at the start. This would have turned on line feeds in the ELM327 interface and scrolled the screen during each reply from the ELM327 so the 1st char of the responses was not overwritten, however its understandable without this and even clearer if you try it yourself and add this command.
I did not know about 'screen' until I watched this video. Its a nice program and seems to be installed by default in all of my Slackware distributions. It supports creating a log file so you can have a record of your interaction with the ELM327, read the man page and look for 'C-a H' from the keyboard after you have started screen to toggle log file output on and off for file 'screenlog.#'. I run it with two arguments, the comm port to connect with and the baud rate:
screen /dev/tty* baud_rate
ie 'screen /dev/ttyUSB0 9600'

Windows used to come with a terminal program called Hyperterminal by Hilgraeve. I believe they stopped including it in their distributions after WinXP. If you are running windows and need a terminal program you may find PuTTY useful. There are many similar programs out there, and you can do everything you probably need to with a terminal program. Just spend a little time reading the documentation and understanding the codes.

I've found reference to two python based GUI tools that can potentially run with Windows, MACs, and Linux Xwin. I played with these a little but am not a python guru and never got them running. Both Windows and Linux require pyserial, a Python Serial Port Extension, which is available at Sourceforge. I am not sure this works on a Mac, but think so. I downloaded the source tarball successfully after a couple false starts. However if you have trouble try going to the main Soureforge page and search for 'pyserial' it is available! This creates a loadable python module that handles interfacing with serial ports. In python its accessed via 'import serial'. Then I discovered I still didn't have installed which is also required to make these work on my system in Windows and gave up on Windows.

This is a screen shot of the ObdTester program which is apparently open source. The source code is available for download as is an rs232 python library which is required to build the program. Apparently this library works with usb and bluetooth serial emulation in Linux, but not in Windows so if you want to use either of these modes in Windows you have to buy a custom made executable. Since I'd rather run my diagostics in Linux this is not a problem. However I never actually got this to work for me in Linux and eventually wrote my own C code.

I also found a pyOBD-II distribution at sourceforge that looks interesting. Do to my lack of python experience I never got this to run in Linux either, but it maybe worth trying.

I also found a python based system that runs on the Rasberry PI. I have no way of testing this but thought I ought to add the link.


This is the last version of scantool_net that is free and open source. It appears that, LLC became increasingly annoyed with the clone chips and devices being imported from China and stopped the open source development of their open source program with ScanTool.net121. They still offer a free OBDwiz program, but its only for Windows users. From forum comments they have never been very linux friendly, but the last open source software can be compiled and built under linux with a few tweaks.

Wills Console OBD Interface

As a programmer geek type I could not resist writing some of my own code to try these concepts out. obd_tst is a console based program that will interact with an ELM327 device and is capable of automating the process of obtaining data and pulling error codes (ecu 'Check Engine' codes). As described above you can do this manually almost as easily, but I did build in a log facility so one can obtain a log of the responses. Some terminal emulators (ie Linux's screen program) can create logs also. Slightly more interesting is a companion program I wrote, obd_emu, which emulates an ELM327 device connected to a Honda Civic. I have been using obd_emu for testing as I try the various GUI interface programs I've found. I really didn't want to have to run out to the car each time I needed to test a new compilation of a program. obd_emu pretends to be an ELM connected to a vehicle for most of the less exotic commands. Note these are console mode programs, not GUI.

If anyone is interested in these I am making the source code for the current September 2015 versions available under the GNU public license. I have been using these programs in DOS and Linux. These programs require an rs232 communication library, and I have used Teuniz's RS-232 library in Linux. Teueniz's library (and therefore my program in Linux) supports rs232, usb, and bluetooth devices. I have a DOS library which just supports physical rs232 COM ports I cobbled together but am not willing to put it in the public domain so you are on your own there. If anyone wants to try these as text mode DOS executables for rs232 devices email me, I'm happy to make them available.

Let me know if you do any enhancements, especially to obd_emu which could use more responses added for pids which are not available on my vehicles. I'm also interested in the mode 2, freeze frame data, but have not gotten that to work at all yet.

Will's Linux Serial IO Primer

I include this section in the hope it maybe useful to someone else, however its here primarily to remind me of what I have done to get various interfaces to work. Currently I own both a USB ELM327 and a BlueTooth ELM327. I have done tests emulating an RS232 ELM327 with my obd_emu program. These notes are Slackware specific, although must of this is probably distribution independent. I am currently running the Slackware 14.1 distribution with a 3.10.17-smp kernel. This is a very brief overview, for more detail search the internet! According to bluetooth has been supported in linux since the 2.6 kernel series. I'm new to bluetooth which is the primary reason I've added this section, ie as a reminder to myself about how I got this working.

Linux uses device files for most of the system io, including serial communication. A user can view their current list of serial devices by listing the /dev directory with 'ls /dev/tty*'. My rs232 style ports are listed as /dev/ttyS?, ie /dev/ttyS0 maps to the DOS/WIN32 COM1. For each USB to serial adapter on the system a /dev/ttyUSB? file will be created where ? starts at 0 and increases as more adapters are added. All the linux programs discussed above provide a mechanism to specify which device file you want to use to connect to the ELM327. For rs232 and USB devices the device file will be created automatically with a generic Slackware installation.

Bluetooth, at least in Slackware, is a little different. I assume you have the 'bluez-utils' installed, if not download and install them. The next step is to see if you have hardware support for bluetooth on your system. The command 'hciconfig -a' will search any bluetooth devices and display their status, if it returns nothing as initially occurred on my antiquated machine you have to install one. Assuming you have USB ports available the cheapest and easiest route is to purchase a 'BlueTooth dongle' (typically less than $5) and plug it into a USB port. Now hciconfig should give you some output. Note if you are running Xwin and have the Dolphin file manager available you can run it and look at the 'places' listing on the left of the screen, if you have a bluetooth hardware device installed you will see 'Bluetooth' listed as one of the available places, clicking on this icon searches for and lists devices to which you can connect.

I did this, but was still not home free. The device names hciconfig lists are HCI?, in my case I only have one device when the dongle is installed, HCI0. You want hciconfig to report the device is 'UP RUNNING PSCAN', but I mine was 'DOWN'. In Slackware, if you did not request BlueTooth support during installation you must use a file manager (or chmod from the console) to make the /etc/rc.d/rc.bluetooth script file executable. Then reboot or manually run the script with the 'start' parameter:

    #sh /etc/rc.d/rc.bluetooth start
For more detail see internet.

Once your hardware device is up and running try 'hciconfig scan' which should search for and list external bluetooth devices your system detects and can potentially connect with.