obd-parser

A module for interacting with the OBD (On Board Diagnostics) of vehicles via ELM 327 connections.

Install

npm install obd-parser --save

After this you will need to install a module that facilitates connecting to the ECU. At present only obd-parser-serial-connection is available - this requires a USB to OBD connection such as these.

npm install obd-parser-serial-connection --save

Usage

This example uses TypeScript, but the examples folder has the JavaScript code, the JavaScript code is also pasted below for reference.

 
// In your code this should be changed to 'obd-parser'
import * as OBD from 'obd-parser';
 
// Use a serial connection to connect
var getConnector = require('obd-parser-serial-connection');
 
// Returns a function that will allow us to connect to the serial port
var connectorFn:Function = getConnector({
  // This might vary based on OS - this is the Mac OSX example
  serialPath: '/dev/tty.usbserial',
 
  // Might vary based on vehicle. This is the baudrate for a MK6 VW GTI
  serialOpts: {
    baudrate: 38400
  }
});
 
// Need to initialise the OBD module with a "connector" before starting
OBD.init(connectorFn)
  .then(function () {
    // We've successfully connected. Can now create ECUPoller instances
    const rpmPoller:OBD.ECUPoller = new OBD.ECUPoller({
      // Pass an instance of the RPM PID to poll for RPM
      pid: new OBD.PIDS.Rpm(),
      // Poll every 1500 milliseconds
      interval: 1500
    });
 
    // Bind an event handler for anytime RPM data is available
    rpmPoller.on('data', function (output: OBD.OBDOutput) {
      console.log('==== Got RPM Output ====');
      // Timestamp (Date object) for wheb the response was received
      console.log('time: ', output.ts);
      // The bytes returned from the ECU when asked from RPM
      console.log('bytes: ', output.bytes);
      // A value that's usuall numeric e.g 1200
      console.log('value: ', output.value);
      // This will be a value such as "1200rpm"
      console.log('pretty: ', output.pretty);
    });
 
    // Start polling (every 1500ms as specified above)
    rpmPoller.startPolling();
  });
 

Supported PIDs

Currently the module has support for a limited number of PIDs. PID support can easily be added by adding a new PID definition in lib/pids/pid.ts. You can find information that will assist PID implementation on this Wiki.

For the most up to date list see this directory, or the below list:

• ENGINE_COOLANT_TEMPERATURE (05)
• FUEL_LEVEL_INPUT (2F)
• ENGINE_RPM (0C)
• VEHICLE_SPEED (0D)

If using TypeScript you can also type "OBD.PIDS" and intellisense will display available options.

API

OBD.init(connectorFn)

Initialise the parser. connectorFn should be a connector function generated by a module such as obd-parser-serial-connection.

OBD.ECUPoller(args: PollerArgs) (Class)

A class that can be used to create ECUPoller instances. These must be passed an args Object that contains:

• pid - An instance of any PID, e.g new OBD.PIDS.Rpm()
• interval - The number of milliseconds two wait bewteen polling if startPolling() is called.

You should only create one instance of a given ECUPoller and PID combination at a time unless you're sure about what you're doing.

ECUPoller.poll()

Sends a poll to the ECU for this ECUPoller's PID. Returns Promise that will resolve with an Object matching the OBDOutput interface. If you want you can ignore the Promise and instead bind a "data" listener like the example in this README file.

ECUPoller.startPolling() and ECUPoller.stopPolling()

Starts a constant poll loop that queries as near to the args.interval passed to this ECUPoller. If it is not receiving responses it will not send new polls even if it reaches the interval since we want to prevent flooding the ECU.

OBD.PIDS

This is an Object with PID Classes attached, currently valid options are demonstrated below:

import * as OBD from 'obd-parser';
 
new OBD.PIDS.FuelLevel();
new OBD.PIDS.Rpm();
new OBD.PIDS.VehicleSpeed();
new OBD.PIDS.CoolantTemp();
 
// This is the base class used by all above PIDS. You might want to extend
// this to create your own PIDs (don't forget to contribute them here!)
new OBD.PIDS.PID();

OBD.OBDOutput

Used in TypeScript environments to apply typing to poll "data" events and Promise results.

Pure JavaScript Example

Pure JavaScript example. It is almost identical to the TypeScript version from above in this README.

'use strict';
 
var OBD = require('obd-parser');
 
var getConnector = require('obd-parser-serial-connection');
 
var connect = getConnector({
  serialPath: '/dev/tty.usbserial',
  serialOpts: {
    baudrate: 38400
  }
});
 
OBD.init(connect)
  .then(function () {
    var rpmPoller = new OBD.ECUPoller({
      pid: new OBD.PIDS.Rpm(),
      interval: 1500
    });
 
    rpmPoller.on('data', function (output) {
      console.log('==== Got RPM Output ====');
      console.log('time: ', output.ts);
      console.log('bytes: ', output.bytes);
      console.log('value: ', output.value);
      console.log('pretty: ', output.pretty);
    });
 
    rpmPoller.startPolling();
});

CHANGELOG

• 0.2.1

  • Ensure definition files are included in published code

• 0.2.0

  • Rewrite using TypeScript and Classes (inner conflict regarding Classes)
  • Simplify getting and creating ECUPollers and PIDS
  • Upadted documentation and example

• < 0.2.0 - (ಠ_ಠ)