Skip to content

pulls changes from upstream master #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 25 commits into
base: pull-from-brandon-w
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
a61b3de
Define CI pipeline using Github Actions
nyukhalov Apr 14, 2022
a08424d
Fix test_populate_ecu_map test
nyukhalov Apr 27, 2022
dbfd379
Only treat "OK" as a response terminator when appropriate
interfect May 20, 2022
d64064d
Update pint version to 0.19.*
nyukhalov Apr 11, 2022
c7be924
Update the python version range to 3.8-3.10
nyukhalov Jun 2, 2022
c55a7a9
tox.ini: Bump the python and pypi versions
alistair23 Jan 24, 2023
7642ad6
setup.py: Bump pint version
alistair23 Jan 24, 2023
e952b91
Fixed printing with brackets
Mario2407 Mar 7, 2023
d95554a
bumped to v0.7.2
Jul 10, 2023
7d5cd05
Proper `obd.Unit.percent`
green-green-avk Jul 9, 2023
eb8679e
Added readthedocs yaml config file before config files are enforced
Aug 14, 2023
3ecbf6f
Fixed mkdocs pages -> nav config
Aug 14, 2023
d7aad00
Revert docs updates: This is more finicky than I anticipated
Aug 14, 2023
d7c781a
Added readthedocs yaml config file before config files are enforced
Aug 14, 2023
e0304c3
Several spelling and grammatical fixes.
ion-mironov Feb 20, 2024
0c9abbc
Fix escaped serial port label string
dkg Feb 6, 2025
a47d791
Included note mentioning which OBD it will work with.
ion-mironov Feb 20, 2024
0c01901
Uprev pint to 0.24.* for python 3.13+ support
Apr 7, 2025
c30cfc3
Uprev tox.ini to test python 3.13
Apr 7, 2025
75a8820
Merge pull request #289 from brendan-w/user/brendan/uprev-pint
brendan-w Apr 7, 2025
630f0be
setup.py -> pyproject.toml
Apr 7, 2025
3d1beba
Updated the testing docs with modern build commands
Apr 7, 2025
289a889
Merge pull request #290 from brendan-w/user/brendan/pyproject.toml
brendan-w Apr 7, 2025
b53cbcb
bumped to 0.7.3
Apr 7, 2025
a378bdd
Merge pull request #291 from brendan-w/user/brendan/0.7.3
brendan-w Apr 7, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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
14 changes: 14 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -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
29 changes: 0 additions & 29 deletions .travis.yml

This file was deleted.

4 changes: 3 additions & 1 deletion docs/Async Connections.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# Async Connections

Since the standard `query()` function is blocking, it can be a hazard for UI event loops. To deal with this, python-OBD has an `Async` connection object that can be used in place of the standard `OBD` object. `Async` is a subclass of `OBD`, and therefore inherits all of the standard methods. However, `Async` adds a few in order to control a threaded update loop. This loop will keep the values of your commands up to date with the vehicle. This way, when the user `query`s the car, the latest response is returned immediately.

The update loop is controlled by calling `start()` and `stop()`. To subscribe a command for updating, call `watch()` with your requested OBDCommand. Because the update loop is threaded, commands can only be `watch`ed while the loop is `stop`ed.
Expand Down Expand Up @@ -32,7 +34,7 @@ connection = obd.Async()

# a callback that prints every new value to the console
def new_rpm(r):
print r.value
print (r.value)

connection.watch(obd.commands.RPM, callback=new_rpm)
connection.start()
Expand Down
4 changes: 3 additions & 1 deletion docs/Command Lookup.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
`OBDCommand`s are objects used to query information from the vehicle. They contain all of the information neccessary to perform the query, and decode the cars response. Python-OBD has [built in tables](Command Tables.md) for the most common commands. They can be looked up by name, or by mode & PID.
# Command Lookup

`OBDCommand`s are objects used to query information from the vehicle. They contain all of the information necessary to perform the query and decode the car's response. Python-OBD has [built in tables](Command Tables.md) for the most common commands. They can be looked up by name or by mode & PID.

```python
import obd
Expand Down
18 changes: 10 additions & 8 deletions docs/Command Tables.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# OBD-II adapter (ELM327 commands)
# Commands

## OBD-II adapter (ELM327 commands)

|PID | Name | Description | Response Value |
|-----|-------------|-----------------------------------------|-----------------------|
Expand All @@ -7,7 +9,7 @@

<br>

# Mode 01
## Mode 01

|PID | Name | Description | Response Value |
|----|---------------------------|-----------------------------------------|-----------------------|
Expand Down Expand Up @@ -110,7 +112,7 @@

<br>

# Mode 02
## Mode 02

Mode 02 commands are the same as mode 01, but are metrics from when the last DTC occurred (the freeze frame). To access them by name, simple prepend `DTC_` to the Mode 01 command name.

Expand All @@ -124,7 +126,7 @@ obd.commands.DTC_RPM # the Mode 02 command

<br>

# Mode 03
## Mode 03

Mode 03 contains a single command `GET_DTC` which requests all diagnostic trouble codes from the vehicle. The response will contain the codes themselves, as well as a description (if python-OBD has one). See the [DTC Responses](Responses.md#diagnostic-trouble-codes-dtcs) section for more details.

Expand All @@ -135,15 +137,15 @@ Mode 03 contains a single command `GET_DTC` which requests all diagnostic troubl

<br>

# Mode 04
## Mode 04

|PID | Name | Description | Response Value |
|-----|-----------|-----------------------------------------|-----------------------|
| N/A | CLEAR_DTC | Clear DTCs and Freeze data | N/A |

<br>

# Mode 06
## Mode 06

<span style="color:red">*WARNING: mode 06 is experimental. While it passes software tests, it has not been tested on a real vehicle. Any debug output for this mode would be greatly appreciated.*</span>

Expand Down Expand Up @@ -252,7 +254,7 @@ Mode 06 commands are used to monitor various test results from the vehicle. All

<br>

# Mode 07
## Mode 07

The return value will be encoded in the same structure as the Mode 03 `GET_DTC` command.

Expand All @@ -262,7 +264,7 @@ The return value will be encoded in the same structure as the Mode 03 `GET_DTC`

<br>

# Mode 09
## Mode 09

<span style="color:red">*WARNING: mode 09 is experimental. While it has been tested on a hardware simulator, only a subset of the supported
commands have (00-06) been tested. Any debug output for this mode, especially for the untested PIDs, would be greatly appreciated.*</span>
Expand Down
1 change: 1 addition & 0 deletions docs/Connections.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
# Connections

After installing the library, simply `import obd`, and create a new OBD connection object. By default, python-OBD will scan for Bluetooth and USB serial ports (in that order), and will pick the first connection it finds. The port can also be specified manually by passing a connection string to the OBD constructor. You can also use the `scan_serial` helper retrieve a list of connected ports.

Expand Down
12 changes: 6 additions & 6 deletions docs/Custom Commands.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
# Custom Commands

If the command you need is not in python-OBDs tables, you can create a new `OBDCommand` object. The constructor accepts the following arguments (each will become a property).

Expand All @@ -13,8 +14,7 @@ If the command you need is not in python-OBDs tables, you can create a new `OBDC
| header (optional) | string | If set, use a custom header instead of the default one (7E0) |


Example
-------
## Example

```python
from obd import OBDCommand, Unit
Expand Down Expand Up @@ -58,7 +58,7 @@ Here are some details on the less intuitive fields of an OBDCommand:

---

### OBDCommand.decoder
## OBDCommand.decoder

The `decoder` argument is a function of following form.

Expand All @@ -83,7 +83,7 @@ def <name>(messages):

---

### OBDCommand.ecu
## OBDCommand.ecu

The `ecu` argument is a constant used to filter incoming messages. Some commands may listen to multiple ECUs (such as DTC decoders), where others may only be concerned with the engine (such as RPM). Currently, python-OBD can only distinguish the engine, but this list may be expanded over time:

Expand All @@ -94,13 +94,13 @@ The `ecu` argument is a constant used to filter incoming messages. Some commands

---

### OBDCommand.fast
## OBDCommand.fast

The optional `fast` argument tells python-OBD whether it is safe to append a `"01"` to the end of the command. This will instruct the adapter to return the first response it recieves, rather than waiting for more (and eventually reaching a timeout). This can speed up requests significantly, and is enabled for most of python-OBDs internal commands. However, for unusual commands, it is safest to leave this disabled.

---

### OBDCommand.header
## OBDCommand.header

The optional `header` argument tells python-OBD to use a custom header when querying the command. If not set, python-OBD assumes that the default 7E0 header is needed for querying the command. The switch between default and custom header (and vice versa) is automatically done by python-OBD.

Expand Down
2 changes: 2 additions & 0 deletions docs/Debug.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# Debug

python-OBD uses python's builtin logging system. By default, it is setup to send output to `stderr` with a level of WARNING. The module's logger can be accessed via the `logger` variable at the root of the module. For instance, to enable console printing of all debug messages, use the following snippet:

```python
Expand Down
18 changes: 10 additions & 8 deletions docs/Responses.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# Responses

The `query()` function returns `OBDResponse` objects. These objects have the following properties:

| Property | Description |
Expand All @@ -11,7 +13,7 @@ The `query()` function returns `OBDResponse` objects. These objects have the fol

---

### is_null()
## is_null()

Use this function to check if a response is empty. Python-OBD will emit empty responses when it is unable to retrieve data from the car.

Expand All @@ -25,7 +27,7 @@ if not r.is_null():
---


# Pint Values
## Pint Values

The `value` property typically contains a [Pint](http://pint.readthedocs.io/en/latest/) `Quantity` object, but can also hold complex structures (depending on the request). Pint quantities combine a value and unit into a single class, and are used to represent physical values such as "4 seconds", and "88 mph". This allows for consistency when doing math and unit conversions. Pint maintains a registry of units, which is exposed in python-OBD as `obd.Unit`.

Expand Down Expand Up @@ -71,7 +73,7 @@ import obd

---

# Status
## Status

The status command returns information about the Malfunction Indicator Light (check-engine light), the number of trouble codes being thrown, and the type of engine.

Expand Down Expand Up @@ -111,7 +113,7 @@ Here are all of the tests names that python-OBD reports:

---

# Diagnostic Trouble Codes (DTCs)
## Diagnostic Trouble Codes (DTCs)

Each DTC is represented by a tuple containing the DTC code, and a description (if python-OBD has one). For commands that return multiple DTCs, a list is used.

Expand All @@ -129,7 +131,7 @@ response.value = ("P0104", "Mass or Volume Air Flow Circuit Intermittent")

---

# Fuel Status
## Fuel Status

The fuel status is a tuple of two strings, telling the status of the first and second fuel systems. Most cars only have one system, so the second element will likely be an empty string. The possible fuel statuses are:

Expand All @@ -144,7 +146,7 @@ The fuel status is a tuple of two strings, telling the status of the first and s

---

# Air Status
## Air Status

The air status will be one of these strings:

Expand All @@ -157,7 +159,7 @@ The air status will be one of these strings:

---

# Oxygen Sensors Present
## Oxygen Sensors Present

Returns a 2D structure of tuples (representing bank and sensor number), that holds boolean values for sensor presence.

Expand All @@ -183,7 +185,7 @@ response.value[1][2] == True # Bank 1, Sensor 2 is present
```
---

# Monitors (Mode 06 Responses)
## Monitors (Mode 06 Responses)

All mode 06 commands return `Monitor` objects holding various test results for the requested sensor. A single monitor response can hold multiple tests, in the form of `MonitorTest` objects. The OBD standard defines some tests, but vehicles can always implement custom tests beyond the standard. Here are the standard Test IDs (TIDs) that python-OBD will recognize:

Expand Down
5 changes: 2 additions & 3 deletions docs/Troubleshooting.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

# Debug Output

If python-OBD is not working properly, the first thing you should do is enable debug output. Add the following line before your connection code to print all of the debug information to your console:
Expand Down Expand Up @@ -52,7 +51,7 @@ Here are some common logs from python-OBD, and their meanings:

### Unresponsive ELM

```
```none
[obd] ========================== python-OBD (v0.4.0) ==========================
[obd] Explicit port defined
[obd] Opening serial port '/dev/pts/2'
Expand Down Expand Up @@ -93,7 +92,7 @@ print ports # ['/dev/ttyUSB0', '/dev/ttyUSB1']

### Unresponsive Vehicle

```
```none
[obd] ========================== python-OBD (v0.4.0) ==========================
[obd] Explicit port defined
[obd] Opening serial port '/dev/pts/2'
Expand Down
16 changes: 9 additions & 7 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# Welcome

Python-OBD is a library for handling data from a car's [**O**n-**B**oard **D**iagnostics port](https://en.wikipedia.org/wiki/On-board_diagnostics) (OBD-II). It can stream real time sensor data, perform diagnostics (such as reading check-engine codes), and is fit for the Raspberry Pi. This library is designed to work with standard [ELM327 OBD-II adapters](http://www.amazon.com/s/ref=nb_sb_noss?field-keywords=elm327).
Python-OBD is a library for handling data from a car's [**O**n-**B**oard **D**iagnostics](https://en.wikipedia.org/wiki/On-board_diagnostics) port. Please keep in mind that the car **must** have OBD-II (any car made in 1996 and up); this will _**not**_ work with OBD-I.

Python-OBD can stream real time sensor data, perform diagnostics (such as reading check-engine codes), and is fit for the Raspberry Pi. This library is designed to work with standard [ELM327 OBD-II adapters](http://www.amazon.com/s/ref=nb_sb_noss?field-keywords=elm327).

<span style="color:red">*NOTE: Python-OBD is below 1.0.0, meaning the API may change between minor versions. Consult the [GitHub release page](https://github.com/brendan-w/python-OBD/releases) for changelogs before updating.*</span>

<br>

# Installation
## Installation

Install the latest release from pypi:

Expand All @@ -22,7 +24,7 @@ $ sudo apt-get install bluetooth bluez-utils blueman

<br>

# Basic Usage
## Basic Usage

```python
import obd
Expand All @@ -31,17 +33,17 @@ connection = obd.OBD() # auto-connects to USB or RF port

cmd = obd.commands.SPEED # select an OBD command (sensor)

response = connection.query(cmd) # send the command, and parse the response
response = connection.query(cmd) # send the command and parse the response

print(response.value) # returns unit-bearing values thanks to Pint
print(response.value.to("mph")) # user-friendly unit conversions
```

OBD connections operate in a request-reply fashion. To retrieve data from the car, you must send commands that query for the data you want (e.g. RPM, Vehicle speed, etc). In python-OBD, this is done with the `query()` function. The commands themselves are represented as objects, and can be looked up by name or value in `obd.commands`. The `query()` function will return a response object with parsed data in its `value` property.
OBD connections operate in a request-reply fashion. To retrieve data from the car, you must send commands that query for the data you want (e.g. RPM, Vehicle speed, etc). In python-OBD this is done with the `query()` function. The commands themselves are represented as objects and can be looked up by name or value in `obd.commands`. The `query()` function will return a response object with parsed data in its `value` property.

<br>

# Module Layout
## Module Layout

```python
import obd
Expand All @@ -59,7 +61,7 @@ obd.logger # the OBD module's root logger (for debug)

<br>

# License
## License

GNU General Public License V2

Expand Down
1 change: 1 addition & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
mkdocs==1.5.2
2 changes: 1 addition & 1 deletion mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ repo_url: https://github.com/brendan-w/python-OBD
repo_name: GitHub
extra_javascript:
- assets/extra.js
pages:
nav:
- 'Getting Started': 'index.md'
- 'OBD Connections': 'Connections.md'
- 'Command Lookup': 'Command Lookup.md'
Expand Down
Loading