pyOBD-II Code
Status: Alpha
Brought to you by:
pjcreath
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 |
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.