NAME
Device::ELM327 - Methods for reading OBD data with an ELM327 module.
VERSION
Version 0.06
SYNOPSIS
This module provides a Perl interface to a device containing an Elm Electronics ELM327 OBD Interpreter and provides access to the following functions:
Read OBD parameters and extract individual values from results.
Read OBD Trouble Codes and expand them to their full form.
Reset OBD Trouble Codes.
Read ELM327 parameters.
Write and write the ELM327 data byte.
Calibrate ELM327 Voltage.
Switchable diagnostic trace and replay function for debugging.The module is written entirely in Perl and works with both Linux and Windows. Depending on which operating system it is run on it uses either the Win32::SerialPort or Device::SerialPort module (which you'll need to install first) so it should work on any platform that supports one of them.
use Device::ELM327;
my $obd = Device::ELM327->new();
# Read status information...
$obd->Show("ELM identity");
$obd->Show("Vehicle Identification Number");
$obd->Show("Engine RPM");
$obd->ShowTroubleCodes();
undef $obd;SUBROUTINES/METHODS
new - the constructor for the module.
To open the device and have it search for an ELM module:
my $obd = Device::ELM327->new();If you know the port name (e.g. 'COM5', '/dev/ttyUSB7' etc) it may be quicker to pass it into the function:
my $obd = Device::ELM327->new($port_name);If you want extra debugging information, it can be enabled by setting $debug_level to a positive number in the range 1 to 3, with more information being displayed as the number increases:
my $obd = Device::ELM327->new($port_name, $debug_level);A value of either undef or "" can be passed for the $port_name:
my $obd = Device::ELM327->new("", $debug_level);The module can replay previously captured debugging information:
my $obd = Device_ELM327->new(undef, $debug_level, $replay_filename);To produce a file containing replayable data simply set $debug_level to 1 or higher and pipe the output to a text file:
perl test.pl>test_output.txtPortOK
Returns 1 if the serial port and ELM module are working or 0 if no ELM device could be connected to.
$obd->PortOK();ShowReadableValues
Displays the list of values that can be read from the ELM/ECU.
$obd->ShowReadableValues();Show
When passed the name of an OBD value (e.g. "Engine RPM") in $value_name, it displays the address of the ECU which returned the value, the name of the value which was read or the name of one of many parameters returned followed by the value and the name of any unit associated with the value.
If an error occurred, a message will be displayed instead.
$obd->Show($value_name);This function calls the 'Read' function.
Read
When passed the name of an OBD value (e.g. "Engine RPM") in $value_name, it returns a reference to a structure containing a status flag and any responses:
my $response = $obd->Read($value_name);
if ($response->{'status'} == 0)
{
foreach my $result (@{$response->{'results'}})
{
print "$result->{'address'} - $result->{'name'}: $result->{'value'} $result->{'unit'}\n"
}
}In the example above, $result->{'address'} contains the address of the ECU which returned the value, $result->{'name'} contains the name of the value which was read or the name of one of many parameters returned. $result->{'value'} and $result->{'unit'} contain the value and the name of any unit associated with the value.
Error conditions are indicated by a non-zero value of $response->{'status'} and an error message in $response->{'status_message'} (the default is 'ok' when there is no error).
Error code Meaning 0 ok -1 Unrecognised value -2 No data returned for value -3 Unsupported value
ShowTroubleCodes
Display any trouble codes on the console:
$obd->ShowTroubleCodes();ClearTroubleCodes
Clear any Trouble Codes and sensor data:
$obd->ClearTroubleCodes();Note that clearing the sensor data will cause the vehicle to run on default values until it has recalibrated itself. This may affect performance and fuel economy.
The ISO specification also insists that any user interface which invokes this function should display an "are you sure?" message to the user before calling it.
CalibrateVoltage
Changes the calibration value used by the ELM module. The value $Voltage is a string containing a fixed point value of the form: xx.xx, e.g "11.99", "12.01" etc.
$obd->CalibrateVoltage($Voltage);The Voltage can be read by calling:
my $response = $obd->read("Input Voltage");
ResetVoltage
Resets the ELM module's Voltage calibration to the factory setting:
$obd->ResetVoltage();WriteStoredDataByte
Writes $byte_value to the ELM module's non-volatile storage area.
$obd->WriteStoredDataByte($byte_value);The value of this byte can be read using:
$obd->Read("Stored data byte");
AUTHOR
Alister Perrott, <aperrott at cpan.org>
BUGS
Please report any bugs or feature requests to bug-device-elm327 at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Device-ELM327. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
Please also include a debug trace showing the error. This can be done by setting $debug_level in the constructor to 1 and piping the output to a file. e.g. perl myOBD.pl&>trace.txt
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Device::ELM327You can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
My ELM327 page
ACKNOWLEDGEMENTS
Many thanks to: The authors of Win32::SerialPort and Device::SerialPort. Larry Wall and all the other people who have worked on Perl. ELM Electronics for creating the ELM327 module. Everyone involved with CPAN.
LICENSE AND COPYRIGHT
Copyright 2012 Alister Perrott.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.