SDB:ELM327 based ODB2 scan tool

This article is in need of attention because it does not follow our wiki guidelines. See Help:Style#General_usability
If you want to contribute, please read the rules for this wiki and if you have any questions, don't hesitate to contact the wiki team, we are more then willing to help you! :-)

openSUSE Support Database

Portal - SDB Categories - How to write an article

With this ELM327 based gizmo it's possible to interface with the on-board computer of a (usually post 1996) car and retrieve lot's of very interesting information, like speed, engine characteristics and Diagnostic Trouble Codes.

Using the seller's list, some of the specs:

Feautures:
- Read Codes display diagnostic Code(DTCs)
- Clear DTC and Reset MIL(check Engine Light )
- Support the latest vehicles with the new CAN-BUT protocols
- No battery required power is supplied by the OBD port
- LED indicate power and show communication staus
OBD-II protocols
- SAE-J1850 PWM (41.6 kbaud)
- SAE-J1850 VPW (10.4 kbaud)
- ISO-9141-2 (5 baud init, 10.4 kbaud)
- ISO-14230-4 (5 baud init / fast init, 10.4 kbaud)
- ISO-15765-4 CAN (11bit/29bit ID, 250/500 kbaud)
- SAE-J1939 CAN (29bit ID, 250kbaud)
Compatible with following vehicles:
- Car in Europe market form 2001
- Diesel cars in Europe from year 2004
- Car (Domestic & Import) in the USA market from 1996
- Light trucks (US Domestic & Import ) from 1996

Look for it on eBay

OBD-II resources

Open Source Software and Interfaces

as mentioned on this page

Opendiag simple OBD-II to RS232 cable and information about Volkswagen-specific extensions.
Freediag open source software that works with six different cables.
the classic "Jeff" interface OBD-II <-> RS232
scantool.net interface vendor offers source code for Windows that is also reported to work in Linux under Wine. How to use the software
Design News article on improving fuel efficiency includes an OBD-II interface circuit and a discussion of how fuel efficiency can be calculated from airflow and vehicle speed.
obddig.net offers a schematic, software, and a kit for a PIC-based computer interface.
Serial interface OBD II or KL to RS232 with cheap ISO IC MC33290 (schematic and PCB; German, translated with babelfish)
USB Port interface OBD II or KKL to USB with cheap ISO IC L9637 (schematic; German, translated with babelfish)
RomRaider ROM editor/ECU logger for Subarus

How to get it working on openSUSE / Linux

Unfortunately the package - and the CD inside it - only contained software and usage information for Windows. Good thing is that it is quite easy to get the scan tool working under openSUSE and of course also under other Linux distributions.

Communication schematics

                          PC ---> |               | <--ODB II scan tool -------> | <- Car
[Serial console, e.g. minicom]    |               |                              |
   |                              |               |                              |
   |                              |               |                              |
   +--[RS-232]--[rfcomm / Bluez]--|--[Bluetooth]--|--[console]--[ODB interface]--|--[ODB II interface ]--[car's on-board computer]
   |                              |               |                              |
   |                              |               |                              |
[ODB II program]                  |               |                              |

A more detailed block diagram of the ELM327 chip itself is shown on page 1 of the ELM327 data sheet (see References)

Required Software

Drivers

The Bluez package provides everything you need to connect with the device. Besides openSUSE and derivate distro's, Bluez is present in all mainstream Linux distributions that I'm aware of.

OBD-II program

Though the scan tool will make it possible to interface with the car's on-board computer (also know as ECU or Engine Control Unit), but in addition to this a specialized program is needed to interrogate it.

There seem to be numerous options on Windows but the choice on Linux is more limited. I've tried pyobd, which - after some tweaking on the initialization routine - was able to take a reading of the ECU.

Preparations

Bluetooth pairing code

The pairing code of this device is: 1234

It is probably not possible to change this, so theoretically anyone in range could connect to the scan tool. Besides being able to take some readings on the engine settings, the thread is quite limited though.

Bluetooth address

Attach the device to the OBD-II port on your car, and use the hcitool to discover the available Bluetooth devices. The scan tool will show up something like this:

$ hcitool scan Scanning ... 00:02:03:ac:a1:d3 EDT

Obviously the address will be different.

Getting connected

To connect to the ELM327 OBD2 scanner, we'll need three parameters:

The bluetooth address of the device, e.g. 00:02:03:ac:a1:d3 (see output from "hcitool scan")
The number of the rfcomm channel the device is providing the serial port profile. The ELM327 OBD2 scanner provides the serial port profile on channel 1.
A unique number X for our device file (/dev/rfcommX).

NOTE: Since it is possible to use other Bluetooth devices on the same computer, it is good practice to use unique device names for each Bluetooth device and make them persistent. This way one can avoid accidentally trying to open a GPS device with the OBD-II diagnostic program, or attempt to go on-line through a Bluetooth mouse because yesterday there used to be an UMTS modem on that device number.

The following command establishes a connection to the bluetooth device 00:02:03:ac:a1:d3 on channel 1 and makes it accessible as /dev/rfcomm99

# rfcomm --auth connect 99 00:02:03:ac:a1:d3 1

It is more easy to do this step while running a Gnome session since it has a nice PIN entry applet.

NOTE:

some devices do not require authentification.
after establishing the bluetooth connection some devices immediately disconnect again if they are not used (not connected as RFCOMM device)

Make the configuration persistent

Pairing code

After the first connection with the scan tool, the pairing PIN will be stored in /var/lib/bluetooth/<local macaddr>/linkkeys, so all subsequent connections will be automatic.

rfcomm settings

Edit the /etc/bluetooth/rfcomm.conf to reflect these settings.

# cat /etc/bluetooth/rfcomm.conf rfcomm99 { bind yes; device 00:02:03:ac:a1:d3; channel 1; comment "ELM327 based OBD II test tool"; }

Allow non-root users to use the scan tool

By default the device file /dev/rfcomm99 is created with ownership and group set to root and read-write access rights to owner and group.

# ls -l /dev/rfcomm99 crw--w---- 1 root root 4, 0 Aug 15 20:30 /dev/rfcomm99

With this simple udev rule one can automate the following actions every time the /dev/rfcomm99 device is created:

assign ownership to user "joe"
assign group ownership to group "dialout"
create the symbolic link /dev/obd-ii-scan-tool to /dev/rfcomm99

# cat /etc/udev/rules.d/99_custom.rules KERNEL=="rfcomm[0-9]*", ATTR{address}=="00:02:03:ac:a1:d3", ATTR{channel}=="1", NAME="%k", OWNER="joe", GROUP="dialout", SYMLINK+="elm327"

Use this to obtain more information about possible criteria for udev rules on the scan tool:

# udevadm info -a -p $(udevadm info -q path -n /dev/rfcomm99)

Using OBD-II software

NOTE: Many ELM327 devices are cheap clones of the original ELM327 from Elmelectronics !
Some are pretty close to the original, but many clones do not provide the full functionality / set of commands of the original. The implementation of commands is also often faulty or faked.
So if you encounter any problems with your device and a OBD-II software, you should always check your device first. See section "AT Command Descriptions" in the product datasheet. (Hint: clones almost never support the command "AT PPS").

Control the connection to the scan tool

An easy option is to use this script to control the connection to the scan tool.

cat /etc/init.d/elm327 #!/bin/bash ### BEGIN INIT INFO # Provides: elm327 # Required-Start: # Required-Stop: # Should-Start: # Should-Stop: $null # Default-Start: 3 5 # Default-Stop: 0 1 2 6 # Short-Description: Start elm327 # Description: starts the elm327 bluetooth device ### END INIT INFO DevNum=99 # DevNum is depending on the rfcom settings /etc/bluetooth/rfcom.cfg case $1 in start) rfcomm bind $DevNum ;; stop) rfcomm release $DevNum ;; status) rfcomm show $DevNum ;; *) cat<<EOF Usage: $0 [ start | stop | status ] EOF esac

The start (and stop) operation will require root privileges, so non-root users should use the script with sudo.

sudo /etc/init.d/elm327 start

OBD-II software configuration

These programs require a serial port through which they can communicate with the ECU, so just point them to use the /dev/rfcomm99 or /dev/elm327 device.

ODB-II codes

There are lots of codes that ECU's are sending about the state of the numerous monitored parts. Some of these codes are standardized, others a manufacturer of maybe even model dependent.

References