panda/boardesp/ELM327.md

ELM327 support for panda
======
The panda now has basic ELM327 support.

### What is ELM327?

ELM327 is a command protocol for interfacing with cars using an OBD-II
port to read [list](standard vehicle diagnostic codes). ELM327
originally referred to a line of programmable microcontrollers that
implemented the ELM327 command protocol, and are still being
developed.

ELM327 devices present a shell and commands are sent via a UART. The
official ELM327 chips only support raw UART communication, but most
devices built with the ELM327 devices (official or clones) expose the
UART in a more modern way (Wifi, USB, etc).

Mechanics use ELM to diagnose vehicles, and reset fault codes in the
car's computer after fixing the issue (turning off the dreaded check
engine light). Car owners can use ELM devices to perform the same
diagnostics in their garage using either a raw terminal to send
commands to the ELM device directly, or using a GUI (like one of
several popular smart phone apps) to translate the OBD error codes
into readable messages. These GUIs also often allow monitoring of the
performance of the car's speed, engine rpm, etc.

The panda natively supports sending all the important OBD diagnostic
messages, but ELM327 support removes the need for the user to manually
craft CAN or LIN packets using the native panda API, and grants
compatibility with many existing tools.

[Wikipedia](https://en.wikipedia.org/wiki/ELM327) can provide
additional information.

### OBD Protocols?

While the commands that the OBD standard describe are in fact
standard, there are several different protocols that those messages
can be sent and received with. All cars after 1991 support one of
these protocols. Which one depends on the car's year and country, as
legal requirements change over the years.

The panda supports the most popular/modern of these protocols, and all
but two can be added as needed. Below is a chart of the OBD-II
protocols supported by the panda.

| Protocol | Support Status |
| --- | --- |
| SAE J1850 PWM (41.6 kbit/s) | Never/Obsolete |
| SAE J1850 VPW (10.4 kbit/s) | Never/Obsolete |
| ISO 9141-2 (5 baud init, 10.4 kbit/s) | Unsupported |
| ISO 14230-4 KWP (5 baud init, 10.4 kbit/s) | Unsupported |
| ISO 14230-4 KWP (fast init, 10.4 kbit/s) | Supported |
| ISO 15765-4 CAN (11 bit ID, 500 kbit/s) | Supported |
| ISO 15765-4 CAN (29 bit ID, 500 kbit/s) | Supported |
| ISO 15765-4 CAN (11 bit ID, 250 kbit/s) | Supported |
| ISO 15765-4 CAN (29 bit ID, 250 kbit/s) | Supported |
| SAE J1939 (250kbps) | Unsupported |

### The Implementation

The panda ELM327 implementation is not a full implementation of all
the features of the official ELM327 microcontroller. Like most ELM327
clones, the panda reports its ELM version as the unreleased version
1.5, despite only implementing commands from protocol version 1.0.


### Testing

These tests require two pandas. One to be tested, and the second to
simulate the vehicle.

The panda used to simulate the vehicle must be plugged into a USB port
of the testing computer.

The computer running the tests must be connected to the panda being
tested's wifi network.

The following command will run the tests (nosetest should work fine
instead of pytest if you still prefer using that). The CANSIMSERIAL
environment variable will force the car simulator to use the correct
panda as the simulator if multiple pandas are attached via usb to the
host computer.

```
CANSIMSERIAL=car_sim_panda_serial pytest tests/automated/elm_wifi.py
```

A single test can be run by putting the test name after the file name
and two colons, like so:

```
CANSIMSERIAL=car_sim_panda_serial pytest tests/automated/elm_wifi.py::test_important_thing
```

For more detail, provide the -s (show output) and the -vv (very
verbose) flags.

```
CANSIMSERIAL=car_sim_panda_serial pytest -s -vv tests/automated/elm_wifi.py
```