PandaJS
Interract with your panda OBD-II Dongle from JavaScript.
Supports
- Browser
- Node
- React Native
Installation
npm i --save @commaai/pandajs
or
yarn add @commaai/pandajs
Usage
import Panda from '@commaai/pandajs';
// create instance
var panda = new Panda();
// register listener
panda.onMessage((msg) => {
console.log(msg.address, msg.busTime, msg.data, msg.bus);
});
// start reading data
panda.start();
// pause data
panda.pause();
// resume reading data
panda.unpause();
// close connects and take everything down
panda.disconnect();
API
new Panda([options])
-> Panda
Creates a new Panda instance
-
options
(optional object)-
selectDevice
: (optionalfunction(devices, callback)
) A user defined function for selecting which available device to use, parameters are an array of discovered devices and a callback function. The method can either return the desired device, return a promise, or use the callback function. There is no timeout for this method, so make sure it eventually does one of those three things. This option does nothing in browser mode since webusb has it's own UI for selecting the device. -
wifi
: (optionalboolean
) Enables wifi mode, communicates with the panda device over an already established wifi connection with it. This option will throw errors if you enable it in browser mode.
-
Methods
Panda.connect()
-> Promise: string
Tell the Panda instance to connect to USB. Does not start reading messages until you call start
. On success, returns the ID of the USB device found.
Panda.disconnect()
-> Promise: boolean
Disconnect from the USB device and stop everything. Returns true if it was running before.
Panda.start()
-> Promise: string
Tell the Panda instance to connect to USB if it's not already and start reading messages. On success, returns the ID of the USB device found.
This function is the same as running
panda.connect()
.then(() => panda.unpause());
Panda.pause()
-> boolean
Pauses reading in messages from the active connection. Returns true only if the stream was not already paused. While paused messages will queue up on the Panda device, however this queue has a limited size so pausing may result in missed messages.
Panda.unpause()
-> boolean
Pauses reading in messages from the active connection. Returns true only if the stream was paused.
Panda.resume()
-> boolean
Alias for unpause
.
Panda.isConnected()
-> boolean
Returns true if the panda instance is currecntly connected to a USB device.
Panda.isPaused()
-> boolean
Returns true if the panda instance currently has message reading paused
Panda.getHealth()
-> HealthStatus
Requests the current health of the Panda unit. Only available while connected, returns the health object on success or errors.
-
HealthStatus
: (object)-
voltage
: (number) -
current
: (number) -
isStarted
: (boolean) -
controlsAreAllowed
: (boolean) -
isGasInterceptorDetector
: (boolean) -
isStartSignalDetected
: (boolean) -
isStartedAlt
: (boolean)
-
Panda.getDeviceMetadata()
-> [string, string]
Requests both the serial number and secret from the Panda device. This is used internally to power getSerialNumber
and getSecret
.
Returns an array with 2 items in, the serial number and then the secret.
Panda.getSerialNumber()
-> string
Requests the serial number.
This function is the same as running
panda.getDeviceMetadata()
.then((result) => result[0])
Panda.getSecret()
-> string
Requests the secret used for wifi among other things.
This function is the same as running
panda.getDeviceMetadata()
.then((result) => result[1])
Panda.getVersion()
-> string
Requests the string version number, output will look something like v1.0.1-11d45090-RELEASE
Panda.isWhite()
-> boolean
Query if the Panda device is a white Panda. Returns true if it is white.
Panda.isGrey()
-> boolean
Query if the Panda device is a grey Panda. Returns true if it is grey.
Panda.isBlack()
-> boolean
Query if the Panda device is a black Panda. Returns true if it is black.
Panda.hasObd()
-> boolean
Query if the Panda device has a connection to the OBD port. Returns true if it has an OBD port connection.
Panda.setObd(connected)
-> void
Connect Panda device to the OBD port (if supported and parameter is true
).
Panda.setSafetyMode(mode)
-> void
Sets the safety mode on the Panda device.
-
mode
: (requiredSafetyMode
) The safety mode to enter. Must be a valid safety mode, safety modes are exposed as constants on the root of the library.
import { SAFETY_NOOUTPUT, SAFETY_ELM327, SAFETY_ALLOUTPUT } from '@commaai/pandajs';
Events
Panda.onMessage(listener)
-> function
Register a handler for receiving messages. This should be done before calling start
to avoid missing any messages. Returns an unlisten
function that will disable the listener when called.
-
listener
: (required,function (messageData)
) Handler to call each time messages are received-
messageData
: (object)-
time
: (number) High precision time in which this event was received. -
canMessages
: (Array)-
bus
: (number) The bus this message came from -
address
: (number) The bus specific address for the message -
busTime
: (number) The recieve time according to the bus -
data
: (ByteArray) Raw data for this message
-
-
-
Panda.onError(listener)
-> function
Register an error handler. Returns an unlisten
function that will disable the listener when called.
-
listener
: (required,function (err)
) Handler to call when errors occur-
err
: (object)-
error
: (Error) Error object incurred -
event
: (string) Description of where the error occured
-
-
Panda.onConnect(listener)
-> function
Register a handler to run when successfully connecting to a Panda device. Returns an unlisten
function that will disable the listener when called.
-
listener
: (required,function (usbId)
) Handler to call when connected-
usbId
: (string) The ID of the USB device connected to.
-
Panda.onDisconnect(listener)
-> function
Register a handler to run when disconnecting from a Panda device. Returns an unlisten
function that will disable the listener when called.
-
listener
: (required,function (usbId)
) Handler to call when disconnected-
usbId
: (string) The ID of the USB device disconnected from.
-
Command Line Tools
This package ships with 2 CLI tools. Check the --help
on each to see all of their options.
dump-can
This is used to dump metadata about the incoming CAN messages, or output the entire messages with -a
.
Examples:
$ dump-can
Connected: ba435375436c2a6d
{ voltage: 12.123,
current: 4.093,
isStarted: false,
controlsAreAllowed: false,
isGasInterceptorDetector: false,
isStartSignalDetected: false,
isStartedAlt: false }
Connect finished, waiting then reading all messages...
Start reading...
Message count: 1
First message CAN count: 256
First CAN message: { address: 420,
busTime: 54858,
data: <Buffer 00 66 00 02 00 00 00 0b>,
bus: 0 }
Message count: 1
First message CAN count: 256
First CAN message: { address: 1024,
busTime: 6626,
data: <Buffer 79 00 02 00 0a 78 00 09>,
bus: 1 }
$ dump-can -an
{"time":7.3178732019999995,"canMessages":[{"address":1024,"busTime":53980,"data":[121,0,2,0,10,120,0,9],"bus":1},{"address":420,"busTime":54066,"data":[0,102,0,2,0,0,0,11],"bus":0},{"address":1024,"busTime":54115,"data":[121,0,2,0,10,120,0,9],"bus":1}]}
{"time":7.318214842000001,"canMessages":[{"address":420,"busTime":54202,"data":[0,102,0,2,0,0,0,11],"bus":0},{"address":1024,"busTime":54250,"data":[121,0,2,0,10,120,0,9],"bus":1},{"address":420,"busTime":54338,"data":[0,102,0,2,0,0,0,11],"bus":0}]}
{"time":7.31846793,"canMessages":[{"address":1024,"busTime":54385,"data":[121,0,2,0,10,120,0,9],"bus":1},{"address":420,"busTime":54474,"data":[0,102,0,2,0,0,0,11],"bus":0}]}
control-panda
This is a convenience tool wrapping each of the get and set methods exposed by this library.
Examples:
$ ./control-panda.js wifi
SID: panda-2baf789dacdacb64
Password: aGBw61RwD0
$ ./control-panda.js version
v1.0.1-11d45090-RELEASE
Contributing
yarn run test
License
MIT @ comma.ai
Read more about how to get started hacking your car with panda here.