React Native Obd2 reader is engineered to seamlessly interface with Bluetooth ELM327 OBD-II readers, providing a robust bridge between your mobile applications and vehicle diagnostics. Inspired by the android-obd-reader project, this library encapsulates the OBD Java API, making it readily accessible within the React Native ecosystem. This guide will walk you through installation, API usage, and leveraging listeners to build powerful vehicle data applications.
Installation
Getting started with react-native-obd2 is straightforward. Execute 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 download the necessary package from npm and automatically link the native modules, making the OBD2 functionalities available in your React Native application.
APIs
This section details the core APIs provided by react-native-obd2, enabling you to interact with OBD-II devices and retrieve real-time vehicle data.
ready()
The ready() method is your starting point. It initializes the Bluetooth adapter on the device and prepares the library for OBD-II communication. This is an essential step before utilizing any other API methods.
const obd2 = require('react-native-obd2');
...
obd2.ready();Calling ready() ensures that the Bluetooth is active and ready to establish a connection with an OBD-II adapter.
getBluetoothDeviceNameList()
getBluetoothDeviceNameList() retrieves a list of available Bluetooth devices in the vicinity, including their names and MAC addresses. This is crucial for allowing users to select their OBD-II Bluetooth adapter from a list within your application. The method returns a Promise that resolves with an array of objects, each containing the ‘name’ and ‘address’ of a 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)));Output
The output will be an array of Bluetooth devices found, formatted as JSON:
Bluetooth device list: [{name: "OBD-II", address: "10:F0:8B:3F:91"}]This output provides the necessary information to connect to a specific OBD-II device programmatically.
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. By default, mock-up mode is disabled (false). Enabling it (true) lets you test your application logic and UI with simulated OBD-II data, streamlining the development process.
startLiveData(btDeviceAddress)
startLiveData(btDeviceAddress) initiates the real-time data stream from the OBD-II adapter. You need to provide the Bluetooth MAC address of the OBD-II device obtained from getBluetoothDeviceNameList() to establish a connection. Once started, OBD-II data will be continuously emitted to listeners you have registered. Make sure to set up your ‘obd2LiveData’ listener before calling this method to capture the incoming data.
Example
const obd2 = require('react-native-obd2');
...
componentDidMount() {
this.obdLiveDataListener = DeviceEventEmitter.addListener('obd2LiveData', this.obdLiveData);
obd2.startLiveData('10:F0:8B:3F:91');
}
componentWillUnmount() {
this.obdLiveDataListener.remove();
}This example demonstrates how to start live data streaming upon component mounting and properly clean up the listener when the component unmounts to prevent memory leaks.
stopLiveData()
stopLiveData() terminates the real-time data stream initiated by startLiveData(). Call this method when you need to stop receiving OBD-II data, for example, when the user navigates away from a data monitoring screen or when the application goes into the background.
Listeners
react-native-obd2 utilizes event listeners to communicate status updates and OBD-II data to your application. You need to register these listeners to react to Bluetooth and OBD-II device status changes, as well as to process live vehicle data.
‘obd2bluetoothStatus’
The ‘obd2bluetoothStatus’ listener provides updates on the Bluetooth connection status. The emitted JSON payload includes a ‘status’ key with the following possible values:
| JSON key | Type | Description |
|---|---|---|
| status | String | ‘connected’, ‘disconnected’, ‘error’, ‘disable’, ‘ready’, ‘connecting’ |
This listener is essential for providing feedback to the user about the Bluetooth connection state, allowing you to handle different scenarios such as connection failures or Bluetooth being disabled.
‘obd2Status’
The ‘obd2Status’ listener reports the status of the OBD-II device connection and data reception. The JSON payload includes a ‘status’ key with these possible values:
| JSON key | Type | Description |
|---|---|---|
| status | String | ‘disconnected’, ‘receiving’, or OBD data result |
The ‘receiving’ status indicates that data is actively being received from the OBD-II device. In case of issues, ‘disconnected’ or error messages might be emitted.
‘obd2LiveData’
The ‘obd2LiveData’ listener is the primary channel for receiving real-time OBD-II data. Data is emitted as a dictionary (JSON object) with the following structure:
{ 'cmdID' : String, 'cmdName' : String, 'cmdResult' : String }cmdID: Identifier for the OBD-II command (e.g., “010C” for engine RPM).cmdName: Human-readable name of the command (e.g., “ENGINE_RPM”).cmdResult: The value received from the OBD-II device for the command.
This listener provides a stream of structured OBD-II data, allowing you to display gauges, charts, and perform real-time vehicle diagnostics within your React Native application.
Example Application
A practical example showcasing the usage of react-native-obd2 is available in the ‘Example’ folder of the library’s repository. This example provides a starting point and demonstrates how to integrate the library into a working React Native application. Exploring this example is highly recommended for a hands-on understanding of the library’s capabilities.
License
This project is distributed under 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.
