Installation

openOBD can be installed and run on any machine that supports one of several compatible programming languages (1). The steps to install openOBD differ depending on the programming language used. This page outlines the steps required to install openOBD.

C#/.NET,C++, Dart, Go, Java, Kotlin, Node,Objective-C, PHP, and Ruby.

Python

To make use of the functionality of openOBD in Python, the openobd library will need to be installed. The library can either be installed system-wide, or in a self-contained virtual environment.

Note

To install the openobd Python library, Python version 3.11 or higher is required. Opening a terminal and running python --version will display the version that is currently installed, if any.

Virtual environmentSystem-wide

A virtual environment can be used to keep the installation of openOBD limited to that environment. In this example, pipenv will be used to create a virtual environment containing Python 3.11. To do this, open a terminal in the desired directory, and run:

pipenv --python 3.11

If the virtual environment has been successfully created, a Pipfile should have been created in the directory. If not, this could be caused due to a parent directory already containing a virtual environment.

Once the virtual environment has been created, the openobd library can be installed by running:

pipenv install openobd

The virtual environment can be activated and deactivated by running pipenv shell and exit respectively.

openOBD can be installed on the entire machine by opening a terminal and running:

pip install openobd

This will make the openobd Python library accessible from any directory on the machine.

Environment variables

The openobd library needs the values stored in the environment variables to perform any gRPC calls. Ensure you have a file containing the required environment variables, as described on this page. These environment variables must be made accessible to Python. This can be achieved in several different ways, some of which are detailed below.

PyCharmVirtual environmentpython-dotenvSystem-wideAs kwargs

When using the PyCharm IDE, it is possible to specify the path to the environment variables inside PyCharm.

PyCharm edit config menu

To do this, first open your project in PyCharm, and open the expandable menu at the top right of the IDE's toolbar. Then click Edit Configurations... to open PyCharm's configurations menu.

PyCharm configurations

If no Python configuration for your script is present yet, create a new one by pressing the + at the top left. In your file's Python configuration, specify the path to your environment variables in the Paths to ".env" files: field, and save it by clicking OK. With this change, running the Python script through PyCharm will also automatically load the environment variables.

The environment variables can be automatically loaded when using a virtual environment. To do this, ensure the file containing the environment variables is named .env and is located in the same directory as the Pipfile. When running pipenv shell to activate the virtual environment, the environment variables will then automatically be loaded.

The python-dotenv library can be used to load environment variables from a file. The library can be installed by opening a terminal and running:

pip install python-dotenv

When installed, it can be used by adding the following code at the start of your Python script:

from dotenv import load_dotenv

load_dotenv()

Without any arguments, the load_dotenv() function requires the environment variables to be defined in a file named .env, and requires this file to be located in the same directory as the Python script. Alternatively, the load_dotenv() function can also be passed a path to the file containing the environment variables.

To make the environment variables accessible from any location on the machine, they can be added to the system's environment variables. How to do this, depends on which operating system is used.

For example, when using Linux, the environment variables can be defined in the .bashrc file, which makes them available in new Bash shell sessions. An environment variable can be defined in the .bashrc file as follows:

export OPENOBD_PARTNER_CLIENT_ID=<Client ID>

For an explanation on how to set environment variables on Windows, see this page.

It is also possible to use openOBD without creating a file containing the environment variables. As a substitute, the values for the environment variables must be passed to the OpenOBD object as kwargs when initializing it. The kwargs it expects are: client_id, client_secret, partner_api_key, cluster_id, and grpc_host. Any missing values will be described in an AssertionError when encountered.

Try out the installation with some code examples