OBD II Scantool on Puppy Precise 5.5

[ericsond]

Since 1996 all cars sold in the US have been required to support the OBD II standard (On-Board Diagnostics). There are many devices available on the market to interface to these cars, both stand alone and PC based. One popular set of devices are based around the ELM327 microcontroller from ELM Electronics, which includes versions in RS-232, USB and Bluetooth. These ELM327 and ELM327 based clones allow a PC to communicate to the car's OBD port, and support most, if not all, OBD II protocols used today.

This post details the steps needed to create a Puppy Linux (or other Linux) based PC OBD II Scantool using the USB version of ELM327 based Diagnostics Interface cables and open source software from scantool.net version 1.21, allegro version 4.2.3.1, and dzcomm version 099i. The correct OBD II cable/interface has an OBD II connector on one end and a USB connector on the other and can be bought online for a (very) nominal price. The open source software OBD II functionality includes:

- Auto detect of OBD protocol (no need to input car vehicle parameters to determine OBD protocol)
- Monitoring of over 70 common sensor parameters
- Read and clear stored Diagnostic Trouble Codes/ Malfunction Indicator Lamp (DTC/MIL)

This was done using Puppy Precise 5.5 (Ubuntu 12.04 LTS based), and would probably work for other Puppy versions as well. The method outlined here also provides an environment to build upon the basic functionality provided by the open source software, that is, additional functionality can be added as needed as all source code is present. Modifications have been implemented to dzcomm to allow use with USB, and Scantool to allow the use of clones, so be sure to use the files as attached; no change is needed for allegro. These changes have been documented on the web previously, and this post is essentially a condensation of those prior works, as related to Puppy Linux.

Everything is done as root for Puppy (by default). Of course for other Linux versions, this is not the case. If you make a mistake during compile and want to start over, use 'make clean'. Comments in parenthesis () are not part of command line.

Basically you will need to do the following:
- compile allegro library (the Ubuntu allegro libraries don't seem to work for Puppy Precise)
- get dzcomm and scantool sources, unzip, and replace modified files with the files from
attached ReplaceFiles.zip file
- compile dzcomm (which handles RS232 to USB conversion)
- compile Scantool121
- clean up any other issues like setting USB port to COM port

Perform all unzip/tar operations at a base directory, e.g. /root/, now referred to as ~ .
This means to place downloaded files at this base ~ directory for operation.
The exception to this is scantool, because the unzip does not generate a new directory.

1. Install devx.sfs package for Puppy (compiler), needs about 140M via Puppy Package Manager

2. tar and compile Allegro source:
Get Allegro source tar.gz from:
http://sourceforge.net/projects/alleg/f ... z/download

In shell console, at ~
tar -zxvf allegro-4.2.3.1.tar.gz
cd /root/path_to_your_allegro_files/
chmod +x fix.sh (change files to Linux compatible)
./fix.sh unix
./configure
make (there will be warnings)
make install

If you want to see if allegro works, run demo at ./demo/demo, hit ESC to end.
Note a sound initialization issue on the demo does not affect Scantool operation.

3. Unzip dzcomm and scantool sources:
Get dzcomm dz099i.zip here, place at base directory:
http://sourceforge.net/projects/dzcomm/files/

In shell console, at ~:
unzip dz099i.zip
mkdir Scantool121 (scantool zip file does not create a new directory)

Get scantool scantool_net121src.zip source here, place in ~/Scantool121/
http://www.scantool.net/downloads/archi ... -software/

In shell console, at ~/Scantool121/:
unzip scantool_net121src.zip

4. Make ReplaceFiles.zip changes to dzcomm and scantool:

Copy attached ReplaceFiles.zip to ~, then in shell console:
unzip -uo ReplaceFiles.zip

This overwrites modified files in both dz0991 and Scantool121 directories with updated files.
Note for this to work, you must have the correct directory names as used here. The -u option
overwrites existing files, and the -o suppresses querying for each file.
An alternative would be to unzip the ReplaceFiles.zip file elsewhere and manually replace those files.

At this point you should have all (3) source directories, all with the correct files.

5. Compile dzcomm source:
In shell console, at ~
chmod +x fixunix.sh
./fixunix.sh
./configure
make (there will be warnings here)
make install

6. Compile Scantool121 source:
In shell console, at ~/Scantool121/:
make
chmod +x ScanTool (make executable)

This creates the output file wanted named ScanTool

7. Determine USB port and map to tty (this is to interface between the dzcomm software and USB):

Determine which port USB is coming in, in shell type ls /dev.
Plug in USB cable, wait 15 seconds, then type ls /dev again
You should see a new device similar to /dev/ttyUSB0

Map the USB port on the PC to a free serial port (e.g. tyyS5).
This can be done by adding 2 lines in /etc/rc.d/rc.local which will run during bootup:

rm /dev/ttyS5
ln -s /dev/ttyUSB0 /dev/ttyS5 (replace with correct USB port found above)

Note ttyS5 corresponds to COM6 on the Scantool GUI Interface Options screen.
Execute these lines as root on the command line if you do not plan to reboot now.

8. Check config of scantool.cfg file in Scantool directory, first lines should be similar to

version = 1.21

[general]
system_of_measurements = 1
display_mode = 1

[comm]
baud_rate = 14
comport_number = 5 (corresponds to ttyS5, and COM6 on ScanTool GUI Interface)

Notes: measurements in US, display in non full windowed, factory default Baud rate is 38400.
Change comport number if not using ttyS5.
Appears ScanTool can only be run in non full windowed mode due to allegro.

9. You should now be able to execute ./ScanTool.
See running ScanTool notes at end for proper sequence.

The remaining steps create a pretty desktop icon.

Create bash shell st with the following:
#!/bin/sh
cd /root/path_to_your_Scantool_dir/
./ScanTool

Make st executable using chmod +x st.

Create desktop icon to run ScanTool via st script, use ~/Scantool121/scantool.ico for icon

This sequence seems to work the best and most consistently.
Turn car on to run position, but do not start car. (Start car if you want to view real time data)
Plug in OBD connector to car
Plug in USB to PC
Wait 5 seconds
execute ./ScanTool from Scantool121 directory, or use pretty Desktop Icon

It appears that some Sensor Data parameters can cause the ScanTool to lock up, perhaps these may be specific to a vehicle and not supported. Luckily, there is a "Reset Interface' button on the Sensor Data screen, be sure to click off the offending parameter first.

As ScanTool runs, it creates a log.txt file in the ScanTool directory, this can be used for troubleshooting.

The following URL contains ELM327 suppoprt documentation from ELM Electronics.
http://www.elmelectronics.com/obdic.html#ELM327


OBDII notes:
OBD-II Diagnostic Trouble Codes are 4-digit, preceded by a letter:
P for engine and transmission (powertrain),
B for body, C for chassis, and U for network.

[ericsond]

Have been able to make some updates to the open source code to add the following functionality:

1) Command and data are now kept in the comm_log.txt file, which is overwritten every time you start ScanTool. This was already present but had to be enabled.

2) OBD PIDs 0, and 20 are now read in during initial entry into the sensor parameter screen, this allows only car specific supported PIDs to be available to the user (no more enabling a non supported PID to have the system hang up). Believe full support for up to PID 40 is now available, although not fully tested. The title bar of ScanTool says 'Initializing' during this initial entry time.

3) Have changed the sensor parameter screen to add new graphing functionality. To use the graphing you must install gnuplot, which is available via the Puppy Package Manager, or other package manager if you run non-Puppy Linux. The new buttons are labelled, 'START', 'STOP', and 'GRAPH', which replaces the one button used previously for 'Options'. The same button is used for all three commands, and starts out with 'START', if pressed changes to 'Stop', if pressed again changes to 'GRAPH'. The graphing feature was added to support only one parameter at a time, and has not been tried with more than one parameter. Full oxygen sensor support is included, and allows the sensor command and trim values to be shown on the same screen (as that is one parameter of the ScanTool parameter list). Sensor Parameter data is stored in the datalog.txt file, which is overwritten every time you start a graph capture run. To use, recommend that you set up the ScanTool to monitor the one parameter you want, then press start, wait whatever time you want capture data, press stop, then press graph. As the datalog.txt file is overwritten everytime a new graph is started, be sure to rename the datalog.txt file if you want to save the data file. With this data file you can also graph the data in Gnumeric or another spread sheet program. GNUPlot graphs can be saved by copying and pasting into Abiword.

4) The Sensor Parameter screen has now been changed to list PID's numerically, with the PID number in the first columns for reference. Again, note only car specific supported PIDs will be shown.

Remember, install GNUPlot if you want graphing capabilities with the new code.
ScanTool system log available in log.txt file, overwritten each time ScanTool starts.
Serial command and data are available in the comm_log.txt file, overwritten each time ScanTool starts.
Sensor parameter data are available in the datalog.txt file, overwritten each time a new graph is started.
All three log files are in the ScanTool directory.

It appears the sensor update rate is mostly dependent on the ability of the car to respond to the requested PID. For example, a new Honda can update at faster than 20 samples per second (even at 38400 Baud), but an older Subaru can only manage 4 samples per second. View the comm_log.txt file to gain some perspective.

Recommend you look at http://en.wikipedia.org/wiki/OBD-II_PIDs for more PID information.

A zipped file (FileUpdates.zip) for all changes is attached, recommend you either unzip elsewhere and copy, or use the unzip -uo option, be sure to be in the ScanTool directory when you do this, as all files changes are only with the ScanTool software. Of course you will need to 'make' after to compile the changes. Also recommend you copy the entire ScanTool directory beforehand, so you still have a working copy in case this does not work for you.

Believe with these changes, ScanTool becomes a much more useful tool for the home mechanic. Would welcome your thoughts as well.