Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/evanshortiss/obd-parser

Write commands to a generic OBDII connection and parse responses
https://github.com/evanshortiss/obd-parser

bluetooth ecu elm327 obd obd-ii obd-parser obd2 poll serial typescript vehicle vehicular-networks

Last synced: 11 days ago
JSON representation

Write commands to a generic OBDII connection and parse responses

Awesome Lists containing this project

README 

        
obd-parser

==========



[![Circle CI](https://circleci.com/gh/evanshortiss/obd-parser/tree/master.svg?style=svg)](https://circleci.com/gh/evanshortiss/obd-parser/tree/master)



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](https://www.amazon.com/s/ref=nb_sb_noss/163-4411256-8552763?url=search-alias%3Daps&field-keywords=obd+usb). 



```

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.



```ts



// 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](https://en.wikipedia.org/wiki/OBD-II_PIDs).



For the most up to date list see this

[directory](https://github.com/evanshortiss/obd-reader/tree/master/lib/pids/pid.ts),

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:



```ts

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.



```javascript

'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 - (ಠ_ಠ)