Project Description

The Onboard Diagnostics Protocol (OBD-II) protocol allows to query the different car engine control units (ECUs) and get real-time data through the CAN bus. The data can be retrieved through specific parameter identifiers (PIDs). However, each car supports a subset of the standard PIDs. In addition, some cars use manufacturer-specific PIDs. The ScanYourCar project connects to the car through an OBD reader (e.g., ELM327) and checks which standard PIDs (Mode 2 and Mode 3 only) are supported by that car. It also gets a snapshot of the data for each supported PID.

Getting Started

To successfully run this source code, a Bluetooth OBD adapter is required. It should be paired to your system.

Prerequisites

This project uses the Python OBD library. To install this library, you need to run:

pip install obd

On Linux-based systems, you may also need to install the BlueZ stack:

sudo apt-get install bluetooth bluez-utils blueman

Usage

To run the project from the command line, you just need to issue the following command:

python3 app.py

This code can also be used from another Python script. You need to instantiate and call the Explorer class:

## Instantiate the Explorer class
cexplorer = explorer.Explorer(command_file = "./explorer/commands.json", output_file = "./test_result.txt")

## Connect to the car
cexplorer.connect()

## Query the car to get the supported commands
rcode = cexplorer.check_supported_commands()

## Query the car to get current data for each supported command
if rcode == 0:
    cexplorer.run_supported_commands()

## Dump the supported commands to a JSON file
cexplorer.dump_supported_commands("./supported_commands.json")

## Close connection to the car
cexplorer.disconnect()

The Explorer class writes supported commands (i.e., PIDs) to the output file output_file. In addition, the class member self.supported_commands holds the list of supported commands. Before the invocation of the check_supported_commands() method, this list is empty. The supported commands can be written to a JSON file using the class method dump_supported_commands.

The Explorer class takes as input a list of OBD commands (PIDs) in JSON format. A default list which enumerates the Mode 2 and 3 commands, supported by Python OBD library, is already provided. If you want to provide your own list of commands, or the commands' list offered by the library evolves in the future, you still have the option to override the default list (by explicitly setting up the command_file parameter to your commands' list filename).

Examples

The ScanYourCar code retrieved the supported commands from three different cars:

• Toyota Corolla -- Toyota Corolla 2006
• Hyundai Accent -- Hyundai Accent 2007
• Mazda 3 -- Mazda 3 2006
• Kia FORTE -- Kia Forte 2019

Built With

• Python 3.7

Tested on

• Ubuntu 18.04
• Raspian 10

License

This project is licensed under the MIT License - see the LICENSE file for more details.