Metadata-Version: 2.4
Name: py-obdii
Version: 0.10.4b0
Summary: A Python library for interacting with OBDII.
Author: PaulMarisOUMary
License: MIT License
        
        Copyright (c) 2025-present PaulMarisOUMary
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Home, https://github.com/PaulMarisOUMary/OBDII
Project-URL: Repository, https://github.com/PaulMarisOUMary/OBDII
Project-URL: Documentation, https://py-obdii.readthedocs.io
Project-URL: Issues, https://github.com/PaulMarisOUMary/OBDII/issues
Project-URL: Changelog, https://github.com/PaulMarisOUMary/OBDII/releases
Project-URL: Discord, https://discord.gg/vn9bHUxeYB
Keywords: obd,obdii,obd2,py-obdii,py-obd2,python obd,ELM327,automotive,torque,car,vehicle,diagnostics,car diagnostics,engine data,car data,vehicle data,can bus
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: pyserial<4,>=3.5
Provides-Extra: test
Requires-Dist: pytest<8.4,>=8.3.5; extra == "test"
Requires-Dist: pytest-cov<6,>=5.0.0; extra == "test"
Requires-Dist: pytest-mock<3.15,>=3.14; extra == "test"
Provides-Extra: dev
Requires-Dist: ruff<1,>=0.15; extra == "dev"
Requires-Dist: ty<1,>=0.0.34; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<10,>=9.1; extra == "docs"
Requires-Dist: sphinx-autobuild<2026,>=2025.0; extra == "docs"
Requires-Dist: sphinxawesome-theme<6,>=5.3; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid<3,>=2.0.2; extra == "docs"
Requires-Dist: sphinx_design<1,>=0.7; extra == "docs"
Provides-Extra: sim
Requires-Dist: ELM327-emulator<4,>=3; extra == "sim"
Dynamic: license-file

OBDII
=====

.. image:: https://img.shields.io/pypi/v/py-obdii?label=pypi&logo=pypi&logoColor=white&link=https%3A%2F%2Fpypi.org%2Fproject%2Fpy-obdii
    :target: https://pypi.org/project/py-obdii
    :alt: PyPI version
.. image:: https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FPaulMarisOUMary%2FOBDII%2Fmain%2Fpyproject.toml&logo=python&logoColor=white&label=python
    :target: https://pypi.org/project/py-obdii
    :alt: Python Version from PEP 621 TOML
.. image:: https://img.shields.io/github/actions/workflow/status/PaulMarisOUMary/OBDII/ci-pytest.yml?branch=main&label=tests&logoColor=white&logo=pytest
    :target: https://github.com/PaulMarisOUMary/OBDII/actions/workflows/ci-pytest.yml
    :alt: PyTest CI status
.. image:: https://img.shields.io/readthedocs/py-obdii/latest?logo=readthedocs&logoColor=white&label=docs&link=https%3A%2F%2Fpy-obdii.rtfd.io
    :target: https://py-obdii.rtfd.io/en/latest
    :alt: Documentation Status (ReadTheDocs)
.. image:: https://img.shields.io/discord/1437417392144912467?logo=discord&logoColor=white&label=discord&color=%235865f2&link=https%3A%2F%2Fdiscord.gg%2Fvn9bHUxeYB
    :target: https://discord.gg/vn9bHUxeYB
    :alt: Discord Support Server invite

Overview
--------

Connect to any vehicle through its `OBDII <https://en.wikipedia.org/wiki/On-board_diagnostics#OBD-II>`_ port and start reading real-time data from Python in a few lines of code.

Plug in a USB, Bluetooth, WiFi or Ethernet adapter, then query engine speed, fault codes, fuel level, VIN, and much more.

Whether you're building a diagnostic tool, a performance data logger, a custom dashboard, a smart home integration, or just learning how vehicles communicate, this library handles the complexity of vehicle communication, so you don't have to.

Installation
------------

Python 3.8 or higher is required.

Install from PyPI using pip:

.. code-block:: console

    pip install py-obdii

For more installation options, see the `Installation Guide <https://py-obdii.readthedocs.io/en/latest/installation.html>`_.

Usage Example
-------------

.. code-block:: python

    from obdii import Connection, at_commands, commands
    from obdii.utils.scan import scan_ports

    # Find first available OBDII device connected via serial
    ports = scan_ports(return_first=True)
    if not ports:
        raise ValueError("No OBDII devices found.")

    # Connect to the adapter
    with Connection(ports[0]) as conn:
        # Query adapter firmware version
        version = conn.query(at_commands.VERSION_ID)
        print(f"Version: {version.value}")

        # Query vehicle's engine speed (rpm)
        response = conn.query(commands.ENGINE_SPEED)
        print(f"Engine Speed: {response.value} {response.units}")

More examples in the `examples folder <https://github.com/PaulMarisOUMary/OBDII/tree/main/examples>`_ and `Usage Guide <https://py-obdii.readthedocs.io/en/latest/usage.html>`_.

Emulator Support
----------------

You don't need a physical OBDII device to start developing.

You can use the `ELM327-Emulator <https://pypi.org/project/ELM327-emulator>`_ library to simulate an OBDII adapter and vehicle responses.

Setting Up the ELM327-Emulator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

#. Install the library with the ``sim`` extra options:

    .. code-block:: console

        pip install py-obdii[sim]

#. Start the ELM327-Emulator:

    .. code-block:: console

        python -m elm -p "REPLACE_WITH_PORT" -s car --baudrate 38400

    .. note::

        Replace ``REPLACE_WITH_PORT`` with the serial port of your choice

For platform-specific instructions, see the `Emulating a Vehicle <https://py-obdii.readthedocs.io/en/latest/emulator.html>`_ guide.

Hardware Requirements
---------------------

For real-world usage, an ELM327-compatible OBDII adapter is required to connect to your vehicle.

- **USB**: reliable, plug and play
- **Ethernet**: reliable, low latency
- **Bluetooth**: wireless, convenient
- **WiFi**: wireless, mobile compatible

More information on connecting to different adapter types can be found in the `Connection Guide <https://py-obdii.readthedocs.io/en/latest/connection.html>`_.

Compatibility
-------------

All ELM327 protocols are supported, covering vehicles from the
mid-1990s through today.

Protocol Support
^^^^^^^^^^^^^^^^

===== ================ ========================
ID    Protocol         Specifications          
===== ================ ========================
0x01  SAE J1850 PWM    41.6 Kbaud              
0x02  SAE J1850 VPW    10.4 Kbaud              
0x03  ISO 9141-2       5 baud init, 10.4 Kbaud 
0x04  ISO 14230-4 KWP  5 baud init, 10.4 Kbaud 
0x05  ISO 14230-4 KWP  fast init, 10.4 Kbaud   
0x06  ISO 15765-4 CAN  11 bit ID, 500 Kbaud    
0x07  ISO 15765-4 CAN  29 bit ID, 500 Kbaud    
0x08  ISO 15765-4 CAN  11 bit ID, 250 Kbaud    
0x09  ISO 15765-4 CAN  29 bit ID, 250 Kbaud    
0x0A  SAE J1939 CAN    29 bit ID, 250 Kbaud    
0x0B  USER1 CAN        11 bit ID, 125 Kbaud    
0x0C  USER2 CAN        11 bit ID, 50 Kbaud     
===== ================ ========================

Support & Contact
-----------------

Found a bug?

- `Open an Issue <https://github.com/PaulMarisOUMary/OBDII/issues>`_

Have a question?

- `Join the Discussion <https://github.com/PaulMarisOUMary/OBDII/discussions>`_
- `Discord Support Server <https://discord.gg/vn9bHUxeYB>`_

Your feedback is greatly appreciated and helps improve this project.

-------

Follow our updates by leaving a star to this repository!
