Harness the power of vehicle diagnostics in your React Native applications with the react-native-obd2 library. Inspired by the robust android-obd-reader, this module bridges the gap between the world of OBD-II vehicle data and the flexibility of React Native development. By wrapping the OBD Java API, react-native-obd2 enables seamless communication with Bluetooth ELM327 OBD-II adapters, opening up a universe of possibilities for creating innovative automotive applications.
Installation
Getting started with react-native-obd2 is straightforward. Simply run the following commands in your project’s root directory to install the library and link it to your React Native project:
$ npm install react-native-obd2 --save
$ react-native linkThese commands will add the react-native-obd2 module to your project and link the necessary native dependencies, preparing your application for OBD-II interaction.
API Reference
The react-native-obd2 library provides a concise yet powerful API to interact with OBD-II devices. Below is a detailed overview of each function available:
ready()
Before you can start reading vehicle data, it’s essential to ensure Bluetooth is enabled and ready to communicate. The ready() method handles this initialization process. It checks the Bluetooth status of the device and prepares the module for OBD-II communication.
const obd2 = require('react-native-obd2');
...
obd2.ready();Calling ready() is the first step in setting up your React Native Obd2 application. It’s typically called once during the application’s initialization phase.
getBluetoothDeviceNameList()
Discovering and connecting to your Bluetooth ELM327 OBD-II adapter is made easy with getBluetoothDeviceNameList(). This method scans for available Bluetooth devices and returns a list of devices, including their names and addresses. The result is an array of objects, each containing the name and address of a discovered Bluetooth device.
Example
const obd2 = require('react-native-obd2');
...
obd2.getBluetoothDeviceNameList()
.then((nameList) => console.log('Bluetooth device list : ' + JSON.stringify(nameList)))
.catch((e) => console.log('Get device name error : ' + e));This example demonstrates how to retrieve the list of Bluetooth devices and log the result to the console. You can then use this list to allow users to select their OBD-II adapter.
Output Example
Bluetooth device list: [{"name": "OBDII", "address": "98:D3:32:2E:57:4A"}, {"name": "AnotherDevice", "address": "00:1A:7D:DA:71:13"}]The output shows an array of Bluetooth devices found, each with a name and address. The address is crucial for establishing a connection with the desired OBD-II adapter.
setMockUpMode(enabled)
For development and testing purposes, react-native-obd2 offers a mock-up mode. setMockUpMode(enabled) allows you to simulate OBD-II data without requiring a physical Bluetooth connection to a vehicle. When enabled (set to true), the library will generate mock OBD-II data, enabling you to test your application’s UI and logic in the absence of a real OBD-II device. By default, mock-up mode is disabled (false), ensuring real-world OBD-II interaction when you are ready to connect to a vehicle.
startLiveData(btDeviceAddress)
The core function for retrieving real-time vehicle data is startLiveData(btDeviceAddress). This method initiates the communication with the OBD-II adapter at the specified Bluetooth device address. Once started, the library begins to listen for and process live data streams from the vehicle’s ECU (Engine Control Unit). To receive this live data, you need to set up an event listener called 'obd2LiveData'.
Example
import { DeviceEventEmitter } from 'react-native';
const obd2 = require('react-native-obd2');
...
componentDidMount() {
this.obdLiveDataListener = DeviceEventEmitter.addListener('obd2LiveData', this.obdLiveData);
obd2.startLiveData('98:D3:32:2E:57:4A'); // Replace with your OBD-II adapter's address
}
componentWillUnmount() {
this.obdLiveDataListener.remove();
}
obdLiveData = (data) => {
console.log('Live OBD2 Data:', data);
// Process and display live OBD-II data
}This example demonstrates how to start live data streaming and set up a listener to receive the data. It’s crucial to replace '98:D3:32:2E:57:4A' with the actual Bluetooth address of your OBD-II adapter. Remember to remove the listener in componentWillUnmount to prevent memory leaks.
stopLiveData()
To stop the continuous stream of live OBD-II data, use the stopLiveData() method. This function terminates the communication with the OBD-II adapter and halts the flow of data to your application. It’s important to call stopLiveData() when you no longer need real-time data, such as when the user navigates away from a data display screen or closes the application.
Listeners: Real-Time OBD-II Status and Data
react-native-obd2 uses event listeners to deliver real-time updates about Bluetooth and OBD-II device status, as well as the live vehicle data itself. Here are the key listeners you’ll use in your application:
'obd2bluetoothStatus'
This listener provides updates on the Bluetooth connection status. It emits events with a JSON payload containing a status key, which can be one of the following values:
| JSON key | Type | Description |
|---|---|---|
status |
String | 'connected', 'disconnected', 'error', 'disable', 'ready', 'connecting' |
You can use this listener to provide visual feedback to the user about the Bluetooth connection status, guiding them through the connection process.
'obd2Status'
The 'obd2Status' listener reports the status of the OBD-II device connection and data reception. The status key in the JSON payload can indicate:
| JSON key | Type | Description |
|---|---|---|
status |
String | 'disconnected', 'receiving', or OBD data result (when a single command is sent) |
This listener is valuable for monitoring the OBD-II connection and ensuring data is being received correctly.
'obd2LiveData'
The 'obd2LiveData' listener is the primary source of real-time vehicle data. It emits events whenever new OBD-II data is received from the vehicle. The data is structured as a dictionary (JavaScript object) where each key-value pair represents a specific OBD-II parameter.
{ 'cmdID' : String, 'cmdName' : String, 'cmdResult' : String }cmdID: The command ID of the OBD-II parameter (e.g., “010C” for engine RPM).cmdName: A descriptive name for the parameter (e.g., “ENGINE_RPM”).cmdResult: The value of the parameter as a string (e.g., “800 rpm”).
You’ll process the data received through the 'obd2LiveData' listener to display vehicle information, create dashboards, or perform other diagnostic or monitoring tasks within your React Native application.
Example Application
To help you get started quickly, a simple working example is included in the Example folder of the react-native-obd2 repository. This example demonstrates the basic usage of the library and provides a foundation for building your own React Native OBD-II applications. Exploring the example code is highly recommended to understand the practical implementation of react-native-obd2.
License
react-native-obd2 is released under the MIT License, making it free for both personal and commercial use.
The MIT License (MIT)
Copyright (c) 2016-present JetBridge, LLC.
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.This license ensures you have the freedom to use, modify, and distribute react-native-obd2 in your projects.
