File	Date	Author	Commit
obd	2009-10-29	Peter J. Creath	[1eb8c4] further testing of obd.interface.create()
test	2009-10-29	Peter J. Creath	[a74f6f] improved error handling for record-all.py
CHANGES.txt	2009-10-29	Peter J. Creath	[a1be5c] added CHANGES
COPYING.txt	2009-09-07	Peter J. Creath	[40ed74] initial public commit
LICENSE.txt	2009-09-07	Peter J. Creath	[40ed74] initial public commit
README.txt	2009-10-29	Peter J. Creath	[095a5a] updated README, TODO for 0.4 release
TODO.txt	2009-10-29	Peter J. Creath	[095a5a] updated README, TODO for 0.4 release
readiness.py	2009-10-28	Peter J. Creath	[7dbff7] generalized obd.interface.create()
record-all.py	2009-10-29	Peter J. Creath	[a87a85] added record-all.py and improved regression tests

Read Me

pyOBD-II alpha 0.4
Copyright (c) 2009 Peter J. Creath


OVERVIEW
--------
pyOBD-II (a.k.a. "pyobd2") is a Python library for communicating with
OBD-II vehicles.  Its goal is to make writing programs for vehicle
diagnostics and monitoring vehicle data as easy as possible.  Being
written entirely in Python, pyobd2 is intended to be portable across
many platforms, including Mac OS X, Linux, BSD, and Windows.

While pyobd2 has been extensively tested with a few vehicles, it has
not yet been tested with a wide variety of vehicles.  As a result,
I would greatly appreciate any bug reports, and especially
communication logs from people with vehicles that speak protocols I
haven't been able to test.  See USAGE below for more details on how
to help.

Many thanks to Vitaliy Maksimov at ScanTool.net for his generous and
in-depth support of this project!  pyobd2 wouldn't have been nearly
as robust or well-tested without his help.  ScanTool.net sells and
supports scan tools and other automotive test equipment at
<http://www.scantool.net>.


EXPLANATION
-----------
If you're intimidated by the acronym soup, here is a short explanation
in lay terms:

Recent and future cars and trucks all contain small computers that,
among other things, monitor their exhaust and emissions and report
those data upon state inspection.  They report this information in a
set of common protocols often called "OBD", short for On-Board
Diagnostic.  (The official name for the protocols and their
specifications involves more alphabet soup.)

You can connect your computer to the OBD interface of your vehicle using
a "scan tool", a small device that sits between your computer's serial
(or USB) port and your car's OBD port.

But then you need to talk to the vehicle.  That's where pyobd2 comes
in.  You can issue queries to the vehicle, and pyobd2 will handle the
details, returning the response to you as a Python object, which you
can then inspect and use as you like.  The goal is to make this very
easy, so that client programs can focus on powerful features and
intuitive user interface without having to worry about the low-level
plumbing.

pyobd2 was written from scratch in 2009 by Peter J. Creath and is
unrelated to the apparently abandoned "pyobd" by Donour Sizemore (last
updated in 2004).  I apologize for the confusing naming -- there are
only so many ways to express "Python OBD library".


REQUIREMENTS
------------
- ELM327-compatible scan tool:
  pyobd2 currently supports only ELM327-compatible scan tools.  You will
  need such a scan tool in order to connect your computer with your car. 

  You can purchase a scan tool from <http://www.scantool.net/scan-tools/>.

- pySerial
  pyobd2 relies on pySerial to communicate with scan tools.  It has been
  tested with pySerial 2.4 and Python 2.6, but should generally work with
  other versions as well.

  NOTE: pySerial 2.5rc1 is known not to work on Darwin.


USAGE
-----
In its present state, pyobd2 is largely a library for further development.
There are two command-line programs of interest:

readiness.py -- queries a vehicle for its emissions inspection readiness;
    Checking for readiness requires that the vehicle's engine be running.
    Then run this script to see which internal monitors are ready for testing.

record-all.py -- runs through all of the regression tests and records the
    communication sessions, packaging them up into "recorded-data.zip".
    To assist in the debugging and development of pyobd2, run this script
    and please send the resulting .zip file.

The above two programs are reasonably useful sample code for using the
pyobd2 library.  The general outline of usage is:

    import obd
    import obd.message.OBDRequest

    # Find the scan tools attached to the computer and pick one
    interfaces = obd.interface.enumerate()
    interface = interfaces[0]

    # Open the connection with the vehicle
    interface.open()
    interface.set_protocol(None)
    interface.connect_to_vehicle()

    # Communicate with the vehicle
    request = obd.message.OBDRequest(sid=0x01, pid=0x00)
    responses = interface.send_request(request)

    # Close the connection
    interface.disconnect_from_vehicle()
    interface.close()



KNOWN LIMITATIONS
-----------------
These limitations are not necessarily intended to be permanent; they are
simply the known limitations as of writing.  If there's a limitation here
that you'd like addressed, please don't hesitate to contact me.

* Only ELM327 and compatible interfaces are currently supported.  This
  includes the ElmScan 5, OBDLink, and OBDLink CI from ScanTool.net.

* Serial port enumeration only works on Darwin (Mac OS X), and maybe BSD.
  An interface may still be created manually on other platforms by explicitly
  passing a known serial port.

* Setting headers (to direct requests to specific ECUs) is not yet supported,
  though it is still possible to ask the interface to set the header manually.

* Handling of group requests (ISO 15765 only) is not yet implemented, though
  it should still be possible to send any arbitrary request to the interface.

* Due to a bug in pySerial 2.4, 230Kbps is the highest baud rate supported
  on Darwin, and probably other POSIX platforms.

* There is no API (yet) for passively monitoring the bus, though it should
  still be possible to ask the interface to begin monitoring.

* There's not much documentation yet.

* The API is not completely stable yet.

* Reading from the serial port may wait slightly longer than the specified
  timeout, up to 0.01 seconds by default.  If necessary, this can be adjusted
  changing the value of obd.serialport.SerialPort.MAX_READ_OVERRUN.

* Many OBD messages are not yet extracted into structured Response objects;
  they are only encapsulated in generic objects that contain the raw data.