chinnk2/pyobd.pi

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI Pipeline
+
+on:
+  push:
+    branches: 'master'
+  pull_request:
+    branches: '*'
+
+jobs:
+  build:
+    runs-on: ubuntu-18.04
+    strategy:
+      max-parallel: 4
+      fail-fast: false
+      matrix:
+        python-version: ['3.8', '3.9', '3.10']
+    steps:
+      - uses: actions/checkout@v1
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install tox tox-gh-actions
+      - name: Test with tox
+        run: tox

.gitignore

@@ -0,0 +1,56 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+env2/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage*
+.cache
+nosetests.xml
+coverage.xml
+.pytest_cache
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/

.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false

COPYING → LICENSE

@@ -1,12 +1,12 @@
-		    GNU GENERAL PUBLIC LICENSE
-		       Version 2, June 1991
+GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
 
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
-                       59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc., <http://fsf.org/>
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
-			    Preamble
+                            Preamble
 
   The licenses for most software are designed to take away your
 freedom to share and change it.  By contrast, the GNU General Public
@@ -15,7 +15,7 @@ software--to make sure the software is free for all its users.  This
 General Public License applies to most of the Free Software
 Foundation's software and to any other program whose authors commit to
 using it.  (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.)  You can apply it to
+the GNU Lesser General Public License instead.)  You can apply it to
 your programs, too.
 
   When we speak of free software, we are referring to freedom, not
@@ -55,8 +55,8 @@ patent must be licensed for everyone's free use or not licensed at all.
 
   The precise terms and conditions for copying, distribution and
 modification follow.
-
-		    GNU GENERAL PUBLIC LICENSE
+
+                    GNU GENERAL PUBLIC LICENSE
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 
   0. This License applies to any program or other work which contains
@@ -110,7 +110,7 @@ above, provided that you also meet all of these conditions:
     License.  (Exception: if the Program itself is interactive but
     does not normally print such an announcement, your work based on
     the Program is not required to print an announcement.)
-
+
 These requirements apply to the modified work as a whole.  If
 identifiable sections of that work are not derived from the Program,
 and can be reasonably considered independent and separate works in
@@ -168,7 +168,7 @@ access to copy from a designated place, then offering equivalent
 access to copy the source code from the same place counts as
 distribution of the source code, even though third parties are not
 compelled to copy the source along with the object code.
-
+
   4. You may not copy, modify, sublicense, or distribute the Program
 except as expressly provided under this License.  Any attempt
 otherwise to copy, modify, sublicense or distribute the Program is
@@ -225,7 +225,7 @@ impose that choice.
 
 This section is intended to make thoroughly clear what is believed to
 be a consequence of the rest of this License.
-
+
   8. If the distribution and/or use of the Program is restricted in
 certain countries either by patents or by copyrighted interfaces, the
 original copyright holder who places the Program under this License
@@ -255,7 +255,7 @@ make exceptions for this.  Our decision will be guided by the two goals
 of preserving the free status of all derivatives of our free software and
 of promoting the sharing and reuse of software generally.
 
-			    NO WARRANTY
+                            NO WARRANTY
 
   11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
@@ -277,9 +277,9 @@ YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGES.
 
-		     END OF TERMS AND CONDITIONS
-
-	    How to Apply These Terms to Your New Programs
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
 
   If you develop a new program, and you want it to be of the greatest
 possible use to the public, the best way to achieve this is to make it
@@ -290,8 +290,8 @@ to attach them to the start of each source file to most effectively
 convey the exclusion of warranty; and each file should have at least
 the "copyright" line and a pointer to where the full notice is found.
 
-    <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
+    {description}
+    Copyright (C) {year}  {fullname}
 
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -303,10 +303,9 @@ the "copyright" line and a pointer to where the full notice is found.
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
 
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 Also add information on how to contact you by electronic and paper mail.
 
@@ -330,11 +329,12 @@ necessary.  Here is a sample; alter the names:
   Yoyodyne, Inc., hereby disclaims all copyright interest in the program
   `Gnomovision' (which makes passes at compilers) written by James Hacker.
 
-  <signature of Ty Coon>, 1 April 1989
+  {signature of Ty Coon}, 1 April 1989
   Ty Coon, President of Vice
 
 This General Public License does not permit incorporating your program into
 proprietary programs.  If your program is a subroutine library, you may
 consider it more useful to permit linking proprietary applications with the
-library.  If this is what you want to do, use the GNU Library General
+library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.
+

README.md

@@ -1,92 +1,86 @@
-pyobd
-=====
+python-OBD
+==========
 
-<pre>OBD-Pi: Raspberry Pi Displaying Car Diagnostics (OBD-II) Data On An Aftermarket Head Unit
+A python module for handling realtime sensor data from OBD-II vehicle
+ports. Works with ELM327 OBD-II adapters, and is fit for the Raspberry
+Pi.
 
-In this tutorial you will learn how to connect your Raspberry Pi to a Bluetooth OBD-II adapter and display realtime engine data to your cars aftermarket head unit.
+Installation
+------------
 
-Hardware Required:
-1. Raspberry Pi
-2. Aftermarket head unit (Note: Must support Auxiliary input)
-3. Plugable USB Bluetooth 4.0 Low Energy Micro Adapter 
-4. 2A Car Supply / Switch or Micro USB Car Charger
-5. ELM327 Bluetooth Adapter or ELM327 USB Cable
-6. RCA cable 
-7. Keyboard (*optional)
+```Shell
+$ pip install obd
+```
 
-What is OBD-II?
-OBD stands for On-Board Diagnostics, and this standard connector has been mandated in the US since 1996. Now you can think of OBD-II as an on-board computer system that is responsible for monitoring your vehicle’s engine, transmission, and emissions control components. 
+Basic Usage
+-----------
 
-Vehicles that comply with the OBD-II standards will have a data connector within about 2 feet of the steering wheel. The OBD connector is officially called a SAE J1962 Diagnostic Connector, but is also known by DLC, OBD Port, or OBD connector. It has positions for 16 pins.
+```Python
+import obd
 
-pyOBD?
-pyOBD (aka pyOBD-II or pyOBD2) is an open source OBD-II (SAE-J1979) compliant scantool software written entirely in Python. It is designed to interface with low-cost ELM 32x OBD-II diagnostic interfaces such as ELM-USB. It will basically allow you to talk to your car's ECU, display fault codes, display measured values, read status tests, etc.
+connection = obd.OBD() # auto-connects to USB or RF port
 
-I took a fork of pyOBD’s software from their GitHub repository, https://github.com/peterh/pyobd, and used this as the basis for my program.
+cmd = obd.commands.SPEED # select an OBD command (sensor)
 
-The program will connect through the OBD-II interface, display the gauges available dependent on the particular vehicle and display realtime engine data to the cars aftermarket head unit in an interactive GUI.
-Software Installation
-Before you start you will need a working install of Raspbian with network access.
+response = connection.query(cmd) # send the command, and parse the response
 
-We'll be doing this from a console cable connection, but you can just as easily do it from the direct HDMI/TV console or by SSH'ing in. Whatever gets you to a shell will work!
+print(response.value) # returns unit-bearing values thanks to Pint
+print(response.value.to("mph")) # user-friendly unit conversions
+```
 
-Note: For the following command line instructions, do not type the '#', that is only to indicate that it is a command to enter. 
+Documentation
+-------------
 
-Before proceeding, run:
-#  sudo apt-get update
-#  sudo apt-get upgrade
-#  sudo apt-get autoremove
-#  sudo reboot
+Available at [python-obd.readthedocs.org](http://python-obd.readthedocs.org/en/latest/)
 
-Install these components using the command:
-#  sudo apt-get install python-serial
-#  sudo apt-get install bluetooth bluez-utils blueman
-#  sudo apt-get install python-wxgtk2.8 python-wxtools wx2.8-i18n libwxgtk2.8-dev
-#  sudo apt-get install git-core
-#  sudo reboot 
+Commands
+--------
 
-Next, download the OBD-Pi Software direct from GitHub (https://github.com/Pbartek/pyobd-pi.git)
+Here are a handful of the supported commands (sensors). For a full list, see [the docs](http://python-obd.readthedocs.io/en/latest/Command%20Tables/)
 
-Or using the command:
-#  cd ~
-#  git clone https://github.com/Pbartek/pyobd-pi.git
+*note: support for these commands will vary from car to car*
 
-Vehicle Installation
-The vehicle installation is quite simple.
+-   Calculated Engine Load
+-   Engine Coolant Temperature
+-   Fuel Pressure
+-   Intake Manifold Pressure
+-   Engine RPM
+-   Vehicle Speed
+-   Timing Advance
+-   Intake Air Temp
+-   Air Flow Rate (MAF)
+-   Throttle Position
+-   Engine Run Time
+-   Fuel Level Input
+-   Number of warm-ups since codes cleared
+-   Barometric Pressure
+-   Ambient air temperature
+-   Commanded throttle actuator
+-   Time run with MIL on
+-   Time since trouble codes cleared
+-   Hybrid battery pack remaining life
+-   Engine fuel rate
+-   Vehicle Identification Number (VIN)
 
-1. Insert the USB Bluetooth dongle into the Raspberry Pi along with the SD card.
+Common Issues
+-------------
 
-2. Insert the OBD-II Bluetooth adapter into the SAE J196216 (OBD Port) connector.
+### Bluetooth OBD-II Adapters
 
-3. Connect you RCA cable to the back of your aftermarket head unit and plug the other end into your Raspberry Pi.
+There are sometimes connection issues when using a Bluetooth OBD-II adapter with some devices (the Raspberry Pi is a common problem). This can be fixed by setting the following arguments when setting up the connection:
 
-4. Install your 2A Car Supply / Switch or Micro USB Car Charger.
+```Python
+fast=False, timeout=30
+```
 
-5. Finally turn your key to the ON position and navigate your head unit to Auxiliary input.
+License
+-------
 
-6. Enter your login credentials and run:
-#  startx
+GNU GPL v2
 
-7. Launch BlueZ, the Bluetooth stack for Linux. Pair + Trust your ELM327 Bluetooth Adapter and Connect To: SPP Dev. You should see the Notification "Serial port connected to /dev/rfcomm0"
+This library is forked from:
 
-Note: Click the Bluetooth icon, bottom right (Desktop) to configure your device. Right click on your Bluetooth device to bring up Connect To: SPP Dev.
+-   <https://github.com/peterh/pyobd>
+-   <https://github.com/Pbartek/pyobd-pi>
 
-8. Open up Terminal and run:
-#  cd pyobd-pi
-#  sudo su
-#  python obd_gui.py
-
-Use the Left and Right arrow key to cycle through the gauge display.
-Note: Left and Right mouse click will also work
-
-To exit the program just press Control and C or Alt and Esc.
-Update: 
-Data Logging
-If you would like to log your data run:
-#  cd pyobd-pi
-#  python obd_recorder.py
-
-The logged data file will be saved under: 
-/home/username/pyobd-pi/log/
-
-Enjoy and drive safe!</pre>
+Enjoy and drive safe!